Settlement

All settlement happens on-chain via USDC on Base. Per-request, immediate, non-custodial.

How It Works

  1. Response completes → server extracts token usage
  2. Cost calculated at seller's listed price (sellerAmount)
  3. Fee calculated: buyerAmount = sellerAmount × feeMultiplier / 10000 + flatFee
  4. settle() called on Settlement contract (via UUPS proxy):
    • Pulls sellerAmount from buyer's wallet → sends to seller (or payout address)
    • Pulls fee from buyer's wallet → sends to feeRecipient
    • All in one Base transaction (~$0.001 gas)

Fee Structure

Two components, both configurable on-chain by addresses with ADMIN_ROLE:

  • feeMultiplier — basis points (10000 = 0% fee, 10300 = 3% fee)
  • flatFee — fixed USDC amount per settlement (covers gas costs)

Current settings: feeMultiplier=10000 (0%), flatFee=0

Minimum feeMultiplier: 10000 (1.0x). Sub-1x subsidy mode is not supported.

Anyone can verify on-chain via calculateFee(sellerAmount) (free view call).

Buyer Setup

API-key marketplace buyers approve USDC for the SettlementV2 proxy. The web app can collect a gasless EIP-2612 permit under the backend-exposed SettlementV2 policy cap; programmatic users can also call usdc.approve(proxyAddress, amount) on-chain. Funds stay in the buyer's wallet — nothing is locked — and the SettlementV2 approval can be capped or revoked at any time.

This is separate from x402 upto, which uses Permit2 plus per-request payment signatures. A Permit2 approval does not satisfy /buy SettlementV2 allowance, and changing /buy to use Permit2 as only a different standing spender would not remove standing-allowance risk. Only a future per-request x402/Permit2 proof flow for /buy would do that.

The SettlementV2 proxy address is permanent — contract upgrades don't require re-approval.

Example

Input:  1,847 tokens    Output: 3,201 tokens
Seller: $12/M input, $48/M output
Fee:    0% + $0.001038 flat

Input cost:  $0.02216
Output cost: $0.15365
sellerAmount: $0.17581

buyerAmount: $0.17581 × 10000/10000 + $0.001038 = $0.176848
Sent to seller:    $0.17581
Sent to fee recipient: $0.001038
Gas:               ~$0.001

Payout Address

Sellers can set an optional payout_address to direct settlement to a different wallet. Use cases:

  • Route to a Bankr wallet for automatic LLM credit top-up
  • Send to a treasury or multisig
  • Separate selling identity from payment destination

Failed Settlements

If a settlement fails after inference has already run, the usage row is marked failed and queued in pending_settlements. A cron job retries with exponential backoff for up to 5 attempts.

If all retries fail, the row is marked permanently_failed and removed from the retry queue. There is no automatic insurance pool or automatic seller reimbursement today. The seller is not paid on-chain until a settlement succeeds or the operator manually reconciles it. For API-key settlement, this means the seller can eat the upstream provider cost if the buyer's balance/allowance disappears and retries never settle. For x402/MPP/operator-mediated settlement, the buyer may already have paid the operator; seller payment still depends on the operator settlement succeeding or being manually remediated.

Contract

SettlementV2 deployed behind a UUPS proxy on Base. Source at contracts/SettlementV2.sol.

Architecture:

  • UUPS proxy (permanent address, buyers approve once)
  • Role-based access control via OPERATOR_ROLE, ADMIN_ROLE, UPGRADER_ROLE, and DEFAULT_ADMIN_ROLE
  • Implementation upgradeable by UPGRADER_ROLE without buyer re-approval
  • No contract-level timelock today

Key functions:

  • settle(buyer, seller, sellerAmount) — execute settlement
  • calculateFee(sellerAmount) → (buyerAmount, fee) — free view call
  • feeMultiplier() → current multiplier in basis points
  • flatFee() → current flat fee in USDC units
  • feeRecipient() → where fees go

Admin / trust model:

  • ADMIN_ROLE: setFeeMultiplier(uint256), setFlatFee(uint256), setFeeRecipient(address)
  • DEFAULT_ADMIN_ROLE: grant/revoke roles
  • UPGRADER_ROLE: upgradeToAndCall(address, bytes)

Current limitation: there is no on-chain timelock or multisig requirement enforced by the contract. A role holder can change fee parameters or upgrade in a single transaction. The current feeMultiplier is 10000, and API-key buyers can limit exposure by approving only the SettlementV2 amount they are willing to spend.

Operator flow (x402/MPP): For x402/MPP, the buyer pays/authorizes payment to the SI operator path first, then SI pays the selected seller via operator-mediated settlement. x402 upto uses Permit2 plus a per-request payment signature; it does not reuse /buy SettlementV2 approval. This avoids route-locking issues where a 402 challenge might name one seller but failover chooses another. Seller payout is still visible as a Base USDC transfer when settlement succeeds.

Previous

Pricing

Next

Health & Routing