/payments

POST/v1/agent/payments

Create a payment operation

Requires API-key authentication (agentAuth, agentId).

Purpose: create a payment operation to an active recurring-payment recipient, active one-off payment, or currently trusted destination.

Auth and scope: header-key auth or OAuth agent:payments:write.

Idempotency: required.

Request:

json

example

{
  "to": "recipient id, address, or handle",
  "asset": "USDC",
  "amount": "1",
  "deliver_as": "auto",
  "prefer": "auto",
  "note": null,
  "slippage_percent": 1
}

Use exactly one of amount or amount_usd. amount is a decimal asset-unit string. For USDC, "1" means 1 USDC.

Use this endpoint directly when an agent needs to pay an approved vendor or service. Do not call earn/withdraw or a withdrawal route first. When the agent's onchain lane allows the required payment and Earn pre-actions, the payment execution path can source from wallet balance and Earn positions.

Fields:

Field	Type	Required
`to`	nonempty string	Yes
`asset`	nonempty string	Yes
`amount`	positive decimal string	One of `amount` or `amount_usd`
`amount_usd`	positive decimal string	One of `amount` or `amount_usd`
`deliver_as`	`auto`, `one_off_payment`, `recurring_payment`, or `trusted_destination`	No
`prefer`	same values as `deliver_as`; defaults to `auto`	No
`note`	string up to 500 chars, `null`, or omitted	No
`slippage_percent`	number from 0 inclusive to 100 exclusive	No

Current v1 execution rejects unsupported modifiers it cannot honor. Omit note unless you have confirmed support for the specific payment path.

Response:

json

example

{
  "ok": true,
  "operation_id": "uuid",
  "status": "submitted",
  "resource": {
    "type": "payment",
    "id": "uuid"
  },
  "fee_usd": "0",
  "human_message": "string"
}

Common errors: recipient_not_allowed, permission_not_granted, asset_not_allowed, limit_exceeded, insufficient_funds, validation_failed, idempotency_key_reuse_mismatch, idempotency_request_in_progress.

Related recipe: Pay a Vendor.