Lotvs Pay quickstart
Install
Section titled “Install”npm install @lotvs/payNode 20 or later. The package is an ES module, so use import. It has no dependencies, and its TypeScript types are included.
Charge for a route
Section titled “Charge for a route”-
Say where the money goes. Payments arrive at an address you control. By default that is a Solana address:
.env LOTVS_PAY_TO=YourSolanaAddressA Solana address must already hold USDC, or have held it once: a payment cannot open the account it lands in. Send yourself a dollar of USDC first. To be paid on Base, see Networks.
-
Put a price on a route.
import express from "express";import { lotvsPay } from "@lotvs/pay";const app = express();app.get("/report", lotvsPay({ price: "0.10" }), (req, res) => {res.json({ report: "Markets were open today." });});app.listen(3000);app/api/report/route.ts import { withLotvsPay } from "@lotvs/pay";export const GET = withLotvsPay({ price: "0.10" }, async (request) => {return Response.json({ report: "Markets were open today." });});import { createServer } from "node:http";import { lotvsPay } from "@lotvs/pay";const paid = lotvsPay({ price: "0.10" });createServer((req, res) => {paid(req, res, () => {res.writeHead(200, { "content-type": "application/json" });res.end(JSON.stringify({ report: "Markets were open today." }));});}).listen(3000); -
Watch it answer. Ask without paying and you get the price back:
Terminal window curl -i http://localhost:3000/reportHTTP/1.1 402 Payment RequiredPAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6Mi... -
Describe what you sell.
descriptionis what an agent reads before it decides to pay:lotvsPay({ price: "0.10", description: "Today's market report" });
Try it with no real money
Section titled “Try it with no real money”One setting moves everything to a test network, where the dollars are not real:
LOTVS_PAY_NETWORK=solana-devnet # or base-sepoliaPrices, payments and receipts behave the same, and payment.test is true.
There is a live route to look at. pay.lotvs.ai charges a cent of test USDC on Solana devnet for a fortune:
curl -i https://pay.lotvs.ai/api/demo/fortuneWho paid
Section titled “Who paid”Inside a paid handler, paymentOf gives the payment that came with the request:
import { lotvsPay, paymentOf } from "@lotvs/pay";
app.get("/report", lotvsPay({ price: "0.10" }), (req, res) => { const payment = paymentOf(req); res.json({ report, for: payment.payer });});To keep a ledger, take every receipt as it happens:
lotvsPay({ price: "0.10", onPayment: async (receipt) => { await db.payments.insert(receipt); }, onFailure: (failure) => { log.warn(failure.stage, failure.reason, failure.charged); },});- Reference: every option, the networks and the errors
- How Lotvs Pay works: when the buyer is charged, and why