x402 Seller Balance, Withdrawal, and Proof Verification

Three complementary endpoints power the seller side of the x402 protocol on FlareHQ. Use GET /api/x402/seller/balance to monitor your accumulated earnings from the Circle Gateway and your on-chain USDC wallet, POST /api/x402/seller/balance/withdraw to pull those funds to any address on Arc testnet or a supported destination chain, and POST /api/x402/verify to cryptographically validate a buyer’s payment proof before granting access to your upstream service. All three endpoints require a merchant Bearer token in the Authorization header.

GET /api/x402/seller/balance

Retrieve your current USDC earnings split across two buckets: your Gateway balance (payments collected but not yet withdrawn) and your on-chain wallet balance (funds already withdrawn to your EOA or SCA). GET https://flarehq.xyz/api/x402/seller/balance

Query Parameters

string

The seller wallet address to inspect. Defaults to the address linked to your merchant account if omitted.

Response

object

Your on-chain USDC wallet state, read directly from the Arc testnet USDC contract (0x3600000000000000000000000000000000000000).

Show wallet fields

string

On-chain USDC balance as a human-readable decimal string (e.g. "12.500000").

object

Your Circle Gateway balance — x402 payments collected but not yet withdrawn.

Show gateway fields

string

Sum of available and withdrawing, as a decimal string.

string

Balance immediately available to withdraw.

string

Amount currently in-flight in a pending withdrawal.

string

Amount eligible to initiate a withdrawal.

Example

curl -X GET "https://flarehq.xyz/api/x402/seller/balance" \
  -H "Authorization: Bearer fhq_sec_..."

const res = await fetch("https://flarehq.xyz/api/x402/seller/balance", {
  headers: { Authorization: "Bearer fhq_sec_..." },
});
const { wallet, gateway } = await res.json();
console.log(`On-chain: ${wallet.balance} USDC | Gateway: ${gateway.available} USDC`);

Response

{
  "wallet": {
    "balance": "12.500000"
  },
  "gateway": {
    "total": "37.250000",
    "available": "35.000000",
    "withdrawing": "2.250000",
    "withdrawable": "35.000000"
  }
}

POST /api/x402/seller/balance/withdraw

Withdraw your accumulated Gateway earnings to a wallet address. Supports same-chain Arc testnet withdrawals (instant) and cross-chain withdrawals to supported destination chains via Circle’s bridging infrastructure. POST https://flarehq.xyz/api/x402/seller/balance/withdraw

Body Parameters

string

required

Amount of USDC to withdraw, as a decimal string (e.g. "10.5"). The value must not exceed your gateway.withdrawable balance.

string

Target chain for the withdrawal. Defaults to "arcTestnet" for a same-chain transfer. Pass another supported Circle chain identifier for cross-chain bridging.

string

Recipient wallet address on the destination chain. Defaults to the seller address tied to your API key if omitted.

Response

boolean

true when the withdrawal transaction was confirmed on-chain.

string

Arc testnet transaction hash for the withdrawal.

string

Human-readable USDC amount that was withdrawn (e.g. "10.500000").

string

The chain from which funds were withdrawn (always arcTestnet for the Gateway).

string

The chain where funds were sent.

string

The address that received the withdrawal.

string

Confirmation state. Returns "confirmed" on success.

string

Direct link to the transaction on ArcScan (e.g. https://testnet.arcscan.app/tx/0x...).

Example

curl -X POST https://flarehq.xyz/api/x402/seller/balance/withdraw \
  -H "Authorization: Bearer fhq_sec_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "10.5",
    "destinationChain": "arcTestnet",
    "destinationAddress": "0xYourWalletAddress"
  }'

const res = await fetch(
  "https://flarehq.xyz/api/x402/seller/balance/withdraw",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer fhq_sec_...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      amount: "10.5",
      destinationChain: "arcTestnet",
      destinationAddress: "0xYourWalletAddress",
    }),
  }
);
const result = await res.json();
console.log(result.explorerUrl);

Response

{
  "success": true,
  "txHash": "0xabc123def456...",
  "amount": "10.500000",
  "sourceChain": "arcTestnet",
  "destinationChain": "arcTestnet",
  "recipient": "0xYourWalletAddress",
  "status": "confirmed",
  "explorerUrl": "https://testnet.arcscan.app/tx/0xabc123def456..."
}

Withdrawals are irreversible once confirmed on-chain. Double-check destinationAddress before calling this endpoint — FlareHQ cannot recover funds sent to the wrong address.

POST /api/x402/verify

Verify a buyer’s payment proof server-side without executing the upstream proxy call. Use this when you want to gate access to your own infrastructure and handle the upstream request yourself, rather than letting FlareHQ proxy it. POST https://flarehq.xyz/api/x402/verify

Body Parameters

string

required

The X-402-Payment-Proof value sent by the buyer. This is the same Circle Nanopayment authorization proof used in /api/x402/pay.

Response

boolean

true when the proof was successfully validated.

boolean

true if the payment settled successfully on Arc testnet. false if the proof is expired, malformed, or references an insufficient amount.

string

The USDC amount covered by this proof, as a decimal string.

string

On-chain address of the buyer who generated the proof.

number

Unix timestamp (seconds) when the proof was issued. Proofs are time-bounded — reject any proof where timestamp is more than 60 seconds in the past.

Example

curl -X POST https://flarehq.xyz/api/x402/verify \
  -H "Authorization: Bearer fhq_sec_..." \
  -H "Content-Type: application/json" \
  -d '{
    "proof": "0x402_proof_..."
  }'

const res = await fetch("https://flarehq.xyz/api/x402/verify", {
  method: "POST",
  headers: {
    Authorization: "Bearer fhq_sec_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ proof: "0x402_proof_..." }),
});

const { valid, amount, payer, timestamp } = await res.json();

if (!valid) {
  return Response.json({ error: "Invalid payment" }, { status: 402 });
}

// Proof is valid — serve your content

Response (valid proof)

{
  "success": true,
  "valid": true,
  "amount": "0.001000",
  "payer": "0xBuyer1234...",
  "timestamp": 1718000000
}

Response (invalid proof)

{
  "success": true,
  "valid": false,
  "amount": "0.000000",
  "payer": "0x0000000000000000000000000000000000000000",
  "timestamp": 0
}

Use /api/x402/verify when you self-host your upstream API and want to check payment before responding — without routing traffic through FlareHQ. Use /api/x402/pay when you want FlareHQ to both verify and proxy the upstream call in one step.

Overview

Payments

Escrow

Streaming

x402

Agents

x402 Seller Balance, Withdrawal, and Proof Verification

GET /api/x402/seller/balance

Query Parameters

Response

Example

POST /api/x402/seller/balance/withdraw

Body Parameters

Response

Example

POST /api/x402/verify

Body Parameters

Response

Example

​GET /api/x402/seller/balance

​Query Parameters

​Response

​Example

​POST /api/x402/seller/balance/withdraw

​Body Parameters

​Response

​Example

​POST /api/x402/verify

​Body Parameters

​Response

​Example

GET /api/x402/seller/balance

Query Parameters

Response

Example

POST /api/x402/seller/balance/withdraw

Body Parameters

Response

Example

POST /api/x402/verify

Body Parameters

Response

Example