Trading API Reference

Overview

Per-user; requires Authorization: Bearer nv_sk_…. Each tenant_user links their own brokerage account via OAuth; Naive proxies the brokerage’s trading API on their behalf. The same endpoints trade stocks, options, and crypto — the order symbol decides the market (AAPL, BTC/USD, AAPL241213C00250000). Naive is not a broker-dealer or investment adviser and does not exercise trading discretion — the user directs and approves every order. Routes are available both company-scoped (/v1/trading/..., acting as the account’s default agent profile) and per-user (/v1/users/:user_id/trading/...). Gated by the trading primitive in the user’s AccountKit.

Money-moving actions (POST /v1/trading/orders, DELETE /v1/trading/orders/:id, DELETE /v1/trading/positions/:symbol) are approval-gated by default. An agent (API-key) call may return 202 { "status": "pending_approval", "approval_id" }; a human approves it via Approvals and the action runs on replay. See Approvals.

Endpoints

Method	Path	Description
POST	`/v1/trading/connect`	Begin OAuth — returns an `authorize_url`
GET	`/v1/trading/oauth/callback`	OAuth redirect target (handled by Naive; no auth)
GET	`/v1/trading/connections`	List linked environments (paper/live)
DELETE	`/v1/trading/connections/:env`	Disconnect (forget the stored token)
GET	`/v1/trading/account`	Get the connected brokerage account
GET	`/v1/trading/assets`	List tradable assets (`?asset_class=`)
GET	`/v1/trading/positions`	List open positions
GET	`/v1/trading/positions/:symbol`	Get one open position
DELETE	`/v1/trading/positions/:symbol`	Close (liquidate) a position — sensitive
GET	`/v1/trading/orders`	List orders (`?status=open\|closed\|all`)
POST	`/v1/trading/orders`	Place an order — sensitive
GET	`/v1/trading/orders/:id`	Get one order
DELETE	`/v1/trading/orders/:id`	Cancel an open order — sensitive
GET	`/v1/trading/market-data`	Latest quote(s) (`?symbols=&class=`)

All GET/DELETE endpoints accept an optional ?env=paper|live query param (required only when both environments are connected). MCP equivalents are naive_trading_*.

Connect

POST /v1/trading/connect

Parameter	Type	Required	Description
`env`	string	No	`paper` (default) or `live`
`scope`	string	No	OAuth scopes (default `account:write trading data`)

curl -X POST https://api.usenaive.ai/v1/trading/connect \
  -H "Authorization: Bearer nv_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "env": "paper" }'

{
  "authorize_url": "https://<brokerage-oauth>/authorize?response_type=code&client_id=...&redirect_uri=...&state=nv_...&scope=account:write%20trading%20data&env=paper",
  "env": "paper",
  "state": "nv_3f2a...",
  "disclosure": "By allowing naive to access your brokerage account, you are granting naive access to your account information and authorization to place transactions in your account at your direction. Naive does not warrant or guarantee that the connected brokerage will work as advertised or expected. Before authorizing, learn more about naive at https://usenaive.ai.",
  "next_steps": [
    { "command": "naive trading connections", "description": "Check the connection status after authorizing" }
  ]
}

Show the returned disclosure to the user (required at connection time), then open authorize_url in a browser. After the user approves, the brokerage redirects to /v1/trading/oauth/callback, which exchanges the code for a token and marks the connection active. The scope’s spaces are %20-encoded (the authorize endpoint rejects the + form).

Place an Order

POST /v1/trading/orders

Parameter	Type	Required	Description
`symbol`	string	Yes	`AAPL`, `BTC/USD`, or an OCC option symbol
`side`	string	Yes	`buy` or `sell`
`qty`	string	One of	Quantity (shares/coins)
`notional`	string	One of	Dollar amount (fractional)
`type`	string	No	`market` (default), `limit`, `stop`, `stop_limit`, `trailing_stop`
`time_in_force`	string	No	`day`, `gtc`, `opg`, `cls`, `ioc`, `fok` (crypto: `gtc`/`ioc`)
`limit_price`	string	Cond.	Required for `limit` / `stop_limit`
`stop_price`	string	Cond.	Required for `stop` / `stop_limit`
`trail_price` / `trail_percent`	string	Cond.	For `trailing_stop`
`order_class`	string	No	`simple`, `bracket`, `oco`, `oto`
`take_profit` / `stop_loss`	object	No	Legs for bracket/OTO orders
`extended_hours`	boolean	No	Allow extended-hours execution (equities)
`env`	string	No	`paper` or `live`

curl -X POST https://api.usenaive.ai/v1/trading/orders \
  -H "Authorization: Bearer nv_sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-2026-06-11-001" \
  -d '{
    "symbol": "BTC/USD",
    "notional": "25",
    "side": "buy",
    "type": "market",
    "time_in_force": "gtc"
  }'

{
  "id": "38e482f3-79a8-4f75-a057-f07a1ec6a397",
  "symbol": "BTC/USD",
  "asset_class": "crypto",
  "notional": "25",
  "qty": null,
  "side": "buy",
  "type": "market",
  "time_in_force": "gtc",
  "status": "pending_new",
  "submitted_at": "2026-06-11T00:36:51.313Z"
}

{
  "status": "pending_approval",
  "approval_id": "appr-uuid",
  "action": "trading.order.create",
  "primitive": "trading",
  "title": "Place buy order: 25 BTC/USD",
  "message": "This action requires human approval before it executes."
}

The request’s Idempotency-Key is forwarded as the order’s client_order_id so a retried order deduplicates at the broker.

Close a Position

DELETE /v1/trading/positions/:symbol

Query	Type	Description
`qty`	string	Quantity to close (default: entire position)
`percentage`	string	Percentage of the position to close
`env`	string	`paper` or `live`

curl -X DELETE "https://api.usenaive.ai/v1/trading/positions/BTCUSD?percentage=50" \
  -H "Authorization: Bearer nv_sk_live_..."

Market Data

GET /v1/trading/market-data

Query	Type	Description
`symbols`	string	Comma-separated symbols, e.g. `BTC/USD,ETH/USD` or `AAPL`
`class`	string	`crypto` (default) or `us_equity`
`env`	string	`paper` or `live`

curl "https://api.usenaive.ai/v1/trading/market-data?symbols=BTC/USD,ETH/USD" \
  -H "Authorization: Bearer nv_sk_live_..."

Errors

Error	Cause	Recovery
`feature_not_configured`	Brokerage OAuth app or `ENCRYPTION_KEY` not configured	AgentProfile must set the OAuth app credentials + `ENCRYPTION_KEY`
`not_configured`	No active brokerage connection for this user/env	`POST /v1/trading/connect`
`unauthorized`	Brokerage token invalid/revoked (HTTP 401) — connection marked `expired`	Reconnect via `connect`
`forbidden`	The brokerage rejected the action (HTTP 403) — e.g. crypto order below the $10 minimum, account restricted to liquidation, or scope not granted. The connection stays valid.	Fix the order/scope; the connection is unaffected
`invalid_input`	Bad order parameters (other 4xx from the brokerage)	Fix params; check asset-class rules
`provider_error`	Brokerage upstream error	Retry; inspect the error `details`

​Overview

​Endpoints

​Connect

​Place an Order

​Close a Position

​Market Data

​Errors

Overview

Endpoints

Connect

Place an Order

Close a Position

Market Data

Errors