> ## 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. # Release an EXPIRED split / merge lock after verifying on-chain absence > User-initiated recovery for an EXPIRED dual-signed operation when the backend's automatic sweeper is disabled in observation-only mode. Releases the off-chain lock back to the caller's balance after PG-side chain verification that the operation did NOT execute on-chain. **Supported `op_kind`**: `SPLIT` and `MERGE`. `CONVERT` / `REDEEM` follow in subsequent releases. **Gates checked in order** (any failure short-circuits with no balance movement): 1. **Ownership** — caller's `X-User-Wallet` must resolve to the same `vault_address` recorded on the signed op (else `403 vault_owner_mismatch`). 2. **Op kind** — must be `SPLIT` or `MERGE` (else `400 op_kind_unsupported`). 3. **Already terminal** — if the op is already `EXPIRED` / `CANCELLED` / `REVERTED` / `REJECTED` / `FAILED` (i.e. refunded by some other path), the call is a `200` no-op with `refundAppliedNow=false` for idempotent client retries. 4. **Age** — `now - deadline >= 90s` (else `425 op_too_recent`). The 90s safety buffer matches the auto-sweeper's `SAFETY_SEC_DEFAULT` so a tx mined just after the off-chain deadline cannot be double-counted. 5. **Chain-watcher liveness** — exchange-service probes chain-watcher's own `/health/chain-sync` endpoint and refuses the release if the indexer is lagging (else `503 chain_watcher_lagging` / `chain_watcher_unreachable` / `chain_watcher_url_unset`). Without this gate, an unindexed chain-confirmed split/merge would falsely look like a no-execute and double-credit the vault. 6. **Chain-row absence** — `LEFT JOIN` against the per-kind events table (`chain_watcher.vault_position_split_events` for `SPLIT`, `chain_watcher.vault_positions_merged_events` for `MERGE`) keyed by `(vault, conditionId, amount)`. If a matching row exists the call returns `409 op_confirmed_on_chain` with the chain `event_key` / `tx_hash` / `blockNumber` in the error `details` payload so operators can re-drive the chain-event-router manually instead of unlocking duplicate funds. On success the op transitions to `EXPIRED`, `refunded=true`, and a single `balance_events` row is appended with reason `split_user_refund_verified` (SPLIT) or `merge_user_refund_verified` (MERGE) — distinct from the sweeper's `*_expired_refund` so audit / reconcile queries can attribute the unlock to the user-driven path. ## OpenAPI ````yaml /api-reference/openapi.json post /api/dual-signed-ops/{opId}/release-expired 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/dual-signed-ops/{opId}/release-expired: post: tags: - Vault summary: Release an EXPIRED split / merge lock after verifying on-chain absence description: >- User-initiated recovery for an EXPIRED dual-signed operation when the backend's automatic sweeper is disabled in observation-only mode. Releases the off-chain lock back to the caller's balance after PG-side chain verification that the operation did NOT execute on-chain. **Supported `op_kind`**: `SPLIT` and `MERGE`. `CONVERT` / `REDEEM` follow in subsequent releases. **Gates checked in order** (any failure short-circuits with no balance movement): 1. **Ownership** — caller's `X-User-Wallet` must resolve to the same `vault_address` recorded on the signed op (else `403 vault_owner_mismatch`). 2. **Op kind** — must be `SPLIT` or `MERGE` (else `400 op_kind_unsupported`). 3. **Already terminal** — if the op is already `EXPIRED` / `CANCELLED` / `REVERTED` / `REJECTED` / `FAILED` (i.e. refunded by some other path), the call is a `200` no-op with `refundAppliedNow=false` for idempotent client retries. 4. **Age** — `now - deadline >= 90s` (else `425 op_too_recent`). The 90s safety buffer matches the auto-sweeper's `SAFETY_SEC_DEFAULT` so a tx mined just after the off-chain deadline cannot be double-counted. 5. **Chain-watcher liveness** — exchange-service probes chain-watcher's own `/health/chain-sync` endpoint and refuses the release if the indexer is lagging (else `503 chain_watcher_lagging` / `chain_watcher_unreachable` / `chain_watcher_url_unset`). Without this gate, an unindexed chain-confirmed split/merge would falsely look like a no-execute and double-credit the vault. 6. **Chain-row absence** — `LEFT JOIN` against the per-kind events table (`chain_watcher.vault_position_split_events` for `SPLIT`, `chain_watcher.vault_positions_merged_events` for `MERGE`) keyed by `(vault, conditionId, amount)`. If a matching row exists the call returns `409 op_confirmed_on_chain` with the chain `event_key` / `tx_hash` / `blockNumber` in the error `details` payload so operators can re-drive the chain-event-router manually instead of unlocking duplicate funds. On success the op transitions to `EXPIRED`, `refunded=true`, and a single `balance_events` row is appended with reason `split_user_refund_verified` (SPLIT) or `merge_user_refund_verified` (MERGE) — distinct from the sweeper's `*_expired_refund` so audit / reconcile queries can attribute the unlock to the user-driven path. operationId: ReleaseExpiredController_releaseExpired parameters: - name: opId in: path required: true description: >- `signed_ops.id` UUID returned by the original split / merge / convert signature endpoint. schema: type: string format: uuid - $ref: '#/components/parameters/UserWalletHeader' responses: '200': description: >- Refund applied, or no-op snapshot of an already-terminal op (use `refundAppliedNow` to distinguish). content: application/json: schema: $ref: '#/components/schemas/ReleaseExpiredResponse' '400': description: >- `op_kind_unsupported` — release-expired is gated to `SPLIT` and `MERGE` in this release. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Missing or invalid `X-Api-Key` / `X-User-Wallet`. '403': description: >- `vault_owner_mismatch` — caller's wallet does not own the op's vault. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: >- `op_not_found` — no `signed_ops` row with the given UUID. `vault_not_found` — caller wallet has no `core.users.vault_address` (user has not finished onboarding). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '409': description: >- `op_confirmed_on_chain` — a matching row exists in the per-kind chain-watcher events table; the op did execute on-chain even though the off-chain side did not transition to `CONFIRMED`. Details include `eventKey`, `txHash`, and `blockNumber` so the chain-event-router can be re-driven. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '425': description: >- `op_too_recent` — `now - deadline < 90s`. Retry after the safety buffer elapses. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate-limited. See per-endpoint limits in the auth overview. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '503': description: >- `chain_watcher_lagging` / `chain_watcher_unreachable` / `chain_watcher_probe_invalid` / `chain_watcher_url_unset` — chain-watcher is not current with chain head, so the chain-row absence check is not authoritative. Fail-closed: retry once the indexer catches up. `details` carries `headBlock` / `processedBlock` / `lagBlocks` when the probe returned a body. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' 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: ReleaseExpiredResponse: type: object required: - signedOpId - opKind - status - vaultAddress - deadline - refunded - refundAppliedNow - updatedAt properties: signedOpId: type: string format: uuid description: >- `signed_ops.id` — same UUID the original signature endpoint returned. opKind: type: string enum: - SPLIT - MERGE description: >- Operation kind. Always `SPLIT` or `MERGE` on success — other kinds short-circuit with `400 op_kind_unsupported`. status: type: string description: >- Post-call status. `EXPIRED` after a successful refund; whatever the row was already in (`EXPIRED` / `CANCELLED` / `REVERTED` / `REJECTED` / `FAILED`) on an idempotent re-request. vaultAddress: $ref: '#/components/schemas/EthereumAddress' deadline: type: integer description: >- Unix seconds the op was signed against. Always more than 90s in the past on a successful response. refunded: type: boolean description: >- `signed_ops.refunded` after this call — `true` for any EXPIRED/CANCELLED/REVERTED/REJECTED/FAILED terminal. refundAppliedNow: type: boolean description: >- `true` if this call performed the refund transition; `false` for an idempotent re-request against an already-terminal op (the row is returned unchanged). reason: type: string nullable: true description: >- `signed_ops.reason` audit string — set to `user:` after a successful refund by this endpoint; may be `sweeper` / `cosigner` / etc. on rows refunded by other paths. txHash: type: string nullable: true description: >- `signed_ops.tx_hash`. Always `null` on this endpoint's responses — the op never confirmed on-chain by definition. updatedAt: type: string format: date-time description: ISO-8601 timestamp of the last `signed_ops` mutation. 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' 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. ````