TypeScript SDK

The Monaco SDK requires a Viem wallet client and network configuration. This page covers installation, SDK initialization, configuration options, and best practices.

Installation

npm install @0xmonaco/core @0xmonaco/types

pnpm add @0xmonaco/core @0xmonaco/types

yarn add @0xmonaco/core @0xmonaco/types

Basic Initialization

Monaco needs a Viem walletClient configured for Sei testnet during private alpha. You can create that client from an injected browser wallet, WalletConnect, a local private key, or any other Viem-supported wallet setup. Monaco will support mainnet wallet clients when mainnet access opens. See the Viem Wallet Client docs for the full set of options.

import { MonacoSDK } from "@0xmonaco/core";
import { createWalletClient, custom } from "viem";
import { seiTestnet } from "viem/chains";

const walletClient = createWalletClient({
  chain: seiTestnet,
  transport: custom(window.ethereum!)
});

await walletClient.requestAddresses();

const sdk = new MonacoSDK({
  walletClient,
  network: "staging",
  seiRpcUrl: "https://evm-rpc-testnet.sei-apis.com", // Required: Your Sei RPC endpoint
});

import { MonacoSDK } from "@0xmonaco/core";
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { seiTestnet } from "viem/chains";

const account = privateKeyToAccount("0x...");
const walletClient = createWalletClient({
  account,
  chain: seiTestnet,
  transport: http()
});

// Initialize SDK
const sdk = new MonacoSDK({
  walletClient,
  network: "staging",
  seiRpcUrl: "https://evm-rpc-testnet.sei-apis.com", // Required: Your Sei RPC endpoint
});

Configuration Options

WalletClient

required

Viem wallet client for signing transactions and messages. Must be configured with a valid account and chain.

string

required

Required (v0.4.0+): Sei blockchain RPC endpoint URL. Each application should configure their own RPC provider to avoid rate limits. For testnet/staging, use https://evm-rpc-testnet.sei-apis.com. For production, use a dedicated RPC provider like Ankr, GetBlock, or AllThatNode.

Network

required

For public usage, set this to "staging" or "mainnet". Selects the chain ("staging" uses Sei testnet; "mainnet" uses Sei mainnet) and the default API and WebSocket URLs. The SDK type also supports internal presets, but public docs intentionally cover only public endpoints.

number

Optional. Poll interval, in milliseconds, for the SDK’s internal viem public client when it waits on transaction receipts. Defaults to 750ms (viem’s own default is 4000ms), so sdk.vault.deposit and sdk.waitForTransaction resolve within about one to two Sei blocks. Must be a positive finite number, otherwise the SDK throws InvalidConfigError on construction. Set it to 4000 to restore the previous cadence.

RequestSigning

Optional. Which protocol signs authenticated REST requests: "legacy" (the default) sends the X-Monaco-* headers, "rfc9421" sends RFC 9421 HTTP message signatures. Both use the same session key, and WebSocket and gRPC authentication are unaffected either way. There is no automatic downgrade, so select "rfc9421" only against a gateway that verifies it. In RFC mode the SDK requires a string request body, disables redirect following on authenticated requests, and throws if the caller supplies a signature header itself. See HTTP message signatures.

Network Configurations

The SDK automatically configures API and WebSocket endpoints based on the network parameter:

Staging (Testnet)

const sdk = new MonacoSDK({
  walletClient,
  network: "staging",
  seiRpcUrl: "https://evm-rpc-testnet.sei-apis.com",
});

Chain: Sei Atlantic-2 testnet
Chain ID: 1328
API: Staging API Gateway
WebSocket: Auto-resolved from network

RPC Provider Options

seiRpcUrl points the SDK at Sei for on-chain reads and transaction confirmation. During private alpha, use the Sei testnet RPC. In production code, source seiRpcUrl from an environment variable rather than hardcoding it.

SDK Instance Properties

Once initialized, the SDK exposes these APIs:

const sdk = new MonacoSDK({
  walletClient,
  network: "staging",
  seiRpcUrl: "https://evm-rpc-testnet.sei-apis.com",
});

// API instances
sdk.auth           // Authentication operations
sdk.applications   // Application config
sdk.fees           // Fee simulation and queries
sdk.vault          // Vault operations (deposits/withdrawals)
sdk.trading        // Trading operations (orders)
sdk.market         // Market data queries
sdk.profile        // User profile and account info
sdk.trades         // Trade history queries
sdk.orderbook      // Orderbook snapshots
sdk.withdrawals    // Low-level withdrawal calldata (no broadcast)
sdk.subAccounts    // Master-account sub-accounts and spending limits
sdk.faucet         // Testnet token faucet

// WebSocket client (v0.5.0+)
sdk.ws             // Unified WebSocket client (auto-connects on init)
sdk.ws.orders()    // Subscribe to order events (requires auth)
sdk.ws.orderbook() // Subscribe to orderbook updates
sdk.ws.ohlcv()     // Subscribe to candlestick data
sdk.ws.trades()    // Subscribe to trade events
sdk.ws.movements() // Subscribe to balance movements (requires auth)

// Blockchain clients
sdk.walletClient   // Viem wallet client
sdk.publicClient   // Viem public client

// Utility methods
sdk.isConnected()       // Check if wallet is connected
sdk.isAuthenticated()   // Check if user is logged in
sdk.getAccountAddress() // Get current wallet address
sdk.getNetwork()        // Get current network name
sdk.getChainId()        // Get current chain ID
sdk.waitForTransaction(hash) // Wait for tx confirmation
sdk.setServerKey(sk)    // Set the application secret key for backend auth

SDK Utility Methods

() => boolean

Check if the SDK has a valid wallet connection

() => boolean

Check if the user has a valid authentication session

() => string

Get the current wallet address. Throws InvalidStateError if no account is connected.Error Handling:

import { InvalidStateError } from "@0xmonaco/core";

try {
  const address = sdk.getAccountAddress();
  console.log("Wallet address:", address);
} catch (error) {
  if (error instanceof InvalidStateError) {
    console.error("No wallet connected");
    // Prompt user to connect wallet
  } else {
    throw error;
  }
}

Best Practice: Use isConnected() before calling:

if (sdk.isConnected()) {
  const address = sdk.getAccountAddress();
} else {
  console.warn("No wallet connected");
}

() => Network

Get the current network name, for example 'staging'

(serverKey: string | undefined) => void

Set the application secret key (sk_...) used for backend-authenticated requests. The key is fanned out to every sub-API in one call and sent in the x-server-key header on those requests. There is no token exchange. Pass undefined to clear it.Server-key auth is independent of sdk.login() / session auth; a client may hold both a session and a server key at the same time.

sdk.setServerKey("sk_live_...");

() => number

Get the current blockchain chain ID (1328 for testnet)

(hash: string, confirmations?: number, timeout?: number) => Promise<TransactionReceipt>

Wait for a transaction to be confirmed on-chainParameters:

hash: Transaction hash to wait for
confirmations?: Number of confirmations required (optional)
timeout?: Timeout in milliseconds (optional)

Returns: Viem TransactionReceipt

Learn

Build

Libraries

APIs

Resources

Installation

Basic Initialization

Configuration Options

Network Configurations

RPC Provider Options

SDK Instance Properties

SDK Utility Methods

​Installation

​Basic Initialization

​Configuration Options

​Network Configurations

​RPC Provider Options

​SDK Instance Properties

​SDK Utility Methods

Installation

Basic Initialization

Configuration Options

Network Configurations

RPC Provider Options

SDK Instance Properties

SDK Utility Methods