mpay

TypeScript SDK for the Machine Payments Protocol.

Documentation

Full documentation, API reference, and guides are available at machinepayments.dev/sdk/typescript.

Install

npm i mpay

pnpm add mpay

bun add mpay

Quick Start

Server

import { Mpay, tempo } from 'mpay/server'

const mpay = Mpay.create({
  methods: [
    tempo({
      currency: '0x20c0000000000000000000000000000000000001',
      recipient: '0x742d35Cc6634c0532925a3b844bC9e7595F8fE00',
    }),
  ],
})

export async function handler(request: Request) {
  const response = await mpay.charge({ amount: '1' })(request)

  if (response.status === 402) return response.challenge

  return response.withReceipt(Response.json({ data: '...' }))
}

Client

import { privateKeyToAccount } from 'viem/accounts'
import { Mpay, tempo } from 'mpay/client'

Mpay.create({
  methods: [tempo({ account: privateKeyToAccount('0x...') })],
})

// Global fetch now handles 402 automatically
const res = await fetch('https://api.example.com/resource')

Examples

| Example | Description | |---------|-------------| | basic | Payment-gated Fortune Teller API | | session/multi-fetch | Multiple paid requests over a single payment channel | | session/sse | Pay-per-token LLM streaming with SSE |

npx gitpick wevm/mpay/examples/basic

pnpx gitpick wevm/mpay/examples/basic

bunx gitpick wevm/mpay/examples/basic

CLI

mpay includes a basic CLI for making HTTP requests with automatic payment handling.

# create account - stored in keychain, autofunded on testnet
pnpm mpay account create

# make request - automatic payment handling, curl-like api
pnpm mpay example.com

mpay/0.1.0

Usage:
  $ mpay [url]

Commands:
  [url]             Make HTTP request with automatic payment
  account [action]  Manage accounts (create, default, delete, fund, list, view)

For more info, run any command with the `--help` flag:
  $ mpay --help
  $ mpay account --help

Actions:
  create   Create new account
  default  Set default account
  delete   Delete account
  fund     Fund account with testnet tokens
  list     List all accounts
  view     View account address

Options:
  -a, --account <name>   Account name (env: MPAY_ACCOUNT)
  -d, --data <data>      Send request body (implies POST unless -X is set)
  -f, --fail             Fail silently on HTTP errors (exit 22)
  -i, --include          Include response headers in output
  -k, --insecure         Skip TLS certificate verification (true for localhost/.local)
  -r, --rpc-url <url>    RPC endpoint, defaults to public RPC for chain (env: MPAY_RPC_URL)
  -s, --silent           Silent mode (suppress progress and info)
  -v, --verbose          Show request/response headers
  -A, --user-agent <ua>  Set User-Agent header
  -H, --header <header>  Add header (repeatable)
  -L, --location         Follow redirects
  -X, --method <method>  HTTP method
  --channel <id>         Reuse existing stream channel ID
  --deposit <amount>     Deposit amount for stream payments (human-readable units)
  --json <json>          Send JSON body (sets Content-Type and Accept, implies POST)
  --yes                  Skip confirmation prompts
  -V, --version          Display version number
  -h, --help             Display this message

Examples:
mpay example.com/content
mpay example.com/api --json '{"key":"value"}'

You can also install globally to use the mpay CLI from anywhere:

npm i -g mpay

pnpm add -g mpay

bun add -g mpay

Payments Proxy

mpay exports a Proxy server handler so that you can create or define a 402-protected payments proxy for any API.

import { openai, stripe, Proxy } from 'mpay/proxy'
import { Mpay, tempo } from 'mpay/server'

const mpay = Mpay.create({ methods: [tempo()] })

const proxy = Proxy.create({
  services: [
    openai({
      apiKey: 'sk-...',
      routes: {
        'POST /v1/chat/completions': mpay.charge({ amount: '0.05' }),
        'POST /v1/completions': mpay.stream({ amount: '0.0001' }),
        'GET /v1/models': mpay.free(),
      },
    }),
    stripe({
      apiKey: 'sk-...',
      routes: {
        'POST /v1/charges': mpay.charge({ amount: '0.01' }),
        'GET /v1/customers/:id': mpay.free(),
      },
    }),
  ],
})

createServer(proxy.listener) // Node.js
Bun.serve(proxy) // Bun
Deno.serve(proxy.fetch) // Deno
app.use(proxy.listener) // Express
app.all('*', (c) => proxy.fetch(c.req.raw)) // Hono
app.all('*', (c) => proxy.fetch(c.request)) // Elysia
export const GET = proxy.fetch // Next.js
export const POST = proxy.fetch // Next.js

This exposes the following routes:

| Route | Pricing | |-------|---------| | POST /openai/v1/chat/completions | charge $0.005 | | POST /openai/v1/completions | stream $0.0001 per token | | GET /openai/v1/models | free | | POST /stripe/v1/charges | charge $0.01 | | GET /stripe/v1/customers/:id | free |

Protocol

Built on the "Payment" HTTP Authentication Scheme. See payment-auth-spec for the full specification.

License

MIT