Endpoint reference

All paths below are relative to https://api.risklabs.co. Send JSON with Content-Type: application/json. Use canonical lowercase addresses, signatures, and bytes32 question IDs; slugs may use lowercase letters, digits, and hyphens. Use the exact paths without trailing slashes or percent-encoded aliases.

identifier is your question ID or market slug; prefer the canonical question ID, derived locally or returned by preparation. candidate_id is a hyphenated UUID. See Find the question ID to derive the question ID from indexed request ancillary data.

For batch request bodies, per-item results, and polling, see Batch proposing. Batch routes use their existing /propose/batch* schema; the single-proposal v1 payloads below cannot be sent to them unchanged.

Check eligibility

GET /v1/proposals/eligibility/{address}

Returns 200 with version, canonical address, and eligible. Unknown or disabled wallets return eligible: false; admission being disabled also returns false. This does not reserve a slot or guarantee acceptance.

Prepare signing data

POST /v1/proposals/{identifier}/signing-data

This endpoint is optional. It constructs the complete typed data for convenience. If you build the Permit2 witness yourself from current request data and trusted configuration, sign locally and submit directly. Submission requires no preparation token or prior signing-data call.

Returns 200 with:

Preparation is stateless: it neither admits a candidate nor reserves a nonce or bond. All Solidity integers are decimal strings, including typed_data.domain.chainId. Token decimals and event indexes remain JSON numbers.

The current API supports the following binary outcome mapping. Market rules schema explains Type 1, Type 2, and clarification updates; Type 2 winner-index submissions are not supported by this API.

Use the returned outcomes for request-specific labels and availability, and verify them against the rules and authorized clarifications. A p3 / 0.5 settlement requires permission in the rules and support from the settlement contract; uncertainty alone is not sufficient. Prices are oracle fixed-point values, not token amounts.

Submit a candidate

POST /v1/proposals/{identifier}

Send version, proposer, outcome, max_payment, and permit using the field requirements above, plus signature (lowercase, even-length hex, up to 8,192 bytes). You can construct this body yourself without calling preparation. If you used the helper, send its request body, unchanged, plus the signature. The API independently reconstructs the witness and validates the signature against the current request. Extra fields are rejected.

• 202: new candidate durably accepted for asynchronous validation.
• 200: exact payload replay in the current request round; existing candidate returned.
• 409: a conflicting active payload or request state prevents admission.

Both successful responses contain version, candidate_id, status, received_at, and a relative status_url. Save the exact payload and acknowledgement. There is no separate idempotency-key header.

Read status

GET /v1/proposals/{identifier}/status/{candidate_id}

Returns 200 with identity, outcome, price, receipt/validation/selection timestamps, candidate status, nullable submission, and nullable failure. The identifier scopes the lookup to the request; a mismatched or unknown candidate returns 404.

submission contains its own status, transaction_hash, submission/confirmation/indexing timestamps, and proposal_event_index. failure contains stage, code, detail, retryable, can_resubmit, and next_action. Signatures and executable transaction data are never returned. See status and retries.

Errors

Application errors use this shape; schema failures can also include a sanitized errors array:

{
  "error": {
    "code": "permit_amount_below_required_bond",
    "detail": "Permit amount is below the current total bond"
  }
}

Treat transport failures and gateway bodies separately from application JSON errors. On uncertain submission outcomes, replay the exact saved payload; do not immediately generate another nonce. Server-side clients are the simplest integration. Browser origins require explicit CORS configuration; this API does not use browser cookies.