Deposit Tokens

Deposit ERC20 tokens into the Monaco Protocol vault for trading and other operations.

Quick Setup

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

// Request account access
const [account] = await window.ethereum.request({ 
  method: 'eth_requestAccounts' 
});

// Connect to user's wallet
const walletClient = createWalletClient({
  account,
  chain: seiTestnet,
  transport: custom(window.ethereum)
});

// Setup SDK
const sdk = new MonacoSDK({
  walletClient,
  network: 'staging',
  seiRpcUrl: 'https://evm-rpc-testnet.sei-apis.com', // public testnet RPC — use a private provider in production
});

// Authenticate first
await sdk.login('your-client-id');

// Get trading pair to find asset IDs
// Asset IDs come from trading pairs, not balances
const tradingPair = await sdk.market.getTradingPairBySymbol('BTC/USDC');

// Get the asset ID for vault operations
const assetId = tradingPair.quoteAssetId;  // USDC asset ID
const amount = parseUnits('100', 6); // 100 USDC

// Step 1: Approve vault to spend tokens
const approvalResult = await sdk.vault.approve(assetId, amount);
console.log('Approval transaction:', approvalResult.hash);

// Step 2: Deposit tokens
const depositResult = await sdk.vault.deposit(assetId, amount);
console.log('Deposit transaction:', depositResult.hash);

Depositing Directly to Margin Collateral

By default, vault.deposit() credits your spot wallet. Pass "margin" as the optional fourth argument to route the on-chain deposit straight into your parent margin account’s collateral — skipping the separate transferCollateralToParentMarginAccount step:

const pair = await sdk.market.getTradingPairBySymbol('BTC/USDC');
const assetId = pair.quoteAssetId; // USDC
const amount = parseUnits('500', 6);

// Approve first (same as a normal deposit)
await sdk.vault.approve(assetId, amount);

// Deposit straight into margin collateral
await sdk.vault.deposit(assetId, amount, true, "margin");

If the deposit cannot be routed to margin safely (for example, an unsupported asset or temporarily unavailable margin routing), it falls back to spot silently. The encoding is handled automatically by encodeDepositApplicationData() — existing spot deposits are byte-identical to before. If you call the vault contract directly instead of through the SDK, encode the deposit’s applicationData with encodeDepositApplicationData(clientId, target) from @0xmonaco/contracts. A spot deposit carries the bare client ID. A margin deposit must carry exactly {"clientId":"<clientId>","depositTarget":"MARGIN"}, byte for byte, with no extra whitespace or keys and a client ID of 1–64 letters, digits, _ or -. The only other accepted JSON form is {"clientId":"<clientId>","depositTarget":"INSURANCE_FUND"}, which Monaco uses to top up its insurance fund. Any other payload that starts with { is not guessed at: it is credited to the spot wallet of Monaco’s default application, not yours.

Understanding Asset IDs

Monaco uses asset IDs (UUIDs) for all vault operations. This provides a consistent interface regardless of the underlying token contract.

Operation	Parameter	Description
`approve()`	`assetId`	Monaco asset UUID
`needsApproval()`	`assetId`	Monaco asset UUID
`deposit()`	`assetId`	Monaco asset UUID
`withdraw()`	`assetId`	Monaco asset UUID
`getAllowance()`	`assetId`	Monaco asset UUID

Trading pairs are the easiest place to discover asset IDs before a user has a balance:

// Get trading pair to access asset IDs
const tradingPair = await sdk.market.getTradingPairBySymbol('BTC/USDC');

// Trading pair contains:
// - baseAssetId: UUID for the base token (BTC)
// - quoteAssetId: UUID for the quote token (USDC)
// - baseTokenContract: Contract address for base token
// - quoteTokenContract: Contract address for quote token

console.log({
  baseAssetId: tradingPair.baseAssetId,
  quoteAssetId: tradingPair.quoteAssetId,
  baseContract: tradingPair.baseTokenContract,
  quoteContract: tradingPair.quoteTokenContract
});

Balances provide current holdings and include assetId for assets already in the account:

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

// Each balance contains:
// - assetId: Monaco asset UUID
// - token: Contract address
// - symbol: Token symbol (e.g., "USDC")
// - decimals: Token decimals
// - availableBalance, lockedBalance, totalBalance

console.log(balances[0]);
// {
//   assetId: "123e4567-e89b-12d3-a456-426614174000",
//   token: "0x23e459c24c4925ba89205c400dceca7abc11723d",
//   symbol: "USDC",
//   decimals: 6,
//   availableBalance: "1000.00",
//   ...
// }

Step-by-Step Deposit Process

1. Authenticate

Authentication is required before any vault operations:

// Log in to authorize an ed25519 session key that signs each request (no tokens)
const authState = await sdk.login('your-client-id');
console.log('Authenticated as:', authState.user.address);

2. Get Asset Information

Retrieve the asset you want to deposit from a trading pair:

// Get trading pair to access asset IDs
const tradingPair = await sdk.market.getTradingPairBySymbol('BTC/USDC');

// For depositing USDC (the quote token):
const assetId = tradingPair.quoteAssetId;
const decimals = 6; // USDC decimals

// For depositing BTC (the base token):
// const assetId = tradingPair.baseAssetId;
// const decimals = 8; // BTC decimals

3. Check Current Allowance

Before approving, check if approval is needed:

const amount = parseUnits('100', decimals);

// Check if approval is needed
const needsApproval = await sdk.vault.needsApproval(assetId, amount);
if (needsApproval) {
  console.log('Approval required');
} else {
  console.log('Sufficient allowance already exists');
}

4. Approve Token Spending

Grant vault permission to spend your tokens:

// Approve vault to spend tokens
const approvalResult = await sdk.vault.approve(assetId, amount);
console.log('Approval confirmed:', approvalResult.status);

5. Execute Deposit

Transfer tokens to the vault:

// Deposit tokens into vault
const depositResult = await sdk.vault.deposit(assetId, amount);
console.log('Deposit confirmed:', depositResult.status);
console.log('Transaction hash:', depositResult.hash);

6. Verify Deposit

Check your vault balance:

const balance = await sdk.profile.getUserBalanceByAssetId(assetId);
console.log(`Vault balance: ${balance.totalBalance} ${balance.symbol}`);

Complete Example

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

async function depositTokens(tradingPairSymbol: string, symbol: string, depositAmount: string) {
  // Request account access
  const [account] = await window.ethereum.request({ 
    method: 'eth_requestAccounts' 
  });

  // Initialize SDK
  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',
  });

  try {
    // 1. Authenticate
    console.log('Authenticating...');
    await sdk.login('your-client-id');

    // 2. Get asset information from trading pair
    console.log('Fetching trading pair...');
    const tradingPair = await sdk.market.getTradingPairBySymbol(tradingPairSymbol);

    // Determine which side of the pair we're depositing
    // For 'BTC/USDC': base = BTC, quote = USDC
    const isBase = symbol === tradingPair.baseToken;
    const assetId = isBase 
      ? tradingPair.baseAssetId 
      : tradingPair.quoteAssetId;
    const decimals = isBase ? 8 : 6; // Adjust based on token
    const amount = parseUnits(depositAmount, decimals);

    // 3. Check if approval is needed
    console.log('Checking allowance...');
    const needsApproval = await sdk.vault.needsApproval(assetId, amount);

    if (needsApproval) {
      // 4. Approve tokens
      console.log('Approving tokens...');
      const approvalResult = await sdk.vault.approve(assetId, amount);
      console.log('Approval confirmed:', approvalResult.hash);
    }

    // 5. Deposit tokens
    console.log('Depositing tokens...');
    const depositResult = await sdk.vault.deposit(assetId, amount);
    console.log('Deposit confirmed:', depositResult.hash);

    // 6. Check new balance
    const balance = await sdk.profile.getUserBalanceByAssetId(assetId);
    console.log(`New vault balance: ${balance.totalBalance} ${balance.symbol}`);

  } catch (error) {
    console.error('Deposit failed:', error.message);
  }
}

// Usage - deposit 100 USDC using the BTC/USDC trading pair
depositTokens('BTC/USDC', 'USDC', '100');

Error Handling

import { ContractError, APIError } from '@0xmonaco/core';

try {
  await sdk.vault.deposit(assetId, amount);
} catch (error) {
  if (error instanceof ContractError) {
    if (error.message.includes('APPROVAL_REQUIRED')) {
      console.error('Need to approve tokens first');
    } else if (error.message.includes('ASSET_NOT_FOUND')) {
      console.error('Invalid asset ID - use trading pairs to get valid asset IDs');
    } else {
      console.error('Contract error:', error.message);
    }
  } else if (error instanceof APIError) {
    console.error('API error:', error.message);
  }
}

Best Practices

Always authenticate first - Login before any vault operations
Get asset IDs from trading pairs - Use sdk.market.getTradingPairBySymbol() or sdk.market.getPaginatedTradingPairs() to get valid asset IDs
Check allowances - Use needsApproval() to avoid unnecessary approval transactions
Handle errors gracefully - Check for ASSET_NOT_FOUND errors if using invalid asset IDs
Verify balances - Check vault balances after deposits

Troubleshooting

Asset Not Found Error

If you get an ASSET_NOT_FOUND error, make sure you’re using a valid asset ID from a trading pair:

// Get valid asset IDs from trading pairs
// Returns ListTradingPairsResponse: { tradingPairs: TradingPair[], page, pageSize, total, totalPages }
const response = await sdk.market.getPaginatedTradingPairs();
const tradingPairs = response.tradingPairs;

console.log('Available assets:', tradingPairs.map(tp => ({
  symbol: tp.symbol,
  baseAssetId: tp.baseAssetId,
  quoteAssetId: tp.quoteAssetId,
  baseContract: tp.baseTokenContract,
  quoteContract: tp.quoteTokenContract
})));

Approval Required Error

// If you get "APPROVAL_REQUIRED" error
const needsApproval = await sdk.vault.needsApproval(assetId, amount);
if (needsApproval) {
  await sdk.vault.approve(assetId, amount);
}

Insufficient Balance

// Check wallet balance before deposit (uses token contract address for direct ERC20 call)
const tokenContractAddress = tradingPair.quoteTokenContract;
const walletBalance = await publicClient.readContract({
  address: tokenContractAddress,
  abi: erc20Abi,
  functionName: 'balanceOf',
  args: [account]
});

Transaction Failed

// The SDK auto-waits for confirmation by default
// You can disable auto-wait if needed:
const result = await sdk.vault.deposit(assetId, amount, false);
// Then manually wait later
const receipt = await sdk.waitForTransaction(result.hash);

Learn

Build

Libraries

APIs

Resources

Quick Setup

Depositing Directly to Margin Collateral

Understanding Asset IDs

Step-by-Step Deposit Process

1. Authenticate

2. Get Asset Information

3. Check Current Allowance

4. Approve Token Spending

5. Execute Deposit

6. Verify Deposit

Complete Example

Error Handling

Best Practices

Troubleshooting

Asset Not Found Error

Approval Required Error

Insufficient Balance

Transaction Failed

​Quick Setup

​Depositing Directly to Margin Collateral

​Understanding Asset IDs

​Step-by-Step Deposit Process

​1. Authenticate

​2. Get Asset Information

​3. Check Current Allowance

​4. Approve Token Spending

​5. Execute Deposit

​6. Verify Deposit

​Complete Example

​Error Handling

​Best Practices

​Troubleshooting

​Asset Not Found Error

​Approval Required Error

​Insufficient Balance

​Transaction Failed

Quick Setup

Depositing Directly to Margin Collateral

Understanding Asset IDs

Step-by-Step Deposit Process

1. Authenticate

2. Get Asset Information

3. Check Current Allowance

4. Approve Token Spending

5. Execute Deposit

6. Verify Deposit

Complete Example

Error Handling

Best Practices

Troubleshooting

Asset Not Found Error

Approval Required Error

Insufficient Balance

Transaction Failed