内容
# paygate-402
> Turn any API or MCP server into a paid service
## table of contents
- [install](#install)
- [usage](#usage)
- [api](#api)
- [configuration](#configuration)
- [payment providers](#payment-providers)
- [http 402](#http-402)
- [contributing](#contributing)
- [license](#license)
## install
```bash
npm install paygate-402
```
## usage
### wrap an existing API
```typescript
import { PayGate } from 'paygate-402';
const paygate = new PayGate({
provider: 'stripe',
apiKey: process.env.STRIPE_KEY,
pricing: {
perRequest: 0.01,
perToken: 0.0001
}
});
// wrap your express app
app.use(paygate.middleware());
// or wrap specific routes
app.get('/api/premium', paygate.protect(), (req, res) => {
res.json({ data: 'premium content' });
});
```
### wrap an MCP server
```typescript
import { MCPPayGate } from 'paygate-402/mcp';
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
const server = new Server({
name: 'my-mcp-server',
version: '1.0.0'
});
const paygate = new MCPPayGate({
provider: 'stripe',
apiKey: process.env.STRIPE_KEY,
pricing: {
perTool: {
'expensive_tool': 0.10,
'cheap_tool': 0.01
}
}
});
paygate.wrap(server);
```
### client usage
```typescript
import axios from 'axios';
const response = await axios.get('https://api.example.com/premium', {
headers: {
'Authorization': 'Bearer YOUR_PAYMENT_TOKEN'
}
});
// handle 402 Payment Required
if (response.status === 402) {
const paymentUrl = response.headers['payment-url'];
console.log('Payment required:', paymentUrl);
}
```
## api
### `PayGate(options)`
Creates a new payment gateway instance.
**Options:**
| Option | Type | Description |
|--------|------|-------------|
| `provider` | `string` | Payment provider (`'stripe'`, `'paypal'`, `'lightning'`) |
| `apiKey` | `string` | Provider API key |
| `pricing` | `PricingConfig` | Pricing configuration |
| `allowCredits` | `boolean` | Allow prepaid credits (default: `true`) |
| `quotaLimits` | `QuotaConfig` | Optional rate limits per user |
### `paygate.middleware()`
Returns Express middleware that intercepts requests and enforces payment.
### `paygate.protect(options?)`
Returns middleware for protecting specific routes.
**Options:**
| Option | Type | Description |
|--------|------|-------------|
| `price` | `number` | Override default price for this route |
| `creditsRequired` | `number` | Require specific credit amount |
### `paygate.createPaymentToken(userId, credits)`
Generates a payment token for a user with prepaid credits.
**Returns:** `Promise<string>`
### `paygate.checkBalance(token)`
Checks remaining balance for a payment token.
**Returns:** `Promise<{ credits: number, spent: number }>`
## configuration
### pricing models
```typescript
// per-request pricing
{
pricing: {
perRequest: 0.05
}
}
// token-based pricing (for LLM APIs)
{
pricing: {
perToken: 0.0001,
perInputToken: 0.00005,
perOutputToken: 0.00015
}
}
// route-specific pricing
{
pricing: {
routes: {
'/api/basic': 0.01,
'/api/premium': 0.10,
'/api/enterprise': 1.00
}
}
}
// credit bundles
{
pricing: {
bundles: [
{ credits: 100, price: 9.99 },
{ credits: 500, price: 44.99 },
{ credits: 1000, price: 79.99 }
]
}
}
```
## payment providers
### stripe
```typescript
{
provider: 'stripe',
apiKey: process.env.STRIPE_SECRET_KEY,
webhookSecret: process.env.STRIPE_WEBHOOK_SECRET
}
```
### paypal
```typescript
{
provider: 'paypal',
clientId: process.env.PAYPAL_CLIENT_ID,
clientSecret: process.env.PAYPAL_CLIENT_SECRET,
sandbox: true
}
```
### lightning network
```typescript
{
provider: 'lightning',
lndHost: process.env.LND_HOST,
macaroon: process.env.LND_MACAROON,
cert: process.env.LND_CERT
}
```
## http 402
This project uses HTTP status code 402 (Payment Required) as defined in RFC 7231. When a request requires payment, the server responds with:
```http
HTTP/1.1 402 Payment Required
Payment-URL: https://pay.example.com/checkout/xyz123
Payment-Amount: 0.05
Payment-Currency: USD
Content-Type: application/json
{
"error": "payment_required",
"amount": 0.05,
"currency": "USD",
"payment_url": "https://pay.example.com/checkout/xyz123"
}
```
## contributing
PRs welcome. Open an issue first for big changes.
Run tests:
```bash
npm test
```
## license
MIT
MCP 市场