Code examples

Every example calls the agent SDK endpoints with the agent’s SDK key as CONTO_API_KEY. Do not use CONTO_ORG_API_KEY for these /api/sdk/* calls. See Keys and scopes.

Before integrating, connect your agent, link a wallet, and generate an SDK key. If you are an autonomous agent evaluating Conto without a human account, try the sandbox first.

The examples use a managed wallet: request, then execute. External wallets use approve, your own transfer, then confirm. See wallet custody.

SDK examples

These use @conto_finance/sdk. See Install the TypeScript SDK.

One-call payment

Use payments.pay() with a managed wallet to request approval and execute in one call. It throws if the payment is denied or needs approval.

import { Conto } from '@conto_finance/sdk';

const conto = new Conto({ apiKey: process.env.CONTO_API_KEY! });

const result = await conto.payments.pay({
  amount: 50,
  recipientAddress: '0x0000000000000000000000000000000000000001',
  recipientName: 'OpenAI',
  purpose: 'API credits',
  category: 'AI_SERVICES',
});

console.log(result.status, result.receipt.transactionId, result.receipt.txHash ?? 'test settlement');

Approval-aware payment

Use request() then execute() when your app handles denied or review-required outcomes before execution.

import { Conto } from '@conto_finance/sdk';

const conto = new Conto({ apiKey: process.env.CONTO_API_KEY! });

const request = await conto.payments.request({
  amount: 100,
  recipientAddress: '0x0000000000000000000000000000000000000001',
  purpose: 'Infrastructure spend',
});

if (request.status === 'DENIED') {
  console.log(request.reasons);
}

if (request.status === 'REQUIRES_APPROVAL') {
  console.log('Awaiting approval:', request.requestId);
}

if (request.status === 'APPROVED') {
  const result = await conto.payments.execute(request.requestId);
  console.log(result.receipt.transactionId, result.receipt.txHash ?? 'test settlement');
}

Setup check

Call conto.setup() on agent startup to read the agent, its wallets, spending limits, and scopes.

import { Conto } from '@conto_finance/sdk';

const conto = new Conto({ apiKey: process.env.CONTO_API_KEY! });
const setup = await conto.setup();

console.log(setup.agent.name);
console.log(setup.scopes);
console.log(setup.wallets);

The shared payment helper

Each framework integration wraps the same two calls: request (policy check), then execute. This helper calls the REST API directly with no SDK dependency. Define it once and call it from each framework’s tool handler. It:

Sends the payment to POST /api/sdk/payments/request with an idempotency key, so Conto checks it against your policies.
Stops if the result is not APPROVED and returns the status, reasons, and actionUrl. pending is true when the payment waits for approval.
Calls POST /api/sdk/payments/{requestId}/execute only for an approved request.
Returns the receipt, transaction hash, and explorer URL. success is true only for a completed payment with a transaction ID.
Returns uncertain or checkStatus when the outcome is unknown. It never retries.

const CONTO_API_KEY = process.env.CONTO_API_KEY;
const CONTO_BASE_URL = process.env.CONTO_BASE_URL ?? 'https://conto.finance';

type PaymentInput = {
  amount: number;
  recipientAddress: string;
  recipientName?: string;
  purpose: string;
  category?: string;
};

async function executeContoPayment(input: PaymentInput, idempotencyKey = crypto.randomUUID()) {
  let requestId: string | undefined;
  try {
    const response = await fetch(`${CONTO_BASE_URL}/api/sdk/payments/request`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${CONTO_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ category: 'OPERATIONS', ...input, idempotencyKey }),
    });
    const request = await response.json();
    requestId = request.requestId;
    if (!response.ok) {
      return { success: false, requestId, idempotencyKey, error: request.error, uncertain: response.status >= 500 };
    }
    if (request.status !== 'APPROVED' || !requestId) {
      return {
        success: false,
        pending: request.status === 'REQUIRES_APPROVAL',
        requestId,
        idempotencyKey,
        status: request.status,
        reasons: request.reasons,
        actionUrl: request.actionUrl,
      };
    }

    const execution = await fetch(
      `${CONTO_BASE_URL}/api/sdk/payments/${encodeURIComponent(requestId)}/execute`,
      { method: 'POST', headers: { Authorization: `Bearer ${CONTO_API_KEY}` } }
    );
    const result = await execution.json();
    if (!execution.ok) {
      return { success: false, requestId, idempotencyKey, error: result.error, checkStatus: true };
    }
    return {
      success: result.status === 'completed' && Boolean(result.receipt?.transactionId),
      pending: result.status === 'processing',
      status: result.status,
      requestId,
      idempotencyKey,
      receipt: result.receipt,
      transactionHash: result.receipt?.txHash,
      amount: result.amount,
      explorerUrl: result.receipt?.explorerUrl,
    };
  } catch {
    return { success: false, uncertain: true, requestId, idempotencyKey, message: 'Check the payment status before trying again.' };
  }
}

A processing result means the payment was submitted and awaits confirmation. A sandbox completed result has a test receipt and does not prove an onchain transfer. Keep the request ID and idempotency key with the operation. After a timeout or an uncertain response, check GET /api/sdk/payments/{requestId} before trying again. If the request response was lost, repeat only the authorization request with the same input and idempotency key to recover it. Do not start a new payment. Neither helper retries automatically. The Python equivalent needs pip install requests:

import os
from typing import Optional

import requests

CONTO_API_KEY = os.environ.get('CONTO_API_KEY')
CONTO_BASE_URL = os.environ.get('CONTO_BASE_URL', 'https://conto.finance')

def make_payment(amount: float, recipient_address: str, purpose: str,
                 recipient_name: Optional[str] = None, idempotency_key: Optional[str] = None):
    """Request and execute once. Keep the returned IDs to recover an uncertain result."""
    import uuid
    idempotency_key = idempotency_key or str(uuid.uuid4())
    request_id = None
    headers = {'Authorization': f'Bearer {CONTO_API_KEY}', 'Content-Type': 'application/json'}
    try:
        response = requests.post(
            f'{CONTO_BASE_URL}/api/sdk/payments/request', headers=headers, timeout=30,
            json={'amount': amount, 'recipientAddress': recipient_address,
                  'purpose': purpose, **({'recipientName': recipient_name} if recipient_name else {}),
                  'category': 'OPERATIONS', 'idempotencyKey': idempotency_key}
        )
        request_data = response.json()
        request_id = request_data.get('requestId')
        if not response.ok:
            return {'success': False, 'requestId': request_id, 'idempotencyKey': idempotency_key,
                    'error': request_data.get('error'), 'uncertain': response.status_code >= 500}
        if request_data.get('status') != 'APPROVED' or not request_id:
            return {'success': False, 'requestId': request_id, 'idempotencyKey': idempotency_key,
                    'pending': request_data.get('status') == 'REQUIRES_APPROVAL',
                    'status': request_data.get('status'), 'reasons': request_data.get('reasons'),
                    'actionUrl': request_data.get('actionUrl')}

        execution = requests.post(f'{CONTO_BASE_URL}/api/sdk/payments/{request_id}/execute',
                                  headers=headers, timeout=30)
        result = execution.json()
        if not execution.ok:
            return {'success': False, 'requestId': request_id, 'idempotencyKey': idempotency_key,
                    'error': result.get('error'), 'checkStatus': True}
        receipt = result.get('receipt') or {}
        return {'success': result.get('status') == 'completed' and bool(receipt.get('transactionId')),
                'pending': result.get('status') == 'processing', 'status': result.get('status'),
                'requestId': request_id, 'idempotencyKey': idempotency_key, 'receipt': receipt,
                'transactionHash': receipt.get('txHash'), 'amount': result.get('amount'),
                'explorerUrl': receipt.get('explorerUrl')}
    except (requests.RequestException, ValueError, AttributeError):
        return {'success': False, 'uncertain': True, 'requestId': request_id,
                'idempotencyKey': idempotency_key,
                'message': 'Check the payment status before trying again.'}

Framework integrations

Each framework needs only its own tool wiring around the shared helper.

OpenAI (Responses API)

import OpenAI from 'openai';

const openai = new OpenAI();

const tools: OpenAI.Responses.FunctionTool[] = [
  {
    type: 'function',
    name: 'make_payment',
    description: 'Make a payment to a recipient',
    strict: false,
    parameters: {
      type: 'object',
      properties: {
        amount: { type: 'number', description: 'Payment amount in USD' },
        recipientAddress: { type: 'string', description: 'Recipient wallet address' },
        recipientName: { type: 'string', description: 'Recipient name' },
        purpose: { type: 'string', description: 'Payment purpose' },
      },
      required: ['amount', 'recipientAddress', 'purpose'],
    },
  },
];

async function runAgent(userMessage: string) {
  const response = await openai.responses.create({
    model: 'gpt-5',
    input: userMessage,
    tools,
  });

  const outputs: OpenAI.Responses.ResponseInputItem[] = [];
  for (const item of response.output) {
    if (item.type === 'function_call' && item.name === 'make_payment') {
      const result = await executeContoPayment(JSON.parse(item.arguments) as PaymentInput);
      outputs.push({ type: 'function_call_output', call_id: item.call_id, output: JSON.stringify(result) });
    }
  }
  if (outputs.length === 0) return response.output_text;

  // Send the payment result back so the model can report it.
  const followUp = await openai.responses.create({
    model: 'gpt-5',
    previous_response_id: response.id,
    input: outputs,
    tools,
  });
  return followUp.output_text;
}

Anthropic Claude (tool use)

import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic();

const tools: Anthropic.Tool[] = [
  {
    name: 'make_payment',
    description: 'Make a payment to a recipient using Conto',
    input_schema: {
      type: 'object',
      properties: {
        amount: { type: 'number', description: 'Payment amount in USD' },
        recipientAddress: { type: 'string', description: 'Recipient wallet address' },
        recipientName: { type: 'string', description: 'Recipient name' },
        purpose: { type: 'string', description: 'Payment purpose' },
      },
      required: ['amount', 'recipientAddress', 'purpose'],
    },
  },
];

async function runAgent(userMessage: string) {
  const response = await anthropic.messages.create({
    model: 'claude-opus-5',
    max_tokens: 1024,
    tools,
    messages: [{ role: 'user', content: userMessage }],
  });

  for (const block of response.content) {
    if (block.type === 'tool_use' && block.name === 'make_payment') {
      const result = await executeContoPayment(block.input as PaymentInput);
      // Continue conversation with tool result...
    }
  }
}

Python (any framework)

Register make_payment (defined above) as a tool in your framework of choice (CrewAI, AutoGen, or a custom loop) and return its dict result to the model as the tool output.

Server handlers

These handlers take payment requests on your own server. They are examples: add your own application authentication and authorization, and configure the recipient allowlist before you expose a payment route.

Validate before paying

Do not pass an untrusted request body directly to payments.pay(). Put authentication, local limits, a recipient allowlist, and a caller-supplied idempotency key in front of the SDK. Both handlers below use this helper:

parsePayment rejects the body unless the amount is positive and at most MAX_PAYMENT_AMOUNT (default 50), the recipient is an EVM address on PAYMENT_RECIPIENT_ALLOWLIST, and the purpose is 1 to 200 characters.
submitPayment asks Conto first. A denial returns 403, a payment waiting for approval returns 202, and any other status that is not APPROVED returns 409.
It executes only an approved request. After a timeout, a dropped connection, or a 408, 409, 429, or 5xx error, it reads the payment status instead of retrying.
mapPaymentError turns SDK errors into HTTP codes: 400 for validation errors, 409 for idempotency conflicts and insufficient balance, 503 for rate limits, and 502 for anything else.

// safe-payment.ts
import { Conto, ContoError, type PaymentRequestInput } from '@conto_finance/sdk';

const conto = new Conto({
  apiKey: process.env.CONTO_API_KEY!,
  timeout: 15_000,
});

const maxAmount = Number(process.env.MAX_PAYMENT_AMOUNT ?? '50');
if (!Number.isFinite(maxAmount) || maxAmount <= 0) {
  throw new Error('MAX_PAYMENT_AMOUNT must be a positive number');
}
const allowedRecipients = new Set(
  (process.env.PAYMENT_RECIPIENT_ALLOWLIST ?? '')
    .split(',')
    .map((address) => address.trim().toLowerCase())
    .filter(Boolean)
);

type PaymentCommand = Pick<PaymentRequestInput, 'amount' | 'recipientAddress' | 'purpose'>;

export function parsePayment(value: unknown): PaymentCommand {
  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
    throw new Error('Body must be an object');
  }
  const body = value as Record<string, unknown>;
  const address = typeof body.recipientAddress === 'string' ? body.recipientAddress : '';
  const purpose = typeof body.purpose === 'string' ? body.purpose.trim() : '';
  if (
    typeof body.amount !== 'number' ||
    !Number.isFinite(body.amount) ||
    body.amount <= 0 ||
    body.amount > maxAmount ||
    !/^0x[0-9a-fA-F]{40}$/.test(address) ||
    !allowedRecipients.has(address.toLowerCase()) ||
    purpose.length < 1 ||
    purpose.length > 200
  ) {
    throw new Error('Invalid amount, recipient, or purpose');
  }
  return { amount: body.amount, recipientAddress: address, purpose };
}

export async function submitPayment(input: PaymentCommand, idempotencyKey: string) {
  const request = await conto.payments.request({ ...input, idempotencyKey });

  if (request.status !== 'APPROVED') {
    const statusCode =
      request.status === 'DENIED' ? 403 : request.status === 'REQUIRES_APPROVAL' ? 202 : 409;
    return {
      statusCode,
      body: { requestId: request.requestId, status: request.status, reasons: request.reasons },
    };
  }

  try {
    const result = await conto.payments.execute(request.requestId);
    return {
      statusCode: result.status === 'processing' ? 202 : 200,
      body: result,
    };
  } catch (error) {
    const deterministicClientError =
      error instanceof ContoError &&
      error.status >= 400 &&
      error.status < 500 &&
      ![408, 409, 429].includes(error.status);
    if (deterministicClientError) throw error;

    // Execution may have succeeded before a timeout, connection drop, 429, or 5xx.
    const state = await conto.payments.status(request.requestId).catch(() => null);
    const transaction = state?.transaction;
    return {
      statusCode:
        transaction?.status === 'failed' ? 409 : transaction?.status === 'completed' ? 200 : 202,
      body: {
        requestId: request.requestId,
        status: transaction?.status ?? 'UNKNOWN',
        transaction,
        message: 'Execution result was reconciled. Do not retry execute blindly.',
      },
    };
  }
}

export function mapPaymentError(error: unknown) {
  if (error instanceof ContoError) {
    let statusCode = 502;
    if (error.code === 'VALIDATION_ERROR') statusCode = 400;
    if (['IDEMPOTENCY_CONFLICT', 'INSUFFICIENT_BALANCE'].includes(error.code)) statusCode = 409;
    if (error.code === 'RATE_LIMITED') statusCode = 503;
    return { statusCode, body: { error: error.code } };
  }
  return { statusCode: 502, body: { error: 'PAYMENT_SERVICE_ERROR' } };
}

Set PAYMENT_RECIPIENT_ALLOWLIST to comma-separated EVM addresses and MAX_PAYMENT_AMOUNT to your application-level cap.

Express

Connect the helper to an authenticated and authorized Express route. The middleware must verify a user or service identity, enforce your application’s payment-operator permission, and set res.locals.subject. Replace the sample import with your implementation.

// app.ts
import { createHash } from 'node:crypto';
import express from 'express';
import { requirePaymentOperator } from './auth';
import { mapPaymentError, parsePayment, submitPayment } from './safe-payment';

const app = express();
app.use(express.json({ limit: '16kb' }));

app.post('/payments/submit', requirePaymentOperator, async (req, res) => {
  const callerKey = req.get('Idempotency-Key');
  if (!callerKey || !/^[A-Za-z0-9:_-]{8,64}$/.test(callerKey)) {
    return res.status(400).json({ error: 'A stable Idempotency-Key is required' });
  }

  let payment: ReturnType<typeof parsePayment>;
  try {
    payment = parsePayment(req.body);
  } catch {
    return res.status(400).json({ error: 'Invalid payment request' });
  }

  const subject = res.locals.subject;
  if (typeof subject !== 'string' || !subject) {
    return res.status(401).json({ error: 'Unauthorized' });
  }
  const idempotencyKey = createHash('sha256').update(`${subject}:${callerKey}`).digest('hex');

  try {
    const response = await submitPayment(payment, idempotencyKey);
    return res.status(response.statusCode).json(response.body);
  } catch (error) {
    const response = mapPaymentError(error);
    return res.status(response.statusCode).json(response.body);
  }
});

Serverless (AWS Lambda)

Put this function behind an API Gateway JWT authorizer and require your application’s own payments:create scope on the route. The handler also checks that scope, rejects requests without a verified subject, validates and caps the body, requires idempotency, and uses the same recipient allowlist and error mapping as the Express route.

import { createHash } from 'node:crypto';
import { mapPaymentError, parsePayment, submitPayment } from './safe-payment';

export const handler = async (event: any) => {
  const claims = event.requestContext?.authorizer?.jwt?.claims;
  const subject = claims?.sub;
  if (typeof subject !== 'string' || !subject) {
    return { statusCode: 401, body: JSON.stringify({ error: 'Unauthorized' }) };
  }

  const scopes = typeof claims.scope === 'string' ? claims.scope.split(/\s+/) : [];
  if (!scopes.includes('payments:create')) {
    return { statusCode: 403, body: JSON.stringify({ error: 'Forbidden' }) };
  }

  const callerKey = event.headers?.['idempotency-key'] ?? event.headers?.['Idempotency-Key'];
  if (typeof callerKey !== 'string' || !/^[A-Za-z0-9:_-]{8,64}$/.test(callerKey)) {
    return {
      statusCode: 400,
      body: JSON.stringify({ error: 'A stable Idempotency-Key is required' }),
    };
  }

  const rawBody = event.isBase64Encoded
    ? Buffer.from(event.body ?? '', 'base64').toString('utf8')
    : (event.body ?? '');
  if (rawBody.length > 16_384) {
    return { statusCode: 413, body: JSON.stringify({ error: 'Request body too large' }) };
  }

  let payment: ReturnType<typeof parsePayment>;
  try {
    payment = parsePayment(JSON.parse(rawBody));
  } catch {
    return { statusCode: 400, body: JSON.stringify({ error: 'Invalid payment request' }) };
  }

  const idempotencyKey = createHash('sha256').update(`${subject}:${callerKey}`).digest('hex');
  try {
    const response = await submitPayment(payment, idempotencyKey);
    return { statusCode: response.statusCode, body: JSON.stringify(response.body) };
  } catch (error) {
    const response = mapPaymentError(error);
    return { statusCode: response.statusCode, body: JSON.stringify(response.body) };
  }
};

Register an agent in an existing organization

If an organization owner has already invited your agent, register it with the owner’s registration token instead of creating a sandbox. A GET request lists the required fields:

curl -sS https://conto.finance/api/agents/register

Post the token to join the organization and receive a scoped SDK key:

curl -sS -X POST https://conto.finance/api/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "registrationToken": "registration_token_from_human_owner",
    "name": "Research Buyer Agent",
    "agentType": "CUSTOM",
    "externalId": "research-buyer-prod",
    "callbackUrl": "https://agent.example.com/webhooks/conto"
  }'

The key has two scopes. With payments:request the agent calls POST /api/sdk/payments/request, which returns a policy decision. With agents:read it reads its own setup with GET /api/sdk/setup and GET /api/sdk/agents/me. Setup includes the agent’s wallet balances, limits, and policy rules even though the key has no wallets:read or policies:read. The key has no payments:execute, payments:approve, or payments:confirm, and it cannot change policies, create keys, or read other agents. An organization owner issues keys with more scopes. See Keys and scopes. Read the agent’s setup with the new key:

curl -sS https://conto.finance/api/sdk/setup \
  -H "Authorization: Bearer $CONTO_API_KEY"

externalId is optional but recommended: it makes retries idempotent and gives your system a durable reconciliation key. The registration response confirms the agent status, granted scopes, credential expiration, and the SDK endpoints that credential can call. It shows the SDK key only on the first successful registration. Registering the same externalId again returns the existing agent and credential reference without revealing the key. A retry never changes the key’s scopes. A key registered before agents:read was included has only payments:request. For that key, GET /api/sdk/setup returns 403 with code: "INSUFFICIENT_SCOPE", requiredScope: "agents:read", actor: "owner", and a nextAction. A registration retry returns the same fields in remediation and leaves setup out of endpoints. Conto never adds scopes to an existing key. An organization owner generates a new key for the agent and revokes the old one.

Handle errors

HTTP errors carry a code such as VALIDATION_ERROR, AUTH_FAILED, INSUFFICIENT_SCOPE or RATE_LIMITED. A 5xx or a timeout leaves the outcome unknown, so look up the request status before retrying execution or creating another payment. See error handling for every code. Policy denials are not HTTP errors. /api/sdk/payments/request returns 200 with status: "DENIED" and a reasons array of fixed messages. Rule names and limits appear only in the dashboard.

Next steps

Send a payment

Every payment method and response shape

Track and recover a payment

Check status and recover an uncertain result

Webhooks

Receive approval and payment events

Recipes

Curl snippets for payments, policies, x402, MPP, and monitoring

Get started

Integrate

Payments

Conto Commerce

Spending controls

Operate

Conto Pay

Code examples

SDK examples

One-call payment

Approval-aware payment

Setup check

The shared payment helper

Framework integrations

OpenAI (Responses API)

Anthropic Claude (tool use)

Python (any framework)

Server handlers

Validate before paying

Express

Serverless (AWS Lambda)

Register an agent in an existing organization

Handle errors

Next steps

Send a payment

Track and recover a payment

Webhooks

Recipes

​SDK examples

​One-call payment

​Approval-aware payment

​Setup check

​The shared payment helper

​Framework integrations

​OpenAI (Responses API)

​Anthropic Claude (tool use)

​Python (any framework)

​Server handlers

​Validate before paying

​Express

​Serverless (AWS Lambda)

​Register an agent in an existing organization

​Handle errors

​Next steps

Send a payment

Track and recover a payment

Webhooks

Recipes

SDK examples

One-call payment

Approval-aware payment

Setup check

The shared payment helper

Framework integrations

OpenAI (Responses API)

Anthropic Claude (tool use)

Python (any framework)

Server handlers

Validate before paying

Express

Serverless (AWS Lambda)

Register an agent in an existing organization

Handle errors

Next steps