Trading API

The API accepts EIP-712 signatures. It never accepts a user's private key. Complete authentication and beta access first.

Read the active chain ID and state-commitment address from Contracts and status. Use those values in every signed payload.

1. Create a restricted authority

Generate a secp256k1 key locally. Keep it encrypted and scoped to WickPlay. The root wallet signs a TradeAuthorityIntent with this domain:

{
  "chainId": "ACTIVE_CHAIN_ID",
  "name": "LaunchLab Intent Executor",
  "version": "1",
  "verifyingContract": "STATE_COMMITMENT_ADDRESS"
}

Field	Type	Meaning
`account`	`address`	Canonical WickPlay account
`rootSigner`	`address`	Authenticated owner wallet
`authority`	`address`	New one-click key
`signerMode`	`uint8`	`1` for the current EOA play key
`epoch`	`uint32`	Random nonzero authority identifier
`validAfter`	`uint64`	First valid Unix second
`validUntil`	`uint64`	Last valid Unix second
`maxStakeAssets`	`uint128`	Per-trade USDG cap
`maxTotalNotionalAssets`	`uint128`	Signed notional bound checked per trade
`maxShareNotionalAssets`	`uint128`	Signed share-funded bound checked per trade
`marketScope`	`bytes32`	Exact market ID or zero for all
`horizonScope`	`uint32`	`60`, `300`, or zero for both
`nonce`	`uint256`	Random authority authorization nonce
`deadline`	`uint64`	Authorization deadline
`chainId`	`uint256`	Active release chain ID
`executor`	`address`	Verified state-commitment address

Send this signed authorization with each trade request. The Market Worker verifies root-wallet ownership and the authority limits. The authority can sign trades. It cannot deposit, withdraw, or delegate another authority.

2. Read an exact quote

Read GET /api/markets/{ticker} and select quotes.60 or quotes.300. Stop when unavailableReason is not null. Keep the returned strike, probability, start, lock, and end times together.

3. Request the pricing authorization

Send the current quote fields to:

POST /api/play/pricing/authorize
Content-Type: application/json
Origin: https://wickplay.com
Cookie: wickplay_session=...

This route checks beta access and the live round. It returns a signed PricingAuthorization that binds the market, strike hash, direction, probability, round start, horizon, and expiry. The authorization lasts no more than five seconds and cannot outlive the round lock.

Recalculate the payout guard from the returned probability. Do not reuse a pricing authorization.

4. Read the sequential nonce

GET /api/play/settlement/account
Cookie: wickplay_session=...

Use the returned nextNonce. Encode it into the legacy trade fields as follows:

nonceWord = floor(nextNonce / 256)
nonceBit = nextNonce mod 256

Settlement still enforces one strictly increasing nonce per account. It does not treat these values as independent bitmap slots.

5. Sign the trade

Use this EIP-712 domain:

{
  "chainId": "ACTIVE_CHAIN_ID",
  "name": "LaunchLab",
  "version": "1",
  "verifyingContract": "STATE_COMMITMENT_ADDRESS"
}

Field	Type	Meaning
`account`	`address`	Canonical WickPlay account
`marketId`	`bytes32`	Keccak-256 of the UTF-8 ticker
`strikePriceHash`	`bytes32`	Exact quote strike commitment
`selection`	`uint8`	`0` Up, `1` Down
`fundingMode`	`uint8`	`2` for exact-credit-first share funding
`stakeAssets`	`uint128`	Six-decimal USDG amount, minimum `10000000`
`probabilityPpm`	`uint32`	Exact authorized probability
`minimumEffectiveMultiplierPpm`	`uint32`	Lowest accepted effective payout multiplier
`sessionEpoch`	`uint32`	Authority identifier
`nonceWord`	`uint32`	Quotient of the sequential nonce
`nonceBit`	`uint8`	Remainder of the sequential nonce
`roundStartsAt`	`uint64`	Quote start in Unix seconds
`horizonSeconds`	`uint32`	`60` or `300`
`deadline`	`uint64`	No later than the pricing expiry

Sign with the restricted one-click key.

6. Submit

POST /api/play/intents/trade
Content-Type: application/json
Origin: https://wickplay.com
Cookie: wickplay_session=...

The request contains intent, pricingAuthorization, accountSignature, and authorityAuthorization. A valid request returns HTTP 202 with:

status: "accepted";
intentId, which is the EIP-712 trade digest and bet ID;
actionId, which binds the ordered settlement action; and
the exact accepted probability, fee, payout, and strike.

The response can also include the latest signed exit claim. Normal acceptance is offchain and does not have a trade transaction hash or TradeAccepted contract event. The settlement service writes the action atomically before it returns acceptance and includes it in a later onchain commitment.

Common rejections

Code	Meaning
`AUTHENTICATION_REQUIRED`	The wallet session is missing or expired
`BETA_ACCESS_REQUIRED`	No WickPass, referral, or valid invite proves access
`QUOTE_UNAVAILABLE`	The current market quote is unavailable
`INTENT_STALE`	The quote, strike, probability, or round changed
`ROUND_LOCKED`	Entry closed before acceptance
`ROUND_SETTLED`	Settlement already recorded the round result
`INSUFFICIENT_BALANCE`	The account does not have enough available USDG
`RISK_LIMIT`	The configured settlement risk limit rejects the stake
`SIGNATURE_INVALID`	The trade or authority signature is invalid
`PRICING_INVALID`	The pricing authorization is invalid or mismatched

Result and finalization

WickPlay orders one result for the round and settles each affected account-round position in the same offchain state. The account balance then includes the exact payout or refund. Points consume the ordered accepted-trade and settlement events.

The service normally commits the state and action-data roots ten minutes after the oldest pending action. A withdrawal commits immediately. The commitment contract does not recalculate the trade result. For service failure, use the forced-exit process described in Contract calls and Withdrawals.