Skip to content

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.

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
| <-------------------------------------------- |
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.

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
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.

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 facilitators to replace the defaults. A facilitator cannot change the amount or where the money goes: the buyer’s signature covers both.

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.

  • 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 503 when 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 onFailure reports charged: "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.