Migrating from Alpaca to Naive

• The brokerage lives behind an APCA-API-KEY-ID + APCA-API-SECRET-KEY pair, its own dashboard, and its own funding — disconnected from wherever the agent’s cards, email, secrets, and KYC live.
• One key pair = one account. To trade on behalf of many end-users you must adopt Alpaca’s OAuth2 flow or the Broker API yourself — registering an app, exchanging codes for tokens, storing and encrypting each user’s token, and isolating per user.
• “Who let this agent place a $5,000 order, and what else can it touch?” is answered in Alpaca for trading, and in unrelated systems for everything else. There is no execution-time approval gate on money-moving actions — a leaked key trades freely until you notice.

• The tenant user that links the brokerage is the same user that owns its cards, its email inboxes, its vault secrets, and its KYC.
• Naive owns the platform OAuth app and performs the token exchange itself, so you never touch OAuth plumbing, token storage, or per-user isolation — connect() returns an authorize URL and Naive stores the bearer token encrypted at rest.
• Whether an agent may place, cancel, or close — and whether each money-moving action freezes for human approval — is decided by that user’s Account Kit and per-agent assignment at execution time, not by an API-key scope you manage separately.

​

Concept map

​

Before / after: the core path

import Alpaca from "@alpacahq/alpaca-trade-api";

// One account behind a static key pair (paper here).
const alpaca = new Alpaca({
  keyId: process.env.APCA_API_KEY_ID!,
  secretKey: process.env.APCA_API_SECRET_KEY!,
  paper: true,
});

// 1. Read the account (GET /v2/account)
const account = await alpaca.getAccount();

// 2. Place an order (POST /v2/orders) — runs immediately, no approval gate.
const order = await alpaca.createOrder({
  symbol: "BTC/USD",
  notional: 25,           // qty OR notional
  side: "buy",
  type: "market",
  time_in_force: "gtc",
});
// → order.id, order.status

// To serve many end-users you must build the OAuth2 flow yourself
// (/oauth/authorize → /oauth/token) and store + encrypt each user's token.

import { Naive, isPendingApproval } from "@usenaive-sdk/server";

const naive = new Naive({ apiKey: process.env.NAIVE_API_KEY! });
const client = naive.forUser("alice"); // same id space as your own users

// 0. One-time: link the user's brokerage via OAuth (Naive owns the app).
//    Open authorize_url in a browser; Naive stores the token encrypted.
const { authorize_url } = await client.trading.connect({ env: "paper" });

// 1. Read the account (proxies GET /v2/account)
const account = await client.trading.account({ env: "paper" });

// 2. Place an order (proxies POST /v2/orders) — SENSITIVE: may freeze for
//    human approval depending on the user's Account Kit.
const res = await client.trading.createOrder({
  symbol: "BTC/USD",
  notional: "25",         // qty OR notional
  side: "buy",
  type: "market",
  time_in_force: "gtc",
  env: "paper",
});
if (isPendingApproval(res)) {
  await client.approvals.wait(res.approval_id); // runs only after a human approves
}
// → order id, status

• One-time connect, not a static key. Alpaca’s direct API authenticates with a key pair for a single account. Naive links each user’s brokerage once via OAuth and proxies thereafter — you never store or encrypt the token.
• Money-moving actions can defer. createOrder, cancelOrder, and closePosition are in Naive’s default approval set. Handle isPendingApproval(res) and approvals.wait; reads (account, positions, orders, quote) never defer.
• env rides on the call. Where Alpaca picks paper/live at client construction, Naive takes env per call (a user can link both).
• The id is your identity, not a separate account. In Alpaca the key pair scopes Alpaca. In Naive the same forUser(id) handle also owns the agent’s cards, email, vault, and KYC.

​

Stocks, options, and crypto

// Stock: limit order, good-for-day
await alpaca.createOrder({
  symbol: "AAPL", qty: 2, side: "buy",
  type: "limit", limit_price: 150, time_in_force: "day",
});

// Stock: limit order, good-for-day (SENSITIVE)
const res = await client.trading.createOrder({
  symbol: "AAPL", qty: 2, side: "buy",
  type: "limit", limit_price: 150, time_in_force: "day", env: "paper",
});
if (isPendingApproval(res)) await client.approvals.wait(res.approval_id);

• Crypto (BTC/USD) trades 24/7 with time_in_force gtc/ioc; the brokerage may enforce minimum order sizes for crypto — see trading and Alpaca’s docs.
• Options use OCC symbols (AAPL241213C00250000); crypto trading must be enabled on the user’s brokerage account (trading.account() → crypto_status) — Naive surfaces it but does not toggle it.

​

Minimal viable migration

npm install @usenaive-sdk/server

​

Consolidate further once you’re on Naive

// One account per key pair; to go multi-user you build OAuth + token storage.
const alpaca = new Alpaca({ keyId, secretKey, paper: true });
await alpaca.createOrder({ symbol: "BTC/USD", notional: 25, side: "buy", type: "market", time_in_force: "gtc" });

// The card, the vault secrets, the email inbox, the KYC for this customer's
// agent live in entirely separate systems with their own tenancy — and nothing
// stops the key from placing an order the moment it leaks.

// One tenant user per customer; isolates *every* primitive.
const acme = await naive.users.create({
  external_id: dbCustomer.id,
  email: dbCustomer.email,
});

const client = naive.forUser(acme.id);

await client.trading.connect({ env: "paper" }); // link once
const res = await client.trading.createOrder({
  symbol: "BTC/USD", notional: "25", side: "buy", type: "market", time_in_force: "gtc", env: "paper",
});
if (isPendingApproval(res)) await client.approvals.wait(res.approval_id);

// The SAME client owns this customer's card, email inbox, vault, and KYC —
// one identity, isolated end to end, every order governed by its Account Kit.
await client.cards.create({ spending_limit_cents: 25_000 });
await client.email.createInbox({ local_part: "ops" });
await client.vault.put("internal.api_key", "key_xyz");

​

Gain #1 — one identity across primitives

• With Alpaca, the agent’s brokerage is an island behind a key pair. With Naive, naive.forUser(acme.id) is a single handle to trading and cards and email and vault and KYC.
• Tear the customer down from one place; sibling tenants should not be able to read each other’s orders, positions, cards, or secrets. The brokerage token is stored encrypted at rest and is never handed to the agent.

​

Gain #2 — execution-time permission enforcement

• Whether an agent may trade at all is the trading primitive on the user’s Account Kit, and whether each order freezes for human review is requiresApproval policy — not a check you hand-write and not an Alpaca key scope you manage separately.

// Trading enabled, but every money-moving action freezes for human approval.
const desk = await naive.accountKits.create({
  name: "Trading desk",
  primitives_config: {
    trading: { enabled: true, requiresApproval: true }, // place/cancel/close → approval
    cards:   { enabled: false },                          // no card for this tier
  },
});
await naive.accountKits.assignUser(desk.id, acme.id);

• The agent’s code is identical for every tier — client.trading.createOrder({ ... }). Whether the order runs is decided at execution time:
  • A user whose Account Kit does not enable trading is refused with forbidden, with no code change on your side.
  • With trading.requiresApproval: true, createOrder / cancelOrder / closePosition return 202 { status: "pending_approval" } and the broker call replays only after a human approves. Reads (account, positions, quote) are never gated.
  • This is a key governance difference for money-moving actions: a leaked Alpaca key can trade immediately; a Naive agent’s trades are subject to Account Kit policy and optional approval.

​

Gain #3 — unified accountability

• Every connect, order, cancel, and close for a customer lands in one per-user activity log — alongside their card, email, vault, and KYC events, not in a separate Alpaca dashboard:

const { events } = await naive.forUser(acme.id).logs.query({ limit: 50 });
// "what did this agent do, for whom?" — trading, cards, email, vault, one timeline

• That is the question that is hard to answer when trading lives in Alpaca, cards live in Stripe, and secrets live somewhere else. Under Naive it is a single query.

​

What does not map yet

​

Where to go next

• trading primitive — full connect/account/order/position lifecycle + governance
• trading SDK sub-client — typed method signatures
• trading CLI — connect, account, order, positions, quote
• Account Kits and Approvals — the policy model behind execution-time governance and money-moving approval
• Tenant users — the identity that owns the brokerage link, cards, email, and vault
• Cards, Email, Vault — the sibling primitives the same identity owns