Accounts

Trading accounts with balance status, manual balance events, payouts, and daily snapshots.

GET /accounts

Scope: read:accounts

List your trading accounts.

Param	Type	Description
include_archived	bool	Default false. Include archived accounts.
broker_key	string	Filter by broker (e.g. tradovate, ninjatrader).
account_type	enum	live, demo, paper, funded, live_funded, trading_combine.

GET /accounts/{id}

Scope: read:accounts (also read:balance to include the balance block)

Single account plus its balance status and computed metrics (current balance, high-water mark, drawdown, P&L since start, profit target, max daily loss, max drawdown, deadlines, source preset).

GET /api/v1/accounts/192

Pass ?include=basic to skip the balance block.

GET /accounts/{id}/balance

Scope: read:balance

Same balance block embedded in GET /accounts/{id} — exposed at this dedicated path for clients that want just the balance row plus computed metrics (current balance, high-water mark, drawdown) and the prop-firm rule snapshot (profit target, daily/total drawdown caps, payout split, deadlines). Returns 404 if the account has no balance profile configured.

GET /api/v1/accounts/192/balance

GET /accounts/{id}/balance/events

Scope: read:balance

Paginated audit log of balance state changes: status changes, rule violations, manual updates, payouts, resets, target adjustments.

Param	Type	Description
limit	int	1-200, default 50.
offset	int	0-based, default 0.
event_type	enum	Filter to a single event type (status_change, rule_violation, payout, etc.).

GET /accounts/{id}/balance/payouts

Scope: read:balance

Paginated payout history: amount, status (pending / approved / paid / rejected), profit split, balance before/after, total profit at request time.

---

POST /accounts

Scope: write:accounts

Create the account shell. Starting balance, prop-firm rules, and trade-template are configured separately via the balance endpoints (or via the settings UI).

Field	Type	Required	Notes
account_name	string (1–100)	yes	Unique among your active accounts.
account_type	enum	no	live (default), demo, paper, funded, live_funded, trading_combine.
currency	ISO 4217	no	Defaults to USD. Three letters; lowercase is auto-uppercased server-side, so "usd" and "USD" are equivalent.
broker_key	string ≤ 64	no	From the /brokers catalog. Unknown keys return 400.
breakeven_offset_low	decimal ≤ 0	no	Defaults to 0.
breakeven_offset_high	decimal ≥ 0	no	Defaults to 0.

Subscription gate: bill_lim_canAddAccount. Over-cap returns 429 limit_reached.

curl -X POST https://app.tradavity.com/api/v1/accounts \
  -H "Authorization: Bearer tvty_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "account_name": "TopStep XFA #2",
    "account_type": "trading_combine",
    "currency": "USD",
    "broker_key": "topstepx"
  }'

PATCH /accounts/{id}

Scope: write:accounts

Update account_name, account_type, currency, broker_key, breakeven_offset_low, breakeven_offset_high, trade_template_id. Send broker_key: null to unlink the broker; trade_template_id: null to clear the template.

Also accepts is_archived: bool on its own (cannot be combined with other field updates). Setting is_archived: true archives the account; false unarchives. Same disconnect cascade as DELETE /accounts/{id} applies. Returns the updated account.

DELETE /accounts/{id}

Scope: write:accounts

Archive an account. Disconnects auto-sync, clears tokens, and pauses sync as a side effect — same flow the settings UI runs. Returns 204 No Content. Re-DELETE on an already-archived account returns 404 not_found. Use PATCH /accounts/{id} with { "is_archived": false } to unarchive.

Cannot archive your only active account — returns 409 conflict. Trades on the archived account still resolve via API (they keep their account_id and show account.is_archived: true).

curl -X DELETE "https://app.tradavity.com/api/v1/accounts/192" \
  -H "Authorization: Bearer tvty_YOUR_KEY_HERE"

---

POST /accounts/{id}/balance/events

Scope: write:balance

Record a manual balance event. The API only allows event_type=manual_update — system-generated event types (status changes, rule violations, payouts) are managed by the platform itself.

Field	Type	Required	Notes
note	string (1–1000)	yes	What this event records.
balance_at_event	decimal	no	Snapshot of current balance.
pnl_at_event	decimal	no	Snapshot of cumulative pnl.
rule_type	string ≤ 50	no	e.g. profit_target, max_drawdown.
rule_limit / rule_actual	decimal	no	For rule-related notes.

curl -X POST "https://app.tradavity.com/api/v1/accounts/192/balance/events" \
  -H "Authorization: Bearer tvty_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"note": "Manual reconciliation: broker statement matches journal."}'

If the account has no balance profile set up (no starting balance ever recorded), this returns 400 validation_error with a message telling the caller to initialize the balance first via the settings UI.

POST /accounts/{id}/balance/payouts

Scope: write:balance

Request a payout. Creates a row with status=pending; gross / firm-cut / net amounts are computed from the account’s profit_split_pct. The lifecycle (approve, mark paid, reject) is handled in the settings UI — not yet exposed via the API.

Field	Type	Required	Notes
gross_amount	decimal > 0	yes	The requested amount before firm cut.
note	string ≤ 500	no

curl -X POST "https://app.tradavity.com/api/v1/accounts/192/balance/payouts" \
  -H "Authorization: Bearer tvty_YOUR_KEY_HERE" \
  -H "Idempotency-Key: payout-2026-05-10-monthly" \
  -H "Content-Type: application/json" \
  -d '{"gross_amount": 2500, "note": "May payout"}'