Skip to main content

Getting Started

This guide walks through a first integration with Senticore.

Sandbox availability

This guide can also target the sandbox (launching — see Status) at https://api.sentico-sandbox.xyz once Status marks it available. Until then, do not assume the faucet or trading routes are live. The sandbox uses mock collateral and has no withdrawal path or chain.

Closed beta access to production

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.
  • In the sandbox: nothing else. The faucet creates and funds the account.
  • In production: whitelisted beta access or delegated API-agent credentials for private endpoints, and 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. Run the credential-free first read​

Download and unpack the self-contained quickstart archive. The example calls only the public markets endpoint and does not read wallet or API credentials:

cd senticore-quickstart
npm install
npm run public-read

This downloadable starter pins the published npm SDK (0.3.0). Repository SDK examples track the newer source version separately.

To build the same read into your application, 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);

listMarkets() returns the GET /api/v1/public/markets object: items[] plus featuredMarketId. Each item carries tickSizeMicro, lotSizeMicro, priceDecimals and instrumentConfig.minNotionalMicro; use them to align prices and quantities before signing.

4. Place your first funded order (optional)​

This step mutates a funded account. Skip it when validating connectivity. The downloadable submit-order.mjs requires an exact SENTICORE_LIVE_ORDER_CONFIRM value, reads fresh nonce state and chain binding, starts the reliable private stream before submitting, and submits exactly once. It never retries an ambiguous order.

SENTICORE_PUBLIC_HTTP_URL=https://api.sentico-labs.xyz \
SENTICORE_TRADING_HTTP_URL=https://api.sentico-labs.xyz \
SENTICORE_ORDER_ENTRY_HTTP_URL=https://api.sentico-labs.xyz \
SENTICORE_PUBLIC_WS_URL=wss://api.sentico-labs.xyz/api/v1/ws/public \
SENTICORE_PRIVATE_WS_URL=wss://api.sentico-labs.xyz/api/v1/ws/private/{account} \
SENTICORE_ACCOUNT=0x... \
SENTICORE_MARKET_ID=... \
SENTICORE_PRICE_MICROS=... \
SENTICORE_QTY_ATOMS=... \
SENTICORE_PRIVATE_KEY=... \
SENTICORE_BEARER_TOKEN=... \
SENTICORE_LIVE_ORDER_CONFIRM=I_UNDERSTAND_THIS_PLACES_A_FUNDED_ORDER \
npm run submit-order

These are the current production beta endpoints. The account must already be approved and funded, and the bearer token must have private-read access. Use the HMAC variables described in the archive README instead when that is how the account is provisioned. Do not substitute sandbox hosts unless Status confirms that environment is live.

Choose MARKET_ID, price and quantity from current public market metadata and your funded-account limits. Do not copy a sample market or nonce. The program prints an admission sequence first, then waits for a terminal orderUpdates event or the terminal receipt for that same sequence. A pending receipt means “keep reconciling”; it is not permission to sign or submit another action.

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 allocate up to 256 action nonces without waiting for acknowledgements. Account, market, risk and rate limits can impose lower practical order concurrency. 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, confirm terminal state, and recover​

Use the downloadable private-stream.mjs. It uses reliablePrivate, authenticates before subscribing, persists channel cursors in the managed stream, and subscribes to both orderUpdates and userFills. It is included with the pinned npm 0.3.0 quickstart archive; run npm run private-stream.

The token comes from POST /api/v1/ws/token and needs a credential with read scope (an agent key without it gets permission_denied). When you resume orderUpdates after a reconnect, send fromSeq as a decimal string together with cursorNamespace: "execution-v1"; see Private Channels. On resume_required, rebuild orders and fills from REST, then create a new stream from the returned recovery boundary. Never relabel an old cursor or resubmit the original signed action as a recovery mechanism.

6. Withdraw​

Production only

There is no withdrawal path in the sandbox. There is no vault, no deposit address, and no MultiCollateralVault to call. WithdrawRequest and WithdrawAssetRequest are rejected on every sandbox lane. Mock USDC is created by the faucet and cannot leave. Skip this section when working against api.sentico-sandbox.xyz.

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