Accept Sub-Cent Nano Payments from Agents

Nano payments are sub-cent USDC charges recorded instantly in FlareHQ’s ledger and settled later in a single batched on-chain transfer. The payer — typically an autonomous agent — is charged per API call, per token, or per second of compute at amounts far too small to justify an individual on-chain transaction. Each charge is recorded in Postgres immediately (settled: false); when the accumulated balance for an agent↔merchant pair reaches the batch threshold, the whole batch is settled to the merchant in one transfer. This is the accounting engine behind the x402 protocol micro-payment model: x402 handles the per-request payment handshake, and nano payments handle the “record now, settle later” batching that makes sub-cent pricing viable onchain.

Use Cases

Per-API-Call Pricing

Charge 0.0001 USDC per request instead of forcing a subscription. Agents pay as they consume.

Token & Compute Billing

Meter LLM output per token or compute per second, with micro charges accumulated into a settleable batch.

Agent↔Merchant Ledger

Track every micro payment an agent makes to a service provider, then reconcile against a single on-chain settlement.

x402 Gateway Settlement

Batch the sub-cent Nanopayment authorizations collected by your x402 gateway into one transfer.

How Nano Payments Work

Record — Each micro charge is POSTed to /api/payments/nano and stored instantly with settled: false.
Track — The unsettled balance for each agent↔merchant pair accumulates. GET /api/payments/nano returns the live total, count, and whether it is ready to settle.
Batch — When the pair’s total reaches the threshold (1 USDC) or the batch age reaches the interval (60 seconds), the pair shouldSettle.
Settle — POST /api/payments/nano/settle locks the pending charges into a batch and transfers the total from the agent’s Circle wallet to the merchant in a single on-chain USDC transfer.

Recording a Nano Payment

REST API Parameters

string

required

The agent wallet being charged. This is the payer — the consumer of the service.

string

required

The merchant wallet receiving funds. This is the provider of the service.

string | number

required

Micro USDC amount, e.g. "0.0001". Must be greater than 0; values are stored and settled to 6 decimal places.

string

What the charge is for, e.g. "1 API call" or "100 tokens".

Tracking the Unsettled Balance

A record-only endpoint never moves funds — it just accumulates ledger entries. Check a pair’s live batch status any time:

curl "https://flarehq.xyz/api/payments/nano?agentSCA=0xAgentWallet...&merchantSCA=0xMerchantWallet..." \
  -H "x-api-key: fhq_sec_test_..."

{
  "success": true,
  "agentSCA": "0xAgentWallet...",
  "merchantSCA": "0xMerchantWallet...",
  "total": 0.4,
  "count": 400,
  "ageMs": 45000,
  "shouldSettle": false,
  "payments": [],
  "thresholdUSDC": 1
}

number

Total unsettled USDC for the pair, to 6 decimal places.

number

Number of unsettled nano payments for the pair.

number

Milliseconds since the oldest unsettled payment was recorded.

boolean

true when total >= 1 USDC or ageMs >= 60000 (60 seconds).

number

The batch settlement threshold, 1 USDC.

Settling a Batch

Once a pair is ready, settle it in a single on-chain transfer:

curl -X POST https://flarehq.xyz/api/payments/nano/settle \
  -H "x-api-key: fhq_sec_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agentSCA": "0xAgentWallet...",
    "merchantSCA": "0xMerchantWallet...",
    "webhookUrl": "https://yoursite.com/webhooks/payments"
  }'

If the pair’s unsettled total is below the threshold, the call returns HTTP 400 with the current balance and the amount still needed:

{
  "success": false,
  "error": "Threshold not reached. 0.400000/1 USDC.",
  "unsettledBalance": 0.4
}

Pass forceSettle: true to settle a pair below the threshold:

{
  "agentSCA": "0xAgentWallet...",
  "merchantSCA": "0xMerchantWallet...",
  "forceSettle": true
}

A successful settlement returns the batch reference, on-chain hash, and totals:

{
  "success": true,
  "batchRef": "nano_550e8400-e29b-41d4-a716-446655440000",
  "txHash": "0xabc123def456...",
  "explorerUrl": "https://explorer.arc.io/tx/0xabc123def456...",
  "total": 1.25,
  "count": 1250,
  "resumed": false,
  "totalSettled": 1.25,
  "paymentsCount": 1250
}

Batch Settlement Behavior

Pending charges are locked into the batch with a batchRef before the transfer begins, so concurrent settle calls cannot double-spend the same charges.
The agent’s Circle wallet must hold enough USDC to cover the batch total.
If a transfer is initiated but the on-chain confirmation stalls, the system resumes or rolls back the lock on a later call rather than losing track of the charges.
The agent must be registered in the agent registry with a Circle wallet before it can settle.

forceSettle and autoSettle

Parameter	Behavior
`forceSettle`	Settles the pair even when the total is below the 1 USDC threshold. Defaults to `false`.
`autoSettle`	Internal mode that processes all unsettled agent↔merchant pairs platform-wide. Requires an internal service API key — a normal merchant key receives `HTTP 403`.

For a normal merchant API key, the single-pair path also verifies that you control either the agentSCA or merchantSCA in the request before settling — otherwise HTTP 403.

Webhook Events

Event	Fired when
`nano.batch_settled`	A pair’s batch is confirmed onchain

{
  "event": "nano.batch_settled",
  "batchRef": "nano_550e8400-e29b-41d4-a716-446655440000",
  "agentSCA": "0xAgentWallet...",
  "merchantSCA": "0xMerchantWallet...",
  "totalSettled": 1.25,
  "paymentsCount": 1250,
  "txHash": "0xabc123def456...",
  "explorerUrl": "https://explorer.arc.io/tx/0xabc123def456...",
  "settledAt": "2026-08-16T10:00:00.000Z"
}

Nano Payments and x402

Nano payments are the settlement layer under the x402 protocol. x402 is the HTTP handshake — it returns a 402 with the sub-cent price, receives the payer’s signed payment authorization, and proxies the paid request to your API. Nano payments are the ledger: every x402 charge is recorded as a nanopayment instantly, then batched and settled on-chain once the accumulated balance reaches the threshold. The result is sub-cent pricing without per-call gas costs. Charge 0.001 or even 0.0005 USDC per request; settle hundreds or thousands of requests in one transfer.

USDC on Arc uses 6 decimal places (Mainnet USDC 0x3600000000000000000000000000000000000000). Record amounts to at most 6 decimal places, and fund the agent’s Circle wallet with USDC before settling — a settlement that fails on balance returns a hint to fund the agent SCA wallet.

Next Steps

See the Nano Payments API reference for full request and response schemas. Read the x402 overview to see how per-request payment handshakes produce the micro charges that nano payments batch and settle.

Get Started

Payments

x402 Protocol

Agentic Finance

Merchant Platform

Consumer Payments

Developer Guide

Accept Sub-Cent Nano Payments from Agents

Use Cases

Per-API-Call Pricing

Token & Compute Billing

Agent↔Merchant Ledger

x402 Gateway Settlement

How Nano Payments Work

Recording a Nano Payment

REST API Parameters

Tracking the Unsettled Balance

Settling a Batch

Batch Settlement Behavior

forceSettle and autoSettle

Webhook Events

Nano Payments and x402

Next Steps

​Use Cases

Per-API-Call Pricing

Token & Compute Billing

Agent↔Merchant Ledger

x402 Gateway Settlement

​How Nano Payments Work

​Recording a Nano Payment

​REST API Parameters

​Tracking the Unsettled Balance

​Settling a Batch

​Batch Settlement Behavior

​forceSettle and autoSettle

​Webhook Events

​Nano Payments and x402

​Next Steps

Use Cases

How Nano Payments Work

Recording a Nano Payment

REST API Parameters

Tracking the Unsettled Balance

Settling a Batch

Batch Settlement Behavior

forceSettle and autoSettle

Webhook Events

Nano Payments and x402

Next Steps