> ## 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. # Return USDC sent to the vault by a plain transfer to the owner wallet (RND-2019) > USDC transferred straight to a vault address (not deposited) is never credited: GET /api/me/vault shows it as `strayUsdc`. This queues the vault's `sweepOffLedgerERC20(USDC)` on the platform relay (no gas for the user): the contract sends everything stray at execution to the wallet that owns the vault — the backend chooses neither amount nor recipient. Default vault: the active one; `vault` names another of the caller's vaults.\n\nIdempotent per vault: while a return is in flight a repeat answers that job (`enqueued: false`, nothing read or queued); once it has ended, a call queues a new one if USDC is stray again. Poll GET /api/me/vault/stray-usdc/return/{jobId}. On `confirmed`, /api/me/activity shows a `stray_usdc_return` row.\n\n202: queued or in flight (body = the job); 200: a call that met a job which had just ended (body = that job). 409 `no_stray_usdc`: nothing stray (nothing queued). 409 `stray_usdc_return_disabled`: off on this environment. 400 `vault_not_deployed` / `invalid_vault`, 404 `vault_not_found`. 422 `stray_usdc_return_reverted`: the simulation reverted; nothing queued. 503 `stray_usdc_unavailable` (`retryAfterSec`): the chain could not be read, or returns are paused on the platform side (`GET /api/me/vault` `strayUsdcReturnBlockedBy` says so up front) — nothing queued, retry. 503 `platform_frozen` / `withdrawals_frozen` (`retryAfterSec`): the platform or the withdrawals freeze is on — nothing is queued; a return queued before the freeze stays `pending` (held, not sent) and goes ahead once it lifts, so keep polling its `jobId`. 429 `rate_limited`. A queued return the relay has not sent in time (a freeze included) ends `expired`; ask again. ## OpenAPI ````yaml /api-reference/openapi.json post /api/me/vault/stray-usdc/return openapi: 3.1.0 info: title: PredictStreet API description: >- Client-facing HTTP API for the PredictStreet prediction-market platform. **Partner kinds.** Every authenticated endpoint except the partner-level platform reads (`/api/platform/status`, `/notices`, `/maintenance`) 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: >- Platform reference data and state. The contract registry and the fee configuration are public and need no key. The freeze flag (`/status`), active notices (`/notices`) and maintenance windows (`/maintenance`) need a partner API key in `X-Api-Key`. paths: /api/me/vault/stray-usdc/return: post: tags: - Portfolio summary: >- Return USDC sent to the vault by a plain transfer to the owner wallet (RND-2019) description: >- USDC transferred straight to a vault address (not deposited) is never credited: GET /api/me/vault shows it as `strayUsdc`. This queues the vault's `sweepOffLedgerERC20(USDC)` on the platform relay (no gas for the user): the contract sends everything stray at execution to the wallet that owns the vault — the backend chooses neither amount nor recipient. Default vault: the active one; `vault` names another of the caller's vaults.\n\nIdempotent per vault: while a return is in flight a repeat answers that job (`enqueued: false`, nothing read or queued); once it has ended, a call queues a new one if USDC is stray again. Poll GET /api/me/vault/stray-usdc/return/{jobId}. On `confirmed`, /api/me/activity shows a `stray_usdc_return` row.\n\n202: queued or in flight (body = the job); 200: a call that met a job which had just ended (body = that job). 409 `no_stray_usdc`: nothing stray (nothing queued). 409 `stray_usdc_return_disabled`: off on this environment. 400 `vault_not_deployed` / `invalid_vault`, 404 `vault_not_found`. 422 `stray_usdc_return_reverted`: the simulation reverted; nothing queued. 503 `stray_usdc_unavailable` (`retryAfterSec`): the chain could not be read, or returns are paused on the platform side (`GET /api/me/vault` `strayUsdcReturnBlockedBy` says so up front) — nothing queued, retry. 503 `platform_frozen` / `withdrawals_frozen` (`retryAfterSec`): the platform or the withdrawals freeze is on — nothing is queued; a return queued before the freeze stays `pending` (held, not sent) and goes ahead once it lifts, so keep polling its `jobId`. 429 `rate_limited`. A queued return the relay has not sent in time (a freeze included) ends `expired`; ask again. operationId: PortfolioController_returnStrayUsdc parameters: - $ref: '#/components/parameters/UserWalletHeader' - name: vault in: query required: false description: >- One of the caller's vaults from GET /api/me/vault `vaults[]`. Default: the active vault. 404 `vault_not_found` otherwise. schema: type: string responses: '200': description: The call met the vault's return job just after it ended. content: application/json: schema: $ref: '#/components/schemas/StrayUsdcReturnRespDto' '202': description: Queued, or the vault's return already in flight. content: application/json: schema: $ref: '#/components/schemas/StrayUsdcReturnRespDto' '400': description: '`vault_not_deployed` or `invalid_vault`.' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: '`vault_not_found`: `vault` is not one of the caller''s vaults.' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '409': description: '`no_stray_usdc` (nothing to return) or `stray_usdc_return_disabled`.' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '422': description: >- `stray_usdc_return_reverted`: the simulation reverted; nothing queued. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: >- Rate limited (`me-vault-stray-usdc-return` 10/min per wallet, 60/min per partner). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '503': description: >- `stray_usdc_unavailable`: the chain read or simulation failed, or returns are paused on the platform side; retry after `retryAfterSec`. `platform_frozen` / `withdrawals_frozen`: a freeze is on, nothing queued. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - ApiKey: [] 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: StrayUsdcReturnRespDto: type: object allOf: - $ref: '#/components/schemas/StrayUsdcReturnJobDto' properties: generation: type: integer enum: - 1 - 2 description: Contract generation of the vault. strayUsdc: type: string nullable: true example: '1950' description: >- The stray USDC read on chain before the job was queued (decimal string). Null when answering an in-flight job. enqueued: type: boolean description: >- true when this call queued the job; false when answering a job already in flight. required: - generation - strayUsdc - enqueued ErrorEnvelope: type: object description: >- Error body returned by every API error (same shape as `Error`). Branch on `error.code`, not on `message`. required: - status - error properties: status: type: integer description: HTTP status, repeated in the body. example: 400 error: type: object required: - code - message properties: code: type: string description: Machine-readable code. example: bad_request 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. EthereumAddress: type: string pattern: ^0x[a-fA-F0-9]{40}$ example: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb3' StrayUsdcReturnJobDto: type: object description: Relay job tracking the return of stray USDC sent to a vault address. properties: jobId: type: string description: Relay job id; poll GET /api/me/vault/stray-usdc/return/{jobId}. vaultAddress: type: string description: The vault the USDC is returned from (lowercase 0x-hex). status: type: string enum: - pending - building - submitted - confirmed - failed_permanent - expired description: >- `pending` / `building` / `submitted`: in progress. `confirmed`: transaction mined — USDC returned to owner wallet. `expired`: nothing sent. `failed_permanent`: see `failureKind`. txHash: type: string nullable: true description: Transaction hash once broadcast. failureKind: type: string nullable: true enum: - reverted - submission_failed - null description: Set on failed_permanent only. nothingToReturn: type: boolean description: >- true when the job ended without a transaction because the vault held no stray USDC anymore by execution time. requestedAt: type: string format: date-time confirmedAt: type: string nullable: true format: date-time required: - jobId - vaultAddress - status - txHash - failureKind - nothingToReturn - requestedAt - confirmedAt 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.