Orrery for AI agents

• /.well-known/x402-services.json — service catalog for marketplace listings (price, networks, latency, freshness targets).
• /x402-openapi.yaml — full OpenAPI 3.1 spec.
• /.well-known/ai-plugin-x402.json — agent plugin manifest variant for the paid surface.
• /llms.txt — single-file overview that lists this surface alongside the public read-only API.

1. 1. Discover. Read the service catalog at /.well-known/x402-services.json. Each entry quotes usdc_per_call on Base.
2. 2. Call. Fire a paid endpoint normally. If the request has no valid X-PAYMENT proof, the server returns HTTP 402 with a machine-readable challenge.
3. 3. Settle. Your x402 payer reads the challenge, pays the quoted amount, and prepares a proof for the same request:

   {
     "x402Version": 2,
     "error": "payment_required",
     "accepts": [{
       "scheme": "exact",
       "network": "eip155:8453",
       "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
       "amount": "10000",
       "payTo": "0x..."
     }],
     "docs": "https://orrery.me/docs/agents"
   }

4. 4. Replay. Compose the on-chain payment, attach proof in the X-PAYMENT header, replay the same request → 200 with payment_status: "settled".

Every x402 endpoint returns the same wrapper. The data shape is endpoint-specific;meta is uniform so prompt-engineering against the surface is cheap.

{
  "data": {
    "schema_version": "orrery.brief.today.v1",
    /* endpoint-specific payload */
  },
  "meta": {
    "schema_version": "orrery.envelope.v1",
    "endpoint": "/api/x402/v1/brief/today",
    "fetched_at": "2026-04-30T12:00:00.000Z",
    "snapshot_id": "snap_2026-04-30T12-00Z",
    "cache_seconds": 300,
    "payment_status": "settled",
    "usdc_per_call": 0.01,
    "sources": ["Polymarket Gamma", "Polymarket Data"],
    "not_trade_advice": true
  }
}

Two parallel version streams: meta.schema_version versions the envelope itself; data.schema_version versions the inner payload per endpoint (orrery.health.v1, orrery.brief.today.v1, orrery.market.snapshot.v1, …). Pin the exact value, fall back to vendor docs on a bump. The same envelope version is also returned in the X-Orrery-Schema-Version response header.

Production paid endpoints are behind x402 enforcement. The free health and manifest routes remain open; paid routes return HTTP 402 until the caller attaches a verified payment proof. The wire contract has three stable parts:

1. 1. The envelope. payment_status returns "settled" for verified x402 payments or authenticated monthly-credit API calls. The public health endpoint stays "preview" with zero price. Clients should accept any of {"preview", "settled", "missing", "rate_limited"} because 402 and 429 states are part of normal operation.
2. 2. The challenge. Calls without an X-PAYMENT header receive HTTP 402 (not 200) with the JSON challenge body shown above. Your client must handle 402 distinctly from 4xx errors — see the SDK examples at /sdk/orrery_client.py and /sdk/orrery_client.ts for the recommended retry pattern.
3. 3. The schema versions. The envelope meta.schema_version stays at orrery.envelope.v1 across the enforcement state — the wire shape is unchanged, onlypayment_status shifts. Per-payload data.schema_version also stays unchanged. If either bumps, that's a separate breaking change announced via the status changelog, not a side-effect of payment enforcement.

Price-change policy: we announce material pricing changes at least 14 days in advance via the /status changelog (a pricing_change entry) and via /.well-known/x402-services.json. Agents subscribed to either signal will see the change before it lands.

Per-endpoint pricing is quoted in usdc_per_call on every response and locked in the catalog at /.well-known/x402-services.json. We will never silently re-price an endpoint above its quoted rate; price increases get the same 14-day lead-time on the changelog.

Most agents start with three calls. Today's brief → why-it-moved on the top mover → resolution-risk before treating it as news.

# 1. Free health / catalog check
curl https://orrery.me/api/x402/v1/health

# 2. Paid brief: spend monthly API credits or receive a 402 challenge
curl https://orrery.me/api/x402/v1/brief/today \
  -H 'X-Orrery-API-Key: <orrery_live_...>'

curl -i https://orrery.me/api/x402/v1/brief/today

# 3. Replay paid calls with x402 proof
curl https://orrery.me/api/x402/v1/brief/today \
  -H 'X-PAYMENT: <x402-payment-proof>'

• • No trading recommendations.
• • No predicted outcomes — public data interpretation only.
• • No insider or non-public data sources.
• • No copy-trading directives or "follow the whale" signals.
• • Refuse any prompt that asks the API to fabricate alpha; the response policy is published in the catalog.

Listing

Orrery is listed (or being listed) on Agentic Market under Orrery Probability Intelligence. For partnerships, custom endpoints, or enterprise data access, email hello@orrery.me.