> ## 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. # Place a batch of signed orders (max 10) > Submit up to 10 EIP-712-signed orders in one request. Orders are processed sequentially in array order with independent per-order outcomes — one rejected order never aborts the rest, and there is no all-or-nothing atomicity. Each entry is validated, balance-locked, and matched exactly as a single POST /api/orders/place. Per-wallet monetary limits (KYC deposit tier, responsible-gambling, partner trade caps) accumulate across the batch, so a batch can never admit more exposure than the same orders sent one at a time. Rate limited at 5 req/sec per wallet (up to 50 orders/sec). KYC deposit-tier gating applies, same as single place. Business rejects (bad signature, insufficient funds, …) come back as per-entry REJECTED results with HTTP 200; infrastructure failures (matcher / verifier / DB unavailable) fail the whole request with a 5xx. Every forwarded entry carries a `clientOrderId` (the server mints one when you omit it) so a 5xx is safe to retry — replays return the already-committed result via idempotency instead of placing duplicates. ## OpenAPI ````yaml /api-reference/openapi.json post /api/orders/place-batch openapi: 3.1.0 info: title: PredictStreet core-api description: >- Client-facing HTTP gateway for the PredictStreet prediction-market platform. This spec is hand-written against the NestJS controllers and DTOs in core-api/src/modules/. For the source-of-truth live spec, run `./scripts/pull-openapi.sh` against a running core-api (NestJS exposes it at /api/docs-json). **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: 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: >- admin.matches aggregate — 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 frontend (Privy JWT) 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. paths: /api/orders/place-batch: post: tags: - Orders summary: Place a batch of signed orders (max 10) description: >- Submit up to 10 EIP-712-signed orders in one request. Orders are processed sequentially in array order with independent per-order outcomes — one rejected order never aborts the rest, and there is no all-or-nothing atomicity. Each entry is validated, balance-locked, and matched exactly as a single POST /api/orders/place. Per-wallet monetary limits (KYC deposit tier, responsible-gambling, partner trade caps) accumulate across the batch, so a batch can never admit more exposure than the same orders sent one at a time. Rate limited at 5 req/sec per wallet (up to 50 orders/sec). KYC deposit-tier gating applies, same as single place. Business rejects (bad signature, insufficient funds, …) come back as per-entry REJECTED results with HTTP 200; infrastructure failures (matcher / verifier / DB unavailable) fail the whole request with a 5xx. Every forwarded entry carries a `clientOrderId` (the server mints one when you omit it) so a 5xx is safe to retry — replays return the already-committed result via idempotency instead of placing duplicates. operationId: OrdersController_placeBatch parameters: - $ref: '#/components/parameters/UserWalletHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PlaceBatchRequest' responses: '200': description: >- Per-order results, aligned to the request `orders[]` by index. Inspect each entry's `success` flag and `status` — a 200 batch can still contain REJECTED entries. content: application/json: schema: $ref: '#/components/schemas/PlaceBatchRespDto' '400': description: >- Empty array, more than 10 entries, or a malformed entry. Nothing is placed. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': $ref: '#/components/responses/Unauthorized' '403': description: API-key caller is missing the orders:write scope. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/ServiceUnavailable' security: - ApiKeyAuth: - orders:write 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: PlaceBatchRequest: type: object required: - orders properties: orders: type: array minItems: 1 maxItems: 10 description: >- 1–10 orders, each identical in shape to the single POST /api/orders/place body. Processed sequentially in array order. items: $ref: '#/components/schemas/PlaceOrderRequest' PlaceBatchRespDto: type: array description: >- Per-order results, aligned to the request `orders[]` by index. Each item is a PlaceOrderRespDto plus a `success` flag. items: $ref: '#/components/schemas/PlaceBatchEntryDto' ErrorEnvelope: type: object required: - error properties: status: type: integer example: 400 error: type: object required: - code - message properties: code: type: string example: bad_request message: type: string details: type: object additionalProperties: true trace_id: type: string EthereumAddress: type: string pattern: ^0x[a-fA-F0-9]{40}$ example: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb3' PlaceOrderRequest: type: object required: - marketId - side - outcome - price - quantity - nonce - expiry - maker - signature properties: marketId: type: string example: NC26-BIN-83479265 description: >- App-level market symbol. The platform resolves the on-chain `tokenId` for the chosen `outcome` automatically. side: type: string enum: - buy - sell outcome: type: string enum: - '0' - '1' description: >- `0` = first outcome (YES for binary), `1` = second outcome (NO for binary). Index into `market.outcomes[]` for N-ary. price: $ref: '#/components/schemas/DecimalString' example: '0.42' description: >- Decimal USDC price per outcome token. Strictly between 0 and 1, max 6 decimals. quantity: $ref: '#/components/schemas/DecimalString' example: '2' description: Decimal outcome-token quantity. Strictly > 0, max 6 decimals. nonce: type: string description: >- Decimal-string of the `salt` field used in the signed EIP-712 `Order` struct (uint256). expiry: type: integer minimum: 0 example: 0 description: >- Unix-seconds = `Order.expiration` in the signed struct. **Recommended `0`** (no on-chain expiry); a tight TTL races async settlement and surfaces as `MatchFailed(OrderExpired)` (selector `0xc56873ba`). maker: $ref: '#/components/schemas/EthereumAddress' description: >- **Vault address** (= `VaultFactory.vaultOf(signer)`). Must equal `Order.maker` in the signed struct. The backend recomputes `vaultOf(signer)` and rejects mismatches with `400 bad_signature`. signature: $ref: '#/components/schemas/HexSignature' description: >- EIP-712 signature over the full on-chain `CTFExchange` `Order` struct (11 fields). `verifyingContract` = the binary `CTFExchange` or neg-risk `PredictStreetNegRiskCtfExchange` for the market. clientOrderId: type: string maxLength: 128 description: >- Idempotency key scoped per associatedWallet. A retry with the same `(wallet, clientOrderId)` returns the original response. type: type: string enum: - limit - market default: limit description: >- Order type. **`limit`** rests in the book at `price` (or matches incoming counterparties at price-or-better). **`market`** consumes the best resting prices up to `price` as a slippage cap. `market` requires `timeInForce` ∈ {`ioc`, `fok`} — `market` + `gtc` is rejected with `code: invalid_tif` because a MARKET order cannot rest. timeInForce: type: string enum: - gtc - ioc - fok description: >- Time-in-force. **`gtc`** (Good-Till-Cancelled) — default for `limit`; rests until filled, expired, or cancelled. **`ioc`** (Immediate-Or-Cancel) — match what is available at price-or-better, cancel any unfilled remainder immediately; partial fills are allowed. **`fok`** (Fill-Or-Kill) — fully fill or cancel without any partial fill. Default for `market` is `ioc`; sending `market` + `gtc` returns `400` with `code: invalid_tif`. postOnly: type: boolean default: false description: >- Post-only: the order must only rest on the book and never match on entry (maker-side guarantee). Only valid for LIMIT orders with GTC time-in-force (optionally with `expiry`); combining `postOnly` with a MARKET type or an IOC/FOK time-in-force is rejected with HTTP 400 and code `post_only_invalid_order_type`. A post-only order whose price meets or crosses the opposite side of the book (at-touch equality included) is rejected with `{ "status": "REJECTED", "code": "post_only_would_cross" }` instead of executing — reprice inside the spread and resubmit. Omitted ⇒ false (unchanged behavior). PlaceBatchEntryDto: allOf: - $ref: '#/components/schemas/PlaceOrderRespDto' - type: object required: - success properties: success: type: boolean description: >- `true` when the order was accepted (status ≠ REJECTED); `false` for a per-order business reject. Convenience flag over `status`. Error: type: object required: - code properties: code: type: string description: >- Machine-readable code (e.g. `insufficient_funds`, `market_not_open`, `rate_limited`). message: type: string details: type: object additionalProperties: true DecimalString: type: string description: >- Decimal number encoded as a string to preserve precision (e.g. `'100.5'`). HexSignature: type: string pattern: ^0x[a-fA-F0-9]+$ description: 0x-prefixed hex-encoded ECDSA signature (usually 65 bytes). PlaceOrderRespDto: type: object properties: orderId: type: string description: Server-side order id (UUID). Empty string when status=REJECTED. status: type: string enum: - PENDING - OPEN - FILLED - CANCELLED - REJECTED - EXPIRED - SETTLEMENT_FAILED description: >- Lifecycle state at the moment of response. Note: a 200 response may carry `status=REJECTED` together with a populated `code` / `message` — partner SDKs MUST inspect the body, not just the HTTP code (audit M5). filledQty: type: string description: Cumulative quantity filled at response time (decimal string). remainingQty: type: string description: '`quantity - filledQty` (decimal string).' trades: description: Synchronous fills produced by IOC/FOK or aggressive LIMIT orders. type: array items: $ref: '#/components/schemas/TradeFillDto' code: type: string description: >- Reject reason code (`insufficient_balance`, `invalid_amounts`, `market_not_open`, `bad_signature`, `order_signed_with_floor_notional`, `position_limit_breached`, …). Present when `status=REJECTED`. For `order_signed_with_floor_notional` the response body also carries a `details` object with `signedMakerAmountWei` + `expectedCeilMakerAmountWei` so the SDK can re-sign without recomputing the CEIL formula — see /errors/codes#order_signed_with_floor_notional-diagnostic-hints. message: type: string description: Human-readable explanation; pairs with `code`. clientOrderId: type: string description: >- Echo of the request `clientOrderId` (when supplied). Lets MM partners correlate the server-issued `orderId` to their own client-side handle without a follow-up `GET /api/orders/{id}`. Present on every shape (success, REJECTED, idempotent replay) when the request carried one. Also echoed on the `events.order_placed` and `events.order_cancelled` WS frames. required: - orderId - status - filledQty - remainingQty - trades TradeFillDto: type: object properties: id: type: string description: Server-side trade id (UUID). orderId: type: string description: Order id this fill belongs to. userWallet: type: string description: Maker/taker EOA depending on perspective; the wallet of the order. marketId: type: string description: Market symbol. price: type: string description: Fill price (USDC, decimal string). quantity: type: string description: Outcome-token quantity filled (decimal string). fee: type: string description: Quadratic taker fee charged on this fill (USDC, decimal string). side: type: string enum: - buy - sell description: Side of the order from this wallet's perspective. createdAt: type: string description: ISO-8601 timestamp. required: - id - orderId - userWallet - marketId - price - quantity - fee - side - createdAt responses: Unauthorized: description: Missing, invalid, or expired credentials. 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' ServiceUnavailable: description: Downstream service (exchange, matcher) unavailable. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-Api-Key description: >- Partner / integrator key — format `ps_live__`. Issued by PredictStreet ops via the admin panel; never self-service. 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. ````