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

# Wallets & Auth

> Connect Sei wallets, authenticate Monaco sessions, and manage wallet assets, asset IDs, token contracts, and supported balances.

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` |

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

## Who Needs What

<CardGroup cols={3}>
  <Card title="Traders" icon="wallet">
    Connect a Sei-compatible wallet, fund it with test SEI for gas, request Monaco test assets, then deposit funds before trading.
  </Card>

  <Card title="Builders" icon="code">
    Pass a Viem `walletClient` into Monaco SDKs, authenticate with `sdk.login(clientId)`, and keep wallet, spot, and perps balances distinct in your UI.
  </Card>

  <Card title="Market Makers" icon="chart-line">
    Use the owner wallet for custody. Use [delegated agents](/developers/delegated-agents) when a separate bot wallet should trade without withdrawal rights.
  </Card>
</CardGroup>

## Sei Testnet Prerequisites

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

<Steps>
  <Step title="Connect a Sei wallet">
    Use a [Sei-compatible wallet](https://docs.sei.io/learn/wallets) that supports Sei EVM testnet.
  </Step>

  <Step title="Fund gas">
    Get test SEI from the [Sei testnet faucet](https://docs.sei.io/learn/faucet). Users only need SEI gas for deposits and withdrawals.
  </Step>

  <Step title="Use the staging RPC">
    Start with `https://evm-rpc-testnet.sei-apis.com`, then move to a provider-backed RPC URL before heavier usage.
  </Step>

  <Step title="Request Monaco test assets">
    Use the [testnet faucet](/developers/faucet) after wallet authentication when the user needs test assets for deposits, balances, spot orders, or perps collateral.
  </Step>
</Steps>

## Browser Wallet

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

<CardGroup cols={3}>
  <Card title="Injected Wallets" icon="plug">
    Use MetaMask, Rabby, Backpack, or another injected EVM-compatible wallet through `window.ethereum`.
  </Card>

  <Card title="WalletConnect" icon="link">
    Use a WalletConnect transport when your app needs mobile wallet or QR-code connection flows.
  </Card>

  <Card title="Server Wallets" icon="server">
    Backend services can create a Viem wallet client from a private key when they own the signing key.
  </Card>
</CardGroup>

See the [Viem Wallet Client docs](https://viem.sh/docs/clients/wallet) 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.

<Note>
  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.
</Note>

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

<Note>
  There is no backend secret key: the application reporting endpoints are public and select the application by its `clientId` (see [Applications](/sdk/typescript/applications)). User trading, deposits, withdrawals, and account routes use wallet-authorized sessions.
</Note>

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

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

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

```typescript theme={null}
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](/sdk/typescript/auth) or [React `useAuth`](/sdk/react/hooks/use-auth) to create an authenticated Monaco session.
* Use [Account Balances](/developers/account-balances) to read available, locked, total balances, and movements.
* Use [Vault Deposits & Withdrawals](/developers/vault) to deposit and withdraw assets.
* Use [Perps Collateral](/developers/perps-collateral) to fund parent margin accounts and risk buckets.
* Use [Markets](/developers/markets) to resolve pair IDs, product support, and public market data.


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