Pay with x402#

Use this when an agent calls a service that responds with HTTP 402 Payment Required and x402 payment requirements.

Prerequisites#

A Hightop agent with API-key credentials.
An approved owner account. New or unapproved test accounts may be rejected even with valid agent credentials.
A service that accepts x402 payments on Base.
The service's payTo address and required USDC amount.

Sign the Payment#

x402 amount is USDC base units with 6 decimals. "1000000" means 1 USDC.

curlrequest

curl -sS https://api.hightop.com/api/actions/x402/sign \
  -H "content-type: application/json" \
  -H "x-agent-id: $HIGHTOP_AGENT_ID" \
  -H "x-api-key: $HIGHTOP_API_KEY" \
  -d '{
    "payTo": "0x0000000000000000000000000000000000000000",
    "amount": "1000000",
    "targetUrl": "https://example.com/paid-api",
    "maxTimeoutSeconds": 300,
    "idempotencyKey": "x402-payment-001"
  }'

The response includes paymentHeader. Attach it to the retry request according to the paid service's x402 instructions.

Optional TypeScript SDK Shape#

typescriptexample

const signed = await client.actions.x402.sign({
  payTo: '0x0000000000000000000000000000000000000000',
  amount: 1000000n,
  targetUrl: 'https://example.com/paid-api',
  maxTimeoutSeconds: 300,
  idempotencyKey: 'x402-payment-001',
})

The SDK serializes the BigInt amount for this route. If you call the route with raw JSON, send amount as a string-compatible integer as shown in the curl example.

Follow Up#

x402 signing creates Hightop Activity and a pending x402 payment record. A settlement task later marks it settled or expired. It does not return an AgentOperation.

Likely errors: invalid address, invalid amount, insufficient USDC available to top up the signer EOA, signing failure, auth failure.