Execute an x402 Micro-Payment — POST /api/x402/pay

The /api/x402/pay endpoint is the core of the FlareHQ x402 protocol. You send a payment proof alongside the details of the upstream API you want to call — FlareHQ verifies the proof, settles USDC on Arc testnet, and returns the proxied response from the upstream API in a single round-trip. No pre-registration is required on the buyer side; the payment proof itself acts as your authorisation.

This endpoint does not require an Authorization header. The paymentProof field (or the X-402-Payment-Proof request header) serves as the sole authentication mechanism for the buyer.

Request

POST https://flarehq.xyz/api/x402/pay

Headers

Header	Required	Description
`Content-Type`	Yes	Must be `application/json`
`X-Agent-ID`	No	ERC-8004 agent identifier (`8004:5042002:{tokenId}`). Marks the payment as agent-originated.
`X-Agent-Signature`	No	EIP-712 signed timestamp proving the agent wallet controls this request.
`X-402-Payment-Proof`	No	Alternative to passing `paymentProof` in the request body.

Body Parameters

string

required

The marketplace listing slug that identifies which upstream API to call and what price to charge. Example: "solana-whale-tracker".

string

required

HTTP method to use when forwarding the request to the upstream API. Accepted values: GET, POST, PUT, PATCH, DELETE.

string

required

Circle Nanopayment authorization proof. This value is verified on-chain before the upstream call is made. Can alternatively be passed via the X-402-Payment-Proof request header.

object

Query parameters or body fields to forward to the upstream API. The object is passed verbatim — FlareHQ does not transform keys or values.

Show Example params object

{
  "minVolume": "100000",
  "token": "SOL",
  "limit": 50
}

string

ERC-8004 agent identifier in the format 8004:{chainId}:{tokenId}. On Arc testnet this looks like 8004:5042002:1042. Providing this ties the payment record to the agent’s on-chain identity. Also accepted via the X-Agent-ID header.

Response

200 — Success

boolean

true when the payment was accepted and the upstream API returned a successful response.

object

The full response body returned by the upstream API, passed through without modification.

object

On-chain settlement details for the payment.

Show settlement fields

string

Arc testnet transaction hash for the USDC settlement. Verify on ArcScan.

string

USDC amount paid, as a human-readable decimal string (e.g. "0.001000").

string

Echo of the slug you provided, confirming which listing was charged.

400 — Bad Request

Returned when slug, method, or a valid paymentProof is missing, or when the buyer’s Gateway balance is insufficient to cover the listing price.

{
  "success": false,
  "error": "No Gateway balance. Deposit USDC to your Gateway account before making x402 payments.",
  "walletBalance": "0.000000",
  "gatewayBalance": "0"
}

500 — Server Error

Returned when the upstream API call fails or an internal error occurs.

{
  "success": false,
  "error": "Upstream API returned 503"
}

Examples

curl -X POST https://flarehq.xyz/api/x402/pay \
  -H "Content-Type: application/json" \
  -H "X-Agent-ID: 8004:5042002:1042" \
  -d '{
    "slug": "solana-whale-tracker",
    "method": "GET",
    "params": { "minVolume": "100000" },
    "paymentProof": "0x402_proof_..."
  }'

const response = await fetch("https://flarehq.xyz/api/x402/pay", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Agent-ID": "8004:5042002:1042",
  },
  body: JSON.stringify({
    slug: "solana-whale-tracker",
    method: "GET",
    params: { minVolume: "100000" },
    paymentProof: "0x402_proof_...",
  }),
});

const result = await response.json();
console.log(result.settlement.txHash);

import requests

resp = requests.post(
    "https://flarehq.xyz/api/x402/pay",
    headers={
        "Content-Type": "application/json",
        "X-Agent-ID": "8004:5042002:1042",
    },
    json={
        "slug": "solana-whale-tracker",
        "method": "GET",
        "params": {"minVolume": "100000"},
        "paymentProof": "0x402_proof_...",
    },
)
print(resp.json()["settlement"]["txHash"])

Success Response

{
  "success": true,
  "data": {
    "whales": [
      { "address": "0xDe0B...6789", "balanceUSDC": "4200000.00" }
    ]
  },
  "settlement": {
    "txHash": "0xabc123def456...",
    "amount": "0.001000",
    "listingSlug": "solana-whale-tracker"
  }
}

Your Gateway account must be funded with USDC before calling this endpoint. On Arc testnet, get test USDC at faucet.circle.com and select ARC-TESTNET. Calls made with a zero Gateway balance will return HTTP 400.

Agent-Authenticated Payments

When an ERC-8004 agent makes a payment, include both X-Agent-ID and X-Agent-Signature in your request headers. The signature is an EIP-712 signed timestamp generated by the agent’s SCA wallet. FlareHQ links the payment to the agent’s on-chain identity, which feeds into its reputation score over time.

curl -X POST https://flarehq.xyz/api/x402/pay \
  -H "Content-Type: application/json" \
  -H "X-Agent-ID: 8004:5042002:1042" \
  -H "X-Agent-Signature: 0xd4e5f6..." \
  -d '{
    "slug": "defi-price-oracle",
    "method": "GET",
    "paymentProof": "0x402_proof_..."
  }'

The USDC contract on Arc testnet is 0x3600000000000000000000000000000000000000 (chain ID 5042002).

Overview

Payments

Escrow

Streaming

x402

Agents

Execute an x402 Micro-Payment — POST /api/x402/pay

Request

Headers

Body Parameters

Response

200 — Success

400 — Bad Request

500 — Server Error

Examples

Success Response

Agent-Authenticated Payments

​Request

​Headers

​Body Parameters

​Response

​200 — Success

​400 — Bad Request

​500 — Server Error

​Examples

​Success Response

​Agent-Authenticated Payments

Request

Headers

Body Parameters

Response

200 — Success

400 — Bad Request

500 — Server Error

Examples

Success Response

Agent-Authenticated Payments