Nanopayments — POST /api/payments/nano & /api/payments/nano/settle

Nanopayments are micro USDC charges (e.g. "0.0001" per API call, per token, or per second of compute) recorded instantly in Postgres without moving tokens on-chain. Charges accrue per agent→merchant pair and are batched, then settled together via POST /api/payments/nano/settle — when the unsettled balance reaches the batch threshold (1.0 USDC) or the batch interval (60 seconds) elapses. Agents paying for metered services typically call /nano for every unit of usage and rely on the settle route (or internal automation) to move the accumulated balance on-chain.

The batch threshold and interval are fixed constants on the server: 1.0 USDC and 60 seconds. The readyToSettle flag in the record response tells you when the threshold is met for that pair.

Record a Nanopayment

Endpoint

POST https://flarehq.xyz/api/payments/nano

Request

Headers

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

Body Parameters

string

required

SCA wallet address of the agent (the consumer of the service) being charged.

string

required

SCA wallet address of the merchant (the provider of the service) receiving the charge.

string

required

Micro amount in USDC as a decimal string — e.g. "0.0001". Must parse to a value greater than 0.

string

What this charge was for — e.g. "1 API call", "100 tokens".

Response

boolean

true when the nanopayment was recorded.

object

The persisted nanopayment record.

Show nano fields

string

Echoed agent SCA address.

string

Echoed merchant SCA address.

number

The amount as a float — e.g. 0.0001.

boolean

Always false immediately after recording — the charge is pending settlement.

number

Total unsettled USDC accrued for this agent→merchant pair, including the charge just recorded.

number

Number of unsettled nanopayments for this pair.

boolean

true when unsettledBalance has reached the 1.0 USDC batch threshold — the pair is ready to settle.

string

Human-readable confirmation including the current pending balance and threshold.

Examples

curl -X POST https://flarehq.xyz/api/payments/nano \
  -H "x-api-key: fhq_sec_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agentSCA":    "0xAgentSCAWalletAddress",
    "merchantSCA": "0xMerchantSCAWalletAddress",
    "amount":      "0.0001",
    "description": "1 API call"
  }'

const res = await fetch('https://flarehq.xyz/api/payments/nano', {
  method: 'POST',
  headers: {
    'x-api-key': 'fhq_sec_test_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    agentSCA: '0xAgentSCAWalletAddress',
    merchantSCA: '0xMerchantSCAWalletAddress',
    amount: '0.0001',
    description: '1 API call',
  }),
});

const { unsettledBalance, readyToSettle } = await res.json();
if (readyToSettle) {
  // Threshold reached — call POST /api/payments/nano/settle
}

Success Response

{
  "success": true,
  "nano": {
    "agentSCA": "0xAgentSCAWalletAddress",
    "merchantSCA": "0xMerchantSCAWalletAddress",
    "amount": 0.0001,
    "settled": false
  },
  "unsettledBalance": 0.0002,
  "unsettledCount": 2,
  "readyToSettle": false,
  "message": "Nanopayment recorded. 0.000200 USDC pending (threshold: 1 USDC)."
}

Error Responses

{
  "success": false,
  "error": "agentSCA, merchantSCA and amount are required."
}

{
  "success": false,
  "error": "Amount must be greater than 0."
}

You can inspect the pending balance for a pair with GET /api/payments/nano?agentSCA=...&merchantSCA=..., which returns the batch summary (total, count, ageMs, shouldSettle) plus thresholdUSDC.

Batch-Settle Nanopayments

Endpoint

POST https://flarehq.xyz/api/payments/nano/settle

Settles the unsettled balance for a specific agent→merchant pair (or all pairs, with autoSettle) by moving USDC on-chain from the agent’s Circle wallet to the merchant. The settlement is idempotent: if a settlement is already in-flight (SUBMITTED) or completed, the route resumes/returns the existing result rather than double-paying.

Request

Headers

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

Body Parameters

string

SCA wallet address of the agent whose unsettled charges are being settled. Required unless autoSettle is used.

string

SCA wallet address of the merchant receiving the settlement. Required unless autoSettle is used.

string

Publicly reachable HTTPS URL that receives a nano.batch_settled event after a successful settlement.

boolean

default:"false"

When true, settle even if the unsettled balance is below the 1.0 USDC threshold. By default a sub-threshold balance is rejected with HTTP 400.

boolean

default:"false"

When true, settle all unsettled pairs platform-wide that meet the threshold/interval criteria. Restricted to internal service API keys only — any other caller receives HTTP 403.

Response

Single-pair settlement

boolean

true when the batch settled (or an in-flight settlement was resumed).

string

Unique batch reference with the prefix nano_ — e.g. "nano_3f9c2e0a-...". The reference of the associated paymentLog record.

string

On-chain transaction hash for the batch transfer.

string

Arc Explorer link — https://explorer.arc.io/tx/{txHash}.

number

Total USDC settled in this batch.

number

Number of nanopayments included in the batch.

boolean

true when this response reflects an already in-flight (SUBMITTED) settlement that was resumed, rather than a newly initiated one.

number

Total USDC settled, mirroring total.

number

Number of payments settled, mirroring count.

autoSettle settlement

number

Number of agent→merchant pairs settled successfully.

number

Number of pairs that failed to settle.

array

Per-pair outcome. Each entry includes the pair (agentSCA, merchantSCA), success, and — on success — batchRef, txHash, explorerUrl, total, count, resumed; on failure, error.

string

Summary, e.g. "Auto-settled 2 pairs. 0 failed.".

Examples

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

curl -X POST https://flarehq.xyz/api/payments/nano/settle \
  -H "x-api-key: fhq_sec_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agentSCA":    "0xAgentSCAWalletAddress",
    "merchantSCA": "0xMerchantSCAWalletAddress",
    "forceSettle": true
  }'

const res = await fetch('https://flarehq.xyz/api/payments/nano/settle', {
  method: 'POST',
  headers: {
    'x-api-key': 'fhq_sec_test_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    agentSCA: '0xAgentSCAWalletAddress',
    merchantSCA: '0xMerchantSCAWalletAddress',
  }),
});

const { batchRef, txHash, totalSettled } = await res.json();
console.log(batchRef, txHash, totalSettled);

Success Response

{
  "success": true,
  "batchRef": "nano_3f9c2e0a-b1d4-4a7e-9c22-1f0d6a8b5c3e",
  "txHash": "0xaaa111bbb222ccc333ddd444eee555fff666777888999000111222333444555666",
  "explorerUrl": "https://explorer.arc.io/tx/0xaaa111bbb222ccc333ddd444eee555fff666777888999000111222333444555666",
  "total": 1.2,
  "count": 12,
  "resumed": false,
  "totalSettled": 1.2,
  "paymentsCount": 12
}

Error Responses

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

{
  "success": false,
  "error": "autoSettle requires an internal service API key."
}

{
  "success": false,
  "error": "You do not control either party in this settlement (agentSCA or merchantSCA)."
}

{
  "success": false,
  "error": "Insufficient balance in the source wallet.",
  "hint": "Fund the Agent SCA wallet with USDC on Arc Mainnet."
}

Notes

Settlements are executed on-chain on Arc Mainnet via Circle developer-controlled wallets. The payer wallet is resolved from the agent’s registered Circle wallet; if no wallet is registered for agentSCA, the request fails with an error indicating the agent has no Circle wallet.

The route is idempotent across retries. If a settlement is already SUBMITTED on-chain, a second call resumes it and returns resumed: true instead of initiating a duplicate transfer.

A sub-threshold balance is rejected with HTTP 400 unless you pass forceSettle: true. Set webhookUrl to receive the nano.batch_settled event (including batchRef, txHash, and totalSettled) so you don’t have to poll for completion.

Overview

Payments

Escrow

Streaming

CCTP Bridge

Checkout

x402

Agents

Jobs

Merchant

Consumer

Payroll

Nanopayments — POST /api/payments/nano & /api/payments/nano/settle

Record a Nanopayment

Endpoint

Request

Headers

Body Parameters

Response

Examples

Success Response

Error Responses

Batch-Settle Nanopayments

Endpoint

Request

Headers

Body Parameters

Response

Single-pair settlement

autoSettle settlement

Examples

Success Response

Error Responses

Notes

​Record a Nanopayment

​Endpoint

​Request

​Headers

​Body Parameters

​Response

​Examples

​Success Response

​Error Responses

​Batch-Settle Nanopayments

​Endpoint

​Request

​Headers

​Body Parameters

​Response

​Single-pair settlement

​autoSettle settlement

​Examples

​Success Response

​Error Responses

​Notes

Record a Nanopayment

Endpoint

Request

Headers

Body Parameters

Response

Examples

Success Response

Error Responses

Batch-Settle Nanopayments

Endpoint

Request

Headers

Body Parameters

Response

Single-pair settlement

autoSettle settlement

Examples

Success Response

Error Responses

Notes