# @0xmonaco/core 中文文档

规范地址：https://npmcn.com/package/%400xmonaco/core/

版本：1\.1\.8
npm 元数据更新时间：2026-11-06T01:23:07.723Z
中文译文更新时间：2026-11-06T00:29:40.459Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%400xmonaco/core
原文对照：https://npmcn.com/package/%400xmonaco/core/?lang=original
项目主页：https://docs.0xmonaco.com/sdk/typescript

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：781 kB，148 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：5 个
- peer 依赖：viem ^2\.45\.2
- 首次发布：2025-08-28T01:53:21.840Z
- 最新版本发布：2026-11-06T01:23:07.520Z
- 近 30 天下载量：8175（2026-10-04 至 2026-11-02，npm 官方下载统计）
- 已发布版本数：197（近 12 个月 173 个）

## 中文简介

与摩纳哥议定书互动的核心SDK执行。 SDK提供了认证、断层、交易、市场和配置 API 的全面实施,以非拘禁会话密钥认证和安全 API Gateway integrat

## 安装

```sh
npm install @0xmonaco/core
```

也可以使用：`pnpm add @0xmonaco/core`、`yarn add @0xmonaco/core`、`bun add @0xmonaco/core`

## README

# 摩纳哥核心SDK

与摩纳哥议定书互动的核心SDK执行。 这一SDK提供了认证、断层、交易、市场和概况API的综合实施,其特点是非拘禁会话键认证和安全的API网关整合.

## 安装

```bash
npm install @0xmonaco/core
```

**所需的同伴依赖 :**

```bash
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 (英语)](https://apimonaco.xyz/)。 WebSocket URLs 自动解决.

```typescript
import { MonacoSDK } from "@0xmonaco/core";

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

## 快速启动

```typescript
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类.

### 配置

```typescript
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 签名授权它, 并用私钥签下随后的每个请求 —— 服务器从未持有可以冒充您的证书 .

```typescript
// 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()`。 。 。 .

```typescript
// 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`: 您应用程序的客户端ID
    -   `options.connectWebSocket`: (可选)登录后自动连接 WebSocket(默认: `false`(中文(简体) )
    -   回返 `AuthState` 包含会话 keypair、 过期和用户信息
-   `logout()` - 取消会话、断开WebSocket和清除状态
    -   电话 `auth.revokeSession()` 内部
    -   断开已认证的 WebSocket 频道
    -   清除本地认证状态
-   `refreshAuth()` - 延长本届会议的会期
-   `isAuthenticated()` - 检查会话是否活动
-   `getAuthState()` - 用会话键盘获取当前认证状态
-   `setAuthState(authState)` - 直接设置认证状态(可用于共享 SDK 实例)

### 默认 API

保险库 API 提供安全标志管理操作 :

```typescript
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提供全面订单管理:

```typescript
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提供交易配对元数据:

```typescript
interface MarketAPI extends BaseAPI {
  // Market data
  getTradingPairs(): Promise<TradingPair[]>;
  getTradingPairBySymbol(symbol: string): Promise<TradingPair | undefined>;
}
```

### WebSocket 认证

SDK为三个WebSocket客户端提供了不同的认证要求:

#### 公共 WebSockets (OHLCV 和顺序书)

不需要认证 。 提供公共市场数据。 您总是手动连接 :

```typescript
// 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:自动连接(推荐给经认证的频道)**

```typescript
// 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:人工连接(公共渠道需要,认证需要可选)**

```typescript
// 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使用结构化错误分类来进行全面的错误处理:

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

### 开发设置

1.  清除仓库 :
    
    ```bash
    git clone https://github.com/monaco-protocol/monaco-monorepo.git
    cd monaco-monorepo
    ```
    
2.  安装依赖性 :
    
    ```bash
    bun run install
    ```
    
3.  构建软件包 :
    
    ```bash
    bun run build --filter @0xmonaco/core
    ```
    

### 测试

运行测试套件 :

```bash
bun run test --filter @0xmonaco/core
```

### 代码样式

该项目使用ESLint和Prettier进行代码格式化. 运行线条 :

```bash
bun run lint --filter @0xmonaco/core
```

## 安全特性

### 会话键认证

-   **非拘禁**: ed25519 会话密钥是本地生成的; 服务器从未持有可以冒充您的证书
-   **EIP-712 登录**: 钱包签名授权每个会话密钥
-   **会话刷新**: 延长到期时不重新提示钱包

### API 网关整合

-   **安全通讯**: 所有 API 呼叫的 TLS 加密
-   **请求签名**: 后端验证每次认证请求的会话签名
-   **限制费率**:防止虐待
-   **审计记录**: 完整的交易历史

### 链上安全

-   **智能合同验证**: 所有在链上验证的操作
-   **签字核查**: EIP-712 认证签名
-   **多签名支持**:机构用户的高级安保

## 业绩考量

-   **批量操作**:高效处理多个业务
-   **连接集**: 优化API 连接
-   **缓存**: 智能缓存经常访问的数据
-   **Async 操作**: 改善UX的非封锁行动

### 发展 工作流量

1.  叉子存储器
2.  创建特性分支
3.  做你的改变
4.  添加新功能测试
5.  确保所有测试通过
6.  提交拉动请求

## 许可证

这个项目根据麻省理工学院的许可证获得许可.

## 支助

支持请:

-   在 GitHub 上打开一期
-   加入我们 [Discord 社区](https://discord.gg/monaco)
-   拜访我们 [文档网站](https://docs.monaco.xyz/)
-   检查我们 [API 文档](https://docs.0xmonaco.com/)

## 常见问题

### @0xmonaco/core 是什么？

与摩纳哥议定书互动的核心SDK执行。 SDK提供了认证、断层、交易、市场和配置 API 的全面实施,以非拘禁会话密钥认证和安全 API Gateway integrat

### 如何安装 @0xmonaco/core？

在项目目录运行 npm install @0xmonaco/core，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：viem（^2\.45\.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @0xmonaco/core 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @0xmonaco/core 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @0xmonaco/core 可以商用吗？

@0xmonaco/core 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @0xmonaco/core 的下载量有多少？

根据 npm 官方下载统计，@0xmonaco/core 在 2026/10/04 – 2026/11/02 这 30 天内被下载 8,175 次，日均约 273 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @0xmonaco/core 还在维护吗？

最新版本 1\.1\.8 发布于 2026/11/06（1 天前）；至今共发布 197 个版本，其中过去 12 个月发布了 173 个；首次发布于 2025/08/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。