Skip to main content
POST
Create an x402 spend mandate (BETA)

Authorizations

x-api-key
string
header
required

Headers

x-idempotency-key
string<uuid>
required

Unique key to ensure request idempotency. If the same key is used within a certain time window, the original response will be returned instead of executing the request again.

Path Parameters

payment_agent_id
string
required

Body

application/json
asset
string
required

Asset symbol. Only USDC is supported in this release; any other value is refused with a 400, since such a mandate could never be used.

network
string
required

Network the mandate covers, e.g. base-sepolia. Only Base and Base Sepolia are supported.

max_per_call
string
required

Per-authorization ceiling, in atomic units.

max_per_window
string

Ceiling on total committed spend across ALL payees in one rolling window, in atomic units. Omit for unbounded (discouraged).

window_seconds
integer

Rolling aggregate window. Defaults to 24h.

max_calls_per_window
integer

Optional cap on authorizations per window. 0 is no cap.

valid_for_seconds
integer

Mandate lifetime from now. Defaults to 30 days.

payee_policy
object

What an x402 mandate may pay for, beyond its budget. Omit the whole object to leave the budget as the only control. mode is required when the object is present, and the list must match it: address_allowlist needs addresses and reads no domains, domain_allowlist needs domains and reads no addresses, and any_screened enforces neither, so it carries no list. A policy that breaks those rules is refused with a 400 rather than stored as a restriction nothing applies. any_screened accepts any payee that passes address screening. address_allowlist pins the payee address itself. domain_allowlist pins the RESOURCE host the caller names when it asks for a signature - the readable form, since an operator approves "any metered API under this vendor's domain" rather than a hex address. Note that it bounds the resource, not the payee: a seller who prices one resource can be paid for it whatever address it nominates.

Response

Mandate created

id
string
required
agent_id
string
required
wallet_id
string
required
asset
string
required
network
string
required
max_per_call
string
required
window_seconds
integer
required
payee_policy
object
required

What an x402 mandate may pay for, beyond its budget. Omit the whole object to leave the budget as the only control. mode is required when the object is present, and the list must match it: address_allowlist needs addresses and reads no domains, domain_allowlist needs domains and reads no addresses, and any_screened enforces neither, so it carries no list. A policy that breaks those rules is refused with a 400 rather than stored as a restriction nothing applies. any_screened accepts any payee that passes address screening. address_allowlist pins the payee address itself. domain_allowlist pins the RESOURCE host the caller names when it asks for a signature - the readable form, since an operator approves "any metered API under this vendor's domain" rather than a hex address. Note that it bounds the resource, not the payee: a seller who prices one resource can be paid for it whatever address it nominates.

valid_from
string<date-time>
required
valid_until
string<date-time>
required
max_per_window
string
max_calls_per_window
integer
revoked_at
string<date-time>
window_committed
string

Spend already committed in the current window, in atomic units. Counts outstanding holds as well as settled ones.

window_calls
integer

Authorizations already issued in the current window.