pay-kit

<div align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://github.com/solana-foundation/pay-kit/raw/main/docs/assets/banner-main-dark.png"> <source media="(prefers-color-scheme: light)" srcset="https://github.com/solana-foundation/pay-kit/raw/main/docs/assets/banner-main-light.png"> <img alt="Solana Pay Kit" width="100%" src="https://github.com/solana-foundation/pay-kit/raw/main/docs/assets/banner-main-light.png"> </picture> </div> <p align="center"> <a href="https://skills.sh/solana-foundation/pay"><img alt="skills.sh" src="https://skills.sh/b/solana-foundation/pay"></a> <a href="https://x402.org"><img alt="x402" src="https://img.shields.io/badge/protocol-x402-black"></a> <a href="https://paymentauth.org"><img alt="MPP" src="https://img.shields.io/badge/protocol-MPP-black"></a> <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-green"></a> </p> <p align="center"> <b>Add a stablecoin paywall to any HTTP route.</b><br/> In TypeScript, Rust, Go, Python, Ruby, PHP, Lua, Kotlin, or Swift. </p> --- ## Why stablecoins? Stablecoins are digital dollars (USDC, USDT, PYUSD, EURC, …) that move on public payment rails. For a developer building an API, a SaaS, or an agent that needs to pay for things, they unlock a few properties that classical card networks can't match: - **No middleman.** Funds settle directly from payer to recipient. No gateway, no acquirer, no PSP holding the money for 2–30 days. - **No 2.9% + 30¢.** Network fees are measured in fractions of a cent, not percentage points. Micro-transactions stop being a rounding error. - **No chargebacks.** Payments are final once confirmed on-chain. Refunds happen because you choose to send one, not because a card network reversed it 90 days later. - **No accounts to open.** Anyone with a wallet — a person, a script, an agent — can pay. No KYC dance before the first dollar moves. - **Programmable.** Splits, fees, sponsored gas, subscriptions, refunds — all expressible as a transaction your server constructs. ## Why Solana? Solana is the most-used blockchain for payments today, and it's the one this kit is built on. - **~200ms settlement.** A buyer signs, your server sees the confirmation before the next render frame. - **~$0.0013 median fee.** Stable, even when the network is busy. Predictable enough to charge $0.001 for an API call without losing money on the transfer. - **~$2T in stablecoin transfers per quarter.** It's the rail Visa, PayPal, Stripe, and Western Union have all plugged into. - **100% of the top 10 stablecoins.** USDC, USDT, PYUSD, EURC — pick the asset that matches your accounting. See [payments.org](https://payments.org) for the long-form pitch. ## What this repo gives you Two open protocols, sharing one mental model: an HTTP server replies `402 Payment Required` with a challenge, the client pays, and the same request is replayed with a proof of payment. The kit ships server and client SDKs for both. - **[x402](https://x402.org)** — The minimalist take. Three-step handshake (request → 402 → pay → replay), single-recipient, the facilitator pays the network fee. Best for "one endpoint, one price, one wallet." - **[MPP](https://paymentauth.org)** — The richer take. Same 402 handshake, but the challenge carries an intent that supports multi-recipient splits, server-side fee accounting, and a separate fee-payer signer. Best for marketplaces, platform fees, and gasless flows. ```mermaid sequenceDiagram autonumber participant C as Client / Agent participant S as Your API participant Sol as Solana C->>S: GET /api/report S-->>C: 402 Payment Required<br/>{ amount: 0.10 USDC, pay_to, nonce } C->>Sol: sign & submit USDC transfer Sol-->>C: tx signature C->>S: GET /api/report<br/>X-PAYMENT: <signed proof> S->>Sol: verify settlement Sol-->>S: confirmed S-->>C: 200 OK + X-PAYMENT-RESPONSE ``` Live playground: [402.surfnet.dev](https://402.surfnet.dev). ## Quick start A paid endpoint in seven lines of Ruby. Save as `config.ru`, `bundle exec rackup`, and you have a stablecoin paywall. ```ruby # config.ru require "sinatra/base" require "solana_pay_kit" class App < Sinatra::Base get("/report") do require_payment! usd("0.10") "premium content" end end run App ``` Call it from any HTTP client. Without payment you get a 402; with the [`pay`](https://github.com/solana-foundation/pay) CLI the wallet pops Touch ID, signs a USDC transfer, and replays the request: ```bash brew install pay # or: npm install -g @solana/pay curl -i http://127.0.0.1:4567/report # → 402 Payment Required pay curl -i http://127.0.0.1:4567/report # → 200 OK + receipt ``` The same surface is available in nine languages — server-side, client-side, or both: | Language | Server | Client | |------------|:------:|:------:| | [TypeScript](typescript/) | ✅ | ✅ | | [Rust](rust/) | ✅ | ✅ | | [Go](go/) | ✅ | ✅ | | [Python](python/) | ✅ | ✅ | | [Ruby](ruby/) | ✅ | — | | [PHP](php/) | ✅ | — | | [Lua](lua/) | ✅ | — | | [Kotlin](kotlin/) | — | ✅ | | [Swift](swift/) | — | ✅ | Each language directory has its own README with framework-specific snippets (Sinatra/Rails, Express, FastAPI, Axum, Gin, …). ## Playground The [`playground/`](playground/) directory is a local web app that exercises every primitive in the kit end to end against the Solana Payment Sandbox (a hosted test validator — no real funds): single charges with multi-recipient splits, metered sessions that stream content against off-chain vouchers and settle the channel on-chain, subscriptions, and x402 endpoints. Generate a throwaway wallet in the browser, fund it from the built-in faucet, and watch each step of the 402 handshake — challenge, signing, broadcast, settlement — in the request timeline and event log, with a receipt link for every settled transaction. ```bash cd playground pnpm install pnpm dev # server on :3000, web app on :5173 ```  ## License MIT