> ## Documentation Index > Fetch the complete documentation index at: https://docs.testnet.dev.adipredictstreet.com/llms.txt > Use this file to discover all available pages before exploring further. # Find an order by clientOrderId or orderHash > Find one of your orders by a key you hold before you have its `orderId`: the `clientOrderId` you sent (or the server-generated `srv-*` key a `placement_unknown` / `placement_matched` / `placement_resting` 503 returned in `details.clientOrderId`), or the order's EIP-712 `orderHash` (the digest of the struct you signed). Pass exactly one of the two; neither or both answers `400 invalid_request`. Returns the same `Order` as `GET /api/orders/{id}`. An unknown key, and an order of another wallet, answer `404 order_not_found`. Built for recovering from a place request that timed out or answered 5xx. A `404` right after such a timeout does not prove the order was never placed: it may not be recorded yet. Re-sending the identical request under the same `clientOrderId` stays the authoritative answer; never sign a new order until you know the first one was not placed. ## OpenAPI ````yaml /api-reference/openapi.json get /api/orders/lookup openapi: 3.1.0 info: title: PredictStreet API description: >- Client-facing HTTP API for the PredictStreet prediction-market platform. **Partner kinds.** Every authenticated endpoint resolves a request's *effective wallet* from the partner row. `single_wallet` partners bind to one `associatedWallet` set at creation. `multi_wallet` partners declare the actor on every request via an `X-User-Wallet: 0x<40-hex>` header. See the [Partner kinds](/auth/api-keys#partner-kinds) doc for the full contract. version: '2026-06-16' contact: name: PredictStreet partners email: partners@predictstreet.com servers: - url: https://core.api.dev.predictstreet.sde.adifoundation.ai description: Testnet (partner integrator API — final domain TBD) security: [] tags: - name: Deposits description: >- Gasless USDC deposit relay - submit a signed EIP-2612 permit and the platform broadcasts the on-chain deposit for you (no gas). - name: Events description: >- Polymarket-style event grouping with football metadata (group, stage, teams, tags). - name: Tags description: Curated tag taxonomy used to filter events. - name: Markets description: 'Public market data: list, detail, orderbook, trades, OHLC.' - name: Crypto description: >- Crypto price markets: the underlying-asset price curve and Up/Down series navigation. The markets themselves are ordinary binary markets — list them through /api/markets and /api/events. - name: Orders description: >- Signed-order place / cancel / read. Requires `X-Api-Key` with `orders:read` / `orders:write` scope; every write additionally requires an EIP-712 signature over the order. - name: Portfolio description: >- Balances, positions, trades, fees, vault info for the key's `associatedWallet`. Requires `X-Api-Key` with `portfolio:read` scope. - name: Matches description: >- A match groups several events into one fixture/card (1X2 + first-scorer + over-under under one matchup). - name: Vault description: >- Backend co-signatures for ERC-1155 split / merge, and recovery for off-chain locks when the corresponding chain tx never confirmed. Requires `X-Api-Key` with `vault:write` scope plus an EIP-712 signature over the operation. - name: Leaderboard description: Public ranked leaderboard across PnL / volume buckets. - name: Search description: Global search across users, events, and matches. - name: Withdrawal Security description: >- Self-service withdrawal 2FA (TOTP) and withdrawal-address whitelist. Same endpoints serve the web app (user sessions) and API-key integrators. Mutations need `vault:write`, reads `portfolio:read`. Both are opt-in per wallet and only gate withdrawals once the platform enables withdrawal-security enforcement. - name: Platform description: >- Public platform state: the contract registry, the platform fee configuration, the platform freeze flag and active notices. No authentication. paths: /api/orders/lookup: get: tags: - Orders summary: Find an order by clientOrderId or orderHash description: >- Find one of your orders by a key you hold before you have its `orderId`: the `clientOrderId` you sent (or the server-generated `srv-*` key a `placement_unknown` / `placement_matched` / `placement_resting` 503 returned in `details.clientOrderId`), or the order's EIP-712 `orderHash` (the digest of the struct you signed). Pass exactly one of the two; neither or both answers `400 invalid_request`. Returns the same `Order` as `GET /api/orders/{id}`. An unknown key, and an order of another wallet, answer `404 order_not_found`. Built for recovering from a place request that timed out or answered 5xx. A `404` right after such a timeout does not prove the order was never placed: it may not be recorded yet. Re-sending the identical request under the same `clientOrderId` stays the authoritative answer; never sign a new order until you know the first one was not placed. operationId: OrdersController_lookup parameters: - name: clientOrderId in: query required: false description: >- Your idempotency key, matched exactly (case-sensitive, not trimmed), 1–128 characters. URL-encode it: a raw `+` in a query string reads as a space. schema: type: string minLength: 1 maxLength: 128 - name: orderHash in: query required: false description: 'EIP-712 order hash: `0x` followed by 64 hex characters, any case.' schema: type: string pattern: ^0x[0-9a-fA-F]{64}$ - $ref: '#/components/parameters/UserWalletHeader' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Order' type: object '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' security: - ApiKey: - orders:read components: parameters: UserWalletHeader: name: X-User-Wallet in: header required: false description: >- **Required for `multi_wallet` partners on every authenticated request; ignored for `single_wallet`.** Declares the acting end-user wallet for this request — drives KYC checks, balances/positions/orders attribution, rate-limit buckets, and audit. Lower-cased server-side. Missing on a multi_wallet key → 401 `api_key_user_wallet_required`; malformed → 401 `api_key_user_wallet_invalid`. The on-chain `CTFExchange`/`Vault` contracts still verify EIP-712 signer ↔ vault binding, so loosening API-layer attribution is safe by construction. schema: $ref: '#/components/schemas/EthereumAddress' example: '0x1234567890abcdef1234567890abcdef12345678' schemas: Order: type: object properties: id: type: string userWallet: $ref: '#/components/schemas/EthereumAddress' maker: description: 'On-chain `Order.maker`: your vault (`VaultFactory.vaultOf(signer)`).' allOf: - $ref: '#/components/schemas/EthereumAddress' signer: description: Wallet (EOA) that signed the EIP-712 order. allOf: - $ref: '#/components/schemas/EthereumAddress' marketId: type: string side: type: string enum: - buy - sell outcome: type: string price: $ref: '#/components/schemas/DecimalString' quantity: $ref: '#/components/schemas/DecimalString' filledQty: $ref: '#/components/schemas/DecimalString' remainingQty: $ref: '#/components/schemas/DecimalString' expiration: type: integer description: >- Unix seconds, equal to the signed `Order.expiration` (sent as `expiry` when placing). `0` = no expiry. orderType: type: string enum: - LIMIT - MARKET description: Order type (uppercase, unlike the lowercase `type` request field). timeInForce: type: string enum: - GTC - IOC - FOK description: Time-in-force (uppercase, unlike the lowercase request field). status: type: string enum: - PENDING - OPEN - PARTIAL - FILLED - CANCELLED - REJECTED - EXPIRED - SETTLEMENT_FAILED description: Order status. `PARTIAL` = partly filled, the rest still open. clientOrderId: type: string orderHash: type: string nullable: true description: >- EIP-712 digest of the signed order, lowercase `0x` + 64 hex. The same hash the exchange contract emits in `OrderFilled`, and one you can compute before sending; look an order up by it with `GET /api/orders/lookup?orderHash=`. `null` only on a record that never stored one. example: '0x84a930f9e902ae9133b85e4e6c4bde91f2bdc2f0a8e1c9e7b5d6a4f3c2b1a0e9' createdAt: type: string format: date-time updatedAt: type: string format: date-time EthereumAddress: type: string pattern: ^0x[a-fA-F0-9]{40}$ example: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb3' DecimalString: type: string description: >- Decimal number encoded as a string to preserve precision (e.g. `'100.5'`). Error: type: object description: >- Error body returned by every API error (same shape as `ErrorEnvelope`). Branch on `error.code`, not on `message`. required: - status - error properties: status: type: integer description: HTTP status, repeated in the body. example: 404 error: type: object required: - code - message properties: code: type: string description: >- Machine-readable code (e.g. `market_not_found`, `event_not_found`, `invalid_limit`). message: type: string trace_id: type: string description: Request trace id; quote it to support. May be absent. retryAfterSec: type: integer description: >- Seconds to wait before retrying, when the server says so (also sent as the `Retry-After` header). retryable: type: boolean description: >- Whether the same request may be sent again as it is. Absent when the server does not say. details: type: object additionalProperties: true description: >- Extra structured context thrown with the error, e.g. `slug`, `allowed`, `auditId`. responses: BadRequest: description: Client error — invalid request body or parameter. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: >- Rate limit exceeded. `Retry-After` and `X-RateLimit-Reset` headers are set. headers: Retry-After: schema: type: integer X-RateLimit-Limit: schema: type: integer X-RateLimit-Remaining: schema: type: integer X-RateLimit-Reset: schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: ApiKey: type: apiKey in: header name: X-Api-Key description: >- Partner / integrator key — format `ps_live__`. Partner keys are issued by PredictStreet; a user can also create keys bound to their own wallet from their account settings in the web app. Never ship to a browser. `multi_wallet` partners must additionally send `X-User-Wallet: 0x<40-hex>` on every authenticated request to declare the acting wallet. See the [API keys guide](/auth/api-keys) for scope taxonomy, partner kinds, rate limits, and rotation procedure. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.