Getting Started

Place your first prediction market order in 5 minutes. All curl — no SDK required.

All curl below runs against the real, live API. You'll mint an anonymous sandbox key in Step 1 (30 seconds, no email). Sandbox tier caps orders at $10 each / $100 daily, so nothing you type can move real money. Fills are simulated at mid-price against live orderbook state — the same code path production uses, minus the settlement.

Step 1 — Mint a sandbox key

Public endpoint, no authentication. Rate-limited to 1 mint per IP + 1 per browser fingerprint per day.

curl -X POST https://api.predictasiax.com/v1/sandbox-keys \
  -H "Content-Type: application/json" \
  -d '{"org_name":"my-test"}'

Response — copy api_key immediately, shown once:

{
  "ok":         true,
  "key_id":     2,
  "key_prefix": "7d40ce10",
  "api_key":    "sk_live_7d40ce10_12b638913cadfbbd...",   // your bearer, shown ONCE
  "user_id":    "sb_d5b09d2a38d41eca91b5ecc9",
  "org_name":   "my-test",
  "tier":       "self_serve",
  "expires_at": "2026-10-05T04:10:30.814Z",
  "limits":     { "max_order_usdt": 10, "daily_notional_usdt": 100 }
}

# Save it:
export SK=sk_live_7d40ce10_12b638913cadfbbd...

The key belongs to a newly-minted anonymous builder tagged tier=self_serve. It's an sk_live_ prefix accepted on production — the tier flag hard-caps orders at $10 each and $100/day notional.

Step 2 — List markets

PAX D1 has 20 seeded markets across 5 categories (crypto / politics / sports / tech / macro):

curl "https://api.predictasiax.com/v1/markets?q=btc" \
  -H "Authorization: Bearer $SK"

Response (trimmed):

{
  "data": {
    "markets": [
      {
        "id":        "m_btc_150k_2026",
        "title":     "BTC > $150k by end of 2026",
        "category":  "crypto",
        "prices":    { "yes": "0.4200", "no": "0.5800" },
        "volume_usd":"12345.67",
        "status":    "open",
        "closes_at_ms": 1798700400000
      }
    ]
  }
}

Step 3 — Place a $1 order

Buy 2 yes shares at $0.55 = $1.10 notional — well within sandbox $10 cap. Idempotency-Key is required on writes; safe to retry with the same value.

curl -X POST https://api.predictasiax.com/v1/orders \
  -H "Authorization: Bearer $SK" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-first-order-$(date +%s)" \
  -d '{
    "user_id":         "your-user-id",
    "market_id":       "m_btc_150k_2026",
    "side":            "yes",
    "price":           "0.55",
    "size":            "2",
    "client_order_id": "cli-001"
  }'

Response:

{
  "data": {
    "order": {
      "order_id":     "ord_...",
      "status":       "filled",
      "filled_size":  "2",
      "fill_price":   "0.4200",
      "created_at_ms":1787149484561
    },
    "fee": {
      "taker_fee_bps": 30,
      "fee_total":     "0.002520",         // 30 bps of $0.84 notional
      "splits": {
        "acquisition_builder": "0.000000", // unfilled → absorbed by platform_net
        "execution_builder":   "0.000504", // 6 bps — your app
        "operator":            "0.000252", // 3 bps
        "market_creator":      "0.000000", // unfilled → absorbed by platform_net
        "lp":                  "0.000588", // 7 bps
        "platform_net":        "0.001176"  // 3 bps residual + 6 (acq absorbed) + 5 (mc absorbed)
      },
      "attribution": {
        "execution_builder_id":   "sb_d5b09d2a...",   // your builder
        "acquisition_builder_id": null,
        "operator_id":            "op_pax_v3",
        "market_creator_id":      null,
        "builder_tier":           "self_serve",
        "unfilled_roles":         ["acquisition_builder","market_creator"]
      }
    },
    "trace": { "simulated_fill": true, "notional_usd": "0.84" }
  }
}

Notice the splits block — every fill writes idempotent financial_event rows on the Neon ledger via the 5-actor split (acquisition_builder / execution_builder / operator / market_creator / lp, + platform residual). Unfilled attribution roles are absorbed by platform_net so revenue is protected. Progressive tier: at trade_full your builder combined jumps to 14 bps (47% of fee); at genesis/partner to 16 bps (53%). Auto-graduated by 30d attributed volume. See Attribution + Fee Ledger for the full model.

Step 4 — Over-cap request (see tier caps in action)

Try an order over $10:

curl -X POST https://api.predictasiax.com/v1/orders \
  -H "Authorization: Bearer $SK" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: too-big-$(date +%s)" \
  -d '{
    "user_id":"your-user-id","market_id":"m_btc_150k_2026",
    "side":"yes","price":"0.50","size":"100",
    "client_order_id":"too-big"
  }'

Response — 429 TIER_LIMIT_EXCEEDED:

{
  "error": {
    "code":    "TIER_LIMIT_EXCEEDED",
    "message": "order notional 50.00 exceeds tier max_order_usdt 10",
    "details": { "tier": "self_serve", "cap": "10" }
  }
}

To lift the cap: submit Request access to move up to trade_capped ($100/order, $1k/day) or trade_full (uncapped).

Step 5 — Read your portfolio

curl "https://api.predictasiax.com/v1/portfolio" \
  -H "Authorization: Bearer $SK"

Returns your open positions with mark-price recompute (unrealized P&L on the fly).

Step 6 — Cancel an order

curl -X DELETE https://api.predictasiax.com/v1/orders/ord_... \
  -H "Authorization: Bearer $SK"

Filled orders return STATE_CONFLICT (cannot cancel a filled order); open orders transition to cancelled.

Next steps

Going to production? Same host, same base URL — https://api.predictasiax.com/v1. Submit a Request access to move your builder from sandbox to trade_capped or trade_full tier. No environment swap or key rotation required.