Skip to content

Lotvs Pay quickstart

Terminal window
npm install @lotvs/pay

Node 20 or later. The package is an ES module, so use import. It has no dependencies, and its TypeScript types are included.

  1. Say where the money goes. Payments arrive at an address you control. By default that is a Solana address:

    .env
    LOTVS_PAY_TO=YourSolanaAddress

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

  2. 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);
  3. Watch it answer. Ask without paying and you get the price back:

    Terminal window
    curl -i http://localhost:3000/report
    HTTP/1.1 402 Payment Required
    PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6Mi...
  4. Describe what you sell. description is what an agent reads before it decides to pay:

    lotvsPay({ price: "0.10", description: "Today's market report" });

One setting moves everything to a test network, where the dollars are not real:

Terminal window
LOTVS_PAY_NETWORK=solana-devnet # or base-sepolia

Prices, 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:

Terminal window
curl -i https://pay.lotvs.ai/api/demo/fortune

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