Orders and vault operations

Orders

struct Order {
    uint256 salt;
    address maker;
    address signer;
    address taker;
    uint256 tokenId;
    uint256 makerAmount;
    uint256 takerAmount;
    uint256 expiration;
    uint256 feeRateBps;
    uint8   side;             // 0=BUY, 1=SELL
    uint8   signatureType;    // always 1 (VAULT); 0 (EOA) is rejected
}

• maker, in the struct and in the request body: your vault of that generation;
• domain.verifyingContract: the market’s exchange.

// marketExchange / marketGeneration: see Detect a market's generation
const exchange = marketExchange(market);
const maker    = vaults.find(v => v.generation === marketGeneration(market))!.vaultAddress;
const domain   = { name: 'PredictStreet', version: '1', chainId: contracts.chainId, verifyingContract: exchange };

const order = {
  salt, maker, signer: eoa.address,
  taker: '0x0000000000000000000000000000000000000000',
  tokenId: BigInt(tokenId),
  makerAmount, takerAmount, expiration: 0n,
  feeRateBps: BigInt(market.feeTakerBps),
  side: 0, signatureType: 1,
};
const signature = await eoa.signTypedData(domain, types, order);   // `types`: the Order type from EIP-712 signing
// POST /api/orders/place with `maker` = the same vault, as on Placing orders

The vault field

Withdraw

const userSig = await eoa.signTypedData(
  { name: 'PredictStreetVault', version: '1', chainId: contracts.chainId, verifyingContract: vault },
  WITHDRAW_ERC20_TYPES,   // the WithdrawERC20 type from WithdrawERC20 EIP-712
  { token: contracts.usdc, to, amount: parseUnits(amount, 6), salt, deadline },
);
await fetch(`${BASE}/api/withdrawals/request`, {
  method: 'POST', headers: auth,
  body: JSON.stringify({ amount, destination: to, salt: salt.toString(), expiry: Number(deadline), userSig, vault, totpCode }),
});

• Any other destination from a generation-2 vault: 400 withdrawal_destination_not_allowed (details: { destination, vaultAddress, generation }). It is checked before the 2FA code, so the code is not spent. Withdraw to your wallet and transfer from there.
• A listed destination can be removed at any time. A refused destination is final for that request.
• 2FA and whitelist rules are unchanged. A TOTP code is single-use per 30-second step: a second withdrawal in the same step needs the next code or a backup code.
• 503 withdrawal_unknown: the withdrawal may have been created. Do not sign a new one; a new salt is a second withdrawal. Re-send the same body (same salt, expiry, userSig, totpCode) for up to about 60 seconds, then check GET /api/me/withdrawals. A stored request answers with its withdrawal (details.withdrawalId).
• 503 withdrawal_temporarily_unavailable: nothing was created. Retry later, with a new 2FA code if 2FA is on.
• Cancel (POST /api/me/withdrawals/{id}/cancel) now also accepts withdraw:write.

Return stray USDC (RND-2019)

• Returns 202 Accepted (or 200 OK if a return job just finished) with a StrayUsdcReturnRespDto containing jobId, status, and enqueued.
• Idempotent: while a return job is in flight, repeating the call returns the existing job (enqueued: false).
• Poll status via GET /api/me/vault/stray-usdc/return/{jobId} until status: "confirmed".
• When confirmed, /api/me/activity shows a corresponding stray_usdc_return transfer entry.
• Returns 409 no_stray_usdc when nothing is stray; 409 stray_usdc_return_disabled if feature is disabled on the environment; 422 stray_usdc_return_reverted if simulation reverts on chain.
• Returns 503 platform_frozen / 503 withdrawals_frozen (retryAfterSec) while the platform or the withdrawals freeze is on: nothing is queued, so show a paused state rather than an error. A return queued before the freeze stays pending (held, not sent) and goes ahead once the freeze lifts; keep polling its jobId. If the relay has not sent it in time, it ends expired and you ask again.
• Returns 503 stray_usdc_unavailable (retryAfterSec) when the chain could not be read or returns are paused on the platform side; nothing is queued, retry later.

Redeem

const sig = await eoa.signTypedData(
  { name: 'PredictStreetRedeem', version: '1', chainId: contracts.chainId },   // no verifyingContract
  { RedeemAuthorization: [
      { name: 'owner', type: 'address' }, { name: 'marketId', type: 'string' },
      { name: 'outcomeIndex', type: 'uint8' }, { name: 'deadline', type: 'uint256' } ] },
  { owner: eoa.address, marketId, outcomeIndex, deadline },
);
const { v, r, s } = Signature.from(sig);
const body = { marketId, outcomeIndex, vault, auth: { deadline, v, r, s } };

Split / merge / convert

1. POST /api/vault/split-signature (or merge-signature, convert-signature) with { marketId, amount, vault } and an Idempotency-Key header. For neg-risk markets, supply outcomeIndex (uint8, 0..254) to specify the sub-question. The answer carries vaultAddress, the payload and backendSig.
2. Sign the typed data in the domain of vaultAddress (PredictStreetVault / 1). Check it hashes to digest.
3. POST /api/me/positions/op-submit with { signedOpId, ownerSig, backendSig, vault }, then poll GET /api/me/positions/op-submit/{jobId} until confirmed.

Balances and positions

Legacy markets after the upgrade

• Quote and trade them as before, with the generation-1 vault as maker and the generation-1 exchange as verifyingContract, until the generation-1 trading halt (below).
• Resting generation-1 orders stay live and cancel as usual. During the halt they stay on the book but cannot match, since no new order is accepted on the market. When the platform then retires the market (status CLOSED), they are cancelled and their unfilled part is refunded; a partial fill keeps its filled position.
• When a legacy market resolves, redeem with vault = the generation-1 vault, then withdraw or move what is left.

Generation-1 trading halt

• Every generation-1 market sets generationRetired: true and generationHaltedAt (ISO-8601 timestamp).
• A generation-1 market in PRE_MARKET, OPEN, PAUSED, SUSPENDED, POSTPONED, or CLOSED with lifecycle.closedAt >= generationHaltedAt reads tradable: false, tradingMode: "closed", and notTradableReason: "generation_retired" (GET /api/events list rows omit tradingMode and notTradableReason, which can be derived with the same rule). A market that had already closed on its schedule before the halt (lifecycle.closedAt < generationHaltedAt) keeps notTradableReason: "closed_at_cutoff". From DELAYED onward, its settlement state (awaiting_data, awaiting_settlement, under_review, resolved, voided) is kept.
• rfq.available is false on every generation-1 market, and GET /api/markets/{symbol}/executable-price reports tradable: false.
• When the retire walk closes a generation-1 market, market_lifecycle pushes status_changed with toStatus: "CLOSED" and action: "market.retire_gen1" (a normal cutoff close sends action: "market.close"), and each cancelled resting order’s order_cancelled frame carries publicMessage explaining that trading ended with the platform upgrade.