API keys

​

Who this is for

• Market-maker bot quoting a pre-approved wallet
• Copy-trading service mirroring strategy signals
• Data pipeline pulling your positions / fills into a warehouse
• Mobile backend that never ships secrets to the device

​

Format

X-Api-Key: ps_live_0123456789abcdef_AbCdEfGhIjKlMnOpQrStUvWxYz1234567
           ├─── env ───┤├── keyId ──┤├──────── secret ─────────┤

​

Partner kinds

​

Compliance toggle on multi_wallet

​

single_wallet flow

​

multi_wallet flow

curl -X POST https://core.api.dev.predictstreet.sde.adifoundation.ai/api/orders/place \
  -H "X-Api-Key: ps_live_0123456789abcdef_AbCdEfGhIjKlMnOpQrStUvWxYz1234567" \
  -H "X-User-Wallet: 0x1234567890AbCdEf1234567890aBcDeF12345678" \
  -H "Content-Type: application/json" \
  -d '{ "maker": "0x1234…", "signature": "0x…", … }'

• Header missing → 401 api_key_user_wallet_required.
• Header malformed (not 0x + 40 hex) → 401 api_key_user_wallet_invalid.
• KYC enforcement on the header wallet is controlled by the partner’s requirePerWalletKyc flag (see Partner kinds table above). Two options:
  • requirePerWalletKyc: true (default) — every X-User-Wallet sub-account must clear retail KYC (status APPROVED, tier ≥ 1) via the same SumSub flow a retail user goes through. Used for sub-account models where each underlying wallet is a distinct person (Coinbase Prime style).
  • requirePerWalletKyc: false — the partner is KYB-onboarded as a legal entity and takes compliance responsibility for its sub-accounts. KycGuard skips. Used for trading firms / market makers / submitters whose addresses are operational, not retail identities. The first request through the key for a previously unseen X-User-Wallet auto-enqueues a vault deploy; subsequent requests use the deployed vault as soon as match-submitter confirms.
• Each acting wallet still needs its own private key to sign the EIP-712 payload on writes. The on-chain CTFExchange and Vault contracts verify signer ↔ vault cryptographically — looser API-layer attribution costs nothing structurally because the chain is the floor.
• The wallet you pass in X-User-Wallet must match the maker field inside the order payload (and the EIP-712 signer for that order). Mismatches are caught at the matcher / on-chain layer with bad_signature.

​

Getting a key

1. Partner name — internal label.
2. Contact email — for rotation notices, incident pages, and SLA comms.
3. Partner kind — single_wallet (default) or multi_wallet. Pick multi_wallet if one key needs to act across many end-user wallets (trading desk with N sub-accounts, copy-trading platform, custodial broker). See Partner kinds above.
4. Associated wallet — required for single_wallet partners that need write scopes; must have completed SIWE once and cleared KYC tier 1. For multi_wallet partners this field is optional and informational — KYC moves to the partner legal entity.
5. IP allowlist (optional, recommended). Your egress IPs — if set, any request from a different IP is rejected at the edge.
6. Requested scopes — what endpoints you plan to hit (see table below).

​

Scopes

​

Endpoint coverage

​

Authenticated endpoints

​

Public endpoints

• GET /api/markets, /api/markets/{symbol}, /api/markets/{symbol}/orderbook, /api/markets/{symbol}/trades, /api/markets/{symbol}/ohlc
• GET /api/events, /api/events/{id}
• GET /api/matches, /api/matches/{id}
• GET /api/tags
• GET /api/platform/notices, /api/platform/status
• GET /api/compliance/geo
• GET /health, /ready

​

WebSocket

​

Not available via API key

​

Making a request

curl -X POST https://core.api.dev.predictstreet.sde.adifoundation.ai/api/orders/place \
  -H "X-Api-Key: ps_live_0123456789abcdef_AbCdEfGhIjKlMnOpQrStUvWxYz1234567" \
  -H "Content-Type: application/json" \
  -d '{
    "marketId": "UAE-CUP-FINAL-20260425",
    "side": "buy",
    "outcome": "0",
    "price": "0.55",
    "quantity": "100",
    "nonce": "1730289600000000",
    "expiry": 1730376000,
    "maker": "0xYOUR_ASSOCIATED_WALLET",
    "signature": "0x…EIP-712 signature over the order…"
  }'

curl -X POST https://core.api.dev.predictstreet.sde.adifoundation.ai/api/orders/place \
  -H "X-Api-Key: ps_live_0123456789abcdef_AbCdEfGhIjKlMnOpQrStUvWxYz1234567" \
  -H "X-User-Wallet: 0x1234567890AbCdEf1234567890aBcDeF12345678" \
  -H "Content-Type: application/json" \
  -d '{
    "marketId": "UAE-CUP-FINAL-20260425",
    "side": "buy",
    "outcome": "0",
    "price": "0.55",
    "quantity": "100",
    "nonce": "1730289600000000",
    "expiry": 1730376000,
    "maker": "0x1234567890AbCdEf1234567890aBcDeF12345678",
    "signature": "0x…EIP-712 signed by that maker's key…"
  }'

​

What happens on every request

1. Parse the X-Api-Key header into (env, keyId, secret). Bad shape → 401 api_key_bad_format.
2. Lookup the key by keyId (Redis cache, 60s TTL; falls through to Postgres on miss). Unknown → 401 api_key_unknown_key.
3. Verify the hash in constant time. Mismatch → 401 api_key_bad_secret.
4. Lifecycle checks: revoked → 401 api_key_revoked; expired → 401 api_key_expired; partner suspended → 401 api_key_suspended; source IP not in allowlist (if set) → 401 api_key_ip_denied.
5. Scope check. Missing → 403 api_key_scope_missing with the required scope in the response body.
6. Resolve effective wallet — depending on partner kind:
   • single_wallet → partner.associatedWallet. Not attached → 401 api_key_no_associated_wallet.
   • multi_wallet → the X-User-Wallet header (lower-cased). Header missing → 401 api_key_user_wallet_required; not a 0x-prefixed 40-hex address → 401 api_key_user_wallet_invalid.
7. Set identity — the resolved wallet becomes the request’s effective wallet for all downstream checks (KYC, compliance, rate-limit buckets, audit trails).

​

Rate limits

• IP bucket — shared edge defence (same as anonymous traffic).
• Wallet bucket — per effective wallet (the associatedWallet for single_wallet, or the X-User-Wallet header value for multi_wallet). Same ceiling regardless of call volume distribution across your keys.

​

Geo handling

​

Rotation

• Employee who had access leaves.
• Secrets-manager misconfiguration suspected.
• Source-code leak.
• Routine 6-month rotation hygiene.

1. Issue the replacement key via admin. Both keys now work.
2. Roll your services to the new key. No downtime.
3. Revoke the old key via admin. Propagation is near-instant (Redis pub-sub invalidation); worst-case lag 60s.

​

Security invariants

• X-Api-Key is the only session scheme. No cookies, no bearer tokens, no basic-auth fallback on core.api.dev.predictstreet.sde.adifoundation.ai. Missing or malformed header on an authenticated endpoint → 401.
• Scopes are enforced server-side. Adding a scope to your key’s stored list is the only way to access a gated endpoint — client-side claims are ignored.
• Writing still requires EIP-712. The API key proves you’re a pre-approved partner; the EIP-712 order signature proves you authorised the specific trade. CTFExchange verifies this cryptographically on-chain — no compromise of our infrastructure lets anyone move your funds without your private key.
• HMAC request signing (adding an X-Api-Signature header over timestamp + method + path + body) is on the roadmap as an optional hardening for production partners; not required today.