> ## 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. # Submit a signed permit for gasless deposit relay > Gasless USDC deposit. The user signs an EIP-2612 `USDC.permit` TypedData with their embedded wallet (spender = `multicallExecutor` from `GET /api/platform/contracts`, value = amount, nonce = `USDC.nonces(owner)`) and posts the split signature `(v, r, s)` here. The backend ecrecovers the signature (must equal the authenticated wallet), validates deadline / chain / token / nonce + runs compliance + a tier-cap pre-check, persists a `deposit_audit` row, and enqueues a `permit_deposit` job. The relayer then broadcasts an atomic MulticallExecutor batch (permit -> transferFrom -> approve -> Vault.depositERC20 -> cleanup) so the user pays no gas. Poll `GET /api/deposits/relay/{auditId}` for progress. The `auditId` is returned even on failure so it can be referenced in support. Rate-limited 60/min/IP and 10/min/wallet. ## OpenAPI ````yaml /api-reference/openapi.json post /api/deposits/relay 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/deposits/relay: post: tags: - Deposits summary: Submit a signed permit for gasless deposit relay description: >- Gasless USDC deposit. The user signs an EIP-2612 `USDC.permit` TypedData with their embedded wallet (spender = `multicallExecutor` from `GET /api/platform/contracts`, value = amount, nonce = `USDC.nonces(owner)`) and posts the split signature `(v, r, s)` here. The backend ecrecovers the signature (must equal the authenticated wallet), validates deadline / chain / token / nonce + runs compliance + a tier-cap pre-check, persists a `deposit_audit` row, and enqueues a `permit_deposit` job. The relayer then broadcasts an atomic MulticallExecutor batch (permit -> transferFrom -> approve -> Vault.depositERC20 -> cleanup) so the user pays no gas. Poll `GET /api/deposits/relay/{auditId}` for progress. The `auditId` is returned even on failure so it can be referenced in support. Rate-limited 60/min/IP and 10/min/wallet. parameters: - $ref: '#/components/parameters/UserWalletHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RelayDepositBody' responses: '200': description: Permit accepted and enqueued for relay. content: application/json: schema: $ref: '#/components/schemas/RelayDepositResponse' '400': description: >- Permit validation failed (e.g. permit_deadline_passed, permit_deadline_too_soon, permit_chain_mismatch, permit_token_mismatch, permit_nonce_mismatch). Body carries code, message, and auditId. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: >- Authorization or compliance failure (e.g. permit_signer_mismatch, restriction_active, aml_blocked, tier_cap_exceeded, no_vault). Body carries code, message, and auditId. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Rate-limited (60/min/IP or 10/min/wallet). content: application/json: schema: $ref: '#/components/schemas/Error' security: - ApiKeyAuth: - vault: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: RelayDepositBody: type: object required: - amount - permitNonce - permitDeadline - v - r - s properties: amount: type: string description: >- USDC amount in raw units (6 decimals — 1 USDC = "1000000"). Must equal the value signed into the permit. example: '25000000' permitNonce: type: string description: >- Current `USDC.nonces(owner)`, read on-chain immediately before signing. example: '7' permitDeadline: type: integer description: >- EIP-2612 permit deadline, unix seconds. Must leave the submitter enough buffer or the request is rejected with permit_deadline_too_soon. example: 1780000000 v: type: integer description: Recovery id of the permit signature. example: 27 r: type: string description: 32-byte r component of the permit signature (0x-hex). example: 0x... s: type: string description: 32-byte s component of the permit signature (0x-hex). example: 0x... permitOwner: type: string description: >- Optional. The wallet the permit was built for; if present it must equal the authenticated wallet, else permit_signer_mismatch. Defence-in-depth only — the canonical signer is recovered server-side. example: '0x1234567890abcdef1234567890abcdef12345678' RelayDepositResponse: type: object required: - auditId - jobId - status properties: auditId: type: string format: uuid description: Deposit audit id — poll GET /api/deposits/relay/{auditId}. jobId: type: string description: Enqueued meta-tx (permit_deposit) job id. status: type: string description: Initial status, typically PENDING_SCREENING. example: PENDING_SCREENING 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 EthereumAddress: type: string pattern: ^0x[a-fA-F0-9]{40}$ example: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb3' 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. ````