Skip to main content

Getting Started

This guide walks through a first integration with Senticore.

Closed beta access

The 0.1.3 private beta API is live for whitelisted accounts at https://api.sentico-labs.xyz. Public mainnet is not live yet, and access remains capped before the broader Q3 2026 closed beta.

Prerequisites​

  • A Web3 wallet such as MetaMask, Rabby, Frame, or WalletConnect.
  • Whitelisted beta access or delegated API-agent credentials for private endpoints.
  • Capped beta collateral for mutating trading and withdrawal flows.

1. Install the TypeScript SDK​

The TypeScript SDK is publicly available on npm. Python and Rust SDKs are maintained as repository previews until their public registry releases are completed.

npm install @sentico-labs/sdk

See SDKs for the Python and Rust preview paths.

2. Initialize a client​

import { SenticoreClient, signAction, type LocalActionPayload } from "@sentico-labs/sdk";

const client = new SenticoreClient({
  publicHttpBaseUrl: "https://api.sentico-labs.xyz",
  tradingHttpBaseUrl: "https://api.sentico-labs.xyz",
  orderEntryHttpBaseUrl: "https://api.sentico-labs.xyz",
  publicWsUrl: "wss://api.sentico-labs.xyz/api/v1/ws/public",
  privateWsUrl: "wss://api.sentico-labs.xyz/api/v1/ws/private/{account}",
  bearerToken: process.env.SENTICORE_BEARER_TOKEN,
});

3. Browse markets​

const markets = await client.public.listMarkets();
const tickers = await client.public.listTickers();

console.log(markets.data, tickers.data);

4. Place your first order​

Wallet-native trading should use local action signing in the hot path. Build the canonical local payload, sign it with the wallet key or delegated signer, and submit the signed action directly:

const account = "0x1111111111111111111111111111111111111111" as const;

const payload: LocalActionPayload = {
  account,
  nonce: 4810,
  ts: Date.now(),
  action: {
    kind: "SpotPlaceOrder",
    market: 7,
    side: "Bid",
    price: 998400,
    qty: 1000,
    timeInForce: "post_only"
  }
};

const chainBinding = (await client.orderEntry.getActionChainBinding()).data;
const signedAction = signAction(payload, process.env.SENTICORE_PRIVATE_KEY!, {
  chainBinding,
});
const accepted = await client.trading.submitSignedAction(signedAction, {
  idempotencyKey: `client-order-${payload.nonce}`
});

console.log(accepted.data);

Nonce rule for locally signed actions (windowed replay protection):

  1. nonce may be any unused value in the open window [nonceFloor, nonceFloor + nonceWindow) (currently nonceWindow = 256). Gaps and out-of-order submission are allowed - you can pipeline many nonces at once without waiting for acks or reserving a range.
  2. On a nonce reject, read nonceFloor / nonceWindow from the response and choose a fresh unused in-window nonce: nonce_below_floor -> permanently stale (pick a new one), nonce_outside_window -> retry after the floor advances, nonce_replayed -> that nonce is taken (pick another). nextUsableNonce (= nonceFloor) is a convenience hint.
  3. Reservations are deprecated and no longer required - omit nonceReservationId (absent or null). Production signing uses the v2 chain-bound domain.

Because gaps and out-of-order nonces are allowed, one account can keep up to 256 orders in flight at once without waiting for acks. See Order Concurrency & Nonces for the full pipelining model and recovery rules - essential reading for market makers and HFT clients.

POST /api/v1/trading/actions/hash remains available as a debugging/reference round trip, but latency-sensitive clients should use Local Action Signing. Use Raw Signed Actions for exact low-level API payloads. Delegated API agents can use /api/v1/trading/orders and /api/v1/trading/orders/batch.

5. Listen for fills​

const token = await client.trading.issuePrivateWsToken(account, { ttlMs: 60_000 });
const socket = client.ws.connectPrivate(account, token.data.token, (frame) => {
  console.log(frame);
});

6. Withdraw​

Withdrawals are not instant ledger reads. The request is accepted first, then it becomes executable after the relevant batch is included in a committed checkpoint and the proof is available. The frontend should show the pending withdrawal state instead of asking the user to retry immediately.

Next steps​

Last updated on