> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flarehq.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Accept Sub-Cent Nano Payments from Agents

> Record micro USDC charges instantly on Arc Mainnet and settle them in batched, on-chain transfers. Ideal for per-call, per-token, and per-second-of-compute agent payments.

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](/x402/overview) 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

<CardGroup cols={2}>
  <Card title="Per-API-Call Pricing" icon="code">
    Charge `0.0001` USDC per request instead of forcing a subscription. Agents pay as they consume.
  </Card>

  <Card title="Token & Compute Billing" icon="microchip">
    Meter LLM output per token or compute per second, with micro charges accumulated into a settleable batch.
  </Card>

  <Card title="Agent↔Merchant Ledger" icon="robot">
    Track every micro payment an agent makes to a service provider, then reconcile against a single on-chain settlement.
  </Card>

  <Card title="x402 Gateway Settlement" icon="gauge-high">
    Batch the sub-cent Nanopayment authorizations collected by your x402 gateway into one transfer.
  </Card>
</CardGroup>

## How Nano Payments Work

1. **Record** — Each micro charge is `POST`ed to `/api/payments/nano` and stored instantly with `settled: false`.
2. **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.
3. **Batch** — When the pair's total reaches the threshold (1 USDC) or the batch age reaches the interval (60 seconds), the pair `shouldSettle`.
4. **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

<Steps>
  ### Install and Initialise the SDK

  ```bash theme={null}
  npm install @flarehq/sdk
  ```

  ```typescript theme={null}
  import { FlareHQ } from '@flarehq/sdk';

  const flarehq = new FlareHQ({ apiKey: process.env.FLAREHQ_SECRET_KEY! });
  ```

  ### Record a Charge

  `agentSCA` is the wallet being charged (the consumer of the service); `merchantSCA` is the wallet receiving funds (the provider). The amount is a micro USDC value — anything above `0`.

  <CodeGroup>
    ```typescript SDK theme={null}
    const charge = await flarehq.nano.record({
      agentSCA: '0xAgentWallet...',
      merchantSCA: '0xMerchantWallet...',
      amount: '0.0001',
      description: '1 API call: /v1/classify',
    });

    console.log(charge.unsettledBalance, charge.readyToSettle);
    // → 0.0004 false
    ```

    ```bash REST theme={null}
    curl -X POST https://flarehq.xyz/api/payments/nano \
      -H "x-api-key: fhq_sec_test_..." \
      -H "Content-Type: application/json" \
      -d '{
        "agentSCA": "0xAgentWallet...",
        "merchantSCA": "0xMerchantWallet...",
        "amount": "0.0001",
        "description": "1 API call: /v1/classify"
      }'
    ```
  </CodeGroup>

  ### Read the Response

  ```json theme={null}
  {
    "success": true,
    "nano": {
      "id": "uuid...",
      "agentSCA": "0xAgentWallet...",
      "merchantSCA": "0xMerchantWallet...",
      "amount": 0.0001,
      "settled": false
    },
    "unsettledBalance": 0.0004,
    "unsettledCount": 4,
    "readyToSettle": false,
    "message": "Nanopayment recorded. 0.000400 USDC pending (threshold: 1 USDC)."
  }
  ```
</Steps>

## REST API Parameters

<ParamField body="agentSCA" type="string" required>
  The agent wallet being charged. This is the payer — the consumer of the service.
</ParamField>

<ParamField body="merchantSCA" type="string" required>
  The merchant wallet receiving funds. This is the provider of the service.
</ParamField>

<ParamField body="amount" type="string | number" required>
  Micro USDC amount, e.g. `"0.0001"`. Must be greater than `0`; values are stored and settled to 6 decimal places.
</ParamField>

<ParamField body="description" type="string">
  What the charge is for, e.g. `"1 API call"` or `"100 tokens"`.
</ParamField>

## 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:

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

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

<ResponseField name="total" type="number">
  Total unsettled USDC for the pair, to 6 decimal places.
</ResponseField>

<ResponseField name="count" type="number">
  Number of unsettled nano payments for the pair.
</ResponseField>

<ResponseField name="ageMs" type="number">
  Milliseconds since the oldest unsettled payment was recorded.
</ResponseField>

<ResponseField name="shouldSettle" type="boolean">
  `true` when `total >= 1 USDC` or `ageMs >= 60000` (60 seconds).
</ResponseField>

<ResponseField name="thresholdUSDC" type="number">
  The batch settlement threshold, `1` USDC.
</ResponseField>

## Settling a Batch

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

```bash theme={null}
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:

```json theme={null}
{
  "success": false,
  "error": "Threshold not reached. 0.400000/1 USDC.",
  "unsettledBalance": 0.4
}
```

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

```json theme={null}
{
  "agentSCA": "0xAgentWallet...",
  "merchantSCA": "0xMerchantWallet...",
  "forceSettle": true
}
```

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

```json theme={null}
{
  "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 |

```json theme={null}
{
  "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/overview). 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.

<Note>
  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.
</Note>

## Next Steps

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