Payments API

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

Payment SDK routes enforce explicit API-key scopes. Reading payment status requires transactions:read; requesting, approving, and executing payments require their corresponding payments:request, payments:approve, and payments:execute scopes.

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.

Choose The Right Flow

Wallet model	Use this flow	What Conto can stop
Managed (`MANAGED`)	`request -> execute`	Conto stays in the execution path and can block the spend
External (`EXTERNAL`)	`approve -> transfer -> confirm`	Conto governs the Conto-routed flow, but cannot block a direct self-signed transfer outside Conto

payments.execute() is for managed wallets. If your agent holds the signing keys, use the external-wallet approve -> confirm flow instead.

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: If your agent controls its own wallet keys and uses the /api/sdk/payments/approve endpoint instead, chainId is a required parameter. See the Agent Skills guide (OpenClaw and Hermes) for the external-wallet flow.

If you include context.invoice, Conto links the invoice details to the payment for reconciliation and approval review. Supported invoice fields are vendorId, vendorAddress, id, hash, sourceUrl, payload, expectedAmount, currency, and dueDate. Delta verification workflows and payment.executed webhook payloads prefer this typed invoice record for new requests. For a full setup and live test example, see Delta Verification Setup and Delta Smoke Test.

Delta access is currently enabled by Conto during onboarding. If you want to use this flow, contact sales@conto.finance.

If an approval workflow matches any non-denied request, Conto opens the approval request immediately and includes approvalRequestId in the API response. This includes workflows that intentionally gate otherwise policy-approved payments. If the payment controls require approval and no custom workflow matches, Conto still opens an actionable review and returns its approvalRequestId.

External Wallet Approve/Confirm Flow

If your agent holds the signing keys, use the external-wallet flow instead of payments.execute():

Call POST /api/sdk/payments/approve to evaluate policy and receive an approvalToken
Submit the onchain transfer through your own signer or wallet integration
Call POST /api/sdk/payments/{requestId}/confirm with the final txHash, plus the approvalToken when the original /approve response returned one

This keeps the same policy checks and audit trail while leaving execution in the agent’s control. It does not cryptographically block a direct transfer signed outside Conto.

Confirmation atomically claims an approved external-wallet payment before creating the transaction record and updating spend tracking. A repeated confirmation for the same request returns a conflict instead of creating duplicate ledger effects.

If the senderAddress has not been seen before, Conto auto-creates an external wallet record for that address and links it to the agent’s organization. That record still counts toward the organization’s wallet limit, so approval can fail with WALLET_LIMIT_REACHED when the org is already at capacity.

The external-wallet approve flow accepts the same optional context.invoice object as payments.request() and stores the same typed invoice fields on the resulting PaymentRequest.

If an approval workflow matches, /api/sdk/payments/approve returns requiresHumanApproval: true and includes approvalRequestId in the response instead of issuing an approvalToken. After that workflow approves the payment, POST /api/sdk/payments/{requestId}/confirm can be called with just the final txHash. Policy-required reviews use the same response shape even when no custom workflow matches, so every review remains actionable.

Agent-skill approval decisions

OpenClaw can list pending reviews with GET /api/sdk/approval-requests?type=payment&status=PENDING and submit the assigned human owner’s explicit decision with:

curl -X POST https://conto.finance/api/sdk/approval-requests/APPROVAL_REQUEST_ID/decide \
  -H "Authorization: Bearer $CONTO_SDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"decision":"APPROVED","comment":"Approved in OpenClaw"}'

This route requires payments:approve. It resolves the agent’s assigned owner and still enforces that person’s transaction-approval permission plus every workflow eligibility and sequencing rule. When the decision completes the workflow, Conto automatically sends managed-wallet payments and returns receiptUrl. External wallets receive a nextAction payload containing the exact transfer and tokenless confirmation handoff.

Response

interface PaymentRequestResult {
  requestId: string;
  status: 'APPROVED' | 'DENIED' | 'REQUIRES_APPROVAL' | 'ACTION_REQUIRED' | 'PROCESSING';
  amount: number;
  currency: string;
  recipient: string;
  custodyMode?: 'MANAGED' | 'EXTERNAL' | 'SMART_CONTRACT';
  reasons: string[];
  approvalRequestId?: string; // Present when the request is routed into an approval workflow
  statusUrl: string;
  expiresAt?: string;
  actionUrl?: string;
  receipt?: {
    transactionId: string;
    txHash: string;
    settlementMode: 'live' | 'test';
    explorerUrl?: string;
  };
}

approvalRequestId is the stable review reference. Use statusUrl to reconcile the request and follow actionUrl for the next available step. When present, custodyMode tells the caller whether Conto can execute the selected wallet or the customer’s signer must complete the transfer. reasons contains customer-facing explanations; provider diagnostics and stored policy records are not returned.

Payment responses include currency (for example, USDC, USDT, USDC.e, or pathUSD) so the caller can reconcile the requested amount with the selected wallet network.

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 Testnet, it is pathUSD. On Tempo Mainnet, it is USDC.e. 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 and current next action
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('Execute:', request.actionUrl);
    console.log('Expires:', request.expiresAt);
    break;

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

  case 'REQUIRES_APPROVAL':
    console.log('Review:', request.approvalRequestId);
    console.log('Track:', request.statusUrl);
    break;
}

payments.execute()

Execute an approved payment request.

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

payments.execute() rechecks ownership and active spending limits before submitting the payment. Successful responses include the stable Conto transaction ID needed for reconciliation.

Parameters

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

Response

interface PaymentExecuteResult {
  requestId: string;
  status: 'processing' | 'completed';
  amount: number;
  currency: string;
  recipient: string;
  receipt: {
    transactionId: string;
    txHash: string;
    settlementMode: 'live' | 'test';
    explorerUrl?: string;
  };
}

A processing response means the payment was submitted and should be checked with payments.status(requestId). Every successful execution includes a stable Conto transaction ID. Check settlementMode before treating the hash or explorer link as evidence of live settlement.

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('Conto transaction:', result.receipt.transactionId);
  console.log('Settlement mode:', result.receipt.settlementMode);
  console.log('Transaction hash:', result.receipt.txHash);
  if (result.receipt.explorerUrl) console.log('Explorer:', result.receipt.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
If an additional action is required: Throws ContoError with code ACTION_REQUIRED and a validated actionUrl

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');
  } else if (error.code === 'ACTION_REQUIRED') {
    console.log('Open:', error.actionUrl);
  }
}

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. The standard SDK key preset includes both. If a key lacks payments:execute (for example, a legacy custom-scoped key), the flag is silently ignored and the response is a normal APPROVED status that you must execute separately.

How It Works

If APPROVED + autoExecute: true: Starts execution and returns status: "PROCESSING"; a customer receipt is included once execution has produced a transaction ID and hash
If DENIED or REQUIRES_APPROVAL: autoExecute is ignored, normal response returned
If automatic execution does not start: Returns status: "APPROVED" with an actionUrl 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 === 'PROCESSING' && result.receipt) {
  console.log('Conto transaction:', result.receipt.transactionId);
  console.log('Settlement mode:', result.receipt.settlementMode);
  console.log('TX Hash:', result.receipt.txHash);
} else if (result.status === 'APPROVED' && result.actionUrl) {
  const execResult = await fetch(result.actionUrl, {
    method: 'POST',
    headers: { Authorization: `Bearer ${apiKey}` },
  });
}

payments.status()

Check the status of a payment request.

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

Response

interface PaymentStatusResult {
  requestId: string;
  status:
    | 'approved'
    | 'declined'
    | 'review_required'
    | 'action_required'
    | 'processing'
    | 'completed'
    | 'failed'
    | 'expired';
  amount: number;
  currency: string;
  recipient: string;
  recipientName: string | null;
  purpose: string | null;
  category: string | null;
  expiresAt: string | null;
  createdAt: string;
  action: {
    type: 'complete_verification';
    url: string;
  } | null;
  transaction: {
    id: string;
    txHash: string | null;
    status: 'processing' | 'completed' | 'failed';
    confirmedAt: string | null;
    blockNumber: number | null;
    chain: {
      type: 'evm' | 'solana';
      id: string;
    };
    explorerUrl: string | null;
    detailsUrl: string;
  } | null;
}

Example: Polling for Confirmation

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

    if (status.transaction?.status === 'completed') {
      console.log('Conto transaction:', status.transaction.id);
      console.log('Confirmed:', status.transaction.txHash);
      if (status.transaction.explorerUrl) {
        console.log('Explorer:', status.transaction.explorerUrl);
      }
      return status;
    }

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

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

Status Reference

The status endpoint returns this compact status set:

Status	Meaning
`approved`	Ready for the next payment step
`declined`	Stopped by the current payment controls
`review_required`	Waiting for an authorized reviewer
`action_required`	Follow the returned action URL
`processing`	Submitted and still in progress
`completed`	Completed successfully
`failed`	Processing failed
`expired`	The approval window ended before completion

When a transaction is present, its status is one of processing, completed, or failed.

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);
}

Attach Invoice Details

Use the typed context.invoice object when a payment is linked to an invoice:

await conto.payments.pay({
  amount: 100,
  recipientAddress: '0x...',
  purpose: 'API subscription',
  context: {
    invoice: {
      id: 'invoice_1234',
      expectedAmount: 100,
      currency: 'USDC',
    },
  },
});

Start

Products

Build

Guides

Reference

Changelog

Payments

Payments API

Overview

Choose The Right Flow

payments.request()

Parameters

External Wallet Approve/Confirm Flow

Agent-skill approval decisions

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

​Choose The Right Flow

​payments.request()

​Parameters

​External Wallet Approve/Confirm Flow

​Agent-skill approval decisions

​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

Choose The Right Flow

payments.request()

Parameters

External Wallet Approve/Confirm Flow

Agent-skill approval decisions

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