How Lotvs Pay works
Lotvs Pay is not a payment processor. It does not hold money, issue accounts or move funds. For each request it decides what it costs, whether it was paid for, and who is told. The money moves once, from the agent’s wallet to your address.
The 402 handshake
Section titled “The 402 handshake”A paid request is the same request sent twice: once to learn the price, once with the payment attached.
Agent Your API | GET /report | | --------------------------------------------> | No payment came with it, | 402 Payment Required | so the answer is the price | PAYMENT-REQUIRED: $0.10, pay to <you> | | <-------------------------------------------- | | signs a payment of exactly $0.10 | | GET /report | | PAYMENT-SIGNATURE: <signed payment> | | --------------------------------------------> | The payment is checked, | 200 OK | your handler runs, | PAYMENT-RESPONSE: <receipt> | the money moves to you | <-------------------------------------------- |Headers
Section titled “Headers”| x402 version 2 | x402 version 1 | |
|---|---|---|
| The price | PAYMENT-REQUIRED header, base64 JSON |
The JSON body of the 402 |
| The payment | PAYMENT-SIGNATURE header |
X-PAYMENT header |
| The receipt | PAYMENT-RESPONSE header |
X-PAYMENT-RESPONSE header |
Both versions are answered unless you set legacy: false. Decoded, the price looks like this:
{ "x402Version": 2, "error": "Payment required. Pay the amount below and send the request again.", "resource": { "url": "https://api.example.com/report", "description": "Today's market report", "mimeType": "application/json" }, "accepts": [ { "scheme": "exact", "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", "amount": "100000", "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "payTo": "YourSolanaAddress", "maxTimeoutSeconds": 60, "extra": { "feePayer": "…" } } ]}amount is in the token’s smallest unit: 100000 is $0.10 of USDC. A route that takes two networks lists two entries, and the agent pays the one it holds money on.
What is signed
Section titled “What is signed”| Solana | Base | |
|---|---|---|
| The buyer signs | A whole transaction, with the facilitator named in it as fee payer | An authorization for the USDC contract to move the amount (EIP-3009) |
| Who can settle it | Only the facilitator named as fee payer | Any facilitator that takes the network |
A reference (memo) |
Carried in the transaction | Nowhere to carry one, so it is refused at startup |
When the buyer is charged
Section titled “When the buyer is charged”| Charge after success (default) | Collect first (flow: "upfront") |
|
|---|---|---|
| Order | Check the payment, run your code, collect, answer | Collect, run your code, answer |
| If your code fails | The buyer is not charged, and the same payment can be sent again | The money has moved. A refund is yours to make |
| Use it for | Almost everything | Answers that stream, or take more than a few seconds |
Under the default, any response with a status of 400 or above is not charged. Your code has about a minute, which is how long a signed payment lasts. In Express, the response is held back until the payment settles, then released.
A refund is an ordinary transfer from your wallet back to receipt.payer.
Facilitators
Section titled “Facilitators”A facilitator is a service that checks a signed payment, pays the network fee, and puts it on the network. Facilitators are third parties, not Lotvs. By default the SDK uses public ones that need no account:
| Network | Tried in this order |
|---|---|
solana |
PayAI, then Dexter |
solana-devnet |
PayAI, then Dexter |
base |
PayAI, then Dexter |
base-sepolia |
PayAI, then the x402.org facilitator |
- Failover. What each facilitator supports is asked once and kept for five minutes. One that fails to answer is skipped for thirty seconds, so an outage costs one slow request, not every request.
- Only for what it takes. A payment goes only to a facilitator that lists that scheme, network and protocol version.
- On Solana, a quote names the first facilitator that is up as fee payer, and only that one can settle the payment.
- On Base, the payment goes to the first facilitator that is up when it arrives.
- Dexter has a smallest payment. On 6 October 2026 it listed 1,324 atomic units on Solana (about $0.0013) and 1,579 on Base. A price under it would be refused there. PayAI is tried first.
- Your own. Pass
facilitatorsto replace the defaults. A facilitator cannot change the amount or where the money goes: the buyer’s signature covers both.
Replay protection
Section titled “Replay protection”One payment buys one response. Each payment is claimed before anything else happens, so the same payment sent twice at once is served once. A claim lasts 120 seconds. On Solana the claim is keyed on the signed part of the transaction; on Base, on the signer, the nonce, the token and the chain. Past the claim, the network itself refuses a payment that already settled.
If you run several servers, share one replay store between them.
Security model
Section titled “Security model”- No custody. The money goes from the buyer to your
payTo, never through an address of Lotvs’s. - The buyer’s copy of the terms is never trusted. The terms are rebuilt from your settings when a payment arrives, and the buyer’s are only compared with them. A payment made against old terms, such as a previous address or price, is refused, and the buyer is given the new ones.
- Fail closed. A missing address, a facilitator that does not answer and a payment that cannot be confirmed all end in a refusal, never in a free response.
- Addresses are checked before a price is quoted. An address of the wrong kind for its network stops the server from starting, or closes the route with
503when it comes from a function. - Real and test networks never mix, so nobody can buy with test dollars.
- Exact money. Prices are integers in the token’s smallest unit, never floating point.
- When nobody knows, it says so. If a facilitator does not answer a request to settle, the response is withheld, the claim is kept, the buyer is told not to pay again, and
onFailurereportscharged: "unknown".
Lotvs Pay charges sellers nothing. The buyer pays the price you set and nothing on top, and the facilitator pays the network fee. Your bank, an exchange or a wallet may charge their own fees when you move the dollars on.
Status
Section titled “Status”Related
Section titled “Related”- Lotvs Pay quickstart
- Lotvs Pay reference
- x402, the open standard any buyer uses to pay