@ derivexyz/ derive- ts
脚本 SDK 类型 衍生 v3 交换 API — 一个已键入 市场数据、订单、报告调查表、转账、提款、存款、金库、, 会话密钥和 websocket 订阅 .
更详细的文件见 衍生 v3 API 参考。 。 。 .
安装
npm install @derivexyz/derive-ts ethers ws
快速启动
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和前端,做 没有 运送账户所有者的钥匙。 登记范围 语句 一次(由所有者签名),然后只用该键运行:
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,或任何运行时间.
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> 来拉出成功
载荷.
订阅
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/数字 :
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 从不记录密管材料.
许可证
麻省理工学院——见 自由主义。 。 。 .