Skip to main content

Getting Started

This guide walks through a first integration with Senticore.

Closed beta access

The private-beta API is live for approved accounts at https://api.sentico-labs.xyz. Public market, time, status, and readiness reads need no credential. Writes require approved access, wallet/agent authorization, and funded collateral. No broader-access date is implied by this guide.

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.

Wallet onboarding in the web app​

Connecting the wallet is enough to detect an existing engine account and load portfolio, balances, orders, and private account state. Those reads do not depend on a separate Start Trading click.

If the wallet has an engine account but no valid local trading session, the app shows a wallet-scoped Sign to start flawless trading prompt. One owner signature creates the delegated browser agent and private-read session. A new, unfunded wallet instead sees Deposit to start with a link to the portfolio. The completed or dismissed prompt is cached per wallet and may appear again after cache clearing or a terminal session revocation.

Private-read token issuance is independently rate-limited. The current web app coalesces concurrent requests for the same wallet and retries a 429 according to Retry-After; a temporary 429 does not require another wallet signature, another deposit, or another Start Trading action. A terminal FORBIDDEN with agent revoked invalidates that wallet's cached session and requires one fresh owner authorization.

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: 3,
    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​

Custody withdrawals are a two-step authorization:

  1. Submit a wallet-signed WithdrawRequest for USDC or WithdrawAssetRequest for another registered asset.
  2. After the engine accepts it, call the on-chain MultiCollateralVault.requestWithdraw with the exact same asset, native-unit amount, recipient, and nonce.

Persist the accepted request before prompting for the on-chain transaction. If the wallet rejects that prompt or the page reloads, retry step 2 with the same accepted request; do not submit a second engine debit.

Acceptance is not final execution. The request becomes executable only after the relevant batch is included in a committed checkpoint and its proof is available. Show this pending state instead of asking the user to start over.

Pending for an hour can be normal: execution waits for the challenge window, the next successful hourly checkpoint, proof availability, and the executor. Persist and poll the original request id. Never submit a second engine debit or a replacement vault request merely because the first request is pending.

Amounts are asset-native on the withdrawal path. For example, 15 CKT at 18 decimals is 15000000000000000000; USDC uses 6 decimals and therefore a different scale.

POST /api/v1/funding/withdrawals is a legacy strategy-vault share-withdrawal alias. It is not the custody-withdrawal entry point.

Next steps​

Last updated on