Skip to content
Tollgate Docs

Settlement Lifecycle

Settlement converts accepted IOUs into on-chain USDC transfers. Tollgate is non-custodial: the settler's hot wallet never holds user funds. It merely pays gas to call USDC.transferFrom(agent, developer, amount) on each settlement batch, then emits a Settlement event through the wrapper contract so an indexer can cross-reference revenue.

Phases

  1. Accept. The middleware verifies + persists the IOU (POST /v1/verify). Persistence is write-behind and idempotent on (agent, dev, path, nonce).
  2. Batch. Every N minutes (default 10), the settler worker reads the latest IOU per (agent, developer, path)and submits transferFrom via the wrapper contract.
  3. Emit. Settlement(agent, developer, amount, iouNonce, settler) is emitted; the indexer picks it up to update the developer dashboard and accounting ledger.
  4. Webhooks (TASK-20). Macro events (settlement.succeeded, settlement.failed) are delivered to subscribed webhook endpoints. See Webhooks.

Failure modes

  • Allowance revoked. The agent revoked USDC allowance before settlement. The developer is blacklisted from this agent on first failure (TASK-07). See INSUFFICIENT_ALLOWANCE.
  • Agent balance drained. Same outcome — developer scope blacklist on first failure.
  • Stuck tx. Mempool stall > 60s triggers a gas bump. Three bumps = circuit break; ops is alerted.

Who pays the gas?

The settler's hot wallet. This is an operational expense, not your users' burden. Gas is amortised across the entire batch — at Base gas prices a single transferFrom is ~$0.0005, which is <1% of a typical $0.05 price.

When do I actually get paid?

On each settlement batch (see pricing). Free tier settles daily; paid tiers settle hourly with per-batch transfer directly to your configured payoutAddress.