x402 EOA Wallet API — Info & Deposit

Every FlareHQ merchant gets a dedicated x402 buyer EOA (externally owned account) on Arc Mainnet, auto-provisioned the first time it is needed. This wallet holds your USDC and pays x402 invoices through the Circle Gateway — you need it funded before calling POST /api/x402/pay. The private key is encrypted at rest and is never returned by any endpoint; these routes only ever expose the public address and balances.

EOA Wallet Info

Returns the calling merchant’s x402 buyer wallet address and Gateway balances, creating the wallet on first call if it does not exist yet.

Endpoint

GET https://flarehq.xyz/api/x402/eoa-wallet/me

Request

Headers

Header	Value
`x-api-key`	`fhq_sec_test_...` — required, merchant API key

Alternatively, an authenticated dashboard session (merchant_token cookie) is accepted.

Response

boolean

true when wallet info was returned.

string

The merchant’s x402 EOA wallet address on Arc Mainnet (e.g. 0xAbCd...1234). Auto-provisioned on first call if it does not exist.

string

Available USDC balance in the Circle Gateway, as a formatted decimal string (e.g. "10.500000"). This is the balance used to pay x402 invoices.

string

On-chain USDC balance of the EOA wallet itself, as a formatted decimal string (e.g. "0.000000").

Examples

curl https://flarehq.xyz/api/x402/eoa-wallet/me \
  -H "x-api-key: fhq_sec_test_..."

const res = await fetch('https://flarehq.xyz/api/x402/eoa-wallet/me', {
  headers: { 'x-api-key': 'fhq_sec_test_...' },
});
const { address, gatewayBalance, walletBalance } = await res.json();
console.log(`Gateway: ${gatewayBalance} USDC available to spend`);

Success Response

{
  "success": true,
  "address": "0xAbCd1234ef5678901234AbCd1234ef5678901234",
  "gatewayBalance": "10.500000",
  "walletBalance": "0.000000"
}

Error Responses

{
  "success": false,
  "error": "Authentication required."
}

Notes

If a balance cannot be fetched (for example the Gateway API is temporarily unavailable), the endpoint still returns success: true with "0" balances rather than failing the request. The wallet itself is still created and reported.

The wallet’s private key is encrypted at rest with AES-256-GCM and is never included in any API response. Only the public address is ever returned.

Deposit to Gateway

Funds the calling merchant’s own x402 Gateway by moving USDC from the EOA wallet into the Circle Gateway. After depositing, the balance is spendable via POST /api/x402/pay.

Endpoint

POST https://flarehq.xyz/api/x402/eoa-wallet/deposit

Request

Headers

Header	Value
`x-api-key`	`fhq_sec_test_...` — required, merchant or service API key
`Content-Type`	`application/json` — required

Alternatively, an authenticated dashboard session (merchant_token cookie) is accepted.

Body Parameters

string

required

Amount of USDC to deposit, as a decimal string (e.g. "10.5", "1.000000"). Up to 6 decimal places of precision are supported. Do not pass raw atomic units.

Response

boolean

true when the deposit settled on-chain.

string

On-chain transaction hash of the deposit to the Gateway contract. Verify on Arc Explorer.

string | null

Transaction hash of the ERC-20 USDC approval transaction, or null if the existing allowance already covered the deposit.

string

Amount deposited, as a formatted USDC decimal string (e.g. "10.500000").

string

Ready-to-open Arc Explorer URL for the deposit transaction: https://explorer.arc.io/tx/{depositTxHash}.

string

Human-readable confirmation — "Deposited 10.500000 USDC into Gateway for 0xAbCd...1234."

Examples

curl -X POST https://flarehq.xyz/api/x402/eoa-wallet/deposit \
  -H "x-api-key: fhq_sec_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "amount": "10.5" }'

const res = await fetch('https://flarehq.xyz/api/x402/eoa-wallet/deposit', {
  method: 'POST',
  headers: {
    'x-api-key': 'fhq_sec_test_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ amount: '10.5' }),
});

const { success, amountDeposited, explorerUrl } = await res.json();
console.log(`Deposited ${amountDeposited} USDC — ${explorerUrl}`);

Success Response

{
  "success": true,
  "depositTxHash": "0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890",
  "approvalTxHash": null,
  "amountDeposited": "10.500000",
  "explorerUrl": "https://explorer.arc.io/tx/0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890",
  "message": "Deposited 10.500000 USDC into Gateway for 0xAbCd1234ef5678901234AbCd1234ef5678901234."
}

Error Responses

{
  "success": false,
  "error": "Missing amount"
}

{
  "success": false,
  "error": "Authentication required."
}

Notes

For Arc Testnet development only: deposits require the EOA wallet to hold test USDC first. Get test USDC at faucet.circle.com and select ARC-TESTNET, then send it to your wallet address from GET /api/x402/eoa-wallet/me. Production deposits use real USDC on Arc Mainnet.

The EOA wallet’s USDC is tracked separately from its Gateway balance. The Gateway deposit moves USDC from the wallet into the Gateway’s batching contract, where it becomes immediately spendable for x402 payments.

A deposit performs two on-chain transactions — an ERC-20 approve (only when the allowance is insufficient, reported in approvalTxHash) and the deposit itself. Both must be included in the wallet’s transaction history; check approvalTxHash if a deposit appears to fail partway.

Overview

Payments

Escrow

Streaming

CCTP Bridge

Checkout

x402

Agents

Jobs

Merchant

Consumer

Payroll

x402 EOA Wallet API — Info & Deposit

EOA Wallet Info

Endpoint

Request

Headers

Response

Examples

Success Response

Error Responses

Notes

Deposit to Gateway

Endpoint

Request

Headers

Body Parameters

Response

Examples

Success Response

Error Responses

Notes

​EOA Wallet Info

​Endpoint

​Request

​Headers

​Response

​Examples

​Success Response

​Error Responses

​Notes

​Deposit to Gateway

​Endpoint

​Request

​Headers

​Body Parameters

​Response

​Examples

​Success Response

​Error Responses

​Notes

EOA Wallet Info

Endpoint

Request

Headers

Response

Examples

Success Response

Error Responses

Notes

Deposit to Gateway

Endpoint

Request

Headers

Body Parameters

Response

Examples

Success Response

Error Responses

Notes