摩纳哥核心SDK
与摩纳哥议定书互动的核心SDK执行。 这一SDK提供了认证、断层、交易、市场和概况API的综合实施,其特点是非拘禁会话键认证和安全的API网关整合.
安装
npm install @0xmonaco/core
所需的同伴依赖 :
npm install viem@^2.31.7
特征
🔐 认证
- 会话键认证: 非拘禁 Ed25519 会话密钥——服务器从未持有可以冒充你的证书
- 钱包签名验证: EIP-712 签名授权每个会话密钥
- 会话刷新: 延长会话过期而无需重新提示钱包
🏦 默认操作
- 调试批准: ERC20 保险库使用批准
- 存款: 签字验证后的安全代币存款
- 退 款: 带有密码验证的抽取
- 余额查询: 实时金库余额跟踪
📈 贸易业务
- 顺序类型: 限制和市场订单
- 订单管理: 设置、替换和取消命令
- 顺序查询: 分级命令、命令历史和个人命令细节
- 实时更新: 对活订单更新的 WebSocket 支持
📊 市场数据
- 交易对等: 完整的交易对元数据
- 市场信息: 收费、勾选大小、顺序限制
- 发现对等: 搜索和过滤现有市场
👤 简介管理
- 用户配置文件: 账户信息和设置
- 分账户: 多账户管理
- 余额跟踪: 跨平台平衡监测
🔐 安全特性
- 会话键签名: 每一份经认证的请求均用当地持有的 Ed25519 键签名
- EIP-712 签署: 类型安全、结构化的数据签名,供会议授权使用
- API 网关整合: 与摩纳哥后端安全通信
- TLS 加密: 安全API通讯
网络支持
通过提供 network 财务报告和审定财务报表 seiRpcUrl 参数。 使用 "mainnet" 预设,它连接了 Sei 主网和制作 API (https://apimonaco.xyz (英语)。 WebSocket URLs 自动解决.
import { MonacoSDK } from "@0xmonaco/core";
const sdk = new MonacoSDK({
walletClient,
network: "mainnet",
seiRpcUrl: "https://evm-rpc.sei-apis.com",
});
快速启动
import { MonacoSDK } from "@0xmonaco/core";
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { sei } from "viem/chains";
// Initialize the SDK with wallet client
const account = privateKeyToAccount("0x...");
const walletClient = createWalletClient({
account,
chain: sei,
transport: http("https://evm-rpc.sei-apis.com")
});
const monaco = new MonacoSDK({
walletClient,
network: "mainnet",
seiRpcUrl: "https://evm-rpc.sei-apis.com", // public RPC; use a dedicated provider in production
});
// Authentication
async function authExample() {
// Login with client ID and auto-connect authenticated WebSocket channels (Orders)
const authState = await monaco.login("your-client-id", { connectWebSocket: true });
console.log("Authenticated:", authState.user);
console.log("Session:", {
sessionPublicKey: authState.sessionPublicKey,
expiresAt: authState.expiresAt,
});
// Authenticated WebSocket channels are now connected - start receiving real-time updates
// Currently this includes: Orders (personal order updates)
monaco.websocket.orders.subscribeToOrderEvents("BTC/USDC", "SPOT", (event) => {
console.log("Order event:", event.eventType);
});
// Check authentication status
console.log("Is authenticated:", monaco.isAuthenticated());
// Logout (revokes the session and disconnects authenticated WebSockets)
await monaco.logout();
// Or manually revoke the session
await monaco.auth.revokeSession();
}
// Market Data
async function marketExample() {
// Get all trading pairs
const pairs = await monaco.market.getTradingPairs();
console.log("Available pairs:", pairs.length);
// Get specific trading pair
const btcPair = await monaco.market.getTradingPairBySymbol("BTC/USDC");
console.log("BTC pair:", btcPair?.symbol, btcPair?.tickSize);
// Fee rates are tiered: read the pair's schedule (public) or your own tier
if (btcPair) {
const { feeSchedule } = await monaco.fees.getFeeSchedule(btcPair.id);
console.log("Tier 1 taker fee (bps):", feeSchedule[0]?.takerFeeBps);
}
}
// Vault Operations
async function vaultExample() {
// Get asset ID from trading pair
const pair = await monaco.market.getTradingPairBySymbol("USDC/USDT");
const assetId = pair.base_asset_id; // Asset ID (UUID)
// Check vault balance
const balance = await monaco.profile.getUserBalanceByAssetId(assetId);
console.log("Vault balance:", balance.total_balance, balance.symbol);
// Approve vault to spend tokens
const approval = await monaco.vault.approve(assetId, parseEther("1000"));
console.log("Approval transaction:", approval.hash);
// Deposit tokens
const result = await monaco.vault.deposit(assetId, parseEther("100"));
console.log("Deposit transaction:", result.hash);
// Withdraw tokens
const withdrawal = await monaco.vault.withdraw(assetId, parseEther("50"));
console.log("Withdrawal transaction:", withdrawal.hash);
}
// Trading Operations
async function tradingExample() {
// Look up the trading pair UUID first
const pair = await monaco.market.getTradingPairBySymbol("BTC/USDC");
const tradingPairId = pair.id; // UUID
// Place a limit order
const order = await monaco.trading.placeLimitOrder(
tradingPairId, // trading pair UUID
"BUY", // side
"0.001", // quantity
"50000" // price
);
console.log("Order placed:", order.order_id);
// Place a limit order with IOC (Immediate or Cancel)
const iocOrder = await monaco.trading.placeLimitOrder(
tradingPairId,
"BUY",
"0.001",
"50000",
{ timeInForce: "IOC" } // Execute immediately or cancel
);
console.log("IOC order placed:", iocOrder.order_id);
// Place a market order
const marketOrder = await monaco.trading.placeMarketOrder(
tradingPairId,
"SELL",
"0.001"
);
console.log("Market order placed:", marketOrder.order_id);
// Get paginated orders
const orders = await monaco.trading.getPaginatedOrders({
status: "SUBMITTED",
trading_pair: "BTC/USDC",
page: 1,
page_size: 10
});
console.log("Orders:", orders.data.length);
// Replace an order
const replaceResult = await monaco.trading.replaceOrder("order-id", {
quantity: "0.002",
price: "51000"
});
console.log("Order replaced:", replaceResult.order_id);
// Cancel an order
const cancelResult = await monaco.trading.cancelOrder("order-id");
console.log("Order cancelled:", cancelResult.status);
// Get specific order
const orderDetails = await monaco.trading.getOrder("order-id");
console.log("Order details:", orderDetails.order);
}
API 参考
摩纳哥SDK
提供访问所有协议特性的主要SDK类.
配置
interface SDKConfig {
/** Wallet client for signing operations (optional - can be set later via setWalletClient) */
walletClient?: WalletClient;
/** Use "mainnet" (Sei mainnet, production API). */
network: Network;
/** RPC URL for Sei blockchain interactions */
seiRpcUrl: string;
}
认证会话管理( S)
SDK采用非拘禁式会话键式. 它在登录时会在当地生成一个 ed25519 键盘, 您的钱包通过 EIP-712 签名授权它, 并用私钥签下随后的每个请求 —— 服务器从未持有可以冒充您的证书 .
// After login, you receive an AuthState object
const authState = await sdk.login(clientId);
// AuthState structure:
interface AuthState {
sessionPublicKey: string; // ed25519 public key registered with the server
sessionPrivateKey: string; // ed25519 private key used to sign requests (the long-lived credential)
expiresAt: number; // Unix timestamp (seconds) when the session expires
user: User; // User information
}
私钥为长生相证. 坚持到底(如:.
localStorage,与 JWT 相同的风险简介)在不重发钱包的情况下重新装入页面。 届会结束后,请拨refreshAuth()或复为login()。 。 。 .
// Revoke the current session
await sdk.auth.revokeSession();
// 💡 TIP: Use the built-in logout method
await sdk.logout(); // Automatically calls revokeSession internally
会话管理方法:
login(clientId, options?)- 授权会话密钥并认证clientId: 您应用程序的客户端IDoptions.connectWebSocket: (可选)登录后自动连接 WebSocket(默认:false(中文(简体) )- 回返
AuthState包含会话 keypair、 过期和用户信息
logout()- 取消会话、断开WebSocket和清除状态- 电话
auth.revokeSession()内部 - 断开已认证的 WebSocket 频道
- 清除本地认证状态
- 电话
refreshAuth()- 延长本届会议的会期isAuthenticated()- 检查会话是否活动getAuthState()- 用会话键盘获取当前认证状态setAuthState(authState)- 直接设置认证状态(可用于共享 SDK 实例)
默认 API
保险库 API 提供安全标志管理操作 :
interface VaultAPI extends BaseAPI {
// Vault address management
setVaultAddress(vaultAddress: Address): void;
getVaultAddress(): Address | undefined;
// Token operations
approve(token: string, amount: bigint, autoWait?: boolean): Promise<TransactionResult>;
deposit(token: string, amount: bigint, autoWait?: boolean): Promise<TransactionResult>;
withdraw(token: string, amount: bigint, autoWait?: boolean): Promise<TransactionResult>;
}
贸易 API
交易API提供全面订单管理:
interface TradingAPI extends BaseAPI {
// Order placement
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>;
// Order management
cancelOrder(orderId: string): Promise<CancelOrderResponse>;
replaceOrder(
orderId: string,
newOrder: {
price?: string;
quantity: string;
useMasterBalance?: boolean;
}
): Promise<ReplaceOrderResponse>;
// Order queries
getPaginatedOrders(params?: GetPaginatedOrdersParams): Promise<GetPaginatedOrdersResponse>;
getOrder(orderId: string): Promise<GetOrderResponse>;
}
市场 API
市场API提供交易配对元数据:
interface MarketAPI extends BaseAPI {
// Market data
getTradingPairs(): Promise<TradingPair[]>;
getTradingPairBySymbol(symbol: string): Promise<TradingPair | undefined>;
}
WebSocket 认证
SDK为三个WebSocket客户端提供了不同的认证要求:
公共 WebSockets (OHLCV 和顺序书)
不需要认证 。 提供公共市场数据。 您总是手动连接 :
// Step 1: Establish WebSocket connection (no authentication needed)
await monaco.websocket.ohlcv.connect();
await monaco.websocket.orderbook.connect();
// Step 2: Subscribe to public market data
monaco.websocket.ohlcv.subscribeToOHLCV("BTC/USDC", "SPOT", "1m", (event) => {
console.log("OHLCV data:", event.candlestick);
});
monaco.websocket.orderbook.subscribeToOrderbookEvents("BTC/USDC", "SPOT", (event) => {
console.log("Orderbook update:", event.bids.length, "bids");
});
已认证的 WebSockets (命令)
需要经过认证的会话更新个人订单 。 您可以在登录时自动连接, 或者手动连接 :
备选案文1:自动连接(推荐给经认证的频道)
// Login and auto-connect all authenticated WebSocket channels
// Currently includes: Orders (personal order updates)
await monaco.login(clientId, { connectWebSocket: true });
// Subscribe to personal order events (already connected)
monaco.websocket.orders.subscribeToOrderEvents("BTC/USDC", "SPOT", (event) => {
console.log("Personal order event:", event.eventType);
});
备选案文2:人工连接(公共渠道需要,认证需要可选)
// Public channels like OHLCV always require manual connection (no auth needed)
await monaco.websocket.ohlcv.connect();
monaco.websocket.ohlcv.subscribeToOHLCV("BTC/USDC", "SPOT", "1m", (event) => {
console.log("OHLCV data:", event.candlestick);
});
// For authenticated channels, you can also connect manually for more control
await monaco.login(clientId);
await monaco.websocket.orders.connect();
monaco.websocket.orders.subscribeToOrderEvents("BTC/USDC", "SPOT", (event) => {
console.log("Personal order event:", event.eventType);
});
说明:
- 这个
connectWebSocket: true选项将自动连接所有已认证的 WebSocket 频道(目前为命令). - 公共 WebSocket 客户端( OHLCV, Orderbook) 总是需要呼叫
connect()因为他们不需要认证.
处理错误
SDK使用结构化错误分类来进行全面的错误处理:
import { APIError, ContractError } from "@0xmonaco/core";
try {
await sdk.vault.deposit(token, amount);
} catch (error) {
if (error instanceof ContractError) {
console.error("Contract error:", error.message);
console.error("Error code:", error.code);
} else if (error instanceof APIError) {
console.error("API error:", error.message);
console.error("Status:", error.status);
}
}
错误类型 :
MonacoCoreError: 所有 SDK 错误的基准错误分类APIError: API 请求失败和通信错误ContractError: 智能合同操作错误InvalidConfigError: 配置验证错误InvalidStateError无效的状态或操作错误
发展
项目结构
packages/core/
├── src/ # Source code
│ ├── api/ # API implementations
│ │ ├── applications/ # Applications API
│ │ ├── auth/ # Authentication API
│ │ ├── base.ts # Base API class
│ │ ├── market/ # Market data API
│ │ ├── profile/ # Profile management API
│ │ ├── trading/ # Trading operations API
│ │ ├── vault/ # Vault operations API
│ │ ├── websocket/ # WebSocket client
│ │ └── index.ts # API exports
│ ├── constants/ # Constants and configurations
│ ├── errors.ts # Error classes and codes
│ ├── networks.ts # Network endpoint configurations
│ ├── sdk.ts # Main SDK implementation
│ └── index.ts # Public API exports
├── tests/ # Test suite
├── dist/ # Compiled output
├── package.json # Package configuration
└── tsconfig.json # TypeScript configuration
开发设置
-
清除仓库 :
git clone https://github.com/monaco-protocol/monaco-monorepo.git cd monaco-monorepo -
安装依赖性 :
bun run install -
构建软件包 :
bun run build --filter @0xmonaco/core
测试
运行测试套件 :
bun run test --filter @0xmonaco/core
代码样式
该项目使用ESLint和Prettier进行代码格式化. 运行线条 :
bun run lint --filter @0xmonaco/core
安全特性
会话键认证
- 非拘禁: ed25519 会话密钥是本地生成的; 服务器从未持有可以冒充您的证书
- EIP-712 登录: 钱包签名授权每个会话密钥
- 会话刷新: 延长到期时不重新提示钱包
API 网关整合
- 安全通讯: 所有 API 呼叫的 TLS 加密
- 请求签名: 后端验证每次认证请求的会话签名
- 限制费率:防止虐待
- 审计记录: 完整的交易历史
链上安全
- 智能合同验证: 所有在链上验证的操作
- 签字核查: EIP-712 认证签名
- 多签名支持:机构用户的高级安保
业绩考量
- 批量操作:高效处理多个业务
- 连接集: 优化API 连接
- 缓存: 智能缓存经常访问的数据
- Async 操作: 改善UX的非封锁行动
发展 工作流量
- 叉子存储器
- 创建特性分支
- 做你的改变
- 添加新功能测试
- 确保所有测试通过
- 提交拉动请求
许可证
这个项目根据麻省理工学院的许可证获得许可.
支助
支持请:
- 在 GitHub 上打开一期
- 加入我们 Discord 社区
- 拜访我们 文档网站
- 检查我们 API 文档