API Contracts
Virae API keys let external tools call supported application routes as an authenticated app user.
This page describes the practical route families to validate when building scripts, agents, or integrations.
Authentication model
Use the API key created in the web terminal's Settings -> API Keys area.
An API key authenticates supported app routes. It does not replace wallet authority, Turnkey recovery authority, or the signed-in web session used to manage the keys themselves.
Route validation rule
Validate every route your integration needs before depending on it.
Virae has multiple product surfaces and some route families are intentionally narrower than the web UI. A route working for one product area does not mean every product exposes the same behavior.
Common user route families
Useful route families include:
| Area | What to validate |
|---|---|
| Account | current authenticated user, linked identity, account readiness |
| API keys | key creation and revocation are managed from signed-in web, not by another API key |
| Trade readiness | whether the account can trade a specific venue and product |
| Fee quote | expected base fee, commission, settlement rail, and fee collector availability |
| Order submit | supported venue, outcome token, order type, amount, slippage, source attribution |
| Open positions | current account positions by venue or product scope |
| Open orders | outstanding orders and cancelability |
| Claims | claimable resolved positions and claim submission status |
| Activity | trade, funding, claim, and fee history |
| Copy trading | task creation, task state, executions, and stop behavior |
| Rewards | reward summary, ledger, boxes, gift codes, referrals |
| Notifications | account notifications and read state |
Trade workflow contract
A trading integration should usually follow this sequence:
- confirm the authenticated user
- check readiness for the venue and product
- request a fee quote or trade preview when available
- submit the order with explicit product context
- watch order, position, and activity state after submission
- handle claim or settlement separately when the market resolves
Do not assume order submission means every later fee, claim, rebate, or settlement step has already finished.
Source attribution
Virae can distinguish different order entry surfaces, such as web, the Polymarket Bot, the Crypto Bot, and Mini App flows.
Integrations should preserve the intended source attribution when a supported route expects it. This helps users and operators understand where an order came from.
Error handling
Treat readiness and fee-related failures as useful state, not only as transport errors.
Common reasons a request can fail or be blocked include:
- missing account setup
- missing venue credentials
- insufficient balance on the required rail
- stale or unavailable market data
- unsupported product route
- expired or revoked API key
- fee settlement or recovery requirement