@0xmonaco/types

@0xmonaco/types

Core type definitions for the Monaco protocol. This package provides TypeScript types and interfaces used throughout the Monaco ecosystem, focusing on SDK configuration, vault operations, trading operations, market data, and contract management.

Installation

npm install @0xmonaco/types

Note: This package is typically installed as a dependency of @0xmonaco/core or @0xmonaco/react, but you can install it directly for type definitions in your TypeScript project.

Type Categories

SDK Types

Core SDK configuration and main interface types:

import { MonacoSDK, SDKConfig } from "@0xmonaco/types";

// SDK configuration
interface SDKConfig {
  walletClient?: WalletClient; // Wallet client for signing operations
  network: Network; // Use "staging" for public testnet or "mainnet" for production
  seiRpcUrl: string; // RPC URL for Sei blockchain interactions
}

// Main SDK interface
interface MonacoSDK {
  applications: ApplicationsAPI; // Applications operations API
  auth: AuthAPI; // Auth operations API
  vault: VaultAPI; // Vault operations API
  trading: TradingAPI; // Trading operations API
  market: MarketAPI; // Market metadata API
  profile: ProfileAPI; // Profile operations API
  websocket: {
    orders: OrdersWebSocketClient; // WebSocket client for real-time order events
    ohlcv: OHLCVWebSocketClient; // WebSocket client for real-time OHLCV data
    orderbook: OrderbookWebSocketClient; // WebSocket client for real-time orderbook updates
  };
  walletClient: WalletClient; // Wallet client for blockchain operations
  publicClient: PublicClient; // Public client for read-only operations

  // Authentication
  login(clientId: string, options?: { connectWebSocket?: boolean }): Promise<AuthState>;
  logout(): Promise<void>;
  refreshAuth(): Promise<AuthState>;
  getAuthState(): AuthState | undefined;

  // Account management
  isAuthenticated(): boolean;
  isConnected(): boolean;
  getAccountAddress(): string;
  getNetwork(): Network;
  getChainId(): number;
  waitForTransaction(
    hash: string,
    confirmations?: number,
    timeout?: number
  ): Promise<TransactionReceipt>;
}

Vault Types

Types for vault operations including deposits, withdrawals, and balance management:

import { VaultAPI, Balance, TransactionResult } from "@0xmonaco/types";

// Vault operations
interface VaultAPI extends BaseAPI {
  approve(
    assetId: string,
    amount: bigint,
    autoWait?: boolean
  ): Promise<TransactionResult>;
  deposit(
    assetId: string,
    amount: bigint,
    autoWait?: boolean
  ): Promise<TransactionResult>;
  withdraw(
    assetId: string,
    amount: bigint,
    autoWait?: boolean
  ): Promise<TransactionResult>;
  getAllowance(assetId: string): Promise<bigint>;
  needsApproval(assetId: string, amount: bigint): Promise<boolean>;
  getVaultAddress(): Promise<string>;
}

// Vault response types
interface Balance {
  token: string;
  amount: bigint;
  formatted: string;
  symbol: string;
  decimals: number;
}

interface TransactionResult {
  hash: string;
  status: "pending" | "confirmed" | "failed";
  nonce: bigint;
  receipt?: TransactionReceipt;
}

Trading Types

Types for trading operations including order placement and management:

import {
  TradingAPI,
  OrderSide,
  OrderType,
  CreateOrderResponse,
  CancelOrderResponse,
  ReplaceOrderResponse,
  GetPaginatedOrdersResponse,
  GetOrderResponse,
} from "@0xmonaco/types";

// Trading operations
interface TradingAPI extends BaseAPI {
  placeLimitOrder(
    tradingPairId: string,
    side: OrderSide,
    quantity: string,
    price: string,
    options?: {
      tradingMode?: TradingMode;
      useMasterBalance?: boolean;
      expirationDate?: string;
      timeInForce?: TimeInForce;
    }
  ): Promise<CreateOrderResponse>;

  placeMarketOrder(
    tradingPairId: string,
    side: OrderSide,
    quantity: string,
    options?: {
      tradingMode?: TradingMode;
      slippageTolerance?: number;
    }
  ): Promise<CreateOrderResponse>;

  cancelOrder(orderId: string): Promise<CancelOrderResponse>;

  replaceOrder(
    orderId: string,
    newOrder: {
      price?: string;
      quantity: string;
      useMasterBalance?: boolean;
    }
  ): Promise<ReplaceOrderResponse>;

  getPaginatedOrders(
    params?: GetPaginatedOrdersParams
  ): Promise<GetPaginatedOrdersResponse>;
  getOrder(orderId: string): Promise<GetOrderResponse>;
}

// Trading types
type OrderSide = "BUY" | "SELL";
type OrderType = "LIMIT" | "MARKET";
type OrderStatus = "SUBMITTED" | "PARTIALLY_FILLED" | "FILLED" | "SETTLED_ON_CHAIN" | "SETTLED" | "CANCELLED" | "REJECTED" | "EXPIRED";
type TradingMode = "SPOT";
type TimeInForce = "GTC" | "IOC" | "FOK"; // GTC: Good Till Cancel, IOC: Immediate or Cancel, FOK: Fill or Kill

// Trading response types
interface CreateOrderResponse {
  order_id: string;
  status: "SUCCESS" | "FAILED";
  match_result?: {
    remaining_quantity: string;
    status: string;
  };
}

interface CancelOrderResponse {
  order_id: string;
  status: "SUCCESS" | "FAILED";
}

interface ReplaceOrderResponse {
  order_id: string;
  status: "SUCCESS" | "FAILED";
}

Market Types

Types for market data operations including trading pair metadata:

import {
  MarketAPI,
  TradingPair,
  GetTradingPairsParams,
  GetTradingPairsResponse,
  GetTradingPairResponse,
  TradingMode,
} from "@0xmonaco/types";

// Market operations
interface MarketAPI extends BaseAPI {
  getPaginatedTradingPairs(
    params?: GetTradingPairsParams,
  ): Promise<GetTradingPairsResponse>;
  getTradingPair(tradingPairId: string): Promise<TradingPair>;
  getTradingPairBySymbol(
    symbol: string,
    marketType?: TradingMode,
  ): Promise<TradingPair | undefined>;
}

// Market data types
interface TradingPair {
  id: string;
  symbol: string;
  baseToken: string;
  quoteToken: string;
  baseAssetId: string;
  quoteAssetId: string;
  baseTokenContract: string;
  quoteTokenContract: string;
  baseDecimals: number;
  baseIconUrl: string;
  quoteDecimals: number;
  quoteIconUrl: string;
  marketType: TradingMode;
  category: string;
  isActive: boolean;
  makerFeeBps: number;
  takerFeeBps: number;
  minOrderSize: string;
  maxOrderSize: string;
  quantityStepSize: string;
  tickSize: string;
  minLeverage?: string | null;
  maxLeverage?: string | null;
}

// Market response types
interface GetTradingPairsResponse {
  tradingPairs: TradingPair[];
  page: number;
  pageSize: number;
  total: number;
  totalPages: number;
}

interface GetTradingPairResponse {
  tradingPair: TradingPair;
}

Contract Types

Types for contract addresses, instances, and contract-related operations:

import {
  ContractAddresses,
  ContractInstances,
  Token,
  UserBalance,
} from "@0xmonaco/types";

// Contract addresses
interface ContractAddresses {
  VAULT: string; // Vault contract address for managing user balances
}

// Contract instances
type ContractInstances = {
  vault: GetContractReturnType<typeof CONTRACT_ABIS.vault>;
};

// Contract-related types
interface Token {
  address: string;
  decimals: number;
  symbol: string;
  name: string;
}

interface UserBalance {
  token: Token;
  amount: bigint;
  formatted: string;
}

Network Types

Types for network configuration:

import { Network, NetworkEndpoints } from "@0xmonaco/types";

const publicNetwork: Network = "staging";

interface NetworkEndpoints {
  rpcUrl: string;
  apiUrl: string;
}

For public integrations, use "staging" or "mainnet".

Type Reference

SDK Types

• MonacoSDK: Main SDK interface with all API modules
• SDKConfig: Configuration options for the Monaco SDK
• Network: SDK network preset type. Public integrations should use "staging" or "mainnet".
• AuthState: Authentication state information

Vault Types

• VaultAPI: Interface for vault operations (deposits, withdrawals, balances)
• Balance: Token balance information
• TransactionResult: Result of blockchain transactions

Trading Types

• TradingAPI: Interface for trading operations (orders, positions)
• OrderSide: Order side type ("BUY" | "SELL")
• OrderType: Order type ("LIMIT" | "MARKET")
• TimeInForce: Time in force type ("GTC" | "IOC" | "FOK")
• CreateOrderResponse: Response from order placement
• CancelOrderResponse: Response from order cancellation
• ReplaceOrderResponse: Response from order replacement

Market Types

• MarketAPI: Interface for market data operations
• TradingPair: Trading pair metadata with all market information
• GetTradingPairsResponse: Response wrapper for trading pairs list
• GetTradingPairResponse: Response wrapper for single trading pair

Contract Types

• ContractAddresses: Contract address mappings
• ContractInstances: Typed contract instances
• Token: Token interface with metadata
• UserBalance: User's token balance information

Project Structure

The types package is organized into domain-specific modules:

src/
├── api/            # Base API types
│   └── index.ts   # Common API interfaces
├── applications/   # Applications types
├── auth/           # Authentication types
├── contracts/      # Contract types
│   ├── index.ts   # Contract interfaces
│   └── balances.ts # Balance-related types
├── market/         # Market data types
│   └── index.ts   # Market API interface and types
├── profile/        # Profile types
├── sdk/            # SDK types
│   ├── index.ts   # Main SDK interfaces and configuration
│   └── network.ts # Network-related types
├── trading/        # Trading types
│   ├── index.ts   # Trading API interface
│   ├── orders.ts  # Order-related types
│   └── responses.ts # Trading response types
├── vault/          # Vault types
│   ├── index.ts   # Vault API interface
│   └── responses.ts # Vault response types
├── websocket/      # WebSocket types
└── index.ts        # Package exports

Dependencies

This package uses viem for blockchain-related types:

• Address, Hex, Account, WalletClient, PublicClient from viem
• GetContractReturnType for contract instance typing

Best Practices

• Keep types focused and single-purpose
• Use descriptive names that reflect the domain
• Document complex types with JSDoc comments
• Use TypeScript's strict mode
• Maintain backward compatibility
• Follow the established naming conventions
• Group related types in the same file
• Leverage viem types for blockchain operations rather than defining custom ones