SDK: Installation & Setup

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

Installation

npm install @arca-network/sdk

Package Exports

The package exports one main class and all supporting types:

import { Arca } from '@arca-network/sdk';

// Types are also exported for strong typing
import type {
  ArcaObject,
  ArcaBalance,
  Operation,
  TransferOptions,
  PlaceOrderOptions,
  RealmEvent,
  // ... 70+ exported types
} from '@arca-network/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 '@arca-network/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, but they bypass stale cache entries after WebSocket reconnects, delivery-sequence gaps, or chart snapshot updates.

By default, the cache holds up to 50 entries and each entry expires after 5 minutes. You can customize both via the cache config option. Lower ttlMs for stronger freshness, or set it to 0 for no expiry (entries then live until LRU eviction):

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

// 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 '@arca-network/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,
  market: 'hl:0:BTC', side: 'buy', orderType: 'MARKET', size: '0.01',
});
const submitted = await order.submitted; // HTTP acknowledgement before settlement
await order; // wait for placement settlement

// 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?.direction, 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();

// Resize the order (auto-generates a per-resize path that encodes newSize).
// Only sized orders resize: limit orders and sized TP/SL triggers. Unsized
// (sizeToMax: true) triggers are rejected — they always close the whole position.
const resizeResult = await order.resize("0.75");

For backend wrappers around order submission, use a stable operation path per logical order attempt and await order.submitted for the HTTP acknowledgement. Awaiting the handle waits for settlement and can time out even after Arca has accepted the order.

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). Safe to call on every request — eliminates the need for separate create-then-get patterns. Denominated and exchange objects are USD-denominated; the field is server-stamped and not a request input. 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',
  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',
});

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
console.log(detail.object.boundary);   // recovery-hatch state, when frozen

boundary is present only when the object's isolation boundary has been frozen by an on-chain recovery action. Two states: soft_frozen (precautionary lock by the recovery key holder, reversible) and hard_frozen (a Withdrawn event has fired; the funds are no longer the platform's to spend, and user wallets in this boundary have been swept into a system-owned recovery arca at boundary.recoveryArcaPath). Builders should treat any non-active boundary as a freeze — render a banner and disable mutating actions on the object.

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.

Both objects and paths are returned newest-first (createdAt descending) with the entry path as a stable tiebreaker. The legacy folders string array follows the same order as paths.

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

for (const entry of paths ?? []) {
  // entry.createdAt is the folder's effective creation timestamp:
  // for isolation zones, the zone's own created_at; for plain folders,
  // MIN(descendant.createdAt) over the arcas the browse query returned.
  // entry.labels carries folder-level labels stored separately from
  // arca objects — set with updateFolderLabels().
  console.log(entry.path, entry.kind, entry.createdAt, entry.labels);
}

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' }

getFolderLabels(path)

Read folder-level labels for a path. Folders are virtual aggregations of arca paths (see browseObjects()); their labels live independently in a dedicated folder_labels store, surfaced inline on each BrowsePathEntry. Returns an empty labels map when no labels are set.

const { labels, createdAt, updatedAt } = await arca.getFolderLabels('/users/alice');
console.log(labels); // { name: 'Alice', team: 'alpha' }

updateFolderLabels(path, labels)

Replace the entire folder label set with the provided map. Unlike updateLabels(), this is a full overwrite — pass the desired final state, not a delta. Pass an empty map ({}) to clear all labels on the folder.

await arca.updateFolderLabels({
  path: '/users/alice',
  labels: { name: 'Alice', team: 'alpha' },
});

// Clear all labels:
await arca.updateFolderLabels({ path: '/users/alice', labels: {} });

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' — the network takes no transfer fee

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 Asset

fundAccount behavior depends on the realm's asset tier (paper vs live):

• paper (legacy development) — auto-mints tokens to the realm's custody pool and settles automatically within seconds. No real tokens or wallet needed.
• live (legacy 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, operation path, object path, or exact object ID.

const { operations, total } = await arca.listOperations({
  type: 'transfer',                   // single type filter
  types: ['fill', 'transfer'],        // or multiple types (takes precedence)
  arcaId: wallet.id,                  // exact object history
  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?, options?)

Returns P&L time-series data for objects under a path prefix, adjusted for external flows (deposits/withdrawals). Each point includes pnlUsd and raw equityUsd. Pass { anchor: "equity" } to also receive flow-adjusted valueUsd, where transfers are applied to the baseline instead of shown as timeline jumps.

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

Response:

getEquityHistory(prefix, from, to, points?, options?)

Get equity time-series sampled evenly over a time range (default 1000 points, max 1000). The backend ladder picks the finest resolution that fits inside points; the default targets 5m for 24h, 1h for 1M, and 4h for 3M ranges. Pass { kind: 'object', objectId } to chart a single object by id (the server then skips prefix enumeration).

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

// Single object by id (skips prefix enumeration on the server):
const one = await arca.getEquityHistory(
  '/users/alice/main', '2026-02-01T00:00:00Z', '2026-03-01T00:00:00Z', 100,
  { kind: 'object', objectId: 'obj_...' },
);

Response:

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

Create a live equity chart that merges V2 history with real-time chart snapshot recovery and aggregation updates. The rightmost point is treated as the current open bucket and updates as equity changes; after reconnects, app backgrounding, or delivery gaps, the SDK refetches V2 history so sealed buckets converge to the server's authoritative rows. 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 V2 P&L history with real-time chart snapshot recovery and aggregation updates. The rightmost point tracks the current open bucket; reconnects and delivery gaps trigger a V2 history refetch so missed sealed buckets are filled from the server rather than synthesized locally. Deposits, withdrawals, and transfers that cross the path boundary are tracked as external flows and subtracted from equity changes, so P&L reflects 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 '@arca-network/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 '@arca-network/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',
  venue: 'hl-sim', // default — simulated Hyperliquid
});

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.

Position Cost Accumulators

Each SimPosition in state.positions carries running totals of what the account has paid (or earned) to hold the position. These accumulate over the position's current open lot — the period from when net position size last went 0 → non-zero up to now — and reset when the lot ends. A full close removes the position row entirely; a flip-through-zero starts a new lot at the opening-portion's proportional share of the flip-fill's fees. Fields are omitted on positions with no accrued cost so consumers can distinguish "not yet computed" from a placeholder zero.

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,
  market: 'hl:0:BTC',
  leverage: 10,
});

updateIsolatedMargin(opts)

Add or remove collateral from an isolated-margin position. Isolated positions carry their own dedicated collateral and are liquidated independently of the cross pool. A positiveamount moves USD from the account's free balance into the position (lowering its liquidation price); a negative amount removes collateral (raising it). Removal is rejected if it would drop the position below its maintenance margin. Only valid on isolated positions.

await arca.updateIsolatedMargin({
  objectId: exchangeId,
  market: 'hl:1:CL',
  amount: '25', // add $25; use a negative string to remove
});

setMarginMode(opts)

Switch an asset between cross and isolated margin for an exchange Arca object. Rejected on isolated-only (HIP-3) markets and while an open position exists for the asset — close the position first. Leverage is remembered per mode (matching Hyperliquid): switching modes restores the leverage you last set for that mode rather than carrying one value across.

await arca.setMarginMode({
  objectId: exchangeId,
  market: 'hl:0:BTC',
  marginMode: 'isolated',
});

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. Reduce-only orders never reconfigure stored leverage — for a reduceOnly order leverage is optional and treated as a no-op (the close uses the position's current leverage), so you can omit it even on isolated-only markets.

Isolated margin. Isolated-only markets — those whose marginModes is ['isolated'] (e.g. hl:1:CL) — reject cross orders at Hyperliquid's matching engine. Pass isolated: true together with a positive leverage when opening or increasing on those markets; a reduceOnly close/trim is accepted without leverage (it uses the position's current leverage). The platform rejects cross orders on isolated-only markets with a 400 before the operation is created. closePosition() handles this automatically; you only need to set isolated yourself when calling placeOrder directly. Read Market.marginModes via arca.market(id) to discover which margin modes a market supports — do not infer from isHip3, since some HIP-3 markets (e.g. hl:1:TSLA) are cross-eligible.

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

// 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,
  market: 'hl:0: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,
  market: 'hl:0: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.

The helper also auto-fills leverage and isolatedfor isolated-only markets such as hl:1:CL: Hyperliquid's matching engine buckets isolated positions by leverage, so a close must carry both fields to identify the bucket. Pass isolated or leverage to override the inference.

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

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

// Isolated-only close — leverage and isolated are auto-filled from the
// position and the market's marginModes. The SDK reads the position's
// leverage and looks up Market.marginModes for you.
await arca.closePosition({
  path: '/op/close/cl-1',
  objectId: exchangeId,
  market: 'hl:1:CL',
});

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,
  market: 'hl:0: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.

Position TP/SL (ergonomic)

Rather than hand-building a trigger order, attach a stop-loss or take-profit to an existing position with setStopLoss() / setTakeProfit(). Each looks up the open position, infers the closing side (a LONG is protected by a SELL trigger, a SHORT by a BUY), and by default places a reduce-only unsized (sizeToMax: true) order — so when it fires it closes the entire live position regardless of size, and it is cancelled when the position closes or is liquidated. To scale out only part of a position, pass a base-unit size: the leg becomes a sized reduce-only partial that closes exactly that quantity (capped at the live position; min-notional waived). Leverage and isolated are auto-filled from the position and market meta. Both return an OrderHandle; there must be an open position for coin or the call throws NotFoundError.

// Stop-loss: a LONG BTC position gets a reduce-only SELL trigger at 54,000
await arca.setStopLoss({
  path: '/op/tpsl/btc-sl',
  objectId: exchangeId,
  market: 'hl:0:BTC',
  triggerPx: '54000',
}).submitted;

// Take-profit (same shape; tpsl: 'tp' under the hood)
await arca.setTakeProfit({
  path: '/op/tpsl/btc-tp',
  objectId: exchangeId,
  market: 'hl:0:BTC',
  triggerPx: '72000',
}).submitted;

By default a new trigger replaces any existing position TP/SL of the same type for the coin (cancel-then-place); pass replace: false to stack. Pass isMarket: false with a limitPrice for a trigger-limit instead of a market trigger.

setPositionTpsl() attaches both legs in one call (at least one of stopLossPx / takeProfitPx is required) and returns a { stopLoss?, takeProfit? } of handles. The legs derive sub-paths <path>/sl and <path>/tp. clearPositionTpsl() cancels the resting position triggers for a coin (optionally filtered to one tpsl leg) and returns the cancelled orders.

The two legs are linked as a true OCO bracket: both are stamped with one auto-generated ocoGroupId, so when either leg fills — even partially — the venue cancels the other and records cancelReason: 'sibling_filled' on it (readable via getOrder / listOrders). Pass an explicit ocoGroupId to placeOrder() to build your own sized brackets; the id is advisory metadata and is not part of the order's signature.

Pass stopLossSz / takeProfitSz (base units) to make a leg a sized partial instead of a whole-position close. Because a partial fill of one OCO leg cancels its sibling, setPositionTpsl() deliberately does not auto-link the two legs when either is sized — so a take-profit that scales out half won't cancel the stop guarding the remainder. (Pass an explicit ocoGroupId if you do want sized legs linked.)

// Bracket an open position with both legs
const { stopLoss, takeProfit } = await arca.setPositionTpsl({
  path: '/op/tpsl/btc',
  objectId: exchangeId,
  market: 'hl:0:BTC',
  stopLossPx: '54000',
  takeProfitPx: '72000',
});

// Later: cancel both legs (or pass tpsl: 'sl' / 'tp' for one)
const cleared = await arca.clearPositionTpsl({
  path: '/op/tpsl/btc-clear',
  objectId: exchangeId,
  market: 'hl:0:BTC',
});

openWithBracket(opts)

Open a position and attach its reduce-only TP/SL triggers in one atomic batch (Hyperliquid normalTpsl parity). Unlike chaining placeOrder then setPositionTpsl, the entry and its triggers are submitted as a single signed batch to one operation: the whole bracket validates and commits at the venue, or none of it does. The trigger legs arm only when the entry fills (they can't fire on mark price before the position exists), and the venue links them with a shared one-cancels-the-other group so a fill on one cancels its sibling. At least one of takeProfitPx / stopLossPx is required. Each trigger leg closes the whole position by default; set its base-unit size — takeProfitSz / stopLossSz — to make it a sized reduce-only partial instead (note size is the entry size, not the trigger size). Returns one OrderHandle per leg — { entry, takeProfit?, stopLoss? } — all backed by the single bracket operation, so each handle's .filled() / .onFill() / .cancel() targets that specific leg. Use setPositionTpsl instead to attach TP/SL to an already-open position.

Sized-partial caveat: the bracket's legs share one server-stamped OCO group, so a partial take-profit fill cancels the stop on the remainder. To “scale out half and keep a stop on the rest”, open the bracket with just the sized takeProfitSz and attach the (unsized) stop separately with setStopLoss().

const { entry, takeProfit, stopLoss } = arca.openWithBracket({
  path: '/op/bracket/btc-1',
  objectId: exchangeId,
  market: 'hl:0:BTC',
  side: 'buy',
  size: '0.01',
  takeProfitPx: '72000',
  stopLossPx: '58000',
});

await entry;             // bracket placed (entry filled or resting)
await entry.filled();    // wait for the entry to fully fill
// takeProfit / stopLoss arm automatically once the entry fills

// Scale out half at the target, keep the stop on the whole position by
// attaching it separately (the bracket's OCO would otherwise cancel a
// shared-group stop on the partial TP fill):
const { entry: e2, takeProfit: tp } = arca.openWithBracket({
  path: '/op/bracket/btc-scaleout',
  objectId: exchangeId,
  market: 'hl:0:BTC',
  side: 'buy',
  size: '0.02',
  takeProfitPx: '72000',
  takeProfitSz: '0.01', // sized: close half at the target
});
await e2.filled();
await arca.setStopLoss({
  path: '/op/bracket/btc-scaleout/sl',
  objectId: exchangeId,
  market: 'hl:0:BTC',
  triggerPx: '58000', // unsized: protects the remaining position
}).submitted;