Orvion
Get started
Developer Guides
Core objects
Payment Receiving
Invoices
Billing
Collections
Payouts
Webhooks & events
Integrations
SDKs
Administration & security
Changelog & roadmap

API Reference

Beta

Complete API reference for protected routes endpoints, schemas, and response formats.

Dashboard Endpoints (JWT Auth)

These endpoints require JWT authentication and are used by the dashboard.

GET
/v1/billing/protected-routes
GET
/v1/billing/protected-routes/{id}
PATCH
/v1/billing/protected-routes/{id}
DELETE
/v1/billing/protected-routes/{id}

SDK Endpoints (API Key Auth)

These endpoints use API key authentication and are used by SDKs.

GET
/v1/protected-routes/routes
POST
/v1/protected-routes/routes/register
GET
/v1/protected-routes/match?path=...&method=...

Protected Route Schema

FieldTypeRequiredDescriptionExample
idstring
Optional
Unique route identifier (UUID)—
route_patternstring
Optional
URL pattern (e.g., /api/premium/*)—
methodstring
Optional
HTTP method (GET, POST, *, etc.)—
amountstring
Optional
Price per request (e.g., '0.10')—
currencystring
Optional
Currency code (USD, USDC, etc.)—
namestring?
Optional
Optional friendly name—
descriptionstring?
Optional
Description shown in 402 response—
statusstring
Optional
active or paused—
allow_anonymousboolean
Optional
Allow requests without customer ID—
sourcestring?
Optional
Origin: 'sdk-python-fastapi', 'dashboard', etc.—
receiver_config_idstring?
Optional
Optional payment receiver config—

402 Response Format

When a request requires payment, the SDK returns a 402 Payment Required response:

{
  "error": "Payment Required",
  "charge_id": "chg_01HXYZ123ABC",
  "amount": "0.10",
  "currency": "USD",
  "description": "Access to premium data endpoint",
  "x402_requirements": {
    "rail_config": {
      "scheme": "exact",
      "network": "solana-mainnet",
      "asset": "USDC",
      "pay_to_address": "...",
      "max_timeout_seconds": 3600
    },
    "amount": "0.10",
    "currency": "USD",
    "external_ref": "chg_01HXYZ123ABC"
  }
}

Request Examples

List Protected Routes

cURL
curl -X GET "https://api.orvion.sh/v1/billing/protected-routes" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"

Register a Route (SDK)

cURL
curl -X POST "https://api.orvion.sh/v1/protected-routes/routes/register" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "route_pattern": "/api/premium",
  "method": "GET",
  "amount": "0.10",
  "currency": "USDC",
  "name": "Premium API Access",
  "description": "Access to premium features"
}'

Match a Route

cURL
curl -X GET "https://api.orvion.sh/v1/protected-routes/match?path=/api/premium&method=GET" \
-H "Authorization: Bearer YOUR_API_KEY"

Related Documentation