HTTP API

X402

POST/admin/x402/cache/clear

Clear all pricing caches on this instance

POST
/admin/x402/cache/clear

Authorization

bearer_token
AuthorizationBearer <token>

In: header

Response Body

curl -X POST "https://example.com/admin/x402/cache/clear"
Empty
GET/admin/x402/preflight

Run go-live preflight against this server's live configuration

GET
/admin/x402/preflight

Authorization

bearer_token
AuthorizationBearer <token>

In: header

Response Body

application/json

curl -X GET "https://example.com/admin/x402/preflight"
{  "checks": [    {      "check": "string",      "detail": "string",      "passed": true,      "severity": "required"    }  ],  "enabled": true,  "facilitator_url": "string",  "mainnet": true,  "networks": [    "string"  ],  "ready": true}
GET/admin/x402/pricing

List price rules (optionally filtered by type or service)

GET
/admin/x402/pricing

Authorization

bearer_token
AuthorizationBearer <token>

In: header

Query Parameters

rule_type?string

Filter by rule type (default, service, endpoint)

service?string

Filter by service name

page?integer

Page number (1-based)

Formatint64
Range0 <= value
page_size?integer

Page size

Formatint64
Range0 <= value
sort_by?string

Sort field

sort_order?string

Sort order (asc or desc)

Value in

  • "asc"
  • "desc"

Response Body

application/json

curl -X GET "https://example.com/admin/x402/pricing"
{  "pagination": {    "has_more": true,    "page": 0,    "page_size": 0,    "total": 0  },  "rules": [    {      "amount_usd": "string",      "created_at": "2019-08-24T14:15:22Z",      "description": "string",      "discoverable": true,      "enabled": true,      "id": "string",      "method": "string",      "path": "string",      "rule_type": "default",      "service": "string",      "settle_mode": null,      "updated_at": "2019-08-24T14:15:22Z"    }  ]}
GET/admin/x402/pricing/default

Get the default price rule

GET
/admin/x402/pricing/default

Authorization

bearer_token
AuthorizationBearer <token>

In: header

Response Body

application/json

curl -X GET "https://example.com/admin/x402/pricing/default"
{  "amount_usd": "string",  "created_at": "2019-08-24T14:15:22Z",  "description": "string",  "discoverable": true,  "enabled": true,  "id": "string",  "method": "string",  "path": "string",  "rule_type": "default",  "service": "string",  "settle_mode": null,  "updated_at": "2019-08-24T14:15:22Z"}
DELETE/admin/x402/pricing/default

Delete the default price rule

DELETE
/admin/x402/pricing/default

Authorization

bearer_token
AuthorizationBearer <token>

In: header

Response Body

application/json

curl -X DELETE "https://example.com/admin/x402/pricing/default"
{  "deleted": true}
PUT/admin/x402/pricing/default

Create or replace the default price rule

PUT
/admin/x402/pricing/default

Authorization

bearer_token
AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Fields shared by every price rule write.

Response Body

application/json

curl -X PUT "https://example.com/admin/x402/pricing/default" \  -H "Content-Type: application/json" \  -d '{    "amount_usd": "string"  }'
{  "amount_usd": "string",  "created_at": "2019-08-24T14:15:22Z",  "description": "string",  "discoverable": true,  "enabled": true,  "id": "string",  "method": "string",  "path": "string",  "rule_type": "default",  "service": "string",  "settle_mode": null,  "updated_at": "2019-08-24T14:15:22Z"}
POST/admin/x402/pricing/endpoints

Create or replace an endpoint price rule

POST
/admin/x402/pricing/endpoints

Authorization

bearer_token
AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Create or replace an endpoint-level price rule. The owning service is derived from the path's first segment.

Response Body

application/json

curl -X POST "https://example.com/admin/x402/pricing/endpoints" \  -H "Content-Type: application/json" \  -d '{    "amount_usd": "string",    "method": "string",    "path": "string"  }'
{  "amount_usd": "string",  "created_at": "2019-08-24T14:15:22Z",  "description": "string",  "discoverable": true,  "enabled": true,  "id": "string",  "method": "string",  "path": "string",  "rule_type": "default",  "service": "string",  "settle_mode": null,  "updated_at": "2019-08-24T14:15:22Z"}
GET/admin/x402/pricing/endpoints/{method}/{endpoint_path}

Get an endpoint price rule

GET
/admin/x402/pricing/endpoints/{method}/{endpoint_path}

Authorization

bearer_token
AuthorizationBearer <token>

In: header

Path Parameters

method*string

HTTP method

endpoint_path*string

Router path template

Response Body

application/json

curl -X GET "https://example.com/admin/x402/pricing/endpoints/string/string"
{  "amount_usd": "string",  "created_at": "2019-08-24T14:15:22Z",  "description": "string",  "discoverable": true,  "enabled": true,  "id": "string",  "method": "string",  "path": "string",  "rule_type": "default",  "service": "string",  "settle_mode": null,  "updated_at": "2019-08-24T14:15:22Z"}
DELETE/admin/x402/pricing/endpoints/{method}/{endpoint_path}

Delete an endpoint price rule

DELETE
/admin/x402/pricing/endpoints/{method}/{endpoint_path}

Authorization

bearer_token
AuthorizationBearer <token>

In: header

Path Parameters

method*string

HTTP method

endpoint_path*string

Router path template

Response Body

application/json

curl -X DELETE "https://example.com/admin/x402/pricing/endpoints/string/string"
{  "deleted": true}
POST/admin/x402/pricing/services

Create or replace a service price rule

POST
/admin/x402/pricing/services

Authorization

bearer_token
AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Create or replace a service-level price rule.

Response Body

application/json

curl -X POST "https://example.com/admin/x402/pricing/services" \  -H "Content-Type: application/json" \  -d '{    "amount_usd": "string",    "service": "string"  }'
{  "amount_usd": "string",  "created_at": "2019-08-24T14:15:22Z",  "description": "string",  "discoverable": true,  "enabled": true,  "id": "string",  "method": "string",  "path": "string",  "rule_type": "default",  "service": "string",  "settle_mode": null,  "updated_at": "2019-08-24T14:15:22Z"}
GET/admin/x402/pricing/services/{service}

Get a service price rule

GET
/admin/x402/pricing/services/{service}

Authorization

bearer_token
AuthorizationBearer <token>

In: header

Path Parameters

service*string

Service name

Response Body

application/json

curl -X GET "https://example.com/admin/x402/pricing/services/string"
{  "amount_usd": "string",  "created_at": "2019-08-24T14:15:22Z",  "description": "string",  "discoverable": true,  "enabled": true,  "id": "string",  "method": "string",  "path": "string",  "rule_type": "default",  "service": "string",  "settle_mode": null,  "updated_at": "2019-08-24T14:15:22Z"}
DELETE/admin/x402/pricing/services/{service}

Delete a service price rule

DELETE
/admin/x402/pricing/services/{service}

Authorization

bearer_token
AuthorizationBearer <token>

In: header

Path Parameters

service*string

Service name

Response Body

application/json

curl -X DELETE "https://example.com/admin/x402/pricing/services/string"
{  "deleted": true}
PUT/admin/x402/pricing/services/{service}

Update a service price rule

PUT
/admin/x402/pricing/services/{service}

Authorization

bearer_token
AuthorizationBearer <token>

In: header

Path Parameters

service*string

Service name

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Fields shared by every price rule write.

Response Body

application/json

curl -X PUT "https://example.com/admin/x402/pricing/services/string" \  -H "Content-Type: application/json" \  -d '{    "amount_usd": "string"  }'
{  "amount_usd": "string",  "created_at": "2019-08-24T14:15:22Z",  "description": "string",  "discoverable": true,  "enabled": true,  "id": "string",  "method": "string",  "path": "string",  "rule_type": "default",  "service": "string",  "settle_mode": null,  "updated_at": "2019-08-24T14:15:22Z"}
GET/api/v1/x402/balance

The calling principal's prepaid balance

GET
/api/v1/x402/balance

Authorization

bearer_token
AuthorizationBearer <token>

In: header

Response Body

application/json

curl -X GET "https://example.com/api/v1/x402/balance"
{  "balance_atomic": 0,  "balance_usd": "string"}
GET/api/v1/x402/quote

Effective price the calling principal would pay for one route

GET
/api/v1/x402/quote

Authorization

bearer_token
AuthorizationBearer <token>

In: header

Query Parameters

method*string

HTTP method (case-insensitive)

path*string

Router path template or concrete path (e.g. "/kv/{key}")

Response Body

application/json

curl -X GET "https://example.com/api/v1/x402/quote?method=string&path=string"
{  "amount_usd": "string",  "payable": true,  "rule_id": "string",  "settle_mode": null}
GET/api/v1/x402/status

Deployment payment status for the calling principal

GET
/api/v1/x402/status

Authorization

bearer_token
AuthorizationBearer <token>

In: header

Response Body

application/json

curl -X GET "https://example.com/api/v1/x402/status"
{  "enabled": true,  "networks": [    "string"  ],  "settle_mode_default": "verify_then_settle_after"}
POST/api/v1/x402/topup

Top up the prepaid balance with one x402 payment. Without a payment header this responds 402 with the challenge for exactly the requested amount; with one, the payment is verified and settled on-chain before the balance is credited.

POST
/api/v1/x402/topup

Authorization

bearer_token
AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Request to top up the prepaid x402 balance.

Response Body

application/json

curl -X POST "https://example.com/api/v1/x402/topup" \  -H "Content-Type: application/json" \  -d '{    "amount_usd": "string"  }'
{  "balance_atomic": 0,  "balance_usd": "string",  "credited_usd": "string",  "transaction": "string"}
GET/x402/catalog

Public discovery catalog of paid endpoints

GET
/x402/catalog

Response Body

application/json

curl -X GET "https://example.com/x402/catalog"
{  "enabled": true,  "items": [    {      "accepts": [        null      ],      "accepts_v2": [        null      ],      "amount_usd": "string",      "description": "string",      "method": "string",      "path": "string",      "resource": "string",      "service": "string"    }  ]}
POST/x402/session

Buy a short-lived API session with one x402 payment: the paying wallet becomes the principal (its own tenant), no signup. Without a payment header this responds 402 with the session-price challenge; with one, the payment is verified and settled on-chain before the token is minted.

POST
/x402/session

Response Body

application/json

curl -X POST "https://example.com/x402/session"
{  "expires_in": 0,  "principal": "string",  "token": "string",  "token_type": "string"}

WebSocket

Authenticated WebSocket connectivity

On this page

Clear all pricing caches on this instanceRun go-live preflight against this server's live configurationList price rules (optionally filtered by type or service)Get the default price ruleDelete the default price ruleCreate or replace the default price ruleCreate or replace an endpoint price ruleGet an endpoint price ruleDelete an endpoint price ruleCreate or replace a service price ruleGet a service price ruleDelete a service price ruleUpdate a service price ruleThe calling principal's prepaid balanceEffective price the calling principal would pay for one routeDeployment payment status for the calling principalTop up the prepaid balance with one x402 payment. Without a payment header this responds 402 with the challenge for exactly the requested amount; with one, the payment is verified and settled on-chain before the balance is credited.Public discovery catalog of paid endpointsBuy a short-lived API session with one x402 payment: the paying wallet becomes the principal (its own tenant), no signup. Without a payment header this responds 402 with the session-price challenge; with one, the payment is verified and settled on-chain before the token is minted.