# @derivexyz/derive-ts 中文文档

规范地址：https://npmcn.com/package/%40derivexyz/derive-ts/

版本：3\.0\.36
npm 元数据更新时间：2026-10-20T07:31:23.994Z
中文译文更新时间：2026-11-12T00:41:18.632Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40derivexyz/derive-ts
原文对照：https://npmcn.com/package/%40derivexyz/derive-ts/?lang=original
项目主页：https://github.com/derivexyz/derive-ts#readme
源码仓库：https://github.com/derivexyz/derive-ts

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

- 包体积（解压后）：1.7 MB，38 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：2 个
- 首次发布：2026-07-13T05:54:04.201Z
- 最新版本发布：2026-10-20T07:31:23.430Z
- 近 30 天下载量：5093（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 20 个）

## 中文简介

Derive v3 交换 API 的脚本 SDK 类型

## 安装

```sh
npm install @derivexyz/derive-ts
```

也可以使用：`pnpm add @derivexyz/derive-ts`、`yarn add @derivexyz/derive-ts`、`bun add @derivexyz/derive-ts`

## README

# @ derivexyz/ derive- ts

[![npm version](https://img.shields.io/npm/v/@derivexyz/derive-ts)](https://www.npmjs.com/package/@derivexyz/derive-ts) [![CI](https://github.com/derivexyz/derive-ts/actions/workflows/ci.yml/badge.svg)](https://github.com/derivexyz/derive-ts/actions/workflows/ci.yml) [![license](https://img.shields.io/npm/l/@derivexyz/derive-ts)](https://npmcn.com/package/%40derivexyz/derive-ts/LICENSE)

脚本 SDK 类型 [衍生](https://derive.xyz/) v3 交换 API — 一个已键入 市场数据、订单、报告调查表、转账、提款、存款、金库、, 会话密钥和 websocket 订阅 .

更详细的文件见 [衍生 v3 API 参考](https://docs.derive.xyz/)。 。 。 .

## 安装

```bash
npm install @derivexyz/derive-ts ethers ws
```

## 快速启动

```ts
import { DeriveClient } from '@derivexyz/derive-ts';

const client = new DeriveClient({
  network: 'testnet', // 'mainnet' | 'testnet' | 'local'
  wallet: process.env.PRIVATE_KEY, // account owner key (or an ethers Wallet)
});

// Public data needs no auth:
const ticker = await client.marketData.getTicker('ETH-PERP');
console.log('ETH index price', ticker.I);

// Private calls sign automatically. Open the websocket and log in first:
await client.connect();
const subaccountIds = await client.login();

await client.orders.place({
  subaccountId: subaccountIds[0],
  instrumentName: 'ETH-PERP',
  direction: 'buy',
  amount: '0.1',
  limitPrice: '1000', // rests below market
});

await client.close();
```

## 认证会话密钥( S)

登录和每个请求认证使用a **EIP-191 (中文(简体) )** 超过一毫秒的签名 时间戳。 贸易/转让/撤回行动分开 **EIP-712** 签名. 两者都是为你处理的——你只提供一个签名钥匙.

对于bots和前端,做 **没有** 运送账户所有者的钥匙。 登记范围 **语句** 一次(由所有者签名),然后只用该键运行:

```ts
import { DeriveClient, ProtocolScopeCode } from '@derivexyz/derive-ts';
import { Wallet } from 'ethers';

const sessionKey = Wallet.createRandom();
const owner = new DeriveClient({ network: 'testnet', wallet: process.env.PRIVATE_KEY });
await owner.connect();
await owner.login();
await owner.sessionKeys.set({
  publicSessionKey: sessionKey,
  expirySec: Math.floor(Date.now() / 1000) + 7 * 24 * 3600,
  protocolScopes: [ProtocolScopeCode.Trade], // least privilege — never Admin for a bot
  ipWhitelist: ['203.0.113.7'],
});

// Later, in the bot, with only the session key:
const bot = new DeriveClient({
  network: 'testnet',
  sessionKey: sessionKey.privateKey,
  ownerAddress: await (new Wallet(process.env.PRIVATE_KEY!)).getAddress(),
});
```

会话密钥在签名时过期 `expirySec` 并且不能通过 API——设定合理期限. `sessionKeys.edit` 仅在链外更改 属性(label, IP 允许列表).

## API 表面

`DeriveClient` 显示命名空格子 APIs :

| 命名空间 | 它会做什么 |
| --- | --- |
| `client.marketData` | 货币(公共、无认证) |
| `client.subaccounts` | 投资组合、职位、差值、贸易历史 |
| `client.orders` | 位置 / 取消/ 查询命令 |
| `client.rfq` | RFQ 取用器(请求-引文-执行)和制作器(引文)流量 |
| `client.spotTransfers` | `transferInternal` (拥有分账户), `transferExternal` (其他钱包), `updateWhitelistedRecipients` |
| `client.positionTransfers` | 由 RFQ 支持 `transferPositions` 同一钱包拥有的子账户之间 |
| `client.withdrawals` | 签名的 L1 退出 |
| `client.deposits` | `contractCall.*` (自保链上)和 `depositAddress.*` (CEX风格) |
| `client.vaults` | 公开读取 + `vaults.shareholder.*` 财务报告和审定财务报表 `vaults.curator.*` |
| `client.sessionKeys` | 创建/ 列表/ 编辑会话密钥 |
| `client.subscriptions` | websocket 频道(召回或激活) |

任何没有包裹的东西都可以到达,完全输入,通过 `client.send(method, params)`。 。 。 .

### 仅使用类型( stub)

如果您只想要端点型号的分接点——每个分接点的请求/响应形状 公共 RPC 方法, 没有运行时客户端 `types/endpoints` 子路径。 它们来自交换机的光子API谱,所以它们留在里面 与活表面相接; 这里没有拉入 `ethers`, (中文(简体) ), `ws`,或任何运行时间.

```ts
import type { EndpointMap, ParamsOf, ResultFor } from '@derivexyz/derive-ts/types/endpoints';

type PlaceParams = ParamsOf<'private/order'>;
type Ticker = ResultFor<'public/get_ticker'>;
// or reach into the map structurally:
type PlaceParamsStructural = EndpointMap['private/order']['request']['params'];
```

用于代码、工具或输入手卷客户端. `EndpointMap` 键入 方法字符串; 每个条目是 `{ request, response }`时 `response` 这是 `{ result } | { error }` JSON-RPC联盟——使用 `ResultFor<M>` 来拉出成功 载荷.

### 订阅

```ts
import { channel } from '@derivexyz/derive-ts';

await client.connect();
const book = channel('orderbook.{instrument_name}.{group}.{depth}', {
  instrument_name: 'ETH-PERP',
  group: '1',
  depth: '10',
});

const sub = await client.subscriptions.subscribe(book, (data) => console.log(data));
// ...later
await sub.unsubscribe();

// Or as an async iterator:
for await (const update of client.subscriptions.stream(channel('trades.{instrument_name}', { instrument_name: 'ETH-PERP' }))) {
  console.log(update);
}
```

## 价值公约(签署前阅读)

-   **价格、数额和收费** 以十进制字符串/数字来传递(例如:. `'1500.5'`) (中文(简体) ). 在线上, SDK 发送小数字符串; 内部签名动作 数据将其缩放为 1e18。 协议运行在 1e12 精度和 _拒绝_ (不切入)小数位数超过12个的值.
-   **提取数额** 只有一个例外——它们属于ERC-20's **本地小数** (例如USDC有6),因为它们是L1支付值.
-   **退款总是付给签字人.** 如果会话键在 退款,资金到会话关键地址,而不是所有者.
-   **存款是两种不同的流动,明确选择如下:**
    -   `deposits.depositAddress.register(...)` 返回决定性地址; 发送 资金来自任何地方, 和交易所扫荡和信用.
    -   `deposits.contractCall.*` 构建在线核准+行动管理器 乙醚交易 `Signer` 你提供.

## 实例

奔跑的 有评论的走道 [`examples/`](https://npmcn.com/package/%40derivexyz/derive-ts/examples)数字 :

```bash
DERIVE_NETWORK=testnet PRIVATE_KEY=0x... npx tsx examples/01-deposit.ts
```

由v3入职流程订购——您的第一个 **存款创建您的账户**, (中文(简体) ), 接下来 **会话密钥**,然后其余部分: `01-deposit`, (中文(简体) ), `02-session-keys`, (中文(简体) ), `03-market-data`, (中文(简体) ), `04-subscribe`, (中文(简体) ), `05-place-order`, (中文(简体) ), `06-rfq-taker`, (中文(简体) ), `07-rfq-maker`, (中文(简体) ), `08-transfers`, (中文(简体) ), `09-withdraw`, (中文(简体) ), `10-vaults`, (中文(简体) ), `11-position-transfers`。 。 。 .

## 网络签名参数( S)

EIP-712域分隔器是从网络的链码和 协议的常数 `Matching` 校验合同; 动作类型 协议常数。 你通常只是通过 `network: 'mainnet' | 'testnet' | 'local'`。指向一个定制部署,通过一个完整的 `NetworkConfig`。 。 。 .

> **安全说明:** 认证信头被命名 `X-Derive*` 在电线上。 留着吧 密管中的私钥; SDK 从不记录密管材料.

## 许可证

麻省理工学院——见 [自由主义](https://npmcn.com/package/%40derivexyz/derive-ts/LICENSE)。 。 。 .

## 常见问题

### @derivexyz/derive-ts 是什么？

Derive v3 交换 API 的脚本 SDK 类型

### 如何安装 @derivexyz/derive-ts？

在项目目录运行 npm install @derivexyz/derive-ts，或使用 pnpm add / yarn add / bun add。

### @derivexyz/derive-ts 支持 TypeScript 吗？

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

### @derivexyz/derive-ts 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @derivexyz/derive-ts 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @derivexyz/derive-ts 可以商用吗？

@derivexyz/derive-ts 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @derivexyz/derive-ts 的下载量有多少？

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

### @derivexyz/derive-ts 还在维护吗？

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