Agent-to-agent payments

One registered agent requests a payment from another. The paying agent reviews and executes it, subject to its policies and wallet limits.

A2A endpoints enforce explicit API-key scopes: payments:request to create, payments:approve to approve or reject, payments:execute to settle, transactions:read to list or inspect, analytics:read for statistics, and wallets:read to resolve an address.

How it works

Requesting agent -> creates request -> target agent reviews -> target agent executes

Agent A calls POST /api/sdk/a2a/request
Agent B either receives a payment_request.created webhook or lists incoming requests via GET /api/sdk/a2a/requests
Agent B approves via POST /api/sdk/a2a/requests/{id}/approve or rejects via POST /api/sdk/a2a/requests/{id}/reject. If Agent B’s policy requires approval, a person in Agent B’s organization must approve it instead
Agent B executes the approved request via POST /api/sdk/a2a/requests/{id}/execute
The transfer still runs through Conto policy evaluation before settlement

Create a request

Identify the paying agent by targetAgentId or targetWalletAddress.

curl -X POST https://conto.finance/api/sdk/a2a/request \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "targetAgentId": "cmm5a0agt001m49h7bjqza22q",
    "amount": 50,
    "currency": "USDC",
    "purpose": "Reimbursement for API credits",
    "invoiceId": "INV-2026-001",
    "dueDate": "2026-08-01T00:00:00.000Z"
  }'

Response

{
  "success": true,
  "paymentRequest": {
    "id": "cmm5h1a2a001m49h7irxzh22q",
    "status": "review_required",
    "direction": "outgoing",
    "requestingAgent": {
      "id": "cmm59z8fj000l49h7bjqza11p",
      "name": "Purchasing Agent"
    },
    "requestedFromAgent": {
      "id": "cmm5a0agt001m49h7bjqza22q",
      "name": "DevOps Agent"
    },
    "amount": 50,
    "currency": "USDC",
    "purpose": "Reimbursement for API credits",
    "invoiceId": "INV-2026-001",
    "dueDate": "2026-08-01T00:00:00.000Z",
    "expiresAt": "2026-08-07T00:00:00.000Z",
    "links": {
      "details": "/api/sdk/a2a/requests/cmm5h1a2a001m49h7irxzh22q"
    }
  },
  "message": "Payment request sent to DevOps Agent"
}

If you pass targetWalletAddress, Conto resolves it to a registered agent first. Requests to unknown addresses are rejected.

List requests

GET /api/sdk/a2a/requests?direction=incoming&status=review_required&limit=50&offset=0

Lists the authenticated agent’s incoming and outgoing requests. The direction filter accepts incoming, outgoing, or all. List responses and detail responses (GET /api/sdk/a2a/requests/{id}) use these request statuses:

Status	Meaning
`review_required`	Waiting for the paying agent, or for a person when policy requires approval
`approved`	Approved and ready to execute
`declined`	Declined or cancelled
`processing`	Payment is in progress
`completed`	Payment completed successfully
`failed`	Payment processing failed
`expired`	The request expired

When a transaction is present, its status is processing, completed, or failed. When available, it includes the stable transaction ID, network, block number, hash, and explorer URL for reconciliation.

{
  "requests": [
    {
      "id": "cmm5h1a2a001m49h7irxzh22q",
      "status": "review_required",
      "direction": "incoming",
      "amount": 50,
      "currency": "USDC",
      "transaction": null,
      "links": {
        "details": "/api/sdk/a2a/requests/cmm5h1a2a001m49h7irxzh22q",
        "approve": "/api/sdk/a2a/requests/cmm5h1a2a001m49h7irxzh22q/approve",
        "reject": "/api/sdk/a2a/requests/cmm5h1a2a001m49h7irxzh22q/reject",
        "execute": null
      }
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Webhook-first automation

If the paying organization has a webhook URL, or the paying agent has a callback URL, Conto emits payment_request.created as soon as a new request is created. The payload targets the paying agent and includes:

paymentRequestId
requestingAgentId and requestingAgentName
amount, currency, purpose, invoiceId
approveUrl and rejectUrl

Approve or reject a request

The paying agent can approve a pending request before execution when its policies allow the payment outright:

curl -X POST https://conto.finance/api/sdk/a2a/requests/{id}/approve \
  -H "Authorization: Bearer $CONTO_API_KEY"

The response includes the request ID, approved status, and links.details and links.execute for the next call. An agent cannot approve a payment that its policy sends for human approval. In that case the request stays pending and the endpoint returns 403:

{
  "success": false,
  "error": "The payer policy requires human approval for this payment. The request stays pending until an authorized member of the paying organization approves it while signed in to Conto.",
  "code": "HUMAN_APPROVAL_REQUIRED",
  "requestId": "cmm5h1a2a001m49h7irxzh22q",
  "status": "pending_human_approval",
  "links": { "details": "/api/sdk/a2a/requests/cmm5h1a2a001m49h7irxzh22q" }
}

An owner, admin, or manager of the paying organization then approves the request while signed in to Conto: open the paying agent in the dashboard, go to Transactions, and select Approve on the request under Payment requests. After a person approves, the agent can call the execute endpoint. The payments:approve scope does not let an agent clear a human approval step, and nobody can approve a payment that policy denies. To reject it, call the reject endpoint with an optional reason, which is stored with the request.

curl -X POST https://conto.finance/api/sdk/a2a/requests/{id}/reject \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "This invoice is missing the deployment reference"
  }'

Execute a request

The paying agent executes the approved request:

curl -X POST https://conto.finance/api/sdk/a2a/requests/{id}/execute \
  -H "Authorization: Bearer $CONTO_API_KEY"

The response includes the A2A request ID, transaction ID, customer-facing transaction status, and links to both records. Policy, including spend limits, approval rules, and counterparty rules, is checked again at execution. If it requires approval and no authorized person has approved the request, execution returns 403 with code: "HUMAN_APPROVAL_REQUIRED".

Resolve an agent from a wallet address

Returns isAgent, and when true, the agent’s id and name and the organization name.

curl "https://conto.finance/api/sdk/a2a/resolve?address=0x1234567890abcdef..." \
  -H "Authorization: Bearer $CONTO_API_KEY"

A2A statistics

GET /api/sdk/a2a/stats

API reference

Endpoint	Method	Description
`/api/sdk/a2a/request`	POST	Create an A2A payment request
`/api/sdk/a2a/requests`	GET	List A2A requests
`/api/sdk/a2a/requests/{id}`	GET	Get one request
`/api/sdk/a2a/requests/{id}/approve`	POST	Approve (policy must allow it)
`/api/sdk/a2a/requests/{id}/reject`	POST	Reject a pending request
`/api/sdk/a2a/requests/{id}/execute`	POST	Execute an approved request
`/api/sdk/a2a/resolve`	GET	Resolve an agent from a wallet address
`/api/sdk/a2a/stats`	GET	View A2A statistics

Get started

Integrate

Payments

Conto Commerce

Spending controls

Operate

Conto Pay

Agent-to-agent payments

How it works

Create a request

List requests

Webhook-first automation

Approve or reject a request

Execute a request

Resolve an agent from a wallet address

A2A statistics

API reference

​How it works

​Create a request

​List requests

​Webhook-first automation

​Approve or reject a request

​Execute a request

​Resolve an agent from a wallet address

​A2A statistics

​API reference

How it works

Create a request

List requests

Webhook-first automation

Approve or reject a request

Execute a request

Resolve an agent from a wallet address

A2A statistics

API reference