Skip to main content

​
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 operator’s default user) 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

MethodPathDescription
POST/v1/trading/connectBegin OAuth — returns an authorize_url
GET/v1/trading/oauth/callbackOAuth redirect target (handled by Naive; no auth)
GET/v1/trading/connectionsList linked environments (paper/live)
DELETE/v1/trading/connections/:envDisconnect (forget the stored token)
GET/v1/trading/accountGet the connected brokerage account
GET/v1/trading/assetsList tradable assets (?asset_class=)
GET/v1/trading/positionsList open positions
GET/v1/trading/positions/:symbolGet one open position
DELETE/v1/trading/positions/:symbolClose (liquidate) a position — sensitive
GET/v1/trading/ordersList orders (?status=open|closed|all)
POST/v1/trading/ordersPlace an order — sensitive
GET/v1/trading/orders/:idGet one order
DELETE/v1/trading/orders/:idCancel an open order — sensitive
GET/v1/trading/market-dataLatest 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
ParameterTypeRequiredDescription
envstringNopaper (default) or live
scopestringNoOAuth 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
ParameterTypeRequiredDescription
symbolstringYesAAPL, BTC/USD, or an OCC option symbol
sidestringYesbuy or sell
qtystringOne ofQuantity (shares/coins)
notionalstringOne ofDollar amount (fractional)
typestringNomarket (default), limit, stop, stop_limit, trailing_stop
time_in_forcestringNoday, gtc, opg, cls, ioc, fok (crypto: gtc/ioc)
limit_pricestringCond.Required for limit / stop_limit
stop_pricestringCond.Required for stop / stop_limit
trail_price / trail_percentstringCond.For trailing_stop
order_classstringNosimple, bracket, oco, oto
take_profit / stop_lossobjectNoLegs for bracket/OTO orders
extended_hoursbooleanNoAllow extended-hours execution (equities)
envstringNopaper 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"
}
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
QueryTypeDescription
qtystringQuantity to close (default: entire position)
percentagestringPercentage of the position to close
envstringpaper 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
QueryTypeDescription
symbolsstringComma-separated symbols, e.g. BTC/USD,ETH/USD or AAPL
classstringcrypto (default) or us_equity
envstringpaper or live
curl "https://api.usenaive.ai/v1/trading/market-data?symbols=BTC/USD,ETH/USD" \
  -H "Authorization: Bearer nv_sk_live_..."

​
Errors

ErrorCauseRecovery
feature_not_configuredBrokerage OAuth app or ENCRYPTION_KEY not configuredOperator must set the OAuth app credentials + ENCRYPTION_KEY
not_configuredNo active brokerage connection for this user/envPOST /v1/trading/connect
unauthorizedBrokerage token invalid/revoked (HTTP 401) — connection marked expiredReconnect via connect
forbiddenThe 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_inputBad order parameters (other 4xx from the brokerage)Fix params; check asset-class rules
provider_errorBrokerage upstream errorRetry; inspect the error details