Developer Preview

What to expect

What's available

• REST API — Full access to all current endpoints for objects, operations, transfers, deposits, and exchange integration.
• TypeScript SDK (@arca/sdk) — Type-safe client for Node.js and browser environments.
• CLI — Command-line tool for scripting and interactive use.
• Portal — Web dashboard for managing realms, exploring objects, and monitoring operations.
• Real-time streaming — SSE event streams for live operation and balance updates.

What's not available yet

• Production realms and real-money settlement
• Webhooks
• Named IAM policies and teams

Feedback

Your feedback shapes the platform. If you encounter issues, have feature requests, or want to share what you're building, reach out to us directly.

Arca Platform Documentation

Arca is the infrastructure layer for building financial applications. It provides a unified ledger, deterministic state management, and full explainability for every balance change — so you can build trading, payments, and portfolio products without stitching together disparate systems.

Arca exposes three equally supported interfaces. Pick whichever fits your workflow — or combine them:

Core Concepts

Builders

A Builder represents your organization. Each builder has an email, password (bcrypt-hashed), and organization name. Builders authenticate via JWT tokens to manage their resources through the portal or API.

Realms

Realms are isolated environments that scope all Arca data — objects, operations, events, and API keys. There are two types:

Each realm gets a unique slug derived from its name (e.g., development, live-trading). Slugs are unique per builder.

API Keys

API keys provide programmatic access to Arca, scoped to a specific builder and realm. They are the authentication mechanism for SDKs and backend services (as opposed to JWT tokens, which are for portal/interactive use).

Key anatomy:

arca_<prefix>_<secret>
     ^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     visible   only shown once; Arca stores SHA-256 hash

The prefix is always visible (used for identification in the portal and logs). The full key is shown only at creation time.

Arca Objects

An Arca Object is a stateful entity on the ledger. Objects are addressed by hierarchical paths (e.g., /treasury/usd-reserve) and scoped to a realm. Each object has a type that determines its behavior:

Creating an Arca object atomically produces both the object record and a create operation, ensuring every state change is tracked from inception.

System-Owned Objects

Each realm contains platform-managed objects under the /_system/ and /_builder/ path prefixes. These objects absorb fees and reconciliation adjustments so that the conservation equation holds exactly for every operation (no value leaks). System objects are visible in queries and the Explorer but cannot be created, modified, or deleted by builders. They are marked with a System badge in the portal.

The default system objects are:

• /_system/fees/exchange — venue fees (~4.5 bps on fills)
• /_system/fees/platform — Arca platform fee (1 bp on fills)
• /_builder/fees — builder fees (configurable bps, builder can transfer out)

Adjustment objects (/_system/adjustments/{venue}) are created when reconciliation detects drift between expected and venue-reported balances. System objects may hold negative balances.

Object Lifecycle & Deletion

Arca objects follow a status lifecycle: active → deleting → deleted. An active object can be deleted via the delete endpoint. The delete is executed by a Temporal workflow that guarantees completion even if the service restarts mid-flight:

1. Pre-flight check: A unified deletion readiness check verifies all value sources (settled balances, reserved holds, and exchange state). If in-flight operations exist (outbound or inbound holds), the delete is rejected immediately.
2. Activity 1 — Acquire Lock: Sets status to deleting and creates a pending delete operation. All other operations on this object are immediately blocked.
3. Activity 2 — Liquidate (exchange only): If the object is an exchange type with open positions and liquidatePositions is set, all positions are closed via market order.
4. Activity 3 — Withdraw (exchange only): Withdraws all available funds from the exchange account to the platform balance, making them available for the sweep step.
5. Activity 4 — Finalize: If a sweepToPath was provided, remaining funds are transferred to the target. A deletedAt timestamp is set and the status becomes deleted. The operation completes.

The workflow has a 5-minute timeout. If any step fails, the object reverts to active status and the operation is marked as failed.

Using the object ID as the Temporal workflow ID provides natural deduplication — calling delete on an object that is already being deleted reattaches to the existing workflow rather than starting a new one.

The object's path never changes — the deletedAt timestamp is part of the database unique key, so once an object is deleted, a new Arca object can be created at the same path. Previous versions can be viewed via the /versions endpoint. All historical operations, events, and state deltas remain correlated to the same path.

Operations

Operations represent intent — a requested action against one or more Arca objects. Each operation has a type (e.g., transfer, deposit, swap) and transitions through states: pending → completed or failed. Operations form the backbone of the correlation spine: every event and state delta can be traced back to the operation that caused it. Each operation records who initiated it via actorType (one of builder, api_key, scoped_token, or system) and actorId, providing a full audit trail.

Events

Events are immutable records of discrete occurrences within operations. Every state-mutating operation produces at least one event (e.g., object.created, transfer.completed, deposit.completed). State deltas attach exclusively to events. Events can be streamed in real time via SSE.

State Deltas

A State Delta captures the before/after value of a single field change on an Arca object. Delta types include balance_change, settlement_change, position_change, status_change, hold_change, creation, and deletion. Deltas are linked to the event that produced them (via eventId). The originating operation is reachable through the event's operationId, enabling full explainability of every state change.

Arca Balances

Balances represent the current quantity held by a denominated Arca object in a given denomination. They are updated as deposits, withdrawals, and transfers settle. You can query balances per object or see them included in the object detail view.

Path Organization

Object paths are not just identifiers — they are your aggregation structure. The aggregation API sums balances for all objects sharing a path prefix, so the way you organize paths directly determines what rollups are possible.

Principle: Group What You Want to Aggregate

When you create multiple entities of the same kind, place them under a shared prefix. This lets you query aggregate balances across the entire group with a single API call.

Common Patterns

How Aggregation Works

Call GET /api/v1/objects/aggregate?prefix=/users/ to get the total equity, spot balances, and exchange positions across every object whose path starts with /users/. A single standalone account at the root (e.g., /main) is fine — grouping matters when you have collections of similar entities.

There are no explicit “directories” to create. Folders are inferred from path segments automatically — the Browse endpoint and the Explorer UI display them as a navigable tree.

Authentication

Arca supports two authentication mechanisms, each designed for a different context:

JWT Tokens (Interactive Use)

JWT tokens are issued when a builder signs in. They are used for portal access and direct API calls. Include the token in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Tokens contain the builderId and email claims, and expire after the configured TTL (default: 24 hours).

API Keys (Programmatic Use)

API keys are used by SDKs, backend services, and CI pipelines. They are team-scoped (work across all realms) and authenticated via the Authorization: Bearer header using the raw key:

Authorization: Bearer arca_78ae7276_178e3df83d9...

The server identifies the key by computing its SHA-256 hash and looking it up in the database. Only active (non-revoked) keys are accepted.

Quick Start: API

Get up and running with Arca in three steps using raw HTTP requests.

1. Create a Builder Account

A Builder is the primary identity in Arca — it represents your organization. Sign up with an email, password, and organization name.

curl -X POST http://localhost:8080/api/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@company.com",
    "password": "your-secure-password",
    "orgName": "Acme Trading"
  }'

The response includes a JWT token and your builder profile. Save the token — you'll use it for all subsequent requests.

2. Create a Realm

Realms are isolated environments for your data. Start with a demo realm for testing.

curl -X POST http://localhost:8080/api/v1/realms \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Development",
    "type": "demo",
    "description": "My development environment"
  }'

3. Generate an API Key

API Keys are team-scoped and work across all of your realms. They are used for programmatic access (SDKs, backend services, CI). The raw key is shown only once.

curl -X POST http://localhost:8080/api/v1/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend Service"
  }'

Quick Start: TypeScript SDK

Get up and running with the @arca/sdk package. This guide assumes you already have a builder account, realm, and API key (see the API Quick Start above).

1. Install the SDK

npm install @arca/sdk

2. Initialize the Client

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

const arca = new Arca({
  apiKey: 'arca_78ae7276_...',
  realm: 'development',       // slug or UUID
  baseUrl: 'http://localhost:8080', // optional, defaults to https://api.arca.dev
});

// Resolve the realm slug to an ID
await arca.ready();

3. Create, Deposit, Transfer

// Create two wallets (idempotent by path)
await arca.createDenominatedArca({
  ref: '/wallets/main',
  denomination: 'USD',
});
await arca.createDenominatedArca({
  ref: '/wallets/savings',
  denomination: 'USD',
});

// Deposit funds (simulated in demo realms)
await arca.deposit({
  arcaRef: '/wallets/main',
  amount: '1000.00',
});

// Wait for simulated deposit settlement
await new Promise((r) => setTimeout(r, 6000));

// Transfer between wallets (atomic, idempotent by path)
await arca.transfer({
  path: '/op/transfer/fund-savings-1',
  from: '/wallets/main',
  to: '/wallets/savings',
  amount: '250.00',
});

// Check balances
const obj = await arca.getObject('/wallets/main');
const balances = await arca.getBalances(obj.id);
console.log(balances); // [{ denomination: 'USD', amount: '750.00', ... }]

Quick Start: CLI

Get up and running with the Arca CLI. Build the binary from source and work through the same onboarding flow.

1. Build & Authenticate

# Build the CLI
cd cli && go build -o arca .

# Create an account
./arca auth signup

# Configure a local profile
./arca config set local --api-base http://localhost:8080/api/v1
./arca config use local

2. Create a Realm & API Key

# Create a demo realm
arca realm create --name development --type demo

# Set it as the default realm for your profile
arca config set local --realm development

# Create an API key for programmatic use
arca api-key create --name "cli-test"

# Save the key in your profile (optional)
arca config set local --api-key <raw-key-from-output>

3. Create, Deposit, Transfer

# Create two wallets
arca object create --path /wallets/main --denomination USD
arca object create --path /wallets/savings --denomination USD

# Deposit funds (simulated — settles after ~5 seconds)
arca deposit --ref /wallets/main --amount 1000
sleep 6

# Transfer between wallets
arca transfer --path /op/transfer/fund-1 \
  --from /wallets/main \
  --to /wallets/savings \
  --amount 250

# Verify balances (use --output json for machine-parseable output)
arca object list --output json
arca object balances <main-object-id> --output json