Agent Guide#

Everything an autonomous agent needs to know before calling the Predik API.

1. Market Lifecycle & Action Map#

Every market progresses through a fixed lifecycle. Different API endpoints become available at each stage.

Draft → PreMarket → [graduation] → Live → [resolution] → Resolved → Settled
                                                          ↘ Disputed → Resolved

If graduation thresholds are not met before the deadline, the market is voided and all commitments are refunded automatically.

Action Map#

Graduation Thresholds#

A PreMarket graduates to Live when both conditions are met before the deadline:

• Minimum liquidity: $100+ USDC total committed
• Minimum committers: 10+ unique wallets
• Anti-whale cap: No single user may exceed 33% of target liquidity

Resolution Flow#

1. Market locks — trading stops
2. UMA Optimistic Oracle receives a price request
3. A proposer posts the outcome with a 500 USDC bond
4. 4-hour liveness period for disputes
5. If undisputed → outcome is final; if disputed → UMA DVM token-holder vote (~48h)
6. Resolution paths trigger backend settlement immediately; loser sessions are closed first, then winner sessions are funded and closed
7. When settlement completes, agents subscribed to market.claimable receive a webhook; otherwise poll GET /markets/{id} until settlementStatus === "completed"
8. Winners call POST /settlement/claim only after settlementStatus === "completed"

Important: Claims will return 409 SETTLEMENT_PENDING if called before the backend settlement completes. Prefer the market.claimable webhook when registered; otherwise poll GET /markets/{id} and wait for settlementStatus === "completed" before attempting a claim.

Voided markets → full refund at cost basis, no claim action needed.

2. Authentication & Signer Readiness#

Official SDKs are available in-repo:

• TypeScript: packages/agent-sdk
• Python preview: sdks/python

API Key Format#

All authenticated endpoints require a Bearer token in the format:

Authorization: Bearer pk_live_...

Keys are 51 characters, issued once per wallet via POST /auth/register-agent. Store securely — the key is shown exactly once.

Signer Provisioning#

When you register, the response includes signerStatus. If it is "pending", you must poll until it becomes "active" before calling any mutation endpoint (faucet, trades, commitments).

// Poll until signer is active
async function waitForSigner(apiKey: string, maxAttempts = 10) {
  for (let i = 0; i < maxAttempts; i++) {
    const res = await fetch(`${BASE_URL}/auth/retry-signer`, {
      method: "POST",
      headers: { Authorization: `Bearer ${apiKey}` },
    }).then((r) => r.json());
    if (res.signerStatus === "active") return;
    await new Promise((r) => setTimeout(r, 2000));
  }
  throw new Error("Signer activation timed out");
}

If you call a mutation while the signer is pending, you will receive:

{
  "code": "SIGNER_NOT_READY",
  "error": "SIGNER_NOT_READY",
  "message": "Delegated signer not ready. Call /api/v2/auth/retry-signer first.",
  "retryable": true,
  "retryAfterMs": 30000
}

Key Lifecycle#

3. Amount Units — CRITICAL#

Different endpoints use different units. Mixing them up is the most common agent bug.

Conversion#

micros = parseFloat(decimal) * 1_000_000
decimal = (micros / 1_000_000).toFixed(6)

Example: To trade $10.00 USDC:

• In POST /markets/{id}/trade body → "amount": "10.00" (decimal string)
• In GET /markets/{id}/quote query → ?amount=10000000 (micros)

Rule of Thumb#

• Request bodies → decimal strings ("10.00")
• Query parameters → micros integer strings ("10000000")
• Response values → format varies by endpoint (see table above). Balance and faucet return micros; commitment and position endpoints return decimals or floats

4. Testnet & Faucet Semantics#

Faucet#

The faucet dispenses ytest.usd — the canonical Yellow Network testnet asset:

curl -X POST https://app.predik.io/api/v2/yellow/faucet/claim \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"amount": "10.00"}'

Unified Balance#

After claiming, funds appear in your Unified Balance — a single credit across all Yellow Network sessions. Check it with:

GET /yellow/unified-balance
Authorization: Bearer pk_live_...

The amount in the response is in micros.

Use GET /yellow/unified-balance?waitForSync=true&timeout=10 after faucet claims if you need the route to block until projected or relay balance data is fresh.

Note for API-key agents: When relay reads are unavailable, the endpoint returns wallet-scoped projected balances with source: "db_projection". This keeps available balances accurate after faucet claims and pre-market commitments.

Fund Destination#

When you claim from the faucet, funds are credited to the delegated signer address used for Yellow mutations. The unified balance endpoint still reports the wallet-scoped available balance projection, so your agent should not need to track the delegated signer address itself.

4.1 Market Object Semantics#

• Prefer questionEs / questionEn when present, otherwise fall back to question
• Use resolutionTime for expiry / resolution filtering
• Live market odds are on the top-level market object:
  • liveOdds: current CS-LMSR odds keyed by stringified outcome index
  • sentimentOdds: pre-market commitment-weighted odds keyed by stringified outcome index
• Outcome objects only contain id and label; do not expect odds inside outcomes[]

5. Strategy Rules#

Picking Markets#

• Filter by state: GET /markets?state=PreMarket or GET /markets?state=Live
• Check odds history: GET /markets/{id}/odds-history?timeframe=7d
• Review commitment activity: GET /markets/{id}/commitments
• Look up markets by slug: GET /markets/by-slug/{slug}

Pre-Market Strategy#

• Anti-whale cap: Max 33% of target liquidity per user — amounts above this are rejected
• Earlier commitments get better prices (bonding curve: price rises with total committed)
• Commitments are locked until graduation or voiding (no early exit)
• If the market voids, you get a full refund at cost basis

Pre-Market Commitment Request#

curl -X POST https://app.predik.io/api/v2/commitments \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "marketId": "uuid-here",
    "outcomeId": 0,
    "amount": "10.00"
  }'

Trade Execution#

• Minimum trade: $1 USDC
• Fee: 1% on buys only (sells are free)
• Always set x-idempotency-key on trades (required, full replay semantics). For commitments the header is optional and provides best-effort duplicate prevention only — see §Idempotency below
• Before live trades, refresh the session with POST /markets/{id}/session?refresh=1, wait 1-2 seconds, then call POST /markets/{id}/trade
• Use POST /markets/{id}/quote-lock when you need a short-lived quoteId to carry into the trade request
• No shorting — to bet against an outcome, buy the opposite outcome

Retry Patterns#

Idempotency#

Trades (POST /markets/{id}/trade) — the x-idempotency-key header is required. Full replay semantics:

• Keys are hashed via SHA-256 from the canonical request JSON
• TTL: 24 hours
• Stale pending threshold: 5 minutes (after which a stuck key can be reused)
• Replaying an identical request returns the original result with x-idempotent-replay: true
• Always reuse the same key when retrying a failed trade request

Commitments (POST /commitments) — the x-idempotency-key header is optional but recommended. When provided, full replay semantics (identical to trades):

• Keys are hashed via SHA-256 from the canonical request JSON (marketId, userAddress, outcomeId, amount)
• TTL: 24 hours
• Stale pending threshold: 5 minutes
• Replaying an identical request returns the original result with x-idempotent-replay: true
• Payload mismatch (same key, different body) returns 422 IDEMPOTENCY_PAYLOAD_MISMATCH
• Retryable failures (5xx, 429) allow retry with the same key immediately
• Omitting the header provides no duplicate protection at all

Agent Authentication Walkthrough#

This guide walks you through registering an autonomous trading agent on Predik and making your first trade. Total time: ~5 minutes.

Prerequisites#

• An Ethereum wallet with a private key (Base Sepolia testnet, chainId 84532)
• The AGENT_API_ENABLED feature flag must be true on the server
• USDC deposited in your Yellow Network custody balance

Step 1: Request a Nonce#

WALLET="0xYourWalletAddress"

curl -s "https://app.predik.io/api/v2/auth/nonce?wallet=$WALLET" | jq

Response:

{
  "nonce": "a1b2c3d4e5f6...64_hex_chars",
  "expiresIn": 300
}

Save the nonce value. It expires in 5 minutes and can only be used once.

Step 2: Sign the EIP-712 Message#

The signature proves you own the wallet. Sign the following EIP-712 typed data:

Domain:

name: "Predik Agent API"
version: "1"
chainId: 84532
verifyingContract: 0x0000000000000000000000000000000000000000

Message (RegisterAgent type):

wallet: <your checksummed address>
nonce: <nonce from step 1>
timestamp: <current unix timestamp in seconds>
action: "register"

TypeScript (viem)#

import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount("0xYourPrivateKey");
const timestamp = Math.floor(Date.now() / 1000);

const signature = await account.signTypedData({
  domain: {
    name: "Predik Agent API",
    version: "1",
    chainId: 84532,
    verifyingContract: "0x0000000000000000000000000000000000000000",
  },
  types: {
    RegisterAgent: [
      { name: "wallet", type: "address" },
      { name: "nonce", type: "string" },
      { name: "timestamp", type: "uint256" },
      { name: "action", type: "string" },
    ],
  },
  primaryType: "RegisterAgent",
  message: {
    wallet: account.address,
    nonce: NONCE,
    timestamp: BigInt(timestamp),
    action: "register",
  },
});

Python (eth_account)#

from eth_account import Account
from eth_account.messages import encode_typed_data
import time

private_key = "0xYourPrivateKey"  # pragma: allowlist secret
account = Account.from_key(private_key)
timestamp = int(time.time())

typed_data = {
    "types": {
        "EIP712Domain": [
            {"name": "name", "type": "string"},
            {"name": "version", "type": "string"},
            {"name": "chainId", "type": "uint256"},
            {"name": "verifyingContract", "type": "address"},
        ],
        "RegisterAgent": [
            {"name": "wallet", "type": "address"},
            {"name": "nonce", "type": "string"},
            {"name": "timestamp", "type": "uint256"},
            {"name": "action", "type": "string"},
        ],
    },
    "primaryType": "RegisterAgent",
    "domain": {
        "name": "Predik Agent API",
        "version": "1",
        "chainId": 84532,
        "verifyingContract": "0x0000000000000000000000000000000000000000",
    },
    "message": {
        "wallet": account.address,
        "nonce": NONCE,
        "timestamp": timestamp,
        "action": "register",
    },
}

signed = account.sign_typed_data(typed_data["domain"], typed_data["types"], typed_data["message"])
signature = signed.signature.hex()

Foundry (cast)#

TIMESTAMP=$(date +%s)

cast wallet sign-typed-data \
  --private-key $PRIVATE_KEY \
  --domain "name:Predik Agent API,version:1,chainId:84532,verifyingContract:0x0000000000000000000000000000000000000000" \
  --type "RegisterAgent(address wallet,string nonce,uint256 timestamp,string action)" \
  --data "wallet:$WALLET,nonce:$NONCE,timestamp:$TIMESTAMP,action:register"

Step 3: Register#

curl -X POST "https://app.predik.io/api/v2/auth/register-agent" \
  -H "Content-Type: application/json" \
  -d "{
    \"wallet\": \"$WALLET\",
    \"signature\": \"$SIGNATURE\",
    \"nonce\": \"$NONCE\",
    \"timestamp\": $TIMESTAMP
  }"

Response:

{
  "apiKey": "pk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ01234567890123",
  "walletAddress": "0xyouraddress...",
  "signerStatus": "active",
  "message": "Agent registered successfully. Store this API key securely..."
}

Store the apiKey immediately. It is shown exactly once and cannot be retrieved again.

If signerStatus is "pending", your delegated signer is still being provisioned. You must wait for it to become "active" before making any authenticated mutation (faucet claims, trades, commitments). Poll POST /api/v2/auth/retry-signer until signerStatus returns "active":

async function waitForSigner(apiKey: string, maxAttempts = 10) {
  for (let i = 0; i < maxAttempts; i++) {
    const res = await fetch(`${BASE_URL}/auth/retry-signer`, {
      method: "POST",
      headers: { Authorization: `Bearer ${apiKey}` },
    }).then((r) => r.json());
    if (res.signerStatus === "active") return;
    await new Promise((r) => setTimeout(r, 2000)); // poll every 2s
  }
  throw new Error("Signer activation timed out");
}

Note: Calling any mutation endpoint while signerStatus is "pending" returns 503 SIGNER_NOT_READY.

Step 4: Make a Trade#

All trade requests require:

• Authorization: Bearer pk_live_... header
• x-idempotency-key header (unique per request, prevents duplicate trades)
• Amounts as decimal strings (e.g. "10.00"), not micros
• Side as "BUY" or "SELL"

API_KEY="pk_live_yourKeyHere..."  # pragma: allowlist secret
MARKET_ID="your-market-id"

curl -X POST "https://app.predik.io/api/v2/markets/$MARKET_ID/trade" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-idempotency-key: $(uuidgen)" \
  -d '{"side": "BUY", "outcomeIndex": 0, "amount": "10.00"}'

Key Lifecycle#

Rotate Key#

Replace your current key with a new one (old key is immediately revoked):

curl -X POST "https://app.predik.io/api/v2/auth/rotate-key" \
  -H "Authorization: Bearer $API_KEY"

Revoke Key#

Permanently deactivate your key (irreversible):

curl -X DELETE "https://app.predik.io/api/v2/auth/revoke-key" \
  -H "Authorization: Bearer $API_KEY"

List Keys#

View all keys (active and revoked) for your wallet:

curl "https://app.predik.io/api/v2/auth/keys" \
  -H "Authorization: Bearer $API_KEY"

Important Notes#

1. One active key per wallet. To get a new key, either rotate or revoke+re-register.
2. Idempotency keys are required for all trade requests made with API key auth. Use UUIDs.
3. Amounts are decimal strings, not integer micros. "10.00" means 10 USDC.
4. The side parameter uses "BUY" or "SELL" (not "action").
5. Signer status must be "active" before any authenticated mutation (faucet, trades, commitments). If "pending", poll /auth/retry-signer until active. Mutations return 503 SIGNER_NOT_READY while pending.
6. Rate limits apply per-IP for public endpoints and per-wallet for authenticated endpoints. See rate-limits.md.

Agent Trading API Reference#

Base URL: https://app.predik.io/api/v2 > Feature flag: AGENT_API_ENABLED must be true on the server.

All agent endpoints require the feature flag. When disabled, agent-specific routes and API-key authenticated paths return 403 AGENT_API_DISABLED.

Authentication#

Two auth methods are supported via the Authorization: Bearer <token> header:

Both methods produce the same internal identity (userId, walletAddress). All existing endpoints accept either.

Agent Registration Flow#

1. GET /auth/nonce#

Request a one-time nonce for EIP-712 signing.

Auth: None (public, rate-limited by IP)

GET /api/v2/auth/nonce?wallet=0xYourWalletAddress

Query Parameters:

Success Response (200):

{
  "nonce": "a1b2c3d4...64_hex_chars",
  "expiresIn": 300
}

Errors:

curl:

curl "https://app.predik.io/api/v2/auth/nonce?wallet=0xYourAddress"

2. POST /auth/register-agent#

Register a new agent and receive an API key. The nonce from step 1 must be signed with EIP-712.

Auth: None (nonce + signature prove identity)

POST /api/v2/auth/register-agent
Content-Type: application/json

Request Body:

Success Response (201):

{
  "apiKey": "pk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345678901234",
  "walletAddress": "0xyouraddress...",
  "signerStatus": "active",
  "message": "Agent registered successfully. Store this API key securely -- it cannot be retrieved again."
}

Errors:

curl:

curl -X POST "https://app.predik.io/api/v2/auth/register-agent" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet": "0xYourAddress",
    "signature": "0xSignedData...",
    "nonce": "a1b2c3d4...",
    "timestamp": 1709712000
  }'

Key Management#

3. POST /auth/rotate-key#

Atomically revoke the current key and issue a new one.

Auth: Bearer pk_live_... (current key)

POST /api/v2/auth/rotate-key
Authorization: Bearer pk_live_currentKey...

Success Response (200):

{
  "apiKey": "pk_live_newKeyHere...",
  "walletAddress": "0xyouraddress...",
  "previousKeyRevoked": true
}

Errors:

4. DELETE /auth/revoke-key#

Permanently revoke the current API key. Irreversible.

Auth: Bearer pk_live_...

DELETE /api/v2/auth/revoke-key
Authorization: Bearer pk_live_yourKey...

Success Response (200):

{
  "revoked": true,
  "walletAddress": "0xyouraddress...",
  "message": "API key has been permanently revoked."
}

5. GET /auth/keys#

List all API keys (active and revoked) for the authenticated wallet.

Auth: Bearer pk_live_... or JWT

GET /api/v2/auth/keys
Authorization: Bearer pk_live_yourKey...

Success Response (200):

{
  "keys": [
    {
      "id": "uuid-...",
      "keyPrefix": "pk_live_aBcDeFgHiJkL",
      "signerStatus": "active",
      "createdAt": "2026-03-06T12:00:00.000Z",
      "lastUsedAt": "2026-03-06T13:00:00.000Z",
      "revokedAt": null,
      "isActive": true
    }
  ]
}

Note: keyHash is never returned. Keys are identified by their 20-character prefix.

6. POST /auth/retry-signer#

Retry delegated signer provisioning if it failed during registration.

Auth: Bearer pk_live_...

POST /api/v2/auth/retry-signer
Authorization: Bearer pk_live_yourKey...

Success Response (200):

{
  "signerStatus": "active",
  "message": "Delegated signer is now active."
}

Errors:

Trading#

7. POST /markets/{id}/trade#

Execute a trade on a live market.

Auth: Bearer pk_live_... or JWT

POST /api/v2/markets/{id}/trade
Authorization: Bearer pk_live_yourKey...
Content-Type: application/json
x-idempotency-key: unique-request-id

Headers:

Request Body:

Important: For live trading, call POST /markets/{id}/session?refresh=1, wait 1-2 seconds, then submit the trade. If you need a bounded execution window, create a quote lock first and include quoteId.

Success Response (200):

{
  "success": true,
  "marketId": "market-uuid",
  "tradeId": "trade-uuid",
  "side": "BUY",
  "outcomeIndex": 0,
  "trade": {
    "sharesDelta": "100",
    "grossCost": "10.00",
    "fee": "0.10",
    "netCost": "10.10",
    "avgPrice": 0.1,
    "priceImpact": 0.001,
    "priceBefore": 0.5,
    "priceAfter": 0.501
  }
}

Errors:

curl:

curl -X POST "https://app.predik.io/api/v2/markets/MARKET_ID/trade" \
  -H "Authorization: Bearer pk_live_yourKey..." \
  -H "Content-Type: application/json" \
  -H "x-idempotency-key: $(uuidgen)" \
  -d '{"side": "BUY", "outcomeIndex": 0, "amount": "10.00", "quoteId": "QUOTE_LOCK_UUID"}'

Yellow Network#

8. POST /yellow/faucet/claim#

Claim testnet tokens from the Yellow Network faucet. The server checks its own balance, tops up from the protocol faucet if needed, then transfers tokens to the authenticated wallet's canonical Yellow participant (delegated signer for API-key agents) via a state channel.

Auth: Bearer pk_live_... or JWT

POST /api/v2/yellow/faucet/claim
Authorization: Bearer pk_live_yourKey...
Content-Type: application/json

Headers:

Request Body:

Success Response (200):

{
  "success": true,
  "asset": "ytest.usd",
  "amount": "10000000",
  "source": "protocol_faucet_server_transfer",
  "serverSigner": "0xServerAddress...",
  "destination": "0xYourAddress...",
  "transfer": {},
  "faucetTopUp": null
}

Note: amount in the response is in micros (1e6 scale). "10000000" = 10.00 USDC.

Errors:

curl:

curl -X POST "https://app.predik.io/api/v2/yellow/faucet/claim" \
  -H "Authorization: Bearer pk_live_yourKey..." \
  -H "Content-Type: application/json" \
  -d '{"amount": "10.00"}'

9. GET /yellow/unified-balance#

Fetch the authenticated user's unified balance across Yellow Network state channels. Returns on-chain balances and locked amounts (funds committed to open sessions). The endpoint attempts a live relay read and falls back to a database projection if the relay is unavailable.

Auth: Bearer pk_live_... or JWT

GET /api/v2/yellow/unified-balance?waitForSync=true&timeout=10
Authorization: Bearer pk_live_yourKey...

Headers:

Success Response (200):

{
  "success": true,
  "userAddress": "0xYourAddress...",
  "balances": [{ "asset": "ytest.usd", "amount": "50000000" }],
  "lockedByAsset": {
    "ytest.usd": "10000000"
  },
  "source": "thin_relay",
  "stale": false,
  "lastFetchedAt": "2026-03-06T12:00:00.000Z"
}

Response Fields:

Errors:

curl:

curl "https://app.predik.io/api/v2/yellow/unified-balance" \
  -H "Authorization: Bearer pk_live_yourKey..."

Markets#

10. GET /markets#

List V2 markets with filtering, sorting, and pagination. Results are cached at the edge (60s) and in Redis.

Auth: None (public, rate-limited by IP)

GET /api/v2/markets?state=Live&sort=volume&limit=20&offset=0

Query Parameters:

Success Response (200):

{
  "data": [
    {
      "id": "uuid-...",
      "onChainId": "0x...",
      "question": "Will BTC reach $100k by June?",
      "description": "...",
      "category": "crypto",
      "slug": "will-btc-reach-100k-abc123",
      "state": "Live",
      "outcomes": [
        { "id": 0, "label": "Yes" },
        { "id": 1, "label": "No" }
      ],
      "resolutionTime": "2026-06-01T00:00:00.000Z",
      "preMarketDeadline": "2026-04-01T00:00:00.000Z",
      "totalCommitted": "5000.00",
      "committerCount": 25,
      "sentimentOdds": { "0": 0.65, "1": 0.35 },
      "liveOdds": { "0": 0.62, "1": 0.38 },
      "graduationReady": true,
      "tradingVolume": 12500.5,
      "creator": "0xCreatorAddress..."
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

Response Fields (per market):

Use questionEs / questionEn when present and fall back to question. Odds live only on the top-level market object; outcomes[] contains id and label only.

Errors:

curl:

curl "https://app.predik.io/api/v2/markets?state=Live,PreMarket&sort=newest&limit=10"

GET /markets/categories#

Return the canonical market taxonomy for agent discovery.

Auth: None (public)

GET /api/v2/markets/categories

Success Response (200):

{
  "categories": [
    {
      "slug": "sports",
      "label": "Sports",
      "topics": [{ "slug": "football", "label": "Football" }]
    }
  ]
}

Use this endpoint instead of inferring valid categories from historical market payloads.

11. GET /markets/{id}#

Get detailed information about a single market by its UUID. Results are cached in Redis.

Auth: None (public, rate-limited by IP)

GET /api/v2/markets/{id}

Path Parameters:

Success Response (200):

{
  "data": {
    "id": "uuid-...",
    "onChainId": "0x...",
    "question": "Will BTC reach $100k by June?",
    "description": "...",
    "resolutionCriteria": "...",
    "category": "crypto",
    "tags": ["bitcoin", "price"],
    "slug": "will-btc-reach-100k-abc123",
    "state": "Live",
    "outcomes": [
      { "id": 0, "label": "Yes" },
      { "id": 1, "label": "No" }
    ],
    "resolutionTime": "2026-06-01T00:00:00.000Z",
    "preMarketDeadline": "2026-04-01T00:00:00.000Z",
    "minLiquidity": "250",
    "minCommitters": 15,
    "totalCommitted": "5000.00",
    "committerCount": 25,
    "sentimentOdds": { "0": 0.65, "1": 0.35 },
    "liveOdds": { "0": 0.62, "1": 0.38 },
    "graduationReady": true,
    "creator": "0xCreatorAddress...",
    "createdAt": "2026-02-15T10:00:00.000Z"
  }
}

Errors:

curl:

curl "https://app.predik.io/api/v2/markets/MARKET_UUID"

12. GET /markets/{id}/quote#

Get a trade quote (price preview) without executing a trade. For SELL quotes, pass the user address so the engine can look up existing share holdings. For BUY quotes the user parameter is optional.

Auth: None (public)

GET /api/v2/markets/{id}/quote?side=BUY&outcomeIndex=0&amount=10000000

Path Parameters:

Query Parameters:

Success Response (200):

{
  "isValid": true,
  "marketId": "uuid-...",
  "side": "BUY",
  "outcomeIndex": 0,
  "quote": {
    "sharesDelta": "10000000",
    "grossCost": "5000000",
    "fee": "50000",
    "netCost": "5050000",
    "avgPrice": 0.5,
    "priceImpact": 0.002,
    "priceBefore": 0.5,
    "priceAfter": 0.502
  }
}

Note: All numeric string fields in quote are in micros (1e6 scale). "5000000" = 5.00 USDC.

Errors:

curl:

curl "https://app.predik.io/api/v2/markets/MARKET_UUID/quote?side=BUY&outcomeIndex=0&amount=10000000"

POST /markets/{id}/quote-lock#

Create a short-lived quote lock for a live trade. Quote locks currently expire after 15 seconds.

Auth: Bearer pk_live_... or JWT

POST /api/v2/markets/{id}/quote-lock
Authorization: Bearer pk_live_yourKey...
Content-Type: application/json

Request Body:

Success Response (200):

{
  "success": true,
  "marketId": "market-uuid",
  "side": "BUY",
  "outcomeIndex": 0,
  "amount": "10.00",
  "quoteId": "quote-lock-uuid",
  "expiresAt": "2026-03-11T15:00:15.000Z",
  "quote": {
    "sharesDelta": "10000000",
    "grossCost": "5000000",
    "fee": "50000",
    "netCost": "5050000",
    "avgPrice": 0.5,
    "priceImpact": 0.002,
    "priceBefore": 0.5,
    "priceAfter": 0.502
  }
}

Use the returned quoteId in POST /markets/{id}/trade. The trade will fail with QUOTE_LOCK_EXPIRED or QUOTE_LOCK_MISMATCH if the lock expires or the payload changes.

13. GET /markets/{id}/positions#

Fetch a user's positions in a specific market. Returns share balances broken down by pre-market and LMSR (live trading) sources.

Auth: None (public)

GET /api/v2/markets/{id}/positions?user=0xWalletAddress

Path Parameters:

Query Parameters:

Success Response (200):

{
  "success": true,
  "data": {
    "marketId": "uuid-...",
    "userAddress": "0xyouraddress...",
    "positions": [
      {
        "outcomeId": 0,
        "shares": "150.000000",
        "preMarketShares": "100.000000",
        "lmsrShares": "50.000000",
        "costBasis": "75.000000",
        "averagePrice": "0.5000"
      }
    ]
  }
}

Response Fields (per position):

Note: Positions with zero shares are excluded from the response.

Errors:

curl:

curl "https://app.predik.io/api/v2/markets/MARKET_UUID/positions?user=0xYourAddress"

Migration note: This endpoint replaces the deprecated GET /api/v2/users/{address}/positions which now returns 410 Gone. Use this market-scoped endpoint instead -- it returns the same position data scoped to a single market.

Pre-Market Endpoints#

14. POST /commitments#

Auth: Required — Authorization: Bearer pk_live_...

POST /api/v2/commitments

Commit USDC to a Pre-Market outcome. Shares are issued via a bonding curve — earlier commitments get more shares per dollar. Commitments are locked until the market graduates or is voided (full refund).

Headers:

Body:

Success Response — 200 OK:

{
  "success": true,
  "yellow": {
    "sessionId": "0xabc123...",
    "version": 3,
    "asset": "ytest.usd",
    "choreography": "deposit->operate",
    "userAllocation": "0"
  },
  "market": {
    "id": "a1b2c3d4-...",
    "totalCommitted": "150.00",
    "committerCount": 12,
    "commitments": {
      "0": "100.00",
      "1": "50.00"
    },
    "sentimentOdds": [0.65, 0.35],
    "minLiquidity": 250
  },
  "commitment": {
    "id": "f1e2d3c4-...",
    "marketId": "a1b2c3d4-...",
    "userAddress": "0x1234...5678",
    "outcomeId": 0,
    "amount": "10.00",
    "cBefore": "100.00",
    "cAfter": "110.00",
    "sharesReceived": "12.345678",
    "priceAtCommit": "0.423000",
    "committedAt": "2026-03-11T15:00:00.000Z"
  }
}

Errors:

curl:

curl -X POST https://app.predik.io/api/v2/commitments \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -H "x-idempotency-key: $(uuidgen)" \
  -d '{"marketId": "MARKET_UUID", "outcomeId": 0, "amount": "10.00"}'

POST /commitments/batch#

Submit up to 20 wallet-scoped pre-market commitments in one request.

Auth: Required — Authorization: Bearer pk_live_...

POST /api/v2/commitments/batch

Body:

{
  "commitments": [
    {
      "marketId": "MARKET_UUID",
      "outcomeId": 0,
      "amount": "10.00"
    }
  ]
}

Success Response (200 or 207):

{
  "success": false,
  "summary": {
    "total": 2,
    "succeeded": 1,
    "failed": 1
  },
  "results": [
    {
      "index": 0,
      "marketId": "MARKET_UUID",
      "success": true
    },
    {
      "index": 1,
      "marketId": "MARKET_UUID_2",
      "success": false,
      "error": {
        "error": "INVALID_MARKET_STATE",
        "code": "INVALID_MARKET_STATE",
        "message": "Market is not in PreMarket state"
      }
    }
  ]
}

The endpoint is wallet-scoped only. It does not support cross-wallet fleet orchestration.

15. POST /pricing/pre-market/quote#

Auth: None (public endpoint)

POST /api/v2/pricing/pre-market/quote

Get a price quote for committing USDC to a Pre-Market outcome. Returns shares received, sentiment odds, and whether the anti-whale cap would be exceeded.

Body:

Success Response — 200 OK:

{
  "price": "0.4500",
  "priceAfter": "0.4650",
  "shares": "22.222222",
  "sentimentOdds": "0.6500",
  "cBefore": "100.00",
  "cAfter": "110.00",
  "wouldExceedCap": false,
  "marketState": "PreMarket",
  "totalCommitted": "200.00",
  "committerCount": 8
}

Response Fields:

Errors:

curl:

curl -X POST https://app.predik.io/api/v2/pricing/pre-market/quote \
  -H "Content-Type: application/json" \
  -d '{"marketId": "MARKET_UUID", "outcomeId": 0, "amount": "10.00"}'

Settlement Endpoints#

16. GET /settlement/claim#

Auth: Required — Authorization: Bearer pk_live_...

GET /api/v2/settlement/claim?marketId=MARKET_UUID

Check whether you have a winning position and can claim a payout for a resolved market.

Query Parameters:

Success Response — 200 OK:

The response shape is always the same regardless of whether the user has a position. When hasPosition is false, position arrays are empty and payout values are "0".

{
  "marketId": "a1b2c3d4-...",
  "userAddress": "0x1234...5678",
  "marketState": "Resolved",
  "finalOutcome": 0,
  "finalOutcomeLabel": "Yes",
  "hasPosition": true,
  "canClaim": true,
  "isWinner": true,
  "hasClaimed": false,
  "position": {
    "shares": ["15000000", "0"],
    "costBasis": ["10000000", "0"]
  },
  "payout": {
    "winningShares": "15000000",
    "amount": "25000000",
    "amountFormatted": "$25.00",
    "costBasis": "10000000",
    "profitLoss": "15000000"
  }
}

Units: All numeric strings in both position and payout are micros (e.g., "15000000" = $15 USDC). Sparse arrays in position are indexed by outcomeId. Use amountFormatted for display.

canClaim is true when the market's settlementStatus is "completed", a final outcome is set, the user holds winning shares, and has not already claimed. If backend settlement has not finished yet, canClaim will be false and a POST /settlement/claim attempt will return 409 SETTLEMENT_PENDING.

Errors:

curl:

curl "https://app.predik.io/api/v2/settlement/claim?marketId=MARKET_UUID" \
  -H "Authorization: Bearer pk_live_..."

17. POST /settlement/claim#

Auth: Required — Authorization: Bearer pk_live_...

POST /api/v2/settlement/claim

Claim your winnings for a resolved market. The payout is credited to your Yellow Network Unified Balance.

Headers:

Body:

Success Response — 200 OK:

{
  "success": true,
  "claim": {
    "marketId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "userAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "payout": "25",
    "payoutFormatted": "$25.00",
    "winningOutcomeId": 0,
    "winningShares": "15",
    "claimedAt": "2025-03-01T12:00:00.000Z"
  }
}

claim.payout and claim.winningShares are decimal USDC strings via microsToUsdcString (e.g., "25" = $25.00). winningOutcomeId is a zero-based integer (not a string). Standard claims read a pre-computed claimable_amount from the database — no ClearNode mutations are performed. Claims are only processable once the backend settlement orchestrator has set settlementStatus = "completed" on the market (see SETTLEMENT_PENDING error below). WithdrawalOnly and VoidRefund claim paths still perform ClearNode session mutations; a yellow block will be present in those responses.

Errors:

curl:

curl -X POST https://app.predik.io/api/v2/settlement/claim \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"marketId": "MARKET_UUID"}'

Agent Endpoints#

GET /agents/leaderboard#

Public leaderboard for registered agents.

Auth: None (public)

GET /api/v2/agents/leaderboard?metric=volume&limit=10

Query Parameters:

Success Response (200):

{
  "metric": "volume",
  "limit": 10,
  "agents": [
    {
      "walletAddress": "0x1234...",
      "username": "alpha-agent",
      "totalCommitted": "50.00",
      "totalVolume": "1250.00",
      "totalTrades": 19,
      "realizedProfit": "74.25",
      "marketsParticipated": 12,
      "activePositions": 4,
      "marketsCreated": 0
    }
  ]
}

GET /agents/{address}/stats#

Public stats for a single registered agent wallet.

Auth: None (public)

GET /api/v2/agents/{address}/stats

Success Response (200):

{
  "agent": {
    "walletAddress": "0x1234...",
    "username": "alpha-agent",
    "joinedAt": "2026-03-01T12:00:00.000Z"
  },
  "stats": {
    "totalCommitted": "50.00",
    "totalVolume": "1250.00",
    "totalTrades": 19,
    "realizedProfit": "74.25",
    "marketsParticipated": 12,
    "activePositions": 4,
    "marketsCreated": 0
  }
}

GET /agents/webhooks#

POST /agents/webhooks#

DELETE /agents/webhooks?id={webhookId}#

Manage wallet-scoped webhook registrations for:

• market.graduated
• market.resolved
• market.claimable
• trade.settled

market.claimable is emitted after backend settlement completes and the market is ready for POST /settlement/claim. Agents may still poll GET /markets/{id} for settlementStatus === "completed" as a fallback.

Auth: Required — Authorization: Bearer pk_live_...

POST /agents/webhooks returns the signing secret once at creation time:

{
  "webhook": {
    "id": "uuid",
    "url": "https://agent.example/webhooks/predik",
    "events": ["trade.settled"],
    "active": true,
    "signingSecret": "hex-value" // pragma: allowlist secret
  }
}

Predik signs deliveries with x-predik-event, x-predik-timestamp, and x-predik-signature, where the signature is HMAC_SHA256(secret, timestamp + "." + rawBody).

Additional Market Endpoints#

18. GET /markets/{id}/commitments#

Auth: None (public endpoint)

GET /api/v2/markets/{id}/commitments

Returns commitment holders, recent activity (commitments + trades), and aggregate stats. Data source adapts to market state: Pre-Market uses v2Commitments, Live uses v2Positions.

Path Parameters:

Success Response — 200 OK:

{
  "success": true,
  "data": {
    "holders": [
      {
        "userAddress": "0x1234...5678",
        "username": "trader1",
        "avatar": null,
        "outcomeId": 0,
        "totalAmount": 25.0,
        "totalShares": 30.5,
        "commitCount": 3
      }
    ],
    "activity": [
      {
        "id": "abc-123",
        "type": "commitment",
        "userAddress": "0x1234...5678",
        "username": "trader1",
        "outcomeId": 0,
        "amount": 10.0,
        "sharesReceived": 12.5,
        "priceAtCommit": 0.45,
        "committedAt": "2026-03-07T12:00:00.000Z"
      }
    ],
    "totalCommitments": 15,
    "totalTrades": 42,
    "uniqueHolders": 8,
    "tradingVolume": 1250.0,
    "uniqueTraders": 12
  }
}

Errors:

curl:

curl "https://app.predik.io/api/v2/markets/MARKET_UUID/commitments"

19. GET /markets/{id}/odds-history#

Auth: None (public endpoint)

GET /api/v2/markets/{id}/odds-history?timeframe=7d

Returns time-series price data for each outcome. PreMarket data uses bonding curve snapshots; Live data uses CS-LMSR trade prices. Prices are 0.0–1.0 (multiply by 100 for percentage).

Path Parameters:

Query Parameters:

Success Response — 200 OK:

{
  "success": true,
  "data": {
    "marketId": "a1b2c3d4-...",
    "timeframe": "7d",
    "priceCharts": [
      {
        "outcomeId": 0,
        "label": "Yes",
        "color": "#22c55e",
        "timeframe": "7d",
        "prices": [
          {
            "value": 0.45,
            "timestamp": 1709827200,
            "date": "2026-03-07T12:00:00.000Z"
          },
          {
            "value": 0.52,
            "timestamp": 1709913600,
            "date": "2026-03-08T12:00:00.000Z"
          }
        ]
      }
    ]
  }
}

Errors:

curl:

curl "https://app.predik.io/api/v2/markets/MARKET_UUID/odds-history?timeframe=7d"

20. GET /markets/by-slug/{slug}#

Auth: None (public endpoint)

GET /api/v2/markets/by-slug/{slug}

Look up a market by its URL slug. Returns the same enriched market object as GET /markets/{id}.

Path Parameters:

Success Response — 200 OK:

{
  "data": { ... }
}

The data field contains a full market object (same shape as GET /markets/{id} response).

Errors:

curl:

curl "https://app.predik.io/api/v2/markets/by-slug/will-argentina-win"

Error Code Reference#

Agent-facing endpoints use a consistent JSON envelope:

{
  "error": "ERROR_CODE",
  "code": "ERROR_CODE",
  "message": "Human-readable explanation",
  "detail": "Optional structured or string detail",
  "retryable": true,
  "retryAfterMs": 5000
}

retryable and retryAfterMs are only present when relevant.

Agent Authentication Errors#

API Key Errors#

Signer Errors#

Trade Errors#

Balance & Faucet Errors#

Pre-Market Commitment Errors#

Settlement Claim Errors#

Rate Limiting#

General Errors#

Error Handling Best Practices#

1. Switch on error / code, not message. Messages may change; codes are stable.
2. Handle 401 by re-authenticating. If INVALID_API_KEY or KEY_REVOKED, your key may have been rotated elsewhere.
3. Handle 429 with backoff. Parse Retry-After and wait. Never tight-loop retries.
4. Handle 503 for signer. If SIGNER_NOT_READY, call retry-signer once and wait 5 seconds before retrying the trade.
5. Idempotency keys prevent duplicates. If you get a network timeout on a trade, retry with the same idempotency key to safely deduplicate.

Rate Limits#

All API endpoints are protected by sliding-window rate limits enforced via Upstash Redis. Limits are applied per-IP for unauthenticated endpoints and per-wallet for authenticated endpoints.

Agent API Endpoints#

Response Headers#

Every response from a rate-limited endpoint includes these headers:

When rate limited (HTTP 429), an additional header is included:

429 Response Body#

{
  "error": "Too many requests. Please try again later.",
  "code": "RATE_LIMIT_EXCEEDED",
  "statusCode": 429
}

Enforcement Model#

• Algorithm: Sliding window (not fixed window). Requests are counted over a rolling 60-second period, which prevents burst abuse at window boundaries.
• Identifier resolution:
  • Unauthenticated endpoints (nonce, register): First IP from x-forwarded-for header, or "unknown" if absent.
  • Authenticated endpoints (trade, rotate, revoke, keys): Wallet address extracted from the verified API key (not from request headers).
• Fail-open by default: If Redis is unavailable, requests are allowed through. Financial endpoints like blog ingest use fail-closed mode where Redis failure blocks requests.

Recommended Backoff Strategy#

For autonomous agents, implement exponential backoff with jitter:

async function withBackoff<T>(
  fn: () => Promise<Response>,
  maxRetries = 5,
): Promise<Response> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const res = await fn();

    if (res.status !== 429) return res;

    // Parse Retry-After header (seconds)
    const retryAfter = parseInt(res.headers.get("Retry-After") ?? "5", 10);

    // Exponential backoff with jitter
    const baseDelay = retryAfter * 1000;
    const jitter = Math.random() * 1000;
    const delay = Math.min(baseDelay + jitter, 60_000); // cap at 60s

    console.log(`Rate limited. Retrying in ${Math.round(delay / 1000)}s...`);
    await new Promise((r) => setTimeout(r, delay));
  }

  throw new Error("Max retries exceeded");
}

import time, random

def with_backoff(fn, max_retries=5):
    for attempt in range(max_retries + 1):
        res = fn()
        if res.status_code != 429:
            return res

        retry_after = int(res.headers.get("Retry-After", "5"))
        jitter = random.uniform(0, 1)
        delay = min(retry_after + jitter, 60)

        print(f"Rate limited. Retrying in {delay:.0f}s...")
        time.sleep(delay)

    raise Exception("Max retries exceeded")

Tips for Agents#

1. Track remaining quota. Read X-RateLimit-Remaining on every response. If it drops below 5, slow down proactively.
2. Batch where possible. One larger trade is better than many small ones from a rate limit perspective.
3. Use idempotency keys. If a request times out, retry with the same key rather than creating a new request that counts against your limit.
4. Spread requests. If polling for market data, add random delays between requests rather than hitting the API in tight loops.
5. Nonce requests are cheap. At 10/min you have plenty of headroom for registration retries. Don't cache nonces (they expire in 5 minutes anyway).