Lotvs Pay reference
This page describes @lotvs/pay 0.3.0.
Exports
Section titled “Exports”| Export | What it is |
|---|---|
lotvsPay(options) |
Middleware for Express and Connect, or for a plain Node http server: (req, res, next) |
withLotvsPay(options, handler) |
Wraps a Next.js route handler, or any handler that takes a web Request and returns a Response |
paymentOf(request) |
Inside a paid handler, the Payment that came with this request |
createPaywall(options) |
The decision without a framework: begin(request) answers “reply with this” or “proceed, then call finish”. For writing an adapter |
createMemoryReplayStore() |
The default replay store, in memory |
httpFacilitator(url, options) |
A facilitator client over HTTP. Options: headers, fetch, timeoutMs (10 seconds), settleTimeoutMs (45 seconds) |
FacilitatorPool, DEFAULT_FACILITATORS |
The router between facilitators, and the default list for Solana |
FacilitatorError |
Thrown when a facilitator cannot be reached or answers nonsense |
LotvsPayConfigError |
Thrown at startup for a mistake in the options |
toAtomic(price, decimals), fromAtomic(atomic, decimals) |
Prices as exact integers, and back |
encodeJsonHeader, decodeJsonHeader |
Base64 JSON, as x402 headers carry it |
isSolanaAddress, isEvmAddress |
Address checks |
RAILS |
The networks, their tokens and default facilitators |
The adapters are also available alone, as @lotvs/pay/express and @lotvs/pay/next. Types are exported for every option and result, including LotvsPayOptions, Payment, Receipt, Failure, PayTo, NetworkId and ReplayStore.
An OPTIONS request, a CORS preflight, is passed through and never charged.
Options
Section titled “Options”| Option | Default | What it does |
|---|---|---|
price |
required | What one request costs, in dollars: "0.10", "$0.10" or 0.1. At most 6 decimal places, more than zero. Or a function of the request; the same request must always get the same price |
payTo |
LOTVS_PAY_TO |
The address that gets paid. One address, or one for each network: { solana: "…", base: "0x…" }. Or a function that returns either, asked on every request. Checked against its network every time |
network |
LOTVS_PAY_NETWORK, then "solana" |
"solana" or "base" for real money, "solana-devnet" or "base-sepolia" for none. Or several: ["solana", "base"]. Real and test networks cannot be mixed |
currency |
"USD" |
Prices are in US dollars, collected in USDC one for one. "USD" is the only value |
description |
Shown to the buyer’s agent before it pays | |
mimeType |
"application/json" |
What the paid response is |
serviceName |
A name for what is sold, for agents and directories. Plain ASCII, up to 32 characters | |
tags |
Up to 5 tags, each plain ASCII up to 32 characters | |
iconUrl |
An absolute http or https URL of an icon |
|
flow |
"authorization" |
"authorization" collects after your code succeeds. "upfront" collects first. See When the buyer is charged |
memo |
A reference written into the payment, 1 to 256 bytes. A string, or a function of the request. Solana only: with a Base network it stops the server from starting | |
onPayment |
Called once for every payment collected, with the Receipt |
|
onFailure |
Called when a payment was refused, failed, or could not be confirmed, with a Failure |
|
pendingSettlement |
"withhold" |
When a payment was sent but is not confirmed yet: "withhold" the response and answer 402, or "deliver" it and reconcile yourself |
facilitators |
LOTVS_PAY_FACILITATORS, then the defaults for each network |
Who checks and settles payments: https URLs, or your own objects. Each is used only for the networks it says it supports |
replayStore |
in memory | Remembers payments already used. Share one if you run several servers |
legacy |
true |
Also accept clients on version 1 of x402 |
maxTimeoutSeconds |
60 |
How long a buyer has to complete the payment. A whole number from 10 to 600 |
baseUrl |
from the request | Your public address, when it cannot be worked out from the request: "https://api.example.com" |
A mistake in the options stops your server from starting with a LotvsPayConfigError that says which one. The exception is an address that is missing, or that a payTo function got wrong: the route then answers 503 until it has a good one, so it never works for free.
Environment variables
Section titled “Environment variables”| Variable | Read as |
|---|---|
LOTVS_PAY_TO |
payTo, when the option is not given |
LOTVS_PAY_NETWORK |
network, with commas between several |
LOTVS_PAY_FACILITATORS |
facilitators, URLs with commas between them |
Networks
Section titled “Networks”network |
Money | Network id (x402 v2) | x402 v1 name | USDC | Default facilitators, in order |
|---|---|---|---|---|---|
solana (default) |
Real | solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp |
solana |
EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v |
PayAI, Dexter |
base |
Real | eip155:8453 |
base |
0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 |
PayAI, Dexter |
solana-devnet |
Test | solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1 |
solana-devnet |
4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU |
PayAI, Dexter |
base-sepolia |
Test | eip155:84532 |
base-sepolia |
0x036CbD53842c5426634e7929541eC2318f3dCF7e |
PayAI, x402.org |
USDC has 6 decimals on every network. The facilitators are https://facilitator.payai.network, https://x402.dexter.cash and https://x402.org/facilitator.
Addresses. A Solana address must decode to exactly 32 bytes, and must already hold or have held USDC. A Base address is 0x and 40 hex characters; in mixed case its capitals are a checksum, and one out of place is refused as a typo. The all zero address is refused.
Several networks. payTo names one address for each: the keys are network names, or solana and evm for a whole family. A network’s own name is looked for first. A network that cannot be settled at the moment is left out of the offer, and the others go on selling.
Payment and receipt
Section titled “Payment and receipt”paymentOf(request) returns a Payment:
| Field | |
|---|---|
protocol, protocolVersion |
"x402", and 1 or 2 |
network |
The network id it was paid on, such as "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp" or "eip155:8453" |
asset, currency |
The USDC address, and "USDC" |
amount, amountAtomic |
"0.1" and "100000" |
payTo |
Your address |
payer |
The buyer’s address, as the facilitator reports it |
test |
True on a test network |
settled |
False while your handler runs under the default flow: checked, not yet collected |
transaction |
The transaction id, once settled |
onPayment receives a Receipt: a settled Payment with transaction, resource, method, flow, facilitator and settledAt (ISO 8601).
onFailure receives a Failure:
| Field | |
|---|---|
stage |
"verify", "settle" or "handler" |
reason |
Why |
charged |
Whether the buyer’s money moved: "no", "yes" or "unknown". Unknown means it was sent and could not be confirmed: look the transaction up before anything else |
payer, transaction |
When known |
resource, method, facilitator |
What was bought, and who was asked |
What a buyer is told
Section titled “What a buyer is told”Every answer that is not your own. The body is JSON, with the reason in error, and cache-control: no-store.
| Status | error |
When |
|---|---|---|
402 |
The reason, in words | No payment came with the request, or the one that came was refused, failed, did not match the current terms, or was already used. The answer carries the terms, so the buyer can pay and ask again |
402 |
settlement_pending |
The payment went out and is not confirmed yet. The answer carries the transaction and tells the buyer not to pay twice |
402 |
settlement_unconfirmed |
The facilitator did not answer the request to settle, so nobody knows whether the payment went out. The buyer is told not to pay again before checking |
400 |
invalid_payment |
The payment header could not be read at all |
503 |
payments_unavailable |
No facilitator could check the payment, or none is up for any network you take. Nothing was charged, and trying again is safe. Comes with retry-after: 5 |
503 |
payments_not_configured |
The route has no address to be paid to yet, or one that failed its check |
500 |
internal_error |
Express and plain Node only: a paid response could not be finished |
With pendingSettlement: "deliver", the two settlement cases serve your response instead, and onFailure reports charged: "unknown".
Replay store
Section titled “Replay store”interface ReplayStore { claim(key: string, ttlSeconds: number): boolean | Promise<boolean>; release(key: string): void | Promise<void>;}A payment is claimed for 120 seconds before anything else happens. Behind a load balancer, or on serverless, give your servers one store to share:
const replayStore = { claim: async (key, ttlSeconds) => (await redis.set(key, "1", "NX", "EX", ttlSeconds)) === "OK", release: async (key) => void (await redis.del(key)),};
lotvsPay({ price: "0.10", replayStore });