Developer documentation

Discovery

Fetch GET https://api.trueodd.xyz/v1/service-metadata for the service catalog, identifiers, endpoints, and payment configuration. GET /v1/supported-markets lists venues, families, and series.

Buyer-side execution services

Separate from the oracle services above. Every path is static and takes its identifiers — intent_id, buyer_id — in the JSON request body, because a marketplace listing URL cannot carry a path parameter. All twelve are x402-capable.

• Non-custodial. You derive your own venue deposit wallet locally and fund it yourself; this service never publishes a funding address and never takes custody.
• Buyer-submitted egress. You sign and post to the venue from your own network, so the venue's jurisdiction rules follow you rather than this host.
• Every identifier travels in the JSON request body. No path carries a placeholder.
• Autonomous execution is disabled. These endpoints prepare, inspect, and record; promotion to live trading stays locked until the evidence gate passes.

Best Signals command

Command: rwoo_best_signals · Service: rwoo.best_signals · Endpoint: POST /v1/signals

Send natural language such as Give me the best weather signals now or Give me the best signals on Kalshi. The response ranks only candidates that pass the current tradability gates. If none pass, it returns status: "no_signal" rather than an error.

{"message":"Give me the best weather signals now","limit":5}

Sports data available now

Sports are disclosed per family and market shape. A registered model does not by itself mean a live, actionable signal exists. The current scan contains 820 sports rows, of which 0 pass the scanner's actionability gates.

Machine-readable coverage and live counts: GET /v1/supported-markets → sports_coverage and current_sports_scan.

Active hurricane and Henry Hub coverage

Series are discovered from venue settlement metadata on each scan. Discovery never bypasses source, shape, model, or evidence gates.

Natural-language examples: best hurricane signals and best Henry Hub natural gas signals.

Technical boundary: other energy and agriculture settlement sources are not product capabilities. Their exact settlement sources are not yet integrated, so those requests return no_signal.

Payments — OKX Agent Payments (x402)

Paid endpoints use x402 v2. An unpaid request receives HTTP 402 with a base64-encoded PAYMENT-REQUIRED header containing x402Version: 2 and accepts[]. The agent wallet signs an accepted payment and re-sends the identical request body with a PAYMENT-SIGNATURE header; on success it receives 200, a PAYMENT-RESPONSE header, and a receipt whose payment_reference links the settlement.

• The official OKX middleware verifies and settles against the advertised amount, recipient, asset, network, and expiry.
• An Idempotency-Key retry returns the cached decision rather than initiating another application-level charge.
• No buyer private key is ever accepted, and no signing flow is invented — your agent wallet produces the payload.

Prices, asset, network, and recipient appear in /v1/service-metadata. Payment availability is reported independently from oracle coverage and trading execution.

Call it

curl -sS -X POST https://api.trueodd.xyz/v1/signals \
  -H 'Content-Type: application/json' \
  -d '{"message":"Give me the best weather signals now","limit":5}'
# A paid deployment answers 402 with a PAYMENT-REQUIRED header;
# have the agent wallet sign it, then re-send the identical body
# with PAYMENT-SIGNATURE to receive 200.

import httpx

BASE = "https://api.trueodd.xyz"
req = {"message": "Give me the best weather signals now", "limit": 5}
r = httpx.post(f"{BASE}/v1/signals", json=req, timeout=30)
if r.status_code == 402:
    challenge = r.headers['PAYMENT-REQUIRED']
    # Agent wallet signs the challenge; retry the identical body
    # with the resulting PAYMENT-SIGNATURE header.
print(r.json())

const BASE = "https://api.trueodd.xyz";
const req = { message: "Give me the best weather signals now", limit: 5 };
const r = await fetch(`${BASE}/v1/signals`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(req),
});
// On 402, read PAYMENT-REQUIRED, sign with the agent wallet,
// then retry the identical body with PAYMENT-SIGNATURE.
console.log(await r.json());

{"message":"Give me the best weather signals now","limit":5}

Refusals vs errors

A market the oracle cannot safely price is a refusal: HTTP 200, status: "refused", a stable reason_code, an explanation, the missing capability, and a receipt. Malformed requests, unknown services, and payment failures are transport errors (4xx) with a stable JSON shape: { "error": { "code", "message" }, "request_id" }.

Semantics you must not confuse

Idempotency

Send an Idempotency-Key header to make a retry return the same result and receipt without re-charging.

Rate limits & timeouts

Requests are bounded and time-limited; a slow upstream returns UPSTREAM_TIMEOUT rather than hanging.

Confidence is not calibration

Model agreement (confidence) is the spread of the ensemble now. Calibration is the measured, precommitted historical hit rate. A high confidence with zero resolved events is not evidence — the API always reports the independent sample count.

Missing data stays missing

An unknown entity, unbound strike, or unverified fee never becomes a silent zero — it becomes a refusal.

Versions & changelog

Every forecast carries its model_version. Current engine versions:

• v1.0.0 — ASP surface: Best Signals plus three supporting services, receipts, calibration evidence, and the OKX Agent Payments (x402) flow.