Payments API

The payments API allows agents to request authorization and execute stablecoin payments.

Overview

The payment flow has two steps:

Request - Request authorization and policy evaluation
Execute - Execute the approved payment onchain

Or use autoExecute: true to request and execute in a single API call. You can also use the SDK convenience method pay() to do both in one call.

payments.request()

Request authorization for a payment. This evaluates policies without executing.

const request = await conto.payments.request({
  amount: 100,
  recipientAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f...',
  recipientName: 'OpenAI',
  purpose: 'GPT-4 API credits',
  category: 'AI_SERVICES'
});

Parameters

Parameter	Type	Required	Description
`amount`	number	Yes	Payment amount
`recipientAddress`	string	Yes	Wallet address — `0x` + 40 hex chars for EVM, or base58 (32-44 chars) for Solana. Validated via Zod schema.
`recipientName`	string	No	Human-readable name
`purpose`	string	No	Why this payment is needed
`category`	string	No	Spending category
`context`	object	No	Additional metadata
`walletId`	string	No	Specific wallet to use
`urgency`	string	No	LOW, NORMAL, HIGH, CRITICAL
`autoExecute`	`boolean`	No	If `true`, automatically execute the payment when approved. Returns the transaction result directly instead of requiring a separate `execute()` call.
`targetContractAddress`	string	No	Smart contract address for contract interaction policy evaluation
`functionSelector`	string	No	4-byte function selector (e.g., `0xa9059cbb`) for contract allowlist rules
`idempotencyKey`	string	No	Client-supplied key that makes retries safe. Reusing the same key with the same request returns the original request; reusing it with different request parameters returns a conflict.

External wallet users (OpenClaw): If your agent controls its own wallet keys and uses the /api/sdk/payments/approve endpoint instead, chainId is a required parameter. See the OpenClaw guide for the external wallet flow.

Response

interface PaymentRequestResult {
  requestId: string;  // Use this to execute
  status: 'APPROVED' | 'DENIED' | 'REQUIRES_APPROVAL' | 'EXECUTED';
  idempotent?: boolean; // Present when a retry returns an existing request

  // If approved or executed
  wallet?: {
    id: string;
    address: string;
    chainId: string;
    custodyType: string;
    availableBalance: number;
  };
  walletSelectionReason?: string;
  expiresAt?: string;  // ISO timestamp
  currency?: string;   // e.g., "USDC", "USDT", "pathUSD"
  chain?: {
    chainId: string;
    chainName: string;
    chainType: string;
    explorerUrl?: string;
  };

  // If executed (autoExecute was true)
  execution?: {
    transactionId: string;
    txHash: string;
    explorerUrl: string;
    status: string;
  };

  // Always present
  reasons: string[];

  // If denied - includes enriched context
  violations?: {
    type: string;
    limit: number;
    current: number;
    message: string;       // Prefixed with source, e.g. "[Wallet limit]" or "[Policy: Name]"
    source?: 'wallet_limit' | 'policy_rule';
    policyName?: string;   // Present when source is "policy_rule"
  }[];
  context?: {
    wallets?: Array<{ id: string; address: string; chainId: string; custodyType: string; balance: number }>;
    nextSteps?: string[];
  };

  // If autoExecute failed
  autoExecuteError?: string;
}

All payment responses now include currency (e.g., “USDC”, “USDT”, or “pathUSD”) and chain (with chainId, chainName, chainType, and explorerUrl) so agents know exactly which network and token the payment uses.

Currency depends on chain: The currency field reflects the stablecoin used on the wallet’s blockchain. On Base, Ethereum, Arbitrum, and Polygon, both USDC and USDT are supported. On Tempo, it is pathUSD. The amount is always denominated in the stablecoin configured for the payment.

Idempotent Retries

Use idempotencyKey when your caller may retry the same payment request because of network timeouts or uncertain client state.

Same idempotencyKey + same request payload: returns the original requestId with idempotent: true
Same idempotencyKey + different request payload: returns HTTP 409 with code: "IDEMPOTENCY_CONFLICT"
Different idempotencyKey: creates a new payment request

const request = await conto.payments.request({
  amount: 100,
  recipientAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f...',
  purpose: 'Top up API credits',
  idempotencyKey: 'payment-req-2026-04-17-001'
});

Example

const request = await conto.payments.request({
  amount: 50,
  recipientAddress: '0x...',
  purpose: 'API credits'
});

switch (request.status) {
  case 'APPROVED':
    console.log('Payment approved');
    console.log('Wallet:', request.wallet?.address);
    console.log('Expires:', request.expiresAt);
    break;

  case 'DENIED':
    console.log('Payment denied:', request.reasons);
    break;

  case 'REQUIRES_APPROVAL':
    console.log('Needs manual approval');
    break;
}

payments.execute()

Execute an approved payment request.

const result = await conto.payments.execute(requestId);

Parameters

Parameter	Type	Required	Description
`requestId`	string	Yes	The requestId from payment request

Response

interface PaymentExecuteResult {
  transactionId: string;
  txHash: string;  // Blockchain transaction hash
  status: 'CONFIRMING' | 'CONFIRMED' | 'FAILED';
  amount: number;
  currency: string;  // Stablecoin type
  recipient: string;
  recipientName?: string;
  wallet: {
    address: string;
  };
  explorerUrl: string;  // Block explorer link
}

Example

const request = await conto.payments.request({
  amount: 50,
  recipientAddress: '0x...'
});

if (request.status === 'APPROVED') {
  const result = await conto.payments.execute(request.requestId);

  console.log('Transaction hash:', result.txHash);
  console.log('Explorer:', result.explorerUrl);
}

payments.pay()

Convenience method that requests and executes in one call.

const result = await conto.payments.pay({
  amount: 50,
  recipientAddress: '0x...',
  purpose: 'API credits'
});

Behavior

If approved: Executes immediately and returns result
If denied: Throws ContoError with code PAYMENT_DENIED
If requires approval: Throws ContoError with code REQUIRES_APPROVAL

Example

try {
  const result = await conto.payments.pay({
    amount: 50,
    recipientAddress: '0x...',
    purpose: 'API credits'
  });

  console.log('Paid! TX:', result.txHash);
} catch (error) {
  if (error.code === 'PAYMENT_DENIED') {
    console.log('Payment denied:', error.message);
  } else if (error.code === 'REQUIRES_APPROVAL') {
    console.log('Payment needs manual approval');
  }
}

autoExecute Flag

The autoExecute flag lets you request authorization and execute the payment in a single API call, without needing a separate execute() call.

Requires both payments:request and payments:execute scopes. Since payments:execute is not included in default scopes, you must explicitly grant it when creating the SDK key. If the key only has payments:request, the flag is silently ignored and the response is a normal APPROVED status.

How It Works

If APPROVED + autoExecute: true: Executes immediately, returns status: "EXECUTED" with execution object containing txHash
If DENIED or REQUIRES_APPROVAL: autoExecute is ignored, normal response returned
If execution fails: Returns status: "APPROVED" with autoExecuteError message and executeUrl for manual retry

Example

// Single-call payment: request + execute
const result = await fetch('/api/sdk/payments/request', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 50,
    recipientAddress: '0x...',
    recipientName: 'OpenAI',
    purpose: 'API credits',
    autoExecute: true
  })
}).then(r => r.json());

if (result.status === 'EXECUTED') {
  console.log('Payment complete!');
  console.log('TX Hash:', result.execution.txHash);
  console.log('Explorer:', result.execution.explorerUrl);
} else if (result.status === 'APPROVED' && result.autoExecuteError) {
  // Auto-execute failed, retry manually
  console.log('Auto-execute failed:', result.autoExecuteError);
  const execResult = await fetch(result.executeUrl, { method: 'POST', ... });
}

payments.status()

Check the status of a payment request.

const status = await conto.payments.status(requestId);

Response

interface PaymentStatusResult {
  requestId: string;
  status: 'PENDING' | 'APPROVED' | 'DENIED' | 'COMPLETED' | 'EXPIRED';
  policyResult: string;
  amount: number;
  currency: string;
  recipient: string;
  recipientName?: string;
  purpose?: string;
  category?: string;
  wallet?: { address: string };
  requiresApproval: boolean;
  approvedAt?: string;
  deniedAt?: string;
  denialReason?: string;
  expiresAt?: string;
  createdAt: string;

  // If executed
  transaction?: {
    id: string;
    txHash: string;
    status: 'PENDING' | 'CONFIRMING' | 'CONFIRMED' | 'FAILED';
    confirmedAt?: string;
    blockNumber?: number;
  };
}

Example: Polling for Confirmation

async function waitForConfirmation(requestId: string) {
  while (true) {
    const status = await conto.payments.status(requestId);

    if (status.transaction?.status === 'CONFIRMED') {
      console.log('Confirmed at block:', status.transaction.blockNumber);
      return status;
    }

    if (status.transaction?.status === 'FAILED') {
      throw new Error('Transaction failed');
    }

    await new Promise(r => setTimeout(r, 2000));  // Wait 2 seconds
  }
}

Status Reference

Payment requests and transactions use different status values:

Payment Request Status	Description
`APPROVED`	Policies passed, ready to execute
`DENIED`	Blocked by a policy or wallet limit
`REQUIRES_APPROVAL`	Needs manual human approval
`EXECUTED`	Auto-executed successfully (when `autoExecute: true`)
`PENDING`	Awaiting human approval (maps to REQUIRES_APPROVAL in SDK response)
`COMPLETED`	Payment fully confirmed onchain
`EXPIRED`	Approval window elapsed without execution

Transaction Status	Description
`PENDING`	Transaction submitted, awaiting confirmation
`EXECUTING`	Transaction is being processed
`CONFIRMING`	Transaction broadcast, awaiting block confirmation
`CONFIRMED`	Transaction confirmed onchain
`FAILED`	Transaction failed
`REJECTED`	Transaction rejected
`CANCELLED`	Transaction cancelled before execution

Policy Result	Description
`ALLOWED`	All policies passed
`DENIED`	At least one policy denied the payment
`REQUIRES_APPROVAL`	Policies passed but approval threshold triggered
`FLAGGED`	Payment flagged for review
`PENDING`	Policy evaluation not yet complete

Category	Description
`INFRASTRUCTURE`	Cloud, hosting, compute
`AI_SERVICES`	AI APIs, model training
`MARKETING`	Advertising, promotions
`OPERATIONS`	General operations
`VENDOR`	Vendor payments
`EMPLOYEE`	Employee reimbursements
`TESTING`	Test transactions

Urgency Levels

Level	Description
`LOW`	Can wait, batch if possible
`NORMAL`	Standard priority (default)
`HIGH`	Process quickly
`CRITICAL`	Immediate processing

Best Practices

Always Include Purpose

Including purpose improves audit trails and analytics:

await conto.payments.pay({
  amount: 100,
  recipientAddress: '0x...',
  purpose: 'AWS EC2 instance for training job #1234',  // Specific
  category: 'INFRASTRUCTURE'
});

Handle Expiration

Approvals from /request expire after 5 minutes. Approvals from /approve (external wallets) expire after 10 minutes. Check expiration before executing:

const request = await conto.payments.request({ ... });

if (request.status === 'APPROVED') {
  const expiresAt = new Date(request.expiresAt!);

  if (expiresAt > new Date()) {
    await conto.payments.execute(request.requestId);
  } else {
    // Request a new approval
    const newRequest = await conto.payments.request({ ... });
  }
}

Use Two-Step for Complex Flows

Use separate request/execute when you need to:

Validate before executing
Show user confirmation
Handle requires_approval status

const request = await conto.payments.request({ ... });

if (request.status === 'REQUIRES_APPROVAL') {
  // Store requestId, notify approvers
  await notifyApprovers(request.requestId);
  return { pending: true, requestId: request.requestId };
}

if (request.status === 'APPROVED') {
  return conto.payments.execute(request.requestId);
}

Add Context for Debugging

Use the context field for debugging info:

await conto.payments.pay({
  amount: 100,
  recipientAddress: '0x...',
  purpose: 'API subscription',
  context: {
    jobId: '1234',
    userId: 'user_abc',
    environment: 'production'
  }
});

Get Started

API

Quick Start

Conto Pay

CLI

SDK

AI Assistant

MCP Server

Policies

Integrations

Guides

Changelog

Payments

Payments API

Overview

payments.request()

Parameters

Response

Idempotent Retries

Example

payments.execute()

Parameters

Response

Example

payments.pay()

Behavior

Example

autoExecute Flag

How It Works

Example

payments.status()

Response

Example: Polling for Confirmation

Status Reference

Categories

Urgency Levels

Best Practices

Next Steps

Error Handling

Examples

Get Started

API

Quick Start

Conto Pay

CLI

SDK

AI Assistant

MCP Server

Policies

Integrations

Guides

Changelog

​Payments API

​Overview

​payments.request()

​Parameters

​Response

​Idempotent Retries

​Example

​payments.execute()

​Parameters

​Response

​Example

​payments.pay()

​Behavior

​Example

​autoExecute Flag

​How It Works

​Example

​payments.status()

​Response

​Example: Polling for Confirmation

​Status Reference

​Categories

​Urgency Levels

​Best Practices

​Next Steps

Error Handling

Examples

Payments API

Overview

payments.request()

Parameters

Response

Idempotent Retries

Example

payments.execute()

Parameters

Response

Example

payments.pay()

Behavior

Example

autoExecute Flag

How It Works

Example

payments.status()

Response

Example: Polling for Confirmation

Status Reference

Categories

Urgency Levels

Best Practices

Next Steps