npm install @arca/sdk

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

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

// API Key — for backend services, scripts, CI
const arca = new Arca({
  apiKey: 'arca_78ae7276_...',
  realm: 'development',       // slug or UUID
  baseUrl: 'http://localhost:8080', // 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();

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

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

// The builder's backend mints this token and passes it to the frontend
const arca = Arca.fromToken(scopedJwt);

// The realm is extracted from the token claims automatically
await arca.ready();

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

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

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

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

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

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

const balances: ArcaBalance[] = await arca.getBalances(obj.id);
// [{ id: '...', arcaId: '...', denomination: 'USD', amount: '1000.00' }]

// Simple deletion (no balance)
const { object, operation } = await arca.ensureDeleted({
  ref: '/wallets/old',
});

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

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

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

console.log(operation.state); // 'completed' for denominated→denominated
console.log(operation.outcome); // JSON with new balances

const { operation } = await arca.deposit({
  arcaRef: '/wallets/main',
  amount: '1000.00',
  durationSeconds: 5,   // default: 5
  willSucceed: true,     // default: true
});

// operation.state === 'pending' (settlement happens asynchronously)
// Listen for deposit.completed event via events.subscribe()

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 { operations, total } = await arca.listOperations({
  type: 'transfer', // optional filter
});

// Default separator (hyphen)
const { nonce, path } = await arca.nonce('/op/transfer/fund');
// { nonce: 1, path: '/op/transfer/fund-1' }

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

// Use the reserved path as the idempotency key
await arca.transfer({ path, from: '/wallets/alice', to: '/wallets/bob', amount: '100' });

// GOOD — reserve once, store, reuse on retry
const { path } = await arca.nonce('/op/transfer/fund');
// persist `path` in your application state if needed
await arca.transfer({ path, from: '/wallets/a', to: '/wallets/b', amount: '100' });

// BAD — new nonce on every call defeats idempotency
await arca.transfer({
  path: (await arca.nonce('/op/transfer/fund')).path, // different path every time!
  from: '/wallets/a',
  to: '/wallets/b',
  amount: '100',
});

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

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

const state: ExchangeState = await arca.getExchangeState(objectId);
console.log(state.account.usdBalance);
console.log(state.marginSummary.accountValue);
console.log(state.positions);   // SimPosition[]
console.log(state.openOrders);  // SimOrder[]

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

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

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

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

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

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

// Market metadata (supported assets, max leverage, etc.)
const meta: SimMetaResponse = await arca.getMarketMeta();
// { universe: [{ name: 'BTC', maxLeverage: 50, ... }, ...] }

// Current mid prices
const mids: SimMidsResponse = await arca.getMarketMids();
// { mids: { 'BTC': '98234.50', 'ETH': '2847.30', ... } }

// L2 order book
const book: SimBookResponse = await arca.getOrderBook('BTC');
// { coin: 'BTC', bids: [...], asks: [...], time: 1234567890 }

// Subscribe to all events
const sub = arca.events.subscribe((event: RealmEvent) => {
  console.log(event.type, event.entityId, event.entityPath);
});

// Subscribe with prefix filter (client-side)
const sub = arca.events.subscribe(
  { prefix: '/op/' },
  (event) => {
    console.log('Operation event:', event.type);
  },
);

// Close the subscription when done
sub.close();

interface RealmEvent {
  realmId: string;
  type: string;       // e.g. 'deposit.completed'
  entityId: string;   // ID of the affected entity
  entityPath: string; // path of the affected entity
}

import { Arca, ValidationError, NotFoundError, ConflictError } from '@arca/sdk';

try {
  await arca.transfer({
    path: '/op/transfer/fund-1',
    from: '/wallets/alice',
    to: '/wallets/bob',
    amount: '250.00',
  });
} catch (err) {
  if (err instanceof ValidationError) {
    console.error('Invalid input:', err.message);
    // e.g., insufficient balance, denomination mismatch
  } else if (err instanceof NotFoundError) {
    console.error('Object not found:', err.message);
  } else if (err instanceof ConflictError) {
    console.error('Conflict:', err.message);
    // e.g., duplicate resource, object being deleted
  } else {
    throw err; // unexpected
  }
}

class ArcaError extends Error {
  public readonly code: string;   // machine-readable code
  public readonly message: string; // human-readable description
}

const admin = new ArcaAdmin({ token });
const org = await admin.getOrg();
console.log(org.name, org.slug);

const { members, total } = await admin.listMembers();
for (const m of members) {
  console.log(m.email, m.role, m.realmTypeScope);
}

const invitation = await admin.inviteMember({
  email: 'alice@example.com',
  role: 'developer',
  realmTypeScope: ['development', 'staging'],
});
console.log(invitation.inviteLink);

await admin.updateMember('member-id', {
  role: 'admin',
  realmTypeScope: null, // null = all realm types
});

await admin.removeMember('member-id');

await admin.transferOwnership('new-owner-user-id');