Payments

In production, Power Oracle charges for compute-bearing routes through x402 or L402.

Discovery endpoints remain free entry points.

Athlete read endpoints are also free. They are public and gated by possession of the athlete UUID rather than by x402, L402, or bearer auth.

Route Scope

GET /v1/health is free.
GET /v1/movements is free.
GET /v1/athletes/\{athlete_uuid\}/workouts is free.
GET /v1/athletes/\{athlete_uuid\}/workouts/\{workout_id\} is free.
GET /v1/athletes/\{athlete_uuid\}/curve is free.
GET /openapi.json is free.
POST /v1/compute-power is paid.
POST /v1/workouts/\{workout_id\}/revisions is paid.
POST /v1/workouts/\{workout_id\}/void is free.

Billing Boundary

Power Oracle now validates deterministic request problems before it asks for payment.

That means these failures stay free:

malformed JSON
schema validation errors
unsupported or unimplemented movement requests
invalid-unit and other deterministic non-compute validation failures
cheap revision precondition failures such as missing workouts or supersession conflicts

Only requests that pass those prechecks receive payment challenges.

Practical Challenge Flow

When a valid paid route requires payment, it returns:

HTTP 402 Payment Required
a PAYMENT-REQUIRED header for x402 clients
a WWW-Authenticate: L402 ... header for L402 clients

Example header shapes:

PAYMENT-REQUIRED: <x402 payment requirement payload>
WWW-Authenticate: L402 macaroon="<token>", invoice="<lightning invoice>"

The x402 header carries the exact-payment requirement for that request. The L402 header carries the Lightning invoice plus the macaroon token to reuse on retry.

What The Challenge Headers Mean

PAYMENT-REQUIRED carries the x402 payment requirement for the exact request.
WWW-Authenticate carries the L402 challenge for the exact request.

The client then:

reads the challenge header for the protocol it supports
satisfies the exact x402 requirement or pays the Lightning invoice
retries the same request with PAYMENT-SIGNATURE: <x402 proof> or Authorization: L402 <token>:<preimage>
reads PAYMENT-RESPONSE from the successful x402 response when applicable

Current Production Contract

POST /v1/compute-power: $0.10 per request
POST /v1/workouts/\{workout_id\}/revisions: $0.04 per request
x402 uses the published USD price directly as an exact-payment challenge
L402 invoices are sats derived from that same USD route price using a cached live BTC/USD quote
L402 quote refresh uses a 4-hour cache window; if the quote refresh fails after that window, the server continues using the stale cached quote and logs the stale-pricing condition
Successful x402-paid responses include PAYMENT-RESPONSE
Authorized x402 and L402 2xx and post-billable 4xx responses consume or settle the payment
Precheck failures do not challenge for or consume/settle payments
5xx responses do not consume or settle payments
If the live challenge or server behavior differs, treat the live server behavior as authoritative

Payment Request Headers

x402 retry format:

PAYMENT-SIGNATURE: <x402 proof>

Successful x402 responses also include:

PAYMENT-RESPONSE: <x402 settlement payload>

L402 retry format:

Authorization: L402 <token>:<preimage>

Integration Guidance

Treat payment as part of the normal compute and recompute flow, not as an edge case.
You should still validate obvious client-side issues before calling the paid routes.
The server will not challenge or charge for malformed or deterministically invalid requests.
Use GET /v1/payment-requirements as the human-readable price source and /openapi.json as the agent-readable source for both protocols.
Local development may disable payment, but production clients should assume payment is required.

For the rationale behind corrections and voiding, see Workout History And Corrections.

For end-to-end examples with curl, pseudocode, and a minimal Python client, see Calling Power Oracle from a Client.

If you need help using Power Oracle, visit Contact or email workcapacity.io@agentmail.to.