Vanta
Open Vanta
About

Versioning & changelog

This documentation describes v1.5.1 of the API contract. The version lives in the URL, where every endpoint sits under /api/v1/, so a future incompatible revision arrives as a new prefix rather than as a change under your feet.

What can change without notice

Write your client so these are non-events.

  • New fields in a response object. Ignore what you do not recognise; never assert on an exact key set.
  • New endpoints, and new optional request fields on existing ones.
  • New values in a field that behaves like an enum, such as a new execution type or a new account status. Handle the default case rather than crashing.
  • Wording of error messages. Match on HTTP status; treat the string as diagnostic text for a human.
  • Rate limits. Read the headers on a 429 rather than hard-coding the ceiling.

What counts as breaking

These would arrive under a new version prefix.

  • Removing or renaming a response field, endpoint or request field.
  • Changing the type or meaning of an existing field.
  • Changing the signing scheme. The canonical string is versioned by its own v1 prefix and the signature header carries v1=, so a new scheme can run alongside the old one.
  • Changing an HTTP status for an existing failure.
Response shapes are documented by example rather than by a strict schema, and the OpenAPI document is generated from those examples. It is accurate about structure and good for client generation. Treat it as a description, not a validation contract.

Changelog

Most recent first.

  1. v1.5.1

    The daily loss limit's start-of-day value, as the network now measures it.

    • GET /api/v1/trading/account: drawdownRules.dailyLoss.dayStartEquity is the start-of-day balance on standard accounts (evaluation, funded and the transition phase), where it was the start-of-day equity. Since vanta-network #960 the network measures these accounts' daily loss limit from that balance, and dailyLoss.usedPct was already measured from it, so the two now agree. Pro, Instant Funded and Hyperliquid-linked accounts are still measured from start-of-day equity, and the field is unchanged on them. The field keeps its name.
    • Documentation, GET /api/v1/trading/account: the notes on drawdownRules and on challenge.drawdownCriteria (a static account's Rule 2, its daily loss limit) now say the same.

  2. v1.5.0

    Personal limits on the order route, the Classic stage name, and when an automatically promoted pro account starts.

    • POST /api/v1/trading/orders: a new 403 when the account's personal limits, which its owner sets in the trading terminal (a daily loss limit, a cap on new entries per day, a maximum order size), refuse an order that would open a position or add to one. The error is the limit's own message. A personal limit never refuses a close (FLAT), FLAT_ALL, LIMIT_CANCEL or BRACKET, and normally passes a MARKET reduction. The exception: a reduction of a position opened or added to since the account's latest snapshot reads as an opener on that snapshot, so for up to 15 seconds after the snapshot is saved, while the network is slow or unreachable, it can be refused; FLAT closes that position. A LIMIT against the position can be refused when it, with the other orders resting on its side, is larger than the position: a close does not cancel it, so it can fill afterwards as an opener. Errors & rate limits has the details.
    • GET /api/v1/trading/account: evaluation.title ends in "Classic" where it ended in "Evaluation", for example "Crypto 25K Classic". evaluation.status is unchanged and still reads "evaluation".
    • Documentation, GET /api/v1/trading/account: proTrack.transitionEndsAtMs, the next Monday 00:00 UTC, is the latest the pro account starts only for an offered promotion. The network can now also promote an account automatically, and an automatic promotion starts the pro account as soon as the account is flat, or 7 days after the promotion, which can be later than that Monday. The field's value is unchanged, and the response does not say which kind of promotion the account is in.

  3. v1.4.0

    Ask a key what it may do.

    • GET /api/v1/keys/self: new endpoint describing the key that signed the request: its key id, the account it is bound to, its scopes, and orderPlacementPausedUntil, the time at which the key's failed-request cooldown ends while POST /api/v1/trading/orders is answering it 429 too_many_failed_requests (null otherwise). Any active key may call it, whatever its scopes, so a client can check what a key may do without sending a request that needs a scope and reading the 403.

  4. v1.3.0

    The pairs an account may trade, as the network allows them.

    • GET /api/v1/trading/trade-pairs: new endpoint returning the network's allow-list for the key's account (its asset class, narrowed to the pro universe for a pro account), each pair with its category, source and leverage bounds, plus the pairs the network lists for the class but no longer allows.
    • Errors: a 503 when the network's catalog cannot be read; the endpoint never answers an empty list in place of an outage.

  5. v1.2.0

    Network-side account state and payouts.

    • GET /api/v1/trading/account: new fields drawdownRules (both loss limits, by rule), elimination (reason, time, drawdown percent), proTrack (pro promotion objectives), isPro and tradingDays. Existing fields are unchanged.
    • GET /api/v1/trading/payouts: new endpoint returning payout history (paginated with limit and cursor) and the live estimate for the cycle in progress.
    • Errors: a 400 for an invalid limit or cursor query parameter on GET /api/v1/trading/payouts.

  6. v1.1.0

    Fill sizes as numbers, for clients that need to confirm what executed.

    • GET /api/v1/trading/positions: new netQuantity field, the position size in the pair's lot unit, signed like netLeverage.
    • GET /api/v1/trading/trades: new quantity field, the total size opened over the life of the trade, in the same unit.
    • POST /api/v1/trading/orders: new data.order object, the validator's order record parsed into typed fields (quantity, value, price, bindingCap and more). data.order_json is unchanged.
    • GET /api/v1/trading/positions: unrealizedPnl now carries the validator's live figure. It previously read 0 for every position.
    • Documentation: the POST /api/v1/trading/orders response example now shows the real envelope.

  7. v1.0.0

    Public documentation for the v1 trading API.

    • Published this documentation portal covering authentication, endpoints, order payloads and errors.
    • Published a generated OpenAPI 3.1 document at /docs/openapi.json.
    • No change to the API itself. The endpoints described here have been available to key holders from within Settings → Key Management.

Questions

If something here is wrong or missing.

Report documentation problems and API questions through the support channel in your dashboard. Include the endpoint, the HTTP status and your key id, and never your secret. If you suspect a secret has leaked, revoke the key first; see Authentication.