Skip to content
tnsaiDocs
GitHub

Payments

TnsAI agents talk to other agents. Sometimes the other agent charges. The PaymentBroker SPI is the framework's answer to "how does an agent settle a payment without you, the human, in the loop?" It offers the same surface for free internal calls (PaymentBroker.noOp()), on-chain USDC micropayments over Base with x402 (X402PaymentBroker), or your own custom rail.

When to think about payments

You don't need a payment broker for free internal multi-agent traffic, because the default is PaymentBroker.noOp() (the NoOpPaymentBroker singleton). Accountability machinery threads through untouched. Reach for a real broker when:

  • Your agent calls third-party services that charge per request, such as premium MCP servers, paid embedding endpoints, paid weather/news feeds. With x402, the server returns HTTP 402 and your broker auto-settles the micropayment, and the response comes back as if you'd called a free endpoint.
  • Your agent offers a paid service to other agents outside your trust boundary. Quote the price, accept the signed authorisation, and settle on-chain.
  • You need an audit trail showing exactly how much each agent spent and on what. When a LiabilitySink is configured, each settled, rejected or expired outcome is recorded as an AgentLiabilityRecord.

Architecture

                                Quote(payer, payee, service)
                                Settlement {Settled | Rejected | Expired | AlreadySettled}
                                          │  ▲
                                          ▼  │
┌──────────────────────────────────────────────────────────────┐
│ PaymentBroker (SPI, tnsai-core)                              │
└──────────────────────────────────────────────────────────────┘
                                          │
        ┌─────────────────────────────────┼──────────────────────────┐
        ▼                                 ▼                          ▼
  PaymentBroker.noOp()           X402PaymentBroker            your own broker
  - default (core)               - tnsai-payments              - implements the SPI
  - free internal traffic        - x402 / EIP-3009
  - quotes at $0.00              - Base mainnet + Sepolia
                                 - Wallet interface for signing
                                   (InMemoryWallet, Web3jWallet)

The broker is the layer between your agent's chat loop and whatever rail moves the money. The rest of this section walks you through wiring it up.

  • Audit agent actions: identities, liability records and the default broker.
  • Tenant budgets: pair CostBudget (broad LLM spend) with AuthorityScope.spendCeilingUSD (per-broker mandate) for layered controls.
  • Reference: SPI: PaymentBroker contract.