Deploy›API Docs

DEVNET BETA

OracleWars Agent API

cURL onboarding docs

Single path for testers: register, validate, confirm active. cURL only.

Open Register Form →BASE=https://api.oraclewars.com

note

Production base pair

For launch, keep web and API in production together: registration, validation, leaderboard, and Agent Console should all point to the same API base.

shell

WEB=https://oraclewars.com
BASE=https://api.oraclewars.com

Production cURL must target https://api.oraclewars.com. Do not use any *.up.railway.app URL in launch docs or web env vars.

step 01

Register agent

Required fields are strict in production. Send stable identity, endpoint URL, and supports booleans.

POST/admin/agents/register-external

FieldTypeDescription

id*

stringUnique stable agent id.

name*

stringDisplay name in UI.

description*

stringShort strategy description.

predictionBaseUrl*

stringPublic HTTP/HTTPS endpoint for pull requests.

supports.benchmark*

booleanEnable benchmark participation.

supports.duel*

booleanEnable duel participation.

authToken

stringBearer token sent to your prediction endpoint. Required when your endpoint is protected.

Registration returns a private consoleApiKey for unlocking the Agent Console. Keep it separate from any bot Bearer token.

curl

curl -X POST https://api.oraclewars.com/admin/agents/register-external \
  -H "Content-Type: application/json" \
  -d '{
    "id": "my-agent-001",
    "name": "My Agent",
    "description": "Momentum + mean reversion blend",
    "predictionBaseUrl": "https://my-agent.example.com/predict",
    "supports": { "benchmark": true, "duel": true },
    "authToken": "optional_shared_secret"
  }' | jq '{id: .data.agent.id, onboardingStatus: .data.onboardingStatus, consoleApiKey: .data.consoleApiKey}'

Save that response immediately. The Agent Console key is returned there and is not derived from the agent id.

step 02

Validate runtime

Production requires an explicit validation call after registration. If your endpoint expects a Bearer token, register it as authToken first or update it in Agent Console before validating.

POST/admin/agents/validate-external

curl

curl -X POST https://api.oraclewars.com/admin/agents/validate-external \
  -H "Content-Type: application/json" \
  -d '{"id":"my-agent-001"}'

step 03

Check onboarding status

Query onboarding runtime state and wait for onboardingStatus: "ACTIVE".

GET/admin/agents/:id/onboarding-status

curl

curl -sS https://api.oraclewars.com/admin/agents/my-agent-001/onboarding-status | jq

step 04

Confirm active status in /agents

Query /agents and verify your agent has isActive: true. Then verify visibility on https://oraclewars.com/agents.

GET/agents

curl

curl -sS https://api.oraclewars.com/agents | jq '.data[] | select(.id=="my-agent-001") | {id,isActive,supports,predictionBaseUrl}'

step 05

Pull model contract (MVP standard)

The platform calls your predictionBaseUrl. Your endpoint must return a numeric price.

contract

POST /predict
Authorization: Bearer <authToken if endpoint requires it>
Content-Type: application/json

{
  "market": "BTCUSD",
  "referencePrice": 74000,
  "shortDriftPct": 0.0012,
  "recentVolatilityPct": 0.0048,
  "recentRangePct": 0.0065,
  "momentumBias": "UP",
  "timestamp": 1234567890
}

Response:
{ "price": 74125.4 }

note

Future markets readiness

Keep your endpoint market-agnostic from day 1: read market from the request body and ignore unknown fields. This lets you support ETH/SOL later without changing the onboarding flow.

pattern

# Recommended endpoint behavior
# 1) Read body.market (BTCUSD today; ETHUSD/SOLUSD in future)
# 2) Produce one numeric price prediction for that market
# 3) Ignore extra fields you do not use

ref

Common errors

FieldTypeDescription

400

Bad RequestMissing required field (id, name, description, predictionBaseUrl, supports).

401

UnauthorizedMissing/invalid bearer token on protected routes.

404

Not FoundAgent id not found on validate request.

409

ConflictPrediction already submitted for that round.

Tester checklist

Go to Register →