> ## Documentation Index
> Fetch the complete documentation index at: https://docs.0xmonaco.com/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> @0xmonaco/core

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

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @0xmonaco/core @0xmonaco/types
  ```

  ```bash pnpm theme={null}
  pnpm add @0xmonaco/core @0xmonaco/types
  ```

  ```bash yarn theme={null}
  yarn add @0xmonaco/core @0xmonaco/types
  ```
</CodeGroup>

## 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](https://viem.sh/docs/clients/wallet) for the full set of options.

<CodeGroup>
  ```typescript Browser Wallet theme={null}
  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
  });
  ```

  ```typescript Local Account theme={null}
  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
  });
  ```
</CodeGroup>

## Configuration Options

<ParamField path="walletClient" type="WalletClient" required>
  Viem wallet client for signing transactions and messages. Must be configured with a valid account and chain.
</ParamField>

<ParamField path="seiRpcUrl" type="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.
</ParamField>

<ParamField path="network" type="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.
</ParamField>

<ParamField path="pollingInterval" type="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.
</ParamField>

<ParamField path="requestSigning" type="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](/reference/http-message-signatures).
</ParamField>

## Network Configurations

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

<Tabs>
  <Tab title="Staging (Testnet)">
    ```typescript theme={null}
    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`
  </Tab>
</Tabs>

## 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:

```typescript theme={null}
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
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 Utility Methods

<ResponseField name="isConnected" type="() => boolean">
  Check if the SDK has a valid wallet connection
</ResponseField>

<ResponseField name="isAuthenticated" type="() => boolean">
  Check if the user has a valid authentication session
</ResponseField>

<ResponseField name="getAccountAddress" type="() => string">
  Get the current wallet address. Throws `InvalidStateError` if no account is connected.

  **Error Handling:**

  ```typescript theme={null}
  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:

  ```typescript theme={null}
  if (sdk.isConnected()) {
    const address = sdk.getAccountAddress();
  } else {
    console.warn("No wallet connected");
  }
  ```
</ResponseField>

<ResponseField name="getNetwork" type="() => Network">
  Get the current network name, for example `'staging'`
</ResponseField>

<ResponseField name="getChainId" type="() => number">
  Get the current blockchain chain ID (1328 for testnet)
</ResponseField>

<ResponseField name="waitForTransaction" type="(hash: string, confirmations?: number, timeout?: number) => Promise<TransactionReceipt>">
  Wait for a transaction to be confirmed on-chain

  **Parameters:**

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

  **Returns:** Viem `TransactionReceipt`
</ResponseField>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.