Pay with x402#

Use this when an agent calls a service that responds with HTTP 402 Payment Required and x402 payment requirements. This recipe uses the Agent API v1 /v1/agent/x402/* routes. See x402 Payments for the full reference.

Prerequisites#

A Hightop agent with API-key credentials (or an OAuth token with agent:payments:write).
An approved owner account.
A service that accepts x402 payments on Base.

Amounts are USDC base-unit integer strings (6 decimals): "1000000" means 1 USDC.

Option A — one-shot purchase#

purchase fetches the URL, satisfies the x402 challenge, and returns the upstream response. Requires an idempotency key and returns an operation.

curl

request

curl -sS https://api.hightop.com/v1/agent/x402/purchase \
  -H "content-type: application/json" \
  -H "x-agent-id: $HIGHTOP_AGENT_ID" \
  -H "x-api-key: $HIGHTOP_API_KEY" \
  -H "Idempotency-Key: x402-$(uuidgen)" \
  -d '{ "url": "https://example.com/paid-api", "max_amount": "1000000", "method": "GET" }'

The response includes operation_id, paid, seller_accepted, settled, and the upstream response. Poll operation_id to a terminal status if you need to confirm settlement.

Option B — sign, then retry yourself#

sign returns a payment header you attach to your own retry of the seller request.

curl

request

curl -sS https://api.hightop.com/v1/agent/x402/sign \
  -H "content-type: application/json" \
  -H "x-agent-id: $HIGHTOP_AGENT_ID" \
  -H "x-api-key: $HIGHTOP_API_KEY" \
  -H "Idempotency-Key: x402-$(uuidgen)" \
  -d '{ "target_url": "https://example.com/paid-api", "pay_to": "0x...", "amount": "1000000" }'

The response includes payment_header (and payment_header_name / payment_headers). Attach the header(s) to your retry of the paid request per the service's x402 instructions.

Optional — quote first#

quote reports the price without paying (read-only, no idempotency key):

curl

request

curl -sS https://api.hightop.com/v1/agent/x402/quote \
  -H "x-agent-id: $HIGHTOP_AGENT_ID" -H "x-api-key: $HIGHTOP_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "url": "https://example.com/paid-api" }'

Follow up#

sign and purchase are operation-backed: poll operation_id to a terminal status, and handle the stable error codes. Likely errors: invalid address/amount, insufficient USDC to cover the payment, signing failure, auth failure.

A pre-v1 POST /api/actions/x402/sign action route still exists (camelCase fields, body-level idempotencyKey, no AgentOperation) — see x402 Payments. Prefer the v1 routes above.