Payment Protocols
Toll supports two Stellar payment protocols — choose per tool or mix both
X402
HTTP 402 Protocol
Uses the HTTP 402 Payment Required status code. The server returns payment requirements, the client signs a Stellar transaction, and retries with the payment signature header. Settlement is verified on-chain via an x402 facilitator.
Flow
- 1.Agent sends POST /mcp with tool call
- 2.Toll checks for payment-signature header
- 3.If missing, returns HTTP 402 + PaymentRequired JSON
- 4.Agent signs Stellar USDC transaction with exact amount
- 5.Agent retries with base64-encoded payment-signature header
- 6.Toll POSTs to x402 facilitator /settle endpoint
- 7.Facilitator verifies transaction on Stellar network
- 8.Tool executes, earnings recorded
Advantages
- + Web standard (HTTP 402)
- + Simple request/response flow
- + Per-call payment flexibility
- + On-chain settlement proof
Trade-offs
- - Two HTTP round-trips per paid call
- - Requires x402 facilitator service
- - Higher per-call overhead for bulk usage
MPP
Machine Payments Protocol
Session-based payment channel using Stellar smart contracts. The agent opens a payment channel, then uses the Authorization header for subsequent calls. Ideal for high-frequency agent workflows.
Flow
- 1.Agent sends POST /mcp with tool call
- 2.Toll checks for Authorization: Payment header
- 3.If missing, returns 402 + WWW-Authenticate: Payment challenge
- 4.Agent signs payment via @stellar/mpp channel
- 5.Agent retries with Authorization: Payment token
- 6.Toll verifies via mppx paywall
- 7.Payment confirmed through Stellar smart contract
- 8.Tool executes, earnings recorded
Advantages
- + Lower per-call overhead after setup
- + Session-based bulk payments
- + Smart contract security
- + Streaming payment support
Trade-offs
- - Requires @stellar/mpp SDK on client
- - Channel setup overhead for single calls
- - Newer protocol, smaller ecosystem
When to Use Which
| Scenario | Recommended | Why |
|---|---|---|
| One-off tool calls | X402 | Simple single-payment flow, no session setup needed |
| High-frequency API calls | MPP | Session-based channel reduces per-call overhead |
| Variable pricing | X402 | Each call can have different payment amount |
| Bulk agent workflows | MPP | Pre-funded channel handles many calls efficiently |
| Maximum compatibility | X402 | HTTP 402 is a web standard, easier client integration |
| Streaming payments | MPP | Channel-based model supports ongoing payment streams |
Configuration Examples
x402 tool config
json
"search_competitors": {
"price": "0.01",
"currency": "USDC",
"paymentMode": "x402"
}MPP tool config
json
"compare_products": {
"price": "0.05",
"currency": "USDC",
"paymentMode": "mpp"
}