Skip to main content
PredictStreet’s integrator API is server-to-server only. Every authenticated endpoint takes a single header — X-Api-Key — backed by a per-partner secret your ops contact hands you at onboarding. There is no OAuth, no SIWE, no cookie session. Public read endpoints (markets / events / matches / tags) work without a key but accept one to raise your rate-limit ceiling.

​
First time here?

1

Get an API key

Keys are issued by PredictStreet ops, never self-service. Email your integration manager (or partners@predictstreet.com) with the four items in API keys → Getting a key: partner name, contact email, associated wallet (the EOA you’ll sign EIP-712 orders with), and the scopes you need.
2

Walk through the testnet quickstart

Quickstart takes the private key of your associatedWallet from zero to a settled trade in five steps — mint USDC, deploy/verify your vault, deposit, sign + place an order, observe settlement. Every code block is real ethers v6 against the live testnet; copy-paste, swap your secrets, run.
3

Mental model — Wallet, vault, scopes

Every API key is bound at issue time to one (or many) associated wallets — the EOAs whose private key you hold and which sign EIP-712 orders. Each associated wallet has a deterministic vault contract that holds your USDC and your outcome shares; the vault is the maker field of every signed Order. Vaults auto-deploy after the wallet clears KYC tier 1 — you never call VaultFactory.deployVault() manually unless you want to. Scopes on the key gate which endpoint groups the key can hit (orders:write, portfolio:read, vault:write, public reads). The full mental model lives at Platform overview; the concept pages on Vaults and Deposits round it out.

​
Authentication on the playground

Every locked endpoint shows a lock icon with ApiKeyAuth. To enable Try-it-out:
  1. Click Authorize.
  2. Paste the full key (e.g. ps_live_0123456789abcdef_AbCdEfGhIjKlMnOpQrStUvWxYz1234567) into the X-Api-Key field.
  3. The key persists across endpoint pages in your browser session.
Scopes are enforced server-side — your key must carry the scope listed on the operation (orders:write, portfolio:read, etc.) or the request returns 403 api_key_scope_missing. For multi-wallet partners (one key dispatching N actor wallets), set the X-User-Wallet header on every request to the actor wallet the call should run as. Single-wallet partners ignore that header — the key’s static associatedWallet is used unconditionally. See Partner kinds for the full distinction. See API keys for format, full scope taxonomy, endpoint coverage table, rate-limit buckets, and rotation procedure.

​
Endpoint groups

Use the left sidebar to browse. The Scope column lists the API-key scope each group requires — write scopes (orders:write, vault:write) are issued only to keys whose associatedWallet has cleared KYC tier 1.
GroupRequired scopeWhat’s in there
Events / Tags(public)Event discovery and curated tag taxonomy
Matches(public)Fixture / card grouping multiple events into one matchup
Markets(public)List markets, detail, orderbook, public trades, OHLC
Ordersorders:read (GET) / orders:write (POST)Place / cancel / read signed orders
Portfolioportfolio:readBalances, positions, trades, fees, fee tier, vault info, deposit limits
Vaultvault:writeDual-sig signature requests for splitPosition / mergePositions
Withdrawalsvault:write (mutate) / portfolio:read (read)Request, list, fee preview, deposit-source pin, cancel
Surfaces that require retail-user SIWE identity (user profile, KYC submission, consent management, responsible-gambling, session management) live on the retail web surface — app.predictstreet.io — and are intentionally not exposed to integrators. The SUMSUB / geo-fingerprinting layer expects a live retail session for those flows. Partners who need a use case currently outside the API-key surface should reach out — some can be unlocked with a stricter scope set, others are architecturally out of scope.

​
Conventions

  • Base URL: https://core.api.dev.predictstreet.sde.adifoundation.ai (testnet). Staging and mainnet URLs delivered at partner onboarding.
  • Numeric fields are encoded as strings to preserve precision (e.g. "price": "0.5214", not 0.5214). Deserialize into decimal.Decimal / BigDecimal / ethers.parseUnits — not Number.
  • Timestamps are ISO-8601 UTC (e.g. "2026-04-22T10:31:05.124Z").
  • Errors share a common envelope: { code, message, details? }. See Error codes for the full catalogue.
  • Rate limits — three buckets (IP / wallet / partner) apply to every authenticated request; see Rate limits.
  • Business rejects on some endpoints return HTTP 200 (or 201 for POSTs) with a status: "REJECTED" + code field inside the response envelope — notably POST /api/orders/place, which returns 201 Created even when the matcher rejects the order. Always read the body’s status field, not just the HTTP code. Full catalogue in Errors overview.
  • Enum query params (e.g. ?status= on /api/orders/history, ?interval= on /api/markets/{symbol}/ohlc) reject unknown values with 400 bad_request. Typos like ?status=CANCELED (one L) used to silently return an empty result; they now fail fast.
  • Unknown query params that aren’t in the enum-validated set (cursor, extra filters core-api doesn’t know about) are silently ignored rather than rejected. Don’t rely on this behaviour — future versions may tighten to 400.

​
Where to go next

API keys — format, scopes, rotation

The canonical reference for the auth header, scope taxonomy, IP allowlisting, multi_wallet vs single_wallet kinds, and key rotation procedure.

Quickstart — testnet end-to-end

Five-step copy-paste from API key to settled trade against the live testnet.

Vaults — what they are + how they deploy

Why every partner has a vault, how auto-deploy works, what Order.maker should be, and when you’d ever deploy manually.

EIP-712 signing — Order struct + domain

The 11-field Order struct, the binary vs neg-risk verifyingContract swap, and end-to-end signing examples.