Wallets & Auth

Monaco integrations start with a Sei wallet and Monaco asset IDs. The wallet signs authentication challenges and on-chain settlement transactions. Asset IDs identify the tokens Monaco tracks across balances, vault operations, trading pairs, and account history. During private alpha, connect wallets to Sei testnet atlantic-2. Mainnet integrations will use the same pattern on Sei mainnet.

Surface Map

Surface	Use
REST	`POST /api/v1/auth/challenge`, `POST /api/v1/auth/verify`, `POST /api/v1/auth/refresh`, `POST /api/v1/auth/revoke`
TypeScript SDK	`sdk.login()`, `sdk.logout()`, `sdk.refreshAuth()`, `sdk.auth.*`, `sdk.setAuthState()`
React SDK	`useAuth()`, `useMonacoSDK()`
WebSocket	Session-key `Authenticate` message for account channels
gRPC	`AuthService`

Trading inside Monaco is gasless, but deposits and withdrawals are on-chain wallet transactions. Users still need SEI gas for those settlement actions.

Who Needs What

Traders

Connect a Sei-compatible wallet, fund it with test SEI for gas, request Monaco test assets, then deposit funds before trading.

Builders

Pass a Viem walletClient into Monaco SDKs, authenticate with sdk.login(clientId), and keep wallet, spot, and perps balances distinct in your UI.

Market Makers

Use the owner wallet for custody. Use delegated agents when a separate bot wallet should trade without withdrawal rights.

Sei Testnet Prerequisites

Monaco staging settles deposits and withdrawals on Sei testnet, so the connected wallet must be on atlantic-2.

Connect a Sei wallet

Use a Sei-compatible wallet that supports Sei EVM testnet.

Fund gas

Get test SEI from the Sei testnet faucet. Users only need SEI gas for deposits and withdrawals.

Use the staging RPC

Start with https://evm-rpc-testnet.sei-apis.com, then move to a provider-backed RPC URL before heavier usage.

Request Monaco test assets

Use the testnet faucet after wallet authentication when the user needs test assets for deposits, balances, spot orders, or perps collateral.

Browser Wallet

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

const [account] = await window.ethereum.request({
  method: "eth_requestAccounts",
});

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

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

Supported Wallet Sources

Injected Wallets

Use MetaMask, Rabby, Backpack, or another injected EVM-compatible wallet through window.ethereum.

WalletConnect

Use a WalletConnect transport when your app needs mobile wallet or QR-code connection flows.

Server Wallets

Backend services can create a Viem wallet client from a private key when they own the signing key.

See the Viem Wallet Client docs for the full set of wallet-client options.

Authentication Sessions

Wallet connection and Monaco authentication are separate. The wallet client identifies the account and signs a one-time Monaco challenge. sdk.login(clientId) generates an ed25519 session keypair locally, asks the wallet to authorize the session public key, and then signs authenticated REST and WebSocket requests with the session private key. The session is scoped to the wallet address and application clientId. Treat sessionPrivateKey as a credential: keep it client-side, persist it only in secure storage, check expiresAt before restoring a saved session, and call sdk.logout() when the user disconnects.

To access Monaco programmatically — via the TypeScript SDK, REST API, gRPC, or MCP server — use 688a21440e304c06b935f743dae88278 as your clientId. This is the public testnet client ID available to all builders.

const authState = await sdk.login("688a21440e304c06b935f743dae88278");

// Restore a valid persisted session later without another wallet prompt.
sdk.setAuthState(authState);

await sdk.refreshAuth();
await sdk.logout();

There is no backend secret key: the application reporting endpoints are public and select the application by its clientId (see Applications). User trading, deposits, withdrawals, and account routes use wallet-authorized sessions.

Asset IDs

Asset IDs are Monaco UUIDs. They are the primary identifiers for vault and balance operations:

Operation	Identifier
`sdk.vault.approve()`	`assetId`
`sdk.vault.needsApproval()`	`assetId`
`sdk.vault.deposit()`	`assetId`
`sdk.vault.withdraw()`	`assetId`
`sdk.vault.getAllowance()`	`assetId`
`sdk.profile.getUserBalanceByAssetId()`	`assetId`

Monaco intentionally uses asset UUIDs for vault and balance APIs. Treat symbols as display labels, not identifiers.

Where Asset IDs Come From

Trading pairs are the most reliable way to discover asset IDs before a user has a balance:

const pair = await sdk.market.getTradingPairBySymbol("BTC/USDC");

const baseAssetId = pair.baseAssetId;   // BTC asset ID
const quoteAssetId = pair.quoteAssetId; // USDC asset ID

Balances include asset IDs for assets the user already holds:

const { balances } = await sdk.profile.getUserBalances();

const usdc = balances.find((balance) => balance.symbol === "USDC");
console.log(usdc.assetId);

Asset IDs vs Token Contracts

Asset IDs identify the Monaco asset. Token contracts identify the on-chain ERC20 token.

Field	Meaning	Common use
`assetId`	Monaco UUID for the asset	Vault methods, balances, movements
`token`	ERC20 contract address in balance rows	Wallet display, explorer links
`baseTokenContract`	Base asset contract from a trading pair	Wallet UI, approvals, token metadata
`quoteTokenContract`	Quote asset contract from a trading pair	Wallet UI, approvals, token metadata
`symbol`	Human-readable token label	Display only
`decimals`	Token precision	`parseUnits`, `formatUnits`, input validation

Vault Balances

Balance rows tell you what the user can currently use:

const { balances } = await sdk.profile.getUserBalances();

for (const balance of balances) {
  console.log({
    assetId: balance.assetId,
    symbol: balance.symbol,
    available: balance.availableBalance,
    locked: balance.lockedBalance,
    total: balance.totalBalance,
  });
}

Use availableBalance for order entry and withdrawals. Use lockedBalance to explain funds reserved by open orders or pending operations. Use total balance for portfolio display, not for spendable checks.

Builder Guidance

Store and pass asset UUIDs for balance and vault operations.
Use contract addresses when showing token explorer links or wallet metadata.
Always format values with the asset’s decimals.
Refresh balances after fills, cancels, deposits, withdrawals, funding, liquidations, and collateral movements.

Next Steps

Use TypeScript authentication or React useAuth to create an authenticated Monaco session.
Use Account Balances to read available, locked, total balances, and movements.
Use Vault Deposits & Withdrawals to deposit and withdraw assets.
Use Perps Collateral to fund parent margin accounts and risk buckets.
Use Markets to resolve pair IDs, product support, and public market data.

Learn

Build

Libraries

APIs

Resources

Surface Map

Who Needs What

Traders

Builders

Market Makers

Sei Testnet Prerequisites

Browser Wallet

Supported Wallet Sources

Injected Wallets

WalletConnect

Server Wallets

Authentication Sessions

Asset IDs

Where Asset IDs Come From

Asset IDs vs Token Contracts

Vault Balances

Builder Guidance

Next Steps

​Surface Map

​Who Needs What

Traders

Builders

Market Makers

​Sei Testnet Prerequisites

​Browser Wallet

​Supported Wallet Sources

Injected Wallets

WalletConnect

Server Wallets

​Authentication Sessions

​Asset IDs

​Where Asset IDs Come From

​Asset IDs vs Token Contracts

​Vault Balances

​Builder Guidance

​Next Steps

Surface Map

Who Needs What

Sei Testnet Prerequisites

Browser Wallet

Supported Wallet Sources

Authentication Sessions

Asset IDs

Where Asset IDs Come From

Asset IDs vs Token Contracts

Vault Balances

Builder Guidance

Next Steps