@arca-network/sdk (TypeScript)

TypeScript SDK for the Arca platform.

Build

From repo root:

pnpm run sdk:build

Or directly:

cd sdk/typescript
pnpm run build

Dev (watch mode)

pnpm run sdk:dev

Clean

pnpm run sdk:clean

Requirements

• Node.js 20+

WebSocket support

The SDK uses WebSocket for real-time operation tracking. Node.js 22+ provides a native global WebSocket; on Node.js 20–21, the SDK automatically falls back to the bundled ws package. No additional setup is needed.

Equity & P&L Charts

Use the chart APIs below. The server is the single source of truth for every point including the open bucket; the SDK never synthesizes a "now" point and never invalidates the cache on a 5%-deviation heuristic. Each point carries an explicit status flag ('sealed' | 'open' | 'carried' | 'incomplete') the renderer is required to honor.

• getEquityHistory({ path, from, to, points?, kind?, objectId? }) — fetches /objects/aggregate/history using target/kind and normalizes the current response to the stable SDK shape.
• getPnlHistory({ path, from, to, points?, anchor?, kind?, objectId? }) — fetches /objects/pnl/history using target/kind; P&L is derived inline by the server from the same snapshot rows. Use anchor: 'equity' to receive flow-adjusted valueUsd, where deposits/transfers shift the baseline instead of drawing timeline jumps.
• watchEquityChart({ path, from, to, points?, kind?, objectId?, exchange? }) — combines getEquityHistory with live aggregation updates and refetches history after gaps.
• watchPnlChart({ path, from, to, points?, anchor?, kind?, objectId?, exchange? }) — same stream pattern for P&L charts.

Resolution selection is shared with the backend (pickResolution from '@arca-network/sdk'); pick a points budget — the server picks the rung. When the chosen rung's retention has been exceeded for the requested window, the response carries resolutionRequested to indicate which rung was promoted to.

Exported types: EquityChartStream, PnlChartStream, EquityHistoryResponse, PnlHistoryResponse, EquityPoint, PnlPoint, EquityChartUpdate, PnlChartUpdate, Resolution.

const chart = await arca.watchEquityChart({
  path: '/users/alice/',
  from: oneDayAgoIso,
  to: nowIso,
  points: 500,
});
chart.onUpdate(({ response }) => {
  for (const p of response.points) {
    // p.status: 'sealed' | 'open' | 'carried' | 'incomplete'
    // p.equityUsd: string
  }
});

Operation wait recovery

waitForOperation listens before acquiring its subscription. Startup and actual stream gaps, reauthentication, or sparse operation notifications request a fresh, correlated acknowledgement before reading the operation. A failed acknowledgement or read gets at most three attempts per recovery; a healthy pending operation stays on the stream without periodic reads. A terminal push can complete during acknowledgement or snapshot recovery. Timeout stops the wait and preserves the original operation identity; it never submits a replacement operation.

Terminal operations in the initial or buffered subscription snapshot resolve the wait before any HTTP read, including typed failed/expired results. Socket rotation requests fresh operation evidence on the replacement connection; its pong only establishes transport readiness. Stale snapshot request IDs and unrelated operation IDs cannot settle the wait. Verified snapshot operations are shared with all live waiters, including results buffered while another caller refreshes the same root watch; each waiter still accepts only its original operation ID.

Wallet execution candidate (2026-09-30)

Wallet action proposals, verified provider wallets and deposit links express intent and owner consent to Arca. Arca owns execution, source reservations, gas/nonce management and settlement; a builder does not run a sweep worker. The additive wallet accounting envelope includes canonical source, Cash, trading and in-transit money at one committed position. Preserve null amounts and completeness/freshness; custody-only totals retains its earlier meaning.

Go exposes StreamFundingV9WalletsWithTransport; TypeScript exposes streamFundingV9Wallets. Both use bounded buffering and await the consumer before acknowledging a position. Heartbeats indicate connection health only. Reconnect from the last durably applied position, retaining prior coherent money as stale across incomplete/error frames. Wallet mutations are single-send; resolve uncertain outcomes using the original operation/request identity. Deposit links accept optional maxCashMicro and maxDepositMicro product caps; admission preserves partial deposits and leaves the remainder at source. This source has not yet been published; no deployed-wallet parity is implied.