Calling Power Oracle from a Client

Practical curl, pseudocode, and Python guidance for calling Power Oracle and handling x402 or L402 payment.

This page is the operational client guide. Use it when you need the practical path from discovery to a successful paid compute call.

Free Discovery Calls

You can discover the service without payment.

Health

curl https://api.workcapacity.io/v1/health

OpenAPI Schema

curl https://api.workcapacity.io/openapi.json

Movements

curl https://api.workcapacity.io/v1/movements

Paid Compute Flow

Read /.well-known/api-catalog.
Call GET /v1/movements.
Validate the movement names and required inputs you plan to send.
Send POST /v1/compute-power.
If the server returns 402, inspect the payment challenge headers.
Choose the protocol your client supports.
Retry with PAYMENT-SIGNATURE: <x402 proof> or Authorization: L402 <token>:<preimage>.
Read PAYMENT-RESPONSE from the successful x402 response when applicable.

What The 402 Response Looks Like

HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: <x402 payment requirement payload>
WWW-Authenticate: L402 macaroon="<token>", invoice="<lightning invoice>"
Content-Type: application/json

{"detail":"Payment required"}

Important Notes

x402 retry format is PAYMENT-SIGNATURE: <x402 proof>.
L402 retry format is Authorization: L402 <token>:<preimage>.
Successful x402 responses also include PAYMENT-RESPONSE.
Read exact pricing from GET /v1/payment-requirements.
x402 uses the published USD price directly. L402 uses sats derived from the same USD price with a cached live BTC/USD quote.
Authorized client-error responses still settle or consume payments after the billable boundary.
If the live challenge or server behavior differs, treat the live server behavior as authoritative.

Minimal curl Flow

First attempt

curl https://api.workcapacity.io/v1/compute-power \
  -H 'Content-Type: application/json' \
  -d @payload.json

Retry after x402 payment

curl https://api.workcapacity.io/v1/compute-power \
  -H 'Content-Type: application/json' \
  -H 'PAYMENT-SIGNATURE: <x402 proof>' \
  -d @payload.json

Retry after L402 payment

curl https://api.workcapacity.io/v1/compute-power \
  -H 'Content-Type: application/json' \
  -H 'Authorization: L402 <token>:<preimage>' \
  -d @payload.json

Pseudocode

catalog = GET /.well-known/api-catalog
schema = GET /openapi.json
movements = GET /v1/movements
payload = build_valid_payload(schema, movements, workout_input)

response = POST /v1/compute-power(payload)

if response.status == 402:
  if "PAYMENT-REQUIRED" in response.headers:
    requirement = parse_x402_requirement(response.headers["PAYMENT-REQUIRED"])
    proof = build_x402_proof(requirement)
    response = POST /v1/compute-power(payload, PAYMENT-SIGNATURE=proof)
    settlement = response.headers["PAYMENT-RESPONSE"]
  elif "WWW-Authenticate" in response.headers:
    token, invoice = parse_l402_challenge(response.headers["WWW-Authenticate"])
    preimage = pay_lightning_invoice(invoice)
    response = POST /v1/compute-power(payload, Authorization=f"L402 {token}:{preimage}")

interpret(response.json())

Minimal Python Client

This example is intentionally minimal. The x402 proof step is pseudocode because the exact implementation depends on your x402 client tooling.

import requests

BASE_URL = "https://api.workcapacity.io"


def build_x402_proof(payment_required: str) -> str:
    # Replace this with your x402 proof generation.
    raise NotImplementedError


payload = {
    "athlete_uuid": "11111111-1111-1111-1111-111111111111",
    "evaluation_context": "completed",
    "performed_date": "2026-03-20",
    "duration_seconds": 60,
    "user": {
        "height": {"value": 70, "unit": "in"},
        "body_mass": {"value": 180, "unit": "lb"},
    },
    "splits": [
        {
            "duration_seconds": 60,
            "work": {
                "movements": [
                    {
                        "movement": "air_squat",
                        "reps": 10,
                        "spec_overrides": {},
                    }
                ]
            },
        }
    ],
}

response = requests.post(f"{BASE_URL}/v1/compute-power", json=payload, timeout=30)

if response.status_code == 402:
    proof = build_x402_proof(response.headers["PAYMENT-REQUIRED"])
    response = requests.post(
        f"{BASE_URL}/v1/compute-power",
        json=payload,
        headers={"PAYMENT-SIGNATURE": proof},
        timeout=30,
    )

response.raise_for_status()
data = response.json()
print(data["results"]["session"])

Do not guess inputs. Validate the payload against the OpenAPI schema and GET /v1/movements before calling the paid route. Invalid authorized requests can still consume one paid use.

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