Your first trade

This tutorial covers the full flow: connect a client, fund an account, subscribe to market data, and place an order. Create an account in the panel below and the code examples on this page will use it.

Everything here runs on the Preview testnet. The ephemeral and seed-phrase styles generate throwaway keys in your browser; do not reuse them on mainnet. Python examples need pip install sugar-rush-sdk (SDK) or pip install websockets pycardano (raw).

1. Choose how you sign in

The client authenticates with an Identity: an object with an accountId (the hex payment credential of your key) and a signData function that produces CIP-8 signatures. Any Cardano key can back one. Both SDKs ship the same adapters (Python names in parentheses):

• Ephemeral key — ephemeralKey() (ephemeral_key()) generates a throwaway key. Save the exported key to keep the same account next time.
• Seed phrase — mnemonic(words).cardano() derives the standard CIP-1852 account (m/1852'/1815'/0'/0/0), the same key Lace and Eternl control.
• Browser wallet — cip30(api) signs through a CIP-30 extension; the key stays in the extension. Browser-only — in Python use a key file (load_skey) or seed phrase instead.

Connect a client with the style you chose:

import { createClient, ephemeralKey } from "@sugar-rush/sdk";

// A throwaway key, generated in the browser. Persist it to keep the same
// account next time. Testnet only; do not reuse it on mainnet.
const identity = await ephemeralKey(localStorage.getItem("sr-key") ?? undefined);
localStorage.setItem("sr-key", identity.export());

const client = createClient({ wsUrl: "wss://api.sugar.rush.preview.sundae.fi/ws", identity });
await client.connect();

console.log(client.welcome());   // the server's welcome frame

2. Fund your account

You need testnet ADA to trade. deposit builds one L1 Cardano transaction. It locks ADA at the head and credits your L2 account, along with a starter basket of testnet tokens. The deposit absorbs in about 5 minutes.

await client.deposit({
  amountAda: 15,
  blockfrostProjectId: "preview…",   // Node; in the browser your wallet signs it
});

To trade with a session key instead of your wallet key, deposit from your wallet and delegate to an ephemeral key. See Deposits & withdrawals.

3. Watch the book

await client.subscribe({ orderbook: ["DARK-VAN"], ticker: ["DARK-VAN"] });

client.on("orderbook", ({ symbol, book }) => {
  console.log(symbol, book.bids[0]?.price, "/", book.asks[0]?.price);
});
const book = client.orderBook("DARK-VAN");   // materialized, synchronous

4. Place an order

const ack = await client.createOrder({
  symbol: "DARK-VAN", side: "buy", type: "limit",
  price: "2.15", size: "1000", timeInForce: "GTC",
});
console.log("submitted:", ack.requestId);

5. See your fill

client.on("order", (order) => {
  console.log(order.id, order.status.tag, "remaining", order.remaining);
});
const mine = client.openOrders("DARK-VAN");

Done trading? Cancel what's left:

await client.cancelAllOrders();
console.log("open orders:", client.openOrders().length);

From here, the guides cover each area in more detail, and the reference has the full protocol contract.