Activity

Every /verify and /settle call is recorded with metadata you can query — payer, recipient, amount, chain, transaction hash, success or failure reason. Useful for:

Building compliance views
Surfacing transaction history in your UI
Debugging failed payments
Reconciling on-chain activity with off-chain business records

`agents.activity(agentId, opts?)`

const recent = await client.agents.activity('trading-bot-1', {
  days:  7,       // optional — default 7, max 30
  limit: 50,      // optional — default 50, max 200 per type (verifies / settlements)
});

Returns

{
  "agentId":       "trading-bot-1",
  "address":       "0xb0e6ec46cd2d97de006f9318ac5c7994b7aadd2b",
  "daysQueried":   7,
  "chainsQueried": ["avalanche", "fuji"],
  "asOf":          "2026-06-11T17:50:01.845Z",
  "summary": {
    "verifyCount":            12,
    "settlementCount":        10,
    "successfulSettlements":  10,
    "spentTotalUSD":          "2.500000"
  },
  "verifies":    [ /* up to `limit` rows, newest first */ ],
  "settlements": [ /* up to `limit` rows, newest first */ ]
}

Row shape — `settlements[i]`

{
  "sk":                  "1781000340000#a8b3c5",       // sort key (timestamp ms + random)
  "payer":               "0xb0e6ec46cd2d97de006f9318ac5c7994b7aadd2b",
  "recipient":           "0xMerchant...",
  "token":               "0x5425890298aed601595a70AB815c96711a31Bc65",
  "token_symbol":        "USDC",
  "amount":              "500000",                       // atomic units (uint256 string)
  "amount_formatted":    "0.500000",                     // decimal string
  "nonce":               "0x...",
  "network":             "avalanche-fuji",
  "chain_id":            43113,
  "transaction_hash":    "0x5972437a3695b2641855416da6b7f936ceda300c7536189a5dc237e1cc21a8e7",
  "block_number":        56206516,
  "gas_used":            "62541",
  "success":             true,
  "error_reason":        null,                           // string on failure, null on success
  "timestamp":           "2026-06-11T21:44:03.347Z",
  "duration_ms":         312,
  "transaction_time_ms": 8160,
  "total_time_ms":       8472
}

Row shape — `verifies[i]`

{
  "sk":               "1781000300000#7d2e9a",
  "payer":            "0xb0e6ec46cd2d97de006f9318ac5c7994b7aadd2b",
  "recipient":        "0xMerchant...",
  "token":            "0x5425890298aed601595a70AB815c96711a31Bc65",
  "token_symbol":     "USDC",
  "amount":           "500000",
  "amount_formatted": "0.500000",
  "nonce":            "0x...",
  "network":          "avalanche-fuji",
  "chain_id":         43113,
  "is_valid":         true,
  "invalid_reason":   null,                                // 'Invalid signature' / 'Nonce already used' / 'Authorization expired'
  "timestamp":        "2026-06-11T21:43:58.000Z",
  "duration_ms":      45
}

Important things to know

What counts as “activity”

Every client.x402.pay(...) produces one settlement row.
Every client.x402.sign(...) followed by a separate client.facilitator.verify(...) call produces one verify row.
Settle alone (client.facilitator.settle(...)) produces only a settlement row — the facilitator skips verify when called via settle.
Failed settlements are recorded too, with success: false and error_reason set.

Retention

Activity rows are stored with a 90-day TTL. Older rows are automatically pruned. If you need longer retention, fetch periodically and persist to your own database.

Query window

days clamps to [1, 30].
limit clamps to [1, 200] and applies separately to verifies and settlements.
Rows are returned newest first within each list.

Partition scan caveat

Activity is partitioned by (chainId, UTC day). Querying 30 days × 3 chains = 90 partitions per call. Most agents have negligible activity per partition so this is fast, but a hot agent (thousands of settlements per day) on a 30-day window can be slow. Tighten days or limit if you notice latency.

Patterns

Show “last 7 days” stats in a dashboard

const a = await client.agents.activity(agentId, { days: 7 });
return {
  spent:       Number(a.summary.spentTotalUSD).toFixed(2),
  settlements: a.summary.successfulSettlements,
  failed:      a.summary.settlementCount - a.summary.successfulSettlements,
};

Display a transaction table with explorer links

const a = await client.agents.activity(agentId, { days: 7 });
return (
  <table>
    {a.settlements.map((row) => {
      const explorer = row.chain_id === 43114
        ? 'https://snowtrace.io'
        : row.chain_id === 8453
          ? 'https://basescan.org'
          : 'https://testnet.snowtrace.io';
      return (
        <tr key={row.sk}>
          <td>{row.success ? '✅' : '❌'}</td>
          <td>${row.amount_formatted} {row.token_symbol}</td>
          <td>{row.recipient}</td>
          <td><a href={`${explorer}/tx/${row.transaction_hash}`}>Tx</a></td>
          <td>{row.timestamp}</td>
        </tr>
      );
    })}
  </table>
);

Reconcile failed settlements

const a = await client.agents.activity(agentId, { days: 30, limit: 200 });
const failed = a.settlements.filter((r) => r.success === false);
failed.forEach((row) => {
  console.warn(`Failed settle to ${row.recipient}: ${row.error_reason}`);
});