@paytoll/sdk

Developer toolkit for accepting machine payments on Solana via the Machine Payments Protocol (MPP).

Install

npm install @paytoll/sdk

Quick Start

1. Create config

npx paytoll init

This creates paytoll.config.ts:

import { defineConfig } from '@paytoll/sdk'

export default defineConfig({
  recipient: 'YOUR_SOLANA_WALLET_ADDRESS',
  network: 'devnet',
  endpoints: [
    {
      path: '/api/search',
      price: '0.01',
      currency: 'USDC',
      mode: 'charge',
    },
  ],
})

2. Add middleware

Express:

import express from 'express'
import { paytoll } from '@paytoll/sdk/express'
import config from './paytoll.config'

const app = express()
app.use(paytoll(config))

app.get('/api/search', (req, res) => {
  // This only runs after payment is verified
  // Access payment info via req.paytoll
  console.log(`Paid by: ${req.paytoll?.payer}`)
  res.json({ results: ['result1', 'result2'] })
})

app.listen(3000)

Hono:

import { Hono } from 'hono'
import { paytoll } from '@paytoll/sdk/hono'
import config from './paytoll.config'

const app = new Hono()
app.use('*', paytoll(config))

app.get('/api/search', (c) => {
  const { payer, amount } = c.get('paytoll')
  return c.json({ results: ['result1', 'result2'] })
})

export default app

3. Gate a single route (no config file)

import { paytollRoute } from '@paytoll/sdk/express'

app.use(
  '/api/premium',
  paytollRoute({
    recipient: 'YOUR_WALLET',
    price: '0.05',
    currency: 'USDC',
  })
)

How It Works

Agent sends GET /api/search
PayToll middleware returns 402 Payment Required with a challenge
Agent signs a Solana transaction and retries with Authorization: Payment header
PayToll verifies payment on-chain and passes the request to your handler
Your handler runs and the response includes a Payment-Receipt header

Payment Modes

Charge — One-time payment per request. Best for discrete API calls.

Session — Streaming payment channel with micropayments. Best for metered/streaming access.

CLI

npx paytoll init          # Create config file
npx paytoll dev           # Start dev server (coming soon)
npx paytoll test [path]   # Simulate payment (coming soon)
npx paytoll status        # Show stats (coming soon)

Configuration

Option	Type	Default	Description
`recipient`	`string`	—	Solana wallet address (required)
`network`	`string`	`'devnet'`	`'devnet'` or `'mainnet-beta'`
`endpoints`	`array`	`[]`	Endpoint configs
`feePayer`	`string?`	—	Base58 keypair for fee sponsorship
`rpcUrl`	`string?`	auto	Custom Solana RPC URL
`secretKey`	`string?`	auto	HMAC key for challenge signing

Endpoint Config

Option	Type	Description
`path`	`string`	URL path to gate
`price`	`string`	Amount (e.g. `'0.01'`)
`currency`	`string`	`'USDC'`, `'SOL'`, or mint address
`mode`	`string`	`'charge'` or `'session'`
`meter`	`string?`	Session meter name

Status

This is v0.1.0 — the middleware framework, types, config, and CLI scaffold are functional. On-chain payment verification is pending integration with @solana/mpp as the spec stabilizes.

License

MIT