Proxy Configuration

The L402 Proxy allows you to monetize any API - yours or third-party - by creating a payment-gated reverse proxy.

Overview

The proxy sits between clients and target APIs:

Client → L402 Proxy → Target API
           │
           └─ Requires Lightning payment

Use cases:

Monetize your own APIs without modifying them
Resell third-party APIs with a markup
Create premium access to public APIs
Rate-limit expensive APIs via micropayments

Creating a Proxy

Via API

curl -X POST https://api.lightningenable.com/api/proxy \
  -H "X-API-Key: your-merchant-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Weather API",
    "targetBaseUrl": "https://api.weather.com/v1",
    "defaultPriceSats": 10,
    "description": "Weather data with Lightning payments"
  }'

Response:

{
  "proxyId": "premium-weather-api-a1b2",
  "name": "Premium Weather API",
  "targetBaseUrl": "https://api.weather.com/v1",
  "defaultPriceSats": 10,
  "isActive": true,
  "createdAt": "2024-12-29T12:00:00Z"
}

Proxy Endpoint

Your proxy is now available at:

https://api.lightningenable.com/l402/proxy/{proxyId}/{path}

For example:

https://api.lightningenable.com/l402/proxy/premium-weather-api-a1b2/forecast?city=nyc

Configuration Options

Full Configuration

{
  "name": "Premium Weather API",
  "description": "Weather data via Lightning payments",
  "targetBaseUrl": "https://api.weather.com/v1",
  "defaultPriceSats": 10,
  "isActive": true,
  "authHeader": "X-Api-Key",
  "authValue": "your-weather-api-key",
  "timeout": 30,
  "allowedMethods": ["GET", "POST"],
  "allowedPaths": ["/forecast/*", "/current/*"],
  "blockedPaths": ["/admin/*"]
}

Configuration Reference

Field	Type	Required	Description
`name`	string	Yes	Display name for the proxy
`targetBaseUrl`	string	Yes	Base URL of target API
`defaultPriceSats`	int	Yes	Default price per request
`description`	string	No	Proxy description
`isActive`	bool	No	Enable/disable proxy (default: true)
`authHeader`	string	No	Header name for target API auth
`authValue`	string	No	Header value for target API auth
`timeout`	int	No	Request timeout in seconds (default: 30)
`allowedMethods`	array	No	Allowed HTTP methods
`allowedPaths`	array	No	Path whitelist (glob patterns)
`blockedPaths`	array	No	Path blacklist (glob patterns)

Endpoint-Specific Pricing

Set different prices for different endpoints:

curl -X POST https://api.lightningenable.com/api/proxy/{proxyId}/pricing \
  -H "X-API-Key: your-merchant-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "pathPattern": "/forecast/7day",
    "priceSats": 50,
    "description": "7-day forecast (premium)"
  }'

Multiple Price Tiers

# Add pricing for different endpoints
curl -X POST .../pricing -d '{"pathPattern": "/current/*", "priceSats": 5}'
curl -X POST .../pricing -d '{"pathPattern": "/forecast/1day", "priceSats": 10}'
curl -X POST .../pricing -d '{"pathPattern": "/forecast/7day", "priceSats": 50}'
curl -X POST .../pricing -d '{"pathPattern": "/historical/*", "priceSats": 100}'

Price Matching Priority

Prices are matched in order of specificity:

Exact path match
Glob pattern match (most specific first)
Default proxy price

Using the Proxy

Request Flow

Client requests proxy endpoint (no auth):

curl https://api.lightningenable.com/l402/proxy/premium-weather-api-a1b2/forecast?city=nyc

Proxy returns 402 with invoice:

{
  "error": "Payment Required",
  "l402": {
    "macaroon": "AgEL...",
    "invoice": "lnbc100n1p...",
    "amount_sats": 10
  }
}

Client pays invoice, gets preimage
Client retries with L402 credential:

curl https://api.lightningenable.com/l402/proxy/premium-weather-api-a1b2/forecast?city=nyc \
  -H "Authorization: L402 AgEL...:abc123..."

Proxy forwards request to target, returns response:

{
  "city": "New York",
  "forecast": [...]
}

Proxy Management

List Your Proxies

curl https://api.lightningenable.com/api/proxy \
  -H "X-API-Key: your-merchant-api-key"

Get Proxy Details

curl https://api.lightningenable.com/api/proxy/{proxyId} \
  -H "X-API-Key: your-merchant-api-key"

Update Proxy

curl -X PUT https://api.lightningenable.com/api/proxy/{proxyId} \
  -H "X-API-Key: your-merchant-api-key" \
  -d '{"defaultPriceSats": 20}'

Delete Proxy

curl -X DELETE https://api.lightningenable.com/api/proxy/{proxyId} \
  -H "X-API-Key: your-merchant-api-key"

Target API Authentication

Header-Based Auth

{
  "authHeader": "Authorization",
  "authValue": "Bearer your-api-token"
}

API Key Header

{
  "authHeader": "X-Api-Key",
  "authValue": "your-api-key"
}

Query Parameter Auth

For APIs requiring query parameter auth, include in target URL:

{
  "targetBaseUrl": "https://api.example.com/v1?apikey=your-key"
}

note

Auth credentials are stored encrypted and never exposed to clients.

Analytics

Get Proxy Analytics

curl https://api.lightningenable.com/api/proxy/{proxyId}/analytics \
  -H "X-API-Key: your-merchant-api-key"

Response:

{
  "proxyId": "premium-weather-api-a1b2",
  "period": "last_30_days",
  "totalRequests": 5234,
  "totalSatsEarned": 52340,
  "topPaths": [
    { "path": "/forecast/7day", "requests": 2341, "sats": 23410 },
    { "path": "/current/conditions", "requests": 1892, "sats": 9460 }
  ]
}

Testing Proxy

Test Target Reachability

curl -X POST https://api.lightningenable.com/api/proxy/{proxyId}/test \
  -H "X-API-Key: your-merchant-api-key"

Response:

{
  "success": true,
  "responseTime": 234,
  "statusCode": 200
}

Test with Specific Path

curl -X POST .../test \
  -d '{"testPath": "/forecast?city=nyc"}'

Example Configurations

OpenAI API Proxy

{
  "name": "GPT-4 Proxy",
  "targetBaseUrl": "https://api.openai.com/v1",
  "defaultPriceSats": 100,
  "authHeader": "Authorization",
  "authValue": "Bearer sk-...",
  "allowedPaths": ["/chat/completions"],
  "allowedMethods": ["POST"]
}

Endpoint pricing:

[
  { "pathPattern": "/chat/completions", "priceSats": 500 }
]

Weather API Proxy

{
  "name": "Weather Data",
  "targetBaseUrl": "https://api.weatherapi.com/v1",
  "defaultPriceSats": 5,
  "authHeader": "key",
  "authValue": "your-weather-key"
}

Stock Data Proxy

{
  "name": "Stock Market Data",
  "targetBaseUrl": "https://api.polygon.io/v2",
  "defaultPriceSats": 10,
  "authHeader": "Authorization",
  "authValue": "Bearer your-polygon-key",
  "allowedPaths": ["/aggs/*", "/ticker/*"]
}

Error Handling

Proxy Errors

Error	Cause	Solution
`proxy_not_found`	Invalid proxyId	Check proxy ID
`proxy_inactive`	Proxy disabled	Reactivate proxy
`target_unreachable`	Target API down	Check target URL
`target_timeout`	Target too slow	Increase timeout
`path_not_allowed`	Path blocked	Check allowedPaths

Client Errors

Error	Cause	Solution
402	Payment required	Pay invoice
401	Invalid L402	Check credential format
403	Token expired	Get new token

Best Practices

Security

Store target API credentials securely
Use allowedPaths to restrict access
Block sensitive paths (/admin, /internal)
Monitor usage for abuse

Pricing

Research target API costs
Add reasonable markup (20-50%)
Consider volume discounts
Price based on value, not cost

Reliability

Set appropriate timeouts
Handle target API errors gracefully
Monitor target API availability
Have fallback targets if possible

Next Steps

API Reference - Complete L402 API docs
How It Works - Technical details
FAQ - Common questions

Overview​

Creating a Proxy​

Via API​

Proxy Endpoint​

Configuration Options​

Full Configuration​

Configuration Reference​

Endpoint-Specific Pricing​

Multiple Price Tiers​

Price Matching Priority​

Using the Proxy​

Request Flow​

Proxy Management​

List Your Proxies​

Get Proxy Details​

Update Proxy​

Delete Proxy​

Target API Authentication​

Header-Based Auth​

API Key Header​

Query Parameter Auth​

Analytics​

Get Proxy Analytics​

Testing Proxy​

Test Target Reachability​

Test with Specific Path​

Example Configurations​

OpenAI API Proxy​

Weather API Proxy​

Stock Data Proxy​

Error Handling​

Proxy Errors​

Client Errors​

Best Practices​

Security​

Pricing​

Reliability​

Next Steps​

Overview

Creating a Proxy

Via API

Proxy Endpoint

Configuration Options

Full Configuration

Configuration Reference

Endpoint-Specific Pricing

Multiple Price Tiers

Price Matching Priority

Using the Proxy

Request Flow

Proxy Management

List Your Proxies

Get Proxy Details

Update Proxy

Delete Proxy

Target API Authentication

Header-Based Auth

API Key Header

Query Parameter Auth

Analytics

Get Proxy Analytics

Testing Proxy

Test Target Reachability

Test with Specific Path

Example Configurations

OpenAI API Proxy

Weather API Proxy

Stock Data Proxy

Error Handling

Proxy Errors

Client Errors

Best Practices

Security

Pricing

Reliability

Next Steps