Orvion
Get started
Developer Guides
Core objects
Payment Receiving
Invoices
Billing
Collections
Payouts
Webhooks & events
SDKs & examples
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
idstringOptionalUnique route identifier (UUID)—
route_patternstringOptionalURL pattern (e.g., /api/premium/*)—
methodstringOptionalHTTP method (GET, POST, *, etc.)—
amountstringOptionalPrice per request (e.g., '0.10')—
currencystringOptionalCurrency code (USD, USDC, etc.)—
namestring?OptionalOptional friendly name—
descriptionstring?OptionalDescription shown in 402 response—
statusstringOptionalactive or paused—
allow_anonymousbooleanOptionalAllow requests without customer ID—
sourcestring?OptionalOrigin: 'sdk-python-fastapi', 'dashboard', etc.—
receiver_config_idstring?OptionalOptional 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