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.
  • requirePerWalletKyc: false — the partner is KYB-onboarded as a legal entity and takes compliance responsibility for its sub-accounts. Per-wallet KYC is not checked. 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:
    1. vault deploy (VaultFactory on-chain, ~10 sec to confirm);
    2. on-chain limits opening — DepositLimitRegistry.setTier(VIP) and setCustomCaps(0, 0, 0), plus setDepositsRestricted(false) / setTradingRestricted(false) / setWithdrawalsRestricted(false). setCustomCaps(0, 0, 0) clears any per-wallet override, so the VIP tier applies: no on-chain deposit ceiling on singleDeposit / 30d / 12m. PredictStreet broadcasts all five ops; the sub-account is fully usable end-to-end (deposit + trade + withdraw) within ~30 sec of the first request. Without this auto-step the wallet would stay at tier NONE: every vault.depositERC20 would revert with KycRequired, and trading and withdrawals would be blocked on-chain.
    Until the vault is deployed, orders are rejected with vault_not_deployed. While the on-chain limits are still confirming, orders may also be rejected with kyc_blocked. Retry after a few seconds. Need a per-sub-account deposit cap? Contact your integration manager.
• 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 the signer ↔ vault binding, so the X-User-Wallet header alone cannot authorise a trade for a wallet you don’t control.
• Each X-User-Wallet is the order’s signer. Sign the EIP-712 order with that wallet’s private key and put its address in the struct’s signer field. The struct’s maker must be that wallet’s vault (VaultFactory.vaultOf(signer), returned as vaultAddress by GET /api/me/vault), with signatureType: 1 (VAULT). It is never the EOA itself, and signatureType: 0 is not accepted.
• The REST body maker may be either the X-User-Wallet address or its vault. Any other value is rejected at the gateway with maker_mismatch (HTTP 401 on /api/orders/place, a per-entry REJECTED on /api/orders/place-batch).
• If the signature does not recover to the X-User-Wallet address (for example, because it was signed with maker set to the EOA or with signatureType: 0), placement returns status: "REJECTED" with code: "bad_signature". details.platform_canonical_struct is the exact struct the platform verified. Compare it field by field with the struct you signed.

​

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 wallets (trading desk with N sub-accounts). See Partner kinds above, including the market-maker requirement for orders:write.
4. Associated wallet — required for single_wallet partners that need write scopes; the wallet must have signed in to the web app at least once and cleared KYC tier 1. For multi_wallet partners the REST API ignores it, but if it is set, /ws/user binds every connection to that wallet and ignores X-User-Wallet. Leave it empty if you need per-sub-account user streams.
5. IP allowlist — not offered at the moment. Do not request one: the platform cannot yet match your egress IP reliably behind its edge, so an allowlisted key would be refused on every call (api_key_ip_denied). Protect the key by keeping the secret server-side and requesting only the scopes you need.
6. Requested scopes — what endpoints you plan to hit (see table below).

​

Scopes

​

Endpoint coverage

​

Authenticated endpoints

​

Public endpoints

• GET /api/markets, /api/markets/{slug}, /api/markets/{symbol}/orderbook, /api/markets/{symbol}/trades, /api/markets/{symbol}/ohlc
• GET /api/events, /api/events/{slug}, /api/events/featured, /api/events/stats
• GET /api/matches, /api/matches/{slug}
• GET /api/tags
• GET /api/platform/contracts, /api/platform/fee-config, /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 signature by the X-User-Wallet key over the order with maker = its vault…"
  }'

​

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. 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. 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.
6. Scope check. Missing → 403 api_key_scope_missing with the required scope in the response body.
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; worst-case lag 60s.

​

Security invariants

• X-Api-Key is the only scheme for partner integrations. No cookies, no basic-auth fallback on core.api.dev.predictstreet.sde.adifoundation.ai. The API also accepts Authorization: Bearer tokens, but those are web-app user session tokens, not a partner credential. If both are sent, X-Api-Key wins. A request with neither on an authenticated endpoint gets 401 auth_required; a malformed key gets 401 api_key_bad_format.
• 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.