Skip to content

Lotvs Pay reference

This page describes @lotvs/pay 0.3.0.

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.

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.

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

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

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

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 });