Trading - Naïve

The Trading primitive links a user’s brokerage account via an OAuth2 Connect flow. Each user authorizes their own brokerage account (paper and/or live); Naive performs the token exchange and proxies the brokerage’s trading API on their behalf — so you never touch OAuth plumbing, token storage, or per-user isolation. One primitive trades stocks, options, and crypto: the order symbol decides the market (AAPL, BTC/USD, AAPL241213C00250000).

Naive is not the broker, a broker-dealer, or an investment adviser, and does not exercise trading discretion — the connected brokerage is the broker. Naive is a governed gateway in front of your users’ own brokerage accounts: the user directs and approves the trades. Money-moving actions (place/cancel order, close position) are approval-gated by default — see Approvals.

CLI First

# 1. Link a brokerage account (returns an authorize URL to open)
naive trading connect --env paper

# 2. Once authorized, read the account and trade
naive trading account
naive trading order --symbol BTC/USD --notional 25 --side buy --type market --tif gtc
naive trading positions

How the OAuth connection works

Naive owns a single platform OAuth app registered with the brokerage. connect returns an authorize_url; the user opens it, approves access, and the brokerage redirects back to Naive’s callback, which exchanges the code for a bearer token and stores it encrypted. The token is then used to call the brokerage’s trading API for that user.

Start the flow

naive trading connect --env paper

Returns { "authorize_url": "https://<brokerage-oauth>/authorize?...", "env": "paper" }.

User authorizes

Open the authorize_url and approve access. The brokerage redirects to Naive’s callback (/v1/trading/oauth/callback), which stores the token.

Confirm and trade

naive trading connections   # status: "active"
naive trading account

Use --env paper for paper trading and --env live for a funded account. A user can connect both; when both are connected, pass --env (or env) on each call. OAuth access tokens are long-lived (there is no refresh token); if access is ever revoked, calls return unauthorized and you simply reconnect.

Disclosure. A disclosure must be shown to the user at connection time. POST /v1/trading/connect returns it as a disclosure field (and the dashboard renders it as an “Authorize naive” consent step before redirecting). Display it before sending the user to the authorize URL.

Tools

Tool	Type	Description
`trading_connect`	Setup	Start the brokerage OAuth flow (returns an authorize URL)
`trading_connections`	Setup	List linked environments (paper/live) and status
`trading_disconnect`	Setup	Forget a stored connection
`trading_account`	Read	Get the connected brokerage account
`trading_assets`	Read	List tradable assets (filter by asset class)
`trading_positions`	Read	List open positions
`trading_position`	Read	Get one open position
`trading_orders`	Read	List orders
`trading_get_order`	Read	Get one order
`trading_quote`	Read	Latest quote(s) for symbols
`trading_create_order`	Core (sensitive)	Place an order
`trading_cancel_order`	Core (sensitive)	Cancel an open order
`trading_close_position`	Core (sensitive)	Close (liquidate) a position

Placing orders

The same endpoint trades every asset class — the symbol selects the market. Provide either qty (shares/coins) or notional (dollar amount).

# Buy $25 of BTC at market (crypto trades 24/7; time_in_force gtc or ioc)
naive trading order --symbol BTC/USD --notional 25 --side buy --type market --tif gtc

# Buy 2 shares of AAPL with a limit order, good-for-day
naive trading order --symbol AAPL --qty 2 --side buy --type limit --limit-price 150 --tif day

Via the API:

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

import { Naive, isPendingApproval } from "@usenaive-sdk/server";
const naive = new Naive({ apiKey: process.env.NAIVE_API_KEY });

const res = await naive.forUser("alice").trading.createOrder({
  symbol: "BTC/USD", notional: "25", side: "buy", type: "market", time_in_force: "gtc",
});
if (isPendingApproval(res)) {
  // Gated by the user's Account Kit — wait for a human to approve.
  await naive.forUser("alice").approvals.wait(res.approval_id);
}

Order parameters

Parameter	Type	Description
`symbol`	string	Asset symbol — `AAPL`, `BTC/USD`, or an OCC option symbol
`side`	string	`buy` or `sell`
`qty`	string	Quantity (shares/coins). Use `qty` or `notional`
`notional`	string	Dollar amount (fractional). Use `notional` or `qty`
`type`	string	`market` (default), `limit`, `stop`, `stop_limit`, `trailing_stop`
`time_in_force`	string	`day`, `gtc`, `opg`, `cls`, `ioc`, `fok`. Crypto supports `gtc`/`ioc`
`limit_price`	string	Required for `limit` / `stop_limit`
`stop_price`	string	Required for `stop` / `stop_limit`
`order_class`	string	`simple`, `bracket`, `oco`, `oto` (equities)
`extended_hours`	boolean	Allow execution during extended hours (equities)
`env`	string	`paper` or `live` (required if both are connected)

Naive sends the request’s Idempotency-Key as the order’s client_order_id, so a retried logical order deduplicates at the broker.

Asset class differences

	Stocks	Crypto	Options
Symbol	`AAPL`	`BTC/USD`	`AAPL241213C00250000`
Order types	all	`market`, `limit`, `stop_limit`	all
`time_in_force`	`day`, `gtc`, …	`gtc`, `ioc`	`day`, `gtc`
Hours	market + extended	24/7	market
Fractional	yes (`notional`/`qty`)	yes	no

Crypto trading must be enabled on the user’s brokerage account (the crypto agreement signed). Check trading_account → crypto_status. Naive surfaces this but does not toggle it — it’s an account-level setting on the brokerage.

The brokerage enforces a $10 minimum per crypto order. An order below it is rejected with a forbidden error ("cost basis must be >= minimal amount of order 10") — the connection stays valid; just resize the order.

Positions & orders

# Positions
naive trading positions
naive trading position BTCUSD          # crypto position symbols are concatenated
naive trading close BTCUSD             # liquidate (SENSITIVE)
naive trading close AAPL --percentage 50

# Orders
naive trading orders --status open
naive trading get-order <order-id>
naive trading cancel <order-id>        # SENSITIVE

Market data

naive trading quote --symbols BTC/USD,ETH/USD            # crypto (default)
naive trading quote --symbols AAPL --class us_equity     # stocks

Governance

trading.order.create, trading.order.cancel, and trading.position.close are in the default approval set. For a real end-user (not the account’s own default agent profile), an agent (API-key) call returns 202 { "status": "pending_approval" } and the action runs only after a human approves it in Approvals. AgentProfiles can opt in/out per Account Kit via primitives_config.trading.requiresApproval.

Connection statuses

Status	Meaning
`pending`	OAuth started, awaiting authorization
`active`	Connected and ready to trade
`expired`	The brokerage rejected the token (401) — reconnect
`failed`	Token exchange failed

Disconnecting (DELETE /v1/trading/connections/:env) removes the stored connection entirely; reconnecting creates a fresh one.

Configuration

The trading primitive requires the platform OAuth app credentials + an encryption key on the API:

Setting	Purpose
Brokerage OAuth app credentials	Client ID + secret for the platform’s brokerage OAuth app
OAuth redirect URI	Whitelisted callback (defaults to `${API_URL}/v1/trading/oauth/callback`)
Encryption key	64-char hex key used to encrypt stored tokens at rest

Your brokerage OAuth app must be approved before it can execute live trades; paper works for development.

​CLI First

​How the OAuth connection works

​Tools

​Placing orders

​Order parameters

​Asset class differences

​Positions & orders

​Market data

​Governance

​Connection statuses

​Configuration

CLI First

How the OAuth connection works

Tools

Placing orders

Order parameters

Asset class differences

Positions & orders

Market data

Governance

Connection statuses

Configuration