SDK: Installation & Setup

The @arcaresearch/sdk package provides a high-level, typed, idempotent interface for building on Arca. It requires Node.js 18+ and is written in TypeScript (ES2022).

Installation

npm install @arcaresearch/sdk

Package Exports

The package exports one main class and all supporting types:

import { Arca } from '@arcaresearch/sdk';

// Types are also exported for strong typing
import type {
  ArcaObject,
  ArcaBalance,
  Operation,
  TransferOptions,
  PlaceOrderOptions,
  RealmEvent,
  // ... 70+ exported types
} from '@arcaresearch/sdk';

Initialization

The SDK supports two authentication modes. In both cases, call arca.ready() to resolve the realm before making API calls (it is also called automatically on the first API call).

// API Key — for backend services, scripts, CI
const arca = new Arca({
  apiKey: 'arca_78ae7276_...',
  realm: 'development',       // slug or UUID
  baseUrl: 'http://localhost:3052', // optional
});
await arca.ready();

// Scoped Token — for end-user frontends
const arca = Arca.fromToken(scopedJwt);
// realm is extracted from the token claims automatically
await arca.ready();

SDK: Authentication

The SDK mirrors the platform's dual-auth model. Choose the right mode for your context:

API Key (Backend)

API keys are team-scoped with full access across all realms. Use this for server-side code, scripts, and CI pipelines.

import { Arca } from '@arcaresearch/sdk';

const arca = new Arca({
  apiKey: 'arca_78ae7276_...',
  realm: 'development',
});

Scoped Token (Frontend)

Scoped tokens are short-lived JWTs minted by the builder's backend via POST /auth/token. They restrict access to specific paths and permissions within a single realm.

// With automatic refresh (recommended)
const arca = Arca.fromToken(scopedJwt, {
  tokenProvider: async () => {
    const res = await fetch('/api/arca-token');
    return (await res.json()).token;
  },
});
await arca.ready();

// Static token (manual refresh via updateToken())
const arca = Arca.fromToken(scopedJwt);
await arca.ready();

If the token does not embed a realmId claim, provide it explicitly:

const arca = Arca.fromToken(scopedJwt, { realm: 'development' });

Realm Resolution

The SDK accepts realm slugs (e.g., development) and resolves them to UUIDs on arca.ready(). If the input is already a UUID, no resolution call is made. For scoped tokens, the realmId claim is extracted from the JWT payload directly.

Choosing the Right Auth Mode

The recommended pattern: API key in your backend for writes, read-only scoped token in the frontend for reads and streaming. This gives your frontend real-time data without any write risk, while your backend retains full control over mutations.

See Architecture Patterns for a full risk-based decision guide on which write actions to expose to frontends.

Token Refresh

Scoped tokens are short-lived (default 60 min). The SDK provides two approaches to handle expiry, from fully automatic to manual:

Recommended: Token Provider (automatic)

Pass a tokenProvider function that calls your backend to mint a fresh token. The SDK handles the rest:

• Proactive refresh — ~30 seconds before expiry
• 401 retry — if a request fails with 401, the SDK calls the provider, swaps the token, and retries the request once
• WebSocket — on reconnect, the provider is called for a fresh credential

// Recommended: pass a token provider for automatic refresh
const arca = new Arca({
  token: initialScopedJwt,
  tokenProvider: async () => {
    const res = await fetch('/api/arca-token');
    return (await res.json()).token;
  },
});

// Or use the factory method (provider-only, no initial token)
const arca = Arca.fromTokenProvider(async () => {
  const res = await fetch('/api/arca-token');
  return (await res.json()).token;
});

// Listen for unrecoverable auth failures (e.g. provider throws)
arca.onAuthError((error) => {
  showSessionExpiredUI();
});

Manual: updateToken()

If you prefer full control, use updateToken() to swap the token yourself. The new token takes effect immediately for HTTP; if the WebSocket is disconnected, it reconnects immediately with the new token.

arca.updateToken(freshScopedJwt);

Auth Error Event

Register an onAuthError listener to handle unrecoverable authentication failures centrally, regardless of which approach you use. This fires when a 401 cannot be recovered (no provider, or the provider itself fails).

const unsub = arca.onAuthError((error) => {
  console.error('Session expired:', error.message);
  redirectToLogin();
});

// Call unsub() to remove the listener

History Cache

The SDK caches responses from getEquityHistory(), getPnlHistory(), and getCandles() in an in-memory LRU cache. This eliminates redundant network calls when switching between charts or toggling intervals. The watchEquityChart() and watchPnlChart() methods also benefit since they call the history methods internally.

By default, the cache holds up to 50 entries. You can customize this via the cache config option:

// Custom cache size
const arca = new Arca({
  apiKey: 'arca_78ae7276_...',
  realm: 'development',
  cache: { maxEntries: 100 },
});

// Disable caching entirely
const arca = new Arca({
  apiKey: 'arca_78ae7276_...',
  realm: 'development',
  cache: false,
});

// Manually clear the cache (e.g. after a known data change)
arca.clearHistoryCache();

Minting Tokens (ArcaAdmin)

The ArcaAdmin class provides a mintToken() method for your backend to create scoped JWTs:

import { ArcaAdmin } from '@arcaresearch/sdk';

const admin = new ArcaAdmin({ baseUrl: 'http://localhost:3052' });
const { token: jwt } = await admin.signIn('you@company.com', 'password');
admin.setToken(jwt);

// Mint a read-only token for an end-user
const { token: scopedJwt } = await admin.mintToken({
  realmId: '6d25623e-...',
  sub: 'alice',
  scope: {
    statements: [
      { effect: 'Allow', actions: ['arca:Read'], resources: ['*'] },
    ],
  },
  expirationMinutes: 30,
});

// Return scopedJwt to the frontend

SDK: Operation Handles

Every mutation method — ensureDenominatedArca, fundAccount, transfer, placeOrder, etc. — returns an OperationHandle<T> instead of Promise<T>. The handle is thenable: await waits for both HTTP submission and operation settlement, so the common case is a single line.

Simple: Await to Settlement

// Resolves when the fund operation has fully settled
await arca.fundAccount({ arcaRef: '/wallets/main', amount: '1000' });

Progressive Disclosure

When you need the HTTP response before settlement (e.g., to show a pool address to the user), access handle.submitted:

const handle = arca.fundAccount({ arcaRef: '/wallets/main', amount: '1000' });

// Get the HTTP response immediately (before settlement)
const { poolAddress, operation } = await handle.submitted;
console.log(poolAddress); // show to user while settlement is in progress

// Wait for settlement with an explicit timeout
await handle.wait({ timeout: 15000 });

Batching

Handles work with Promise.all for parallel operations:

await Promise.all([
  arca.fundAccount({ arcaRef: '/wallets/main', amount: '500' }),
  arca.fundAccount({ arcaRef: '/wallets/savings', amount: '300' }),
]);

OrderHandle (Exchange Orders)

placeOrder() returns an OrderHandle that extends OperationHandle with fill lifecycle methods:

const order = arca.placeOrder({
  path: '/op/order/btc-buy-1',
  objectId: exchangeId,
  coin: 'hl:BTC', side: 'BUY', orderType: 'MARKET', size: '0.01',
});
await order; // wait for placement

// Wait for fills
const filled = await order.filled({ timeout: 30000 });
console.log(filled.fills);

// Stream fills via async iterator
for await (const fill of order.fills()) {
  console.log(`Filled ${fill.size} @ ${fill.price}`);
}

// Get structured fill summary (P&L, fee breakdown, direction, resulting position)
const summary = await order.fillSummary({ timeout: 30000 });
console.log(summary?.realizedPnl, summary?.dir, summary?.feeBreakdown);

// Callback-based fill listener
const unsub = order.onFill((fill) => console.log(fill));

// Cancel the order (auto-generates cancel path from placement path)
const cancelResult = await order.cancel();

API Summary

SDK: Arca Objects

ensureDenominatedArca(opts)

Ensure a denominated Arca object exists at the given path. Creates it if it doesn't exist; returns the existing one if it does (matching type and denomination). Safe to call on every request — eliminates the need for separate create-then-get patterns. Returns an OperationHandle — await resolves when the object is active (immediate for existing objects, waits for creation workflow otherwise).

const { object } = await arca.ensureDenominatedArca({
  ref: '/wallets/main',
  denomination: 'USD',
  operationPath: '/op/create/wallets/main:1', // optional idempotency key
});

ensureArca(opts)

Ensure an Arca object of any type exists at the given path. Creates if missing, returns existing if matching. Returns an OperationHandle.

New-object creation is asynchronous. The immediate create response gives you a stable object ID right away, but object.createdAt and object.updatedAt may be empty until the background workflow persists the row. If you need an authoritative recency signal shared across devices, wait until the object appears in listObjects() or browseObjects().

const { object } = await arca.ensureArca({
  ref: '/deposits/d1',
  type: 'deposit',
  denomination: 'USD',
});

getObject(path)

Get the active Arca object at a given path.

const obj: ArcaObject = await arca.getObject('/wallets/main');
console.log(obj.id, obj.status, obj.denomination);

getObjectDetail(objectId)

Get full object detail including operations, events, state deltas, and balances.

const detail = await arca.getObjectDetail(obj.id);
console.log(detail.operations.length); // all operations on this object
console.log(detail.balances);          // current balances
console.log(detail.reservedBalances);  // in-flight reserved amounts
console.log(detail.object.isolation);  // boundary metadata, when applicable

listObjects(opts?)

List Arca objects in the realm, optionally filtered by path prefix.

Persisted objects returned here always include authoritative createdAt and updatedAt timestamps. When you need deterministic newest-first selection across devices, sort siblings by createdAt descending and use a stable tie-breaker such as id.

const { objects, total } = await arca.listObjects({
  prefix: '/wallets',
  includeDeleted: false, // default
});

getBalances(objectId)

Get current balances for an Arca object. Each balance includes four fields describing where value is during the transfer lifecycle:

const balances: ArcaBalance[] = await arca.getBalances(obj.id);
// [{ id: '...', arcaId: '...', denomination: 'USD', amount: '1000.00',
//    arriving: '200.00', settled: '800.00', departing: '0.00', total: '1000.00' }]

// Show in-flight state to users
for (const b of balances) {
  if (b.arriving !== '0.00') console.log(`${b.denomination}: ${b.arriving} arriving`);
  if (b.departing !== '0.00') console.log(`${b.denomination}: ${b.departing} departing`);
  console.log(`${b.denomination}: ${b.settled} available, ${b.total} total`);
}

getBalancesByPath(path)

Get balances by Arca path (resolves path to ID internally).

const balances = await arca.getBalancesByPath('/wallets/main');

browseObjects(opts?)

S3-style hierarchical browsing. Returns folders, richer path entries, and objects at the given level.

Like listObjects(), browsed objects have authoritative timestamps once persisted. This is the shared-data view to use when a client must choose the newest sibling account after a reset without any device-local memory.

Use paths and currentIsolation to render explorer-style isolation markers, including empty zones that exist before any object is created under them.

const { folders, paths, currentIsolation, objects } = await arca.browseObjects({
  prefix: '/users/',
  includeDeleted: false,
});

for (const entry of paths ?? []) {
  console.log(entry.path, entry.kind, entry.isolation?.isBoundaryRoot);
}

createIsolationZone(opts)

Declare a path as an isolation-zone root before creating any object beneath it. The call is idempotent by path and returns the existing zone if the same path was already declared.

const zone = await arca.createIsolationZone({
  path: '/users/alice',
});

console.log(zone.boundaryId);
console.log(zone.isolation?.isBoundaryRoot); // true

getObjectVersions(objectId)

Get all versions of an Arca object at the same path (for deleted + recreated objects).

const { versions } = await arca.getObjectVersions(obj.id);

getSnapshotBalances(objectId, asOf)

Get historical balances and positions for an object at a specific timestamp.

const snapshot = await arca.getSnapshotBalances(obj.id, '2026-02-18T18:00:00Z');
console.log(snapshot.balances, snapshot.positions);

ensureDeleted(opts)

Delete an Arca object by path. Returns an OperationHandle — await waits for deletion to complete. If the object has remaining balances, provide a sweep target. For exchange objects with open positions, set liquidatePositions: true to close them via market order first. Deletion is blocked if the object has in-flight operations. Deleted objects keep their canonical path, but the SDK also surfaces a tombstone displayName so repeated deleted generations remain distinguishable in explorer-style UIs.

Full withdrawals are different from deletes: when a non-exchange object reaches zero through withdrawal, the returned ArcaObject will eventually move tostatus: 'withdrawn' with withdrawnAt set. Withdrawn paths stay visible for historical reads and aggregation history, but they are permanently retired and cannot be reused for a new generation.

// Simple deletion (no balance)
await arca.ensureDeleted({ ref: '/wallets/old' });

// Deletion with balance sweep
await arca.ensureDeleted({
  ref: '/wallets/old',
  sweepTo: '/wallets/main',
});

// Exchange deletion with position liquidation
await arca.ensureDeleted({
  ref: '/exchanges/hl1',
  sweepTo: '/wallets/main',
  liquidatePositions: true,
});

updateLabels(objectId, labels)

Update labels on an Arca object. Uses merge semantics: keys with string values are set, keys with null values are removed. Existing labels not mentioned in the call are left unchanged.

const updated = await arca.updateLabels(obj.id, {
  displayName: 'Main Wallet',
  tier: 'gold',
  removeMe: null, // removes this key
});
console.log(updated.labels); // { displayName: 'Main Wallet', tier: 'gold' }

listObjects with labels

Pass include: 'labels' to include labels on each object in the list response.

const { objects } = await arca.listObjects({
  prefix: '/wallets',
  include: 'labels',
});
for (const obj of objects) {
  if (obj.status === 'withdrawn') {
    console.log('retired at', obj.withdrawnAt);
  }
  console.log(obj.displayName ?? obj.labels?.displayName ?? obj.path);
}

SDK: Transfers & Fund Account

transfer(opts)

Execute a transfer between two Arca objects. Returns an OperationHandle. The operation path serves as the idempotency key — resubmitting the same path returns the existing result. Settlement is immediate for denominated targets or async for exchange targets; await handles both transparently.

const { operation, fee } = await arca.transfer({
  path: '/op/transfer/alice-to-bob-1',
  from: '/wallets/alice',
  to: '/wallets/bob',
  amount: '250.00',
});

console.log(operation.state); // 'completed'
console.log(fee); // { amount: '0.05', denomination: 'USD' } (when applicable)

estimateFee(params)

Estimate the fee for a transfer or order operation before executing it.

const estimate = await arca.estimateFee({
  action: 'transfer',
  amount: '1000.00',
  sourcePath: '/wallets/main',
  targetPath: '/exchange/main',
});

console.log(estimate.fee);       // { amount: '0.05', denomination: 'USD' }
console.log(estimate.netAmount); // '999.95'

Static Fee Constants

The Arca.fees static property provides known fee constants for client-side calculations without a network call.

console.log(Arca.fees.exchangeTransfer); // '0.05'

fundAccount(opts)

Fund an Arca object (denominated or exchange). Returns an OperationHandle — await waits for full settlement. Throws OperationFailedError on failure. For exchange objects, the deposit is forwarded to the venue after on-chain confirmation. This is a developer tool for testing and account seeding — for production deposit flows, use createPaymentLink().

Settlement by Realm Type

fundAccount behavior depends on the realm type:

• demo / development / testing — auto-mints tokens to the realm's custody pool and settles automatically within seconds. No real tokens or wallet needed.
• production — creates a deposit intent and returns a poolAddress. The operation stays pending until real tokens (USDC) are sent to that address on-chain. If no tokens arrive before the intent expires (30 min), the operation remains pending indefinitely. Use handle.submitted to access the poolAddress before settlement.

// await waits for full settlement
await arca.fundAccount({
  arcaRef: '/wallets/main',
  amount: '1000.00',
});

// Or access the HTTP response before settlement
const handle = arca.fundAccount({ arcaRef: '/wallets/main', amount: '1000.00' });
const { poolAddress } = await handle.submitted;
await handle.wait({ timeout: 15000 });

defundAccount(opts)

Withdraw funds from an Arca object to an external on-chain address. Returns an OperationHandle. When on-chain custody is active, funds are sent to the destination address. For exchange objects, first transfer funds to a denominated object, then defund from there. This is a developer tool — for production withdrawal flows, use createPaymentLink().

await arca.defundAccount({
  arcaPath: '/wallets/main',
  amount: '500.00',
  destinationAddress: '0xabc...',
});

SDK: Payment Links

Create shareable URLs for deposits and withdrawals. End users can complete the payment without authentication — the link token serves as the credential.

createPaymentLink(opts)

Create a payment link for a deposit or withdrawal. Returns an OperationHandle. Use handle.submitted to get the link URL immediately, or await to wait for the payment to complete.

const handle = arca.createPaymentLink({
  type: 'deposit',
  arcaRef: '/wallets/main',
  amount: '100.00',
  returnUrl: 'https://example.com/thanks',
  returnStrategy: 'redirect',
  expiresInMinutes: 60,
});

// Get the link immediately (before the end user pays)
const { paymentLink } = await handle.submitted;
console.log(paymentLink.url); // shareable link for the end user

// Optionally wait for the payment to settle
await handle;

listPaymentLinks(opts?)

List payment links in the realm, optionally filtered by type and status.

const { paymentLinks, total } = await arca.listPaymentLinks({
  type: 'deposit',   // optional filter
  status: 'pending', // optional filter
});

for (const link of paymentLinks) {
  console.log(link.id, link.status, link.amount, link.denomination);
}

SDK: Operations & Events

getOperation(operationId, options?)

Get operation detail by ID, including correlated events and state deltas.

const detail = await arca.getOperation(operationId);
console.log(detail.operation.type);    // 'transfer', 'deposit', etc.
console.log(detail.operation.state);   // 'pending', 'completed', 'failed'
console.log(detail.events);            // correlated events
console.log(detail.deltas);            // state deltas (before/after values)

const detail = await arca.getOperation(operationId, {
  includeEvidence: true,
});

console.log(detail.evidence?.journal.entries.length);
console.log(detail.evidence?.journal.proofs);
console.log(detail.evidence?.integrity.appendOnlyHistory);

listOperations(opts?)

List operations in the realm, optionally filtered by type.

const { operations, total } = await arca.listOperations({
  type: 'transfer',                   // single type filter
  types: ['fill', 'transfer'],        // or multiple types (takes precedence)
  includeContext: true,               // inline context (amount, fee, etc.)
});

exportOperationEvidence(opts)

Export realm-scoped audit evidence over a time range, with optional operation-type and path filters.

let cursor: string | undefined;
const pages = [];

do {
  const page = await arca.exportOperationEvidence({
    from: '2026-04-01T00:00:00Z',
    to: '2026-04-05T23:59:59Z',
    types: ['transfer', 'deposit'],
    arcaPath: '/wallets/',
    limit: 100,
    cursor,
  });

  pages.push(...page.operations);
  cursor = page.nextCursor ?? undefined;
} while (cursor);

Evidence export in Phase 1 is journal-backed inspection data for builders and auditors. It improves traceability, but it is not yet a standalone cryptographic proof of faithful action.

nonce(prefix, separator?)

Reserve the next unique nonce for a path prefix. Returns a path suitable for use as an idempotency key. Always reserve before the operation and store the result. See Nonce Best Practices in the API Reference for separator conventions and anti-patterns.

const { path } = await arca.nonce('/op/transfer/fund');
await arca.transfer({ path, from: '/wallets/alice', to: '/wallets/bob', amount: '100' });

// Colon separator for create-operation nonces
const { path: opPath } = await arca.nonce('/op/create/wallets/main', ':');

listDeltas(arcaPath)

List state deltas for a given Arca path (before/after values for every state change).

const { deltas, total } = await arca.listDeltas('/wallets/main');

summary()

Get aggregate counts for the realm.

const summary = await arca.summary();
console.log(summary.objectCount);    // 12
console.log(summary.operationCount); // 47
console.log(summary.eventCount);     // 93

Prefix vs. Exact Path

All aggregation methods accept a prefix parameter. A trailing slash aggregates all objects under that path (e.g., /users/alice/ returns all of Alice's objects). Omitting the trailing slash targets a single exact object (e.g., /users/alice/exchanges/hl1 returns only that object).

getPathAggregation(prefix, options?)

Get aggregated valuation for objects matching the prefix (or exact path).

// Aggregate all objects under a prefix
const agg = await arca.getPathAggregation('/users/alice/');
console.log(agg.totalEquityUsd, agg.breakdown);

// Single object
const single = await arca.getPathAggregation('/users/alice/exchanges/hl1');

// Historical aggregation at a past timestamp
const hist = await arca.getPathAggregation('/users/', { asOf: '2026-02-15T00:00:00Z' });

Response:

Per-object valuations are not returned on this endpoint. For a one-shot read, use getObjectValuation(path). For streaming updates, use watchObject(path) or watchObjects(paths).

getPnl(prefix, from, to)

Get P&L for objects matching the prefix (or exact path) over a time range.

const pnl = await arca.getPnl('/users/alice/', '2026-02-01T00:00:00Z', '2026-03-01T00:00:00Z');
console.log(pnl.pnlUsd); // e.g. "1200.00"

Response:

getPnlHistory(prefix, from, to, points?)

Returns P&L time-series data for objects under a path prefix, adjusted for external flows (deposits/withdrawals). Each point includes both pnlUsd and equityUsd.

const history = await arca.getPnlHistory('/users/alice/', '2026-02-01T00:00:00Z', '2026-03-01T00:00:00Z', 100);
console.log(history.pnlPoints[0].pnlUsd, history.pnlPoints[0].equityUsd);

Response:

getEquityHistory(prefix, from, to, points?)

Get equity time-series sampled evenly over a time range (default 200 points, max 1000).

const history = await arca.getEquityHistory('/users/', '2026-02-01T00:00:00Z', '2026-03-01T00:00:00Z', 100);

Response:

watchEquityChart(path, from, to, points?, options?)

Create a live equity chart that merges historical data with real-time aggregation updates. The rightmost point updates on each aggregation event (fills, balance changes, mid-price ticks). Returns an EquityChartStream.

const chart = await arca.watchEquityChart(
  '/users/alice/',
  '2026-02-01T00:00:00Z',
  '2026-03-01T00:00:00Z',
  200,
);

chart.onUpdate(({ points }) => {
  // points: sorted array of { timestamp, equityUsd }
  // Last point is always "now" with live equity
  renderEquityChart(points);
});

chart.close();

watchPnlChart(path, from, to, points?, options?)

Create a live P&L chart that merges historical P&L data with real-time aggregation updates and operation events. The rightmost point updates on each aggregation event. Deposits, withdrawals, and transfers that cross the path boundary are automatically tracked as external flows and subtracted from equity changes, so P&L reflects actual investment performance rather than cash movements.

const chart = await arca.watchPnlChart(
  '/users/alice/',
  '2026-02-01T00:00:00Z',
  '2026-03-01T00:00:00Z',
  200,
);

chart.onUpdate(({ points, externalFlows }) => {
  // points: sorted array of { timestamp, pnlUsd, equityUsd }
  // Last point is always "now" with live P&L
  renderPnlChart(points);

  // externalFlows: itemized deposits/withdrawals/transfers
  // that crossed the path boundary
  console.log('Flows:', externalFlows);
});

// startingEquityUsd is available for reference
console.log('Starting equity:', chart.startingEquityUsd);

chart.close();

// Equity-anchored P&L chart (portfolio value view)
const chart = await arca.watchPnlChart(
  '/users/alice/',
  '2026-02-01T00:00:00Z',
  '2026-03-01T00:00:00Z',
  200,
  { anchor: 'equity' },
);

chart.onUpdate(({ points }) => {
  // Use valueUsd for the y-axis — the live point equals current equity
  renderChart(points.map(p => ({ x: p.timestamp, y: p.valueUsd })));
});

How flow adjustments work: When a deposit or transfer operation completes, PnlChartStream detects the operation event via WebSocket, classifies it as an inflow or outflow relative to the watched path, and adjusts cumulative flows client-side. This means the P&L chart stays accurate across deposits and transfers without any additional server reads or manual recalculation.

Portfolio Aggregation Watches

Aggregation watches provide real-time portfolio valuation for any combination of Arca objects: total equity, asset breakdown, and pass-through in-transit totals. Structural updates stream as PathAggregation snapshots; for per-object detail (balances, positions, reserves), use watchObject(path) or watchObjects(paths).

createAggregationWatch(sources)

Create a watch that tracks objects matching the given sources. Returns the watch ID and an initial aggregation snapshot. After creation, the server pushes aggregation.updated events via WebSocket whenever an object in the watch set changes.

// Track all objects under a user prefix
const { watchId, aggregation } = await arca.createAggregationWatch([
  { type: 'prefix', value: '/users/alice/' },
]);
console.log(aggregation.totalEquityUsd); // e.g. "15734.56"
console.log(aggregation.breakdown);      // per-asset rollup

Source Types

// Combine multiple source types in a single watch
const { watchId } = await arca.createAggregationWatch([
  { type: 'prefix', value: '/users/alice/' },
  { type: 'paths', paths: ['/treasury/usd', '/treasury/btc'] },
  { type: 'pattern', value: '/users/*/exchanges/hl/*' },
]);

watchAggregation(sources, options?)

Subscribe to real-time aggregation updates with a single call. Internally creates a server-side watch, watches for structural change events and mid prices, and performs client-side revaluation so every emission reflects live prices. Call .close() when done — it cleans up everything automatically.

const stream = await arca.watchAggregation([
  { type: 'prefix', value: '/users/alice/' },
]);

stream.onUpdate((agg) => {
  console.log('Equity:', agg.totalEquityUsd);
  console.log('Breakdown:', agg.breakdown);
});

// Clean up when done
stream.close();

The stream emits on both structural changes (fills, balance updates, object creation/deletion) and mid-price ticks. The aggregation property always holds the latest snapshot.

Options: exchange (default 'sim') and flowsSince (ISO timestamp; when set, the server computes cumulative cumInflowsUsd/cumOutflowsUsd from that time instead of from watch creation — used internally by watchPnlChart).

Manual Wiring (Advanced)

For full control you can use createAggregationWatch() with manual WebSocket and price subscriptions. This is useful when you need custom throttling or want to share a single price stream across multiple consumers.

import { revalueAggregation } from '@arcaresearch/sdk';

// 1. Create the watch (get initial snapshot)
const { watchId, aggregation } = await arca.createAggregationWatch([
  { type: 'prefix', value: '/users/alice/' },
]);
let portfolio = aggregation;

// 2. Listen for structural updates
arca.ws.ensureConnected();
arca.ws.on('aggregation.updated', (event) => {
  if (event.aggregation) {
    portfolio = event.aggregation;
    renderPortfolio(portfolio);
  }
});

// 3. Revalue on mid price ticks for real-time USD values
const prices = await arca.watchPrices();
prices.onUpdate((mids) => {
  portfolio = revalueAggregation(portfolio, mids);
  renderPortfolio(portfolio);
});

// 4. Clean up when done
prices.close();
arca.ws.off('aggregation.updated', handler);
await arca.destroyAggregationWatch(watchId);

getWatchAggregation(watchId)

Get the current aggregation for an existing watch (recomputed on demand). Useful for initial page loads or manual refreshes.

const agg = await arca.getWatchAggregation(watchId);
console.log(agg.totalEquityUsd, agg.breakdown);

destroyAggregationWatch(watchId)

Destroy a watch and stop receiving updates. Watches are also automatically evicted after 5 minutes of inactivity (no WebSocket messages referencing the watch).

await arca.destroyAggregationWatch(watchId);

Response shape (PathAggregation):

waitForQuiescence(opts?)

Wait until all pending operations in the realm reach a terminal state. Auto-connects the WebSocket for faster resolution (reacts to settlement events instantly, with periodic HTTP polls as a safety net).

const polls = await arca.waitForQuiescence({
  intervalMs: 1000,    // default
  timeoutMs: 120_000,  // default
  onPoll: (pending) => console.log(`${pending} operations pending`),
});

waitForOperation(operationId, timeoutMs?)

Wait for a specific operation to reach a terminal state. Automatically connects the WebSocket and watches the root path for events — no need to call ws.connect() manually. Uses WebSocket events for immediate resolution. Throws OperationFailedError if the operation ends in failed or expired state.

Note: In most cases, you don't need to call this directly — awaiting an OperationHandle calls it internally. Use it only when you have an operation ID from another source (e.g., a webhook or database).

import { OperationFailedError } from '@arcaresearch/sdk';

try {
  const completed = await arca.waitForOperation(operationId, 30_000);
  console.log(completed.state); // 'completed'
} catch (err) {
  if (err instanceof OperationFailedError) {
    // Human-readable message safe to display to users
    console.error(err.message); // e.g. "Insufficient balance to complete this operation."

    // Also available on the operation object
    console.error(err.operation.failureMessage);

    // Raw outcome JSON for programmatic inspection
    console.error(err.operation.outcome);
  }
}

SDK: Exchange (Perps)

Trade simulated perpetual futures on exchange Arca objects. These methods wrap the sim-exchange API and follow the same idempotency contract as other operations.

ensurePerpsExchange(opts)

Ensure a perps exchange Arca object exists at the given path. Denomination is automatically set to USD.

const { object } = await arca.ensurePerpsExchange({
  ref: '/exchanges/hl1',
  exchangeType: 'hyperliquid', // default
});

getExchangeState(objectId)

Get exchange account state including equity, margin, positions, and open orders. Use marginSummary for account equity and risk thresholds — see getActiveAssetData() below for computing max order sizes.

const state: ExchangeState = await arca.getExchangeState(objectId);
console.log(state.marginSummary.equity); // equity
console.log(state.marginSummary.initialMarginUsed); // initial margin in use
console.log(state.marginSummary.maintenanceMarginRequired); // liquidation threshold
console.log(state.crossMaintenanceMarginUsed); // Hyperliquid-parity alias (cross mode)
console.log(state.positions);   // SimPosition[]
console.log(state.openOrders);  // SimOrder[]

marginSummary Fields

The marginSummary object on ExchangeState contains derived account values. These are the authoritative balance fields for exchange accounts — there is no separate usdBalance field exposed.

updateLeverage(opts)

Set the leverage for a coin. Leverage is a per-coin setting, not per-order. Changing leverage re-margins any existing position. Rejects if insufficient margin.

await arca.updateLeverage({
  objectId: exchangeId,
  coin: 'hl:BTC',
  leverage: 10,
});

placeOrder(opts)

Place a market or limit order. Returns an OrderHandle (extends OperationHandle) with fill lifecycle methods. The path is the idempotency key. When leverage is provided, the account's per-coin leverage is automatically set before placing the order (equivalent to calling updateLeverage then placeOrder). If omitted, the order uses whatever leverage is currently set for the coin on that account.

const order = arca.placeOrder({
  path: '/op/order/btc-buy-1',
  objectId: exchangeId,
  coin: 'hl:BTC',
  side: 'BUY',
  orderType: 'MARKET',
  size: '0.01',
  leverage: 5,
});
await order; // wait for placement

// Wait for the order to be fully filled
const filled = await order.filled({ timeout: 30000 });
console.log(filled.fills);

// Stream fills via async iterator
for await (const fill of order.fills()) {
  console.log(`Filled ${fill.size} @ ${fill.price}`);
}

// Callback-based fill listener (returns unsubscribe function)
const unsub = order.onFill((fill) => console.log(fill));

// Cancel the order
const cancelResult = await order.cancel();

Max Size Orders

When a user selects “max” in your UI, pass useMax: true along with the displayed size as the reference. The server resolves the actual max at execution time, eliminating race conditions between client-side max computation and server-side margin checks.

// Get the current max from the live stream
const maxStream = await arca.watchMaxOrderSize({
  objectId: exchangeId,
  coin: 'hl:BTC',
  side: 'BUY',
  leverage: 5,
});
const displayedMax = maxStream.value.activeAssetData.maxBuySize;

// Place with useMax — server resolves atomically
const order = arca.placeOrder({
  path: '/op/order/btc-max-1',
  objectId: exchangeId,
  coin: 'hl:BTC',
  side: 'BUY',
  orderType: 'MARKET',
  size: displayedMax, // reference (what the user saw)
  useMax: true,       // server resolves fresh max at execution time
});

The server will never fill more tokens than the reference size. If the resolved max is below the reference by more than 2% (default), the order is rejected with a clear message so the user can review the change. Builders can customize the tolerance:

arca.placeOrder({
  // ...
  useMax: true,
  sizeTolerance: 0.05, // allow up to 5% downside deviation
});

sizeTolerance works on any order, not just useMax. When the order fails a margin check (e.g. price drift), the server reduces the size by up to the tolerance percentage. Only reduces, never increases. Recommended: 0.01 for interactive flows, 0.02 for retail. maxSizeTolerance is deprecated but still works as an alias.

Close Position (Market, close-only)

The preferred way to close a position is with closePosition(). It looks up the current position, infers the closing side, defaults to closing the full position, and always sets reduceOnly: trueso the order can never accidentally open or increase a position.

// Close a full BTC position (side + size inferred)
await arca.closePosition({
  path: '/op/close/btc-1',
  objectId: exchangeId,
  coin: 'hl:BTC',
});

// Partial close — close 0.005 of a BTC position
await arca.closePosition({
  path: '/op/close/btc-partial',
  objectId: exchangeId,
  coin: 'hl:BTC',
  size: '0.005',
});

If you need more control (limit price, custom side), use placeOrder directly with reduceOnly: true:

await arca.placeOrder({
  path: '/op/order/btc-close-1',
  objectId: exchangeId,
  coin: 'hl:BTC',
  side: 'SELL',
  orderType: 'MARKET',
  size: '0.01',
  reduceOnly: true,
});

Reverse After Exit (two-step)

If your UX supports reversal, execute it as two operations: first a close-only exit, then a separate open order in the opposite direction. Do not submit a single order at 2× the position size — this will fail with an insufficient-margin error when the position is underwater, because the realized loss on close consumes the released margin and leaves nothing for the new leg. The two-step approach guarantees the close always succeeds (reduce-only orders skip the margin check), and the second leg can be evaluated independently.

To determine whether a reverse is feasible before showing the option, compare the streamed maxSellSize / maxBuySize from watchMaxOrderSize() against twice the exit size. If maxSellSize < 2 × exitSize (for a long), disable the reverse toggle — the account doesn’t have enough margin to open the opposite position after closing.

Trigger orders surface as WAITING_FOR_TRIGGER and TRIGGERED in addition to standard order statuses.

listOrders(objectId, status?)

List orders for an exchange Arca object, optionally filtered by status.

const orders: SimOrder[] = await arca.listOrders(exchangeId);
const openOrders = await arca.listOrders(exchangeId, 'OPEN');

getOrder(objectId, orderId)

Get a specific order with its fill history.

const { order, fills }: SimOrderWithFills = await arca.getOrder(exchangeId, orderId);
console.log(order.status);    // 'FILLED'
console.log(fills.length);     // number of fills

cancelOrder(opts)

Cancel an open order. Returns an OperationHandle. The path is the idempotency key. Prefer order.cancel() on an OrderHandle (auto-generates the cancel path).

await arca.cancelOrder({
  path: '/op/cancel/btc-1',
  objectId: exchangeId,
  orderId: orderId,
});

placeTwap(opts)

Start a TWAP (Time-Weighted Average Price) order that executes a total size over a duration by placing market orders at regular intervals. Returns an OperationHandle.

const twap = await arca.placeTwap({
  exchangeId: exchangeId,
  path: '/wallets/main/twap/btc-accumulate',
  coin: 'hl:BTC',
  side: 'BUY',
  totalSize: '10.0',
  durationMinutes: 120,
  intervalSeconds: 30,
});
console.log(twap.twap.status); // 'active'

cancelTwap(exchangeId, operationId)

Cancel an active TWAP. Returns an OperationHandle.

await arca.cancelTwap(exchangeId, operationId);

getTwap(exchangeId, operationId)

Get TWAP status and progress by its parent operation ID.

const { twap } = await arca.getTwap(exchangeId, operationId);
console.log(twap.executedSize, twap.filledSlices, twap.status);

listTwaps(exchangeId, activeOnly?)

List TWAPs for an exchange object.

const twaps = await arca.listTwaps(exchangeId, true); // active only

getTwapLimits()

Get TWAP limits and constraints for validation before placing a TWAP. Returns static platform limits.

const limits = arca.getTwapLimits();
// { minSliceNotionalUsd: 10, minIntervalSeconds: 10, maxDurationMinutes: 43200, ... }

listPositions(objectId)

List current positions for an exchange Arca object. Each position includes returnOnEquity (unrealized P&L / margin used) and positionValue (size × mark price), computed server-side.

const positions: SimPosition[] = await arca.listPositions(exchangeId);
for (const pos of positions) {
  console.log(pos.coin, pos.side, pos.size, pos.unrealizedPnl);
  console.log('ROE:', pos.returnOnEquity, 'Value:', pos.positionValue);
}

listFills(objectId, opts?)

List historical fills (trades) for an exchange object with per-fill P&L, fee breakdown, trade direction, and resulting position state.

const { fills, cursor }: FillListResponse = await arca.listFills(exchangeId, {
  market: 'hl:BTC',
  limit: 50,
});
for (const fill of fills) {
  console.log(fill.market, fill.side, fill.size, fill.price);
  console.log('  dir:', fill.dir);              // 'Open Long', 'Close Short', etc.
  console.log('  pnl:', fill.realizedPnl);
  console.log('  fees:', fill.exchangeFee, fill.platformFee, fill.builderFee);
  console.log('  position after:', fill.resultingPosition);
  console.log('  order op:', fill.orderOperationId);  // originating order placement
}

watchFills(objectId, opts?)

Subscribe to a live-updating trade history for an exchange object. Returns a FillWatchStream that combines an initial REST snapshot with real-time fill.recorded WebSocket events. Each fill is a platform-levelFill with P&L, fee breakdown, trade direction, and resulting position state.

const stream = await arca.watchFills(exchangeId, { market: 'hl:BTC' });

// Initial fills are available immediately
console.log(stream.fills);

// Live updates as new fills arrive
stream.onUpdate(({ fill, event }) => {
  console.log('New fill:', fill.market, fill.side, fill.size, fill.price);
  console.log('  dir:', fill.dir, 'pnl:', fill.realizedPnl);
});

// Clean up when done
stream.close();

tradeSummary(objectId, opts?)

Get per-market P&L aggregation: total realized P&L, total fees, trade count, and volume, with cross-market totals.

const summary: TradeSummaryResponse = await arca.tradeSummary(exchangeId);
for (const m of summary.markets) {
  console.log(m.market, 'pnl:', m.totalRealizedPnl, 'fees:', m.totalFees, 'trades:', m.tradeCount);
}
console.log('Overall:', summary.totals);

Funding Events

Funding payments are applied hourly to open positions based on the current Hyperliquid funding rate. Use the convenience handler to listen for funding events:

// Callback-based funding listener
const unsub = arca.ws.onExchangeFunding((funding, event) => {
  console.log(funding.coin, funding.side, funding.payment);
  // payment is signed: negative = account paid, positive = account received
});

// Or listen for exchange.funding events directly
arca.ws.on('exchange.funding', (event) => {
  console.log(event.funding);
});

The FundingPayment type contains: accountId, coin, side (LONG/SHORT), size, price (mark price at time of funding), fundingRate, and payment (signed amount).

getLeverage(objectId, coin?)

Get leverage settings for a specific coin or all coins.

// Single coin
const setting = await arca.getLeverage(exchangeId, 'hl:BTC');

// All coins
const settings = await arca.listLeverageSettings(exchangeId);

getActiveAssetData(objectId, coin, builderFeeBps?, leverage?)

Get active trading data for a coin on an exchange object. Returns a one-shot snapshot of max order sizes. For live updates that react to margin, position, and price changes, use watchMaxOrderSize() instead.

const data = await arca.getActiveAssetData(exchangeId, 'hl:BTC');
// Use maxBuySize / maxSellSize for order size sliders
const maxLong  = parseFloat(data.maxBuySize);
const maxShort = parseFloat(data.maxSellSize);

// Pass leverage to override the stored setting
const data10x = await arca.getActiveAssetData(exchangeId, 'hl:BTC', 0, 10);