Paper Trading

Paper trading prices quotes against current market data and records simulated balances, orders, and positions. Live funds never enter the flow. Use it as a production feature (a paper account next to a real one), as a testing and QA tool, or both. There are two surfaces:

Surface	Who calls it	Use it for
`mode: "paper"` on the normal trading calls	Your app, with the user’s session	Users trading a paper account through the same quote and fill flow as live
Paper account management APIs	Your backend, with `x-app-api-key`	Creating, seeding, resetting, and inspecting paper accounts for simulators and test fixtures

Paper trading never submits to venues and never runs bridges, custody transfers, deposits, withdrawals, or redemptions. Do not treat paper balances as funded wallets or venue balances.

How it works

User signs in

Paper mode is user-scoped. A signed-in user gets a paper account for your app the first time they request paper balances, positions, quotes, or a fill.

AGG prices against live books

Quotes and paper fills price against the current order book. The result is simulated, but the quote reflects current market depth.

Your app sends paper mode

Add mode: "paper" to the paper-capable calls in SDK flow. For AGG UI components, set trading.executionMode once on AggProvider.

AGG writes paper state only

Paper fills update the PAPER_USD balance, paper orders, and paper positions. Live wallets, venue accounts, and live orders are not touched.

Keep paper and live state visually separate. A user can have both, but never show them as one balance or one portfolio.

SDK flow

Pass mode: "paper" on these calls. They, and only they, accept it:

SDK method	API reference
`getManagedBalances({ mode: "paper" })`	Get balances
`getSmartRoute({ mode: "paper" })`	Get a quote
`executeManaged({ mode: "paper" })`	Execute quote
`getExecutionStatus({ mode: "paper" })`	Get execution status
`getExecutionPositions({ mode: "paper" })`	Get user positions
`getExecutionOrders({ mode: "paper" })`	Get user orders

import { createAggClient } from "@agg-build/sdk";

const client = createAggClient({
  baseUrl: process.env.AGG_API_BASE_URL!,
  appId: "your-app-id",
});

// After the user signs in...
const balances = await client.getManagedBalances({ mode: "paper" });

const quote = await client.getSmartRoute({
  venueMarketOutcomeId: "vmo_...",
  tradeSide: "buy",
  maxSpend: 25,
  mode: "paper",
});

const fill = await client.executeManaged({ quoteId: quote.quoteId, mode: "paper" });

let status = await client.getExecutionStatus({ quoteId: fill.quoteId, mode: "paper" });
while (!status.terminal) {
  await new Promise((r) => setTimeout(r, status.pollAfterMs ?? 1000));
  status = await client.getExecutionStatus({ quoteId: fill.quoteId, mode: "paper" });
}

Keep the mode the same from quote to fill. A paper quote must be filled with mode: "paper", and a live fill cannot execute a paper quote. Switching modes needs a fresh quote.

Place an order directly (POST /execution/orders) is live only. It has no mode field and rejects one with 400. Use a quote and fill with mode: "paper", or a paper account order from your backend.

UI components

Set paper mode once on AggProvider. HomePage, EventMarketPage, PlaceOrder, and UserProfilePage read it when no executionMode prop is passed.

import { AggProvider } from "@agg-build/ui";
import { QueryClient, QueryClientProvider } from "@agg-build/hooks";
import { HomePage } from "@agg-build/ui/pages";

const queryClient = new QueryClient();

export function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <AggProvider client={client} config={{ trading: { executionMode: "paper" } }}>
        <HomePage />
      </AggProvider>
    </QueryClientProvider>
  );
}

Pass executionMode on one component when it must differ from the provider:

import { EventMarketPage } from "@agg-build/ui/pages";

export function LiveEventOverride({ eventId }: { eventId: string }) {
  return <EventMarketPage eventId={eventId} executionMode="live" />;
}

Hide deposit, withdrawal, and redemption controls in a paper-only experience.

Manage paper accounts from your backend

These endpoints need a server-side x-app-api-key (see Base URL, app IDs & API keys). Never call them from the browser.

SDK method	API reference
`createPaperTradingAccount`	Create a paper trading account
`listPaperTradingAccounts`	List paper trading accounts
`getPaperTradingAccount`	Get a paper trading account
`setPaperTradingBalance`	Set a paper trading account cash balance
`resetPaperTradingAccount`	Reset a paper trading account
`placePaperTradingOrder`	Place a paper trading order
`listPaperTradingPositions`	List paper trading positions
`listPaperTradingOrders`	List paper trading orders
`getPaperTradingPortfolio`	Get a paper trading portfolio

const agg = createAggClient({
  baseUrl: process.env.AGG_API_BASE_URL!,
  appId: process.env.AGG_APP_ID!,
  apiKey: process.env.AGG_APP_API_KEY!, // server-side only
});

Seed the account a user sees

Browser paper mode uses the account whose externalId is user:<aggUserId>. Create or reset that account from your backend and the signed-in user sees the seeded balance in the app.

const aggUserId = "usr_...";

const account = await agg.createPaperTradingAccount({
  name: "QA paper account",
  externalId: `user:${aggUserId}`,
  initialBalanceRaw: "100000000", // 100.000000 PAPER_USD
});

externalId is unique per app, so creating an existing account returns a validation error. Look it up instead:

const page = await agg.listPaperTradingAccounts({ externalId: `user:${aggUserId}` });
const existing = page.data[0] ?? null;

Reset or set cash

resetPaperTradingAccount clears open positions and sets cash. setPaperTradingBalance changes cash only.

await agg.resetPaperTradingAccount(account.id, {
  balanceRaw: "250000000", // 250.000000 PAPER_USD
  reason: "Reset before QA run",
});

await agg.setPaperTradingBalance(account.id, {
  balanceRaw: "50000000", // 50.000000 PAPER_USD
  reason: "Low-balance test case",
});

Raw amounts use 6 decimals. initialBalance, balance, and spend also accept numbers, but raw strings are better for repeatable fixtures. Order history survives a reset.

Place a simulated order

Direct paper orders build known positions before a UI test. They price against the current book and come back filled or rejected.

const order = await agg.placePaperTradingOrder(account.id, {
  venueMarketOutcomeId: "vmo_...",
  side: "buy",
  spendRaw: "25000000",
  slippageBps: 100,
  clientOrderId: "qa-run-123-buy-1",
});

if (order.status === "rejected") {
  console.log(order.rejectionReason);
}

On paper orders, clientOrderId is stored for traceability only. It is not an idempotency key.

Inspect state

const portfolio = await agg.getPaperTradingPortfolio(account.id);
const positions = await agg.listPaperTradingPositions(account.id, { limit: 50 });
const orders = await agg.listPaperTradingOrders(account.id, { limit: 50 });

Testing with paper mode

For pre-release checks or CI smoke tests:

Sign in a test user through the normal auth flow.
Read paper balances and check PAPER_USD is present.
Quote a current open market with mode: "paper", fill it, and poll status to a terminal state.
Read paper orders and positions and check the fill is there and cash changed.

Negative paths:

Fill a paper quote without mode: "paper" and expect a rejection.
Switch from paper to live and require a fresh quote before filling.
Check paper pages show no deposit, withdrawal, bridge, or redemption actions.

For repeatable runs, reset the user’s user:<aggUserId> account before the run, pick test outcomes from current discovery instead of hardcoding one that can close, and use scenario-owned clientOrderId values on backend orders so logs map fixtures to orders.

Launch checklist

Decide whether paper trading is for testing only, user-facing, or both.
Show a clear paper badge or account switcher.
Set config.trading.executionMode = "paper" on AggProvider while the paper account is selected.
Pass mode: "paper" on custom SDK calls for balances, quotes, fills, status, positions, and orders.
Never send mode: "paper" to POST /execution/orders.
Use live mode only after the user explicitly picks their real account.

Start here

Core concepts

SDK reference

Account & identity

Trading guides

Market data & discovery

Security & compliance

Real-time

Webhooks

UI Kit

Releases

How it works

SDK flow

UI components

Manage paper accounts from your backend

Seed the account a user sees

Reset or set cash

Place a simulated order

Inspect state

Testing with paper mode

Launch checklist

​How it works

​SDK flow

​UI components

​Manage paper accounts from your backend

​Seed the account a user sees

​Reset or set cash

​Place a simulated order

​Inspect state

​Testing with paper mode

​Launch checklist

How it works

SDK flow

UI components

Manage paper accounts from your backend

Seed the account a user sees

Reset or set cash

Place a simulated order

Inspect state

Testing with paper mode

Launch checklist