hydric-gateway-js-ts-sdk-user

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

hydric Gateway SDK | Orientation Guide

hydric Gateway SDK | 入门指南

You are an SDK Integration Specialist for

@hydric/gateway

. This skill helps you quickly orient yourself and use the SDK like you built it.

你是

@hydric/gateway

的SDK集成专家。该技能可帮助你快速上手，像开发者一样熟练使用这款SDK。

📚 Where to Find Things

📚 资源查找指南

What You Need	Where to Look
Full SDK Docs	https://docs.hydric.org/sdk-reference/typescript
Live Docs MCP Server	https://docs.hydric.org/mcp
Source Code	https://github.com/hydric-org/gateway-sdk/tree/main/sdks/typescript
NPM Package	`@hydric/gateway`
Supported Chains	https://docs.hydric.org/overview/supported-blockchains
Basket IDs	https://docs.hydric.org/sdk-reference/typescript/token-baskets#available-baskets
Supported Protocols	https://docs.hydric.org/overview/supported-protocols

所需资源	查找位置
完整SDK文档	https://docs.hydric.org/sdk-reference/typescript
在线文档MCP服务器	https://docs.hydric.org/mcp
源代码	https://github.com/hydric-org/gateway-sdk/tree/main/sdks/typescript
NPM包	`@hydric/gateway`
支持的区块链	https://docs.hydric.org/overview/supported-blockchains
资产组合ID	https://docs.hydric.org/sdk-reference/typescript/token-baskets#available-baskets
支持的协议	https://docs.hydric.org/overview/supported-protocols

Installation

安装

the SDK is available as an npm package. So you can install it using npm, yarn, pnpm, bun, etc. Just run:

bash

npm install @hydric/gateway

Node version >= 18 is recommended.

该SDK以npm包形式提供，你可以使用npm、yarn、pnpm、bun等包管理器进行安装，执行以下命令即可：

bash

npm install @hydric/gateway

建议使用Node.js 18及以上版本。

🎯 Mental Model: Resources

🎯 核心概念：资源架构

The SDK has one client and some resources:

javascript

import { HydricGateway } from "@hydric/gateway";

const hydric = new HydricGateway({
  apiKey: process.env.HYDRIC_API_KEY,
});

// The resources:
hydric.multichainTokens; // Multi-chain token aggregation
hydric.singleChainTokens; // Single-chain token operations (faster)
hydric.tokenBaskets; // Curated token baskets of many sectors

该SDK包含一个客户端和若干资源模块：

javascript

import { HydricGateway } from "@hydric/gateway";

const hydric = new HydricGateway({
  apiKey: process.env.HYDRIC_API_KEY,
});

// 资源模块:
hydric.multichainTokens; // 多链代币聚合
hydric.singleChainTokens; // 单链代币操作（速度更快）
hydric.tokenBaskets; // 各领域的精选代币组合

Token Resource Selection Rule

资源模块选择规则

User mentions a specific chain? → Use
```
singleChainTokens
```
User wants global view? → Use
```
multichainTokens
```
User wants curated groups (stablecoins, BTCs, LSTs)? → Use
```
tokenBaskets
```

用户提及特定区块链？→ 使用
```
singleChainTokens
```
用户需要全局视角？→ 使用
```
multichainTokens
```
用户需要精选代币组（稳定币、BTC类资产、LST等）？→ 使用
```
tokenBaskets
```

⚡ Quick Start Pattern

⚡ 快速入门示例

javascript

// 1. Initialize
const hydric = new HydricGateway({ apiKey: "sk_..." });

// 2. Call a resource method
const { tokens } = await hydric.multichainTokens.search({
  search: "USDC",
  config: { limit: 10 },
});

// 3. Handle errors
try {
  const data = await hydric.tokenBaskets.getSingleChainById({
    chainId: 8453,
    basketId: "usd-stablecoins",
  });
} catch (error) {
  if (error instanceof HydricRateLimitError) {
    /* backoff */
  }
  if (error instanceof HydricNotFoundError) {
    /* handle not found */
  }
}

javascript

// 1. 初始化客户端
const hydric = new HydricGateway({ apiKey: "sk_..." });

// 2. 调用资源方法
const { tokens } = await hydric.multichainTokens.search({
  search: "USDC",
  config: { limit: 10 },
});

// 3. 错误处理
try {
  const data = await hydric.tokenBaskets.getSingleChainById({
    chainId: 8453,
    basketId: "usd-stablecoins",
  });
} catch (error) {
  if (error instanceof HydricRateLimitError) {
    /* 退避重试 */
  }
  if (error instanceof HydricNotFoundError) {
    /* 处理资源不存在的情况 */
  }
}

📦 Resource Cheat Sheet

📦 资源模块速查表

multichainTokens

multichainTokens

When: User wants tokens across ALL chains or multiple chains at once. Methods:

list()

search({ search })

适用场景：用户需要查询所有链或多条链上的代币
方法：

list()

search({ search })

singleChainTokens

singleChainTokens

When: User specified ONE chain for getting tokens
Methods:

list(chainId, params)

search(chainId, { search })

适用场景：用户指定单条区块链查询代币
方法：

list(chainId, params)

search(chainId, { search })

tokenBaskets

tokenBaskets

When: User wants curated groups of tokens (stablecoins, BTCs, LSTs)
Methods:

```
list()
```
- All baskets
```
getMultiChainById({ basketId })
```
- Basket across chains

getSingleChainById({ chainId, basketId })

- Basket on one chain

适用场景：用户需要获取精选代币组（稳定币、BTC类资产、LST等）
方法:

```
list()
```
- 获取所有代币组合
```
getMultiChainById({ basketId })
```
- 获取跨链代币组合

getSingleChainById({ chainId, basketId })

- 获取单链代币组合

🚨 Critical Gotchas

🚨 关键注意事项

1. Method Signatures Vary

1. 方法签名存在差异

javascript

// Multi-chain: params object only
hydric.multichainTokens.list({ config, filters });

// Single-chain: chainId FIRST, then params
hydric.singleChainTokens.list(8453, { config, filters });

javascript

// 多链：仅传入参数对象
hydric.multichainTokens.list({ config, filters });

// 单链：第一个参数为chainId，随后是参数对象
hydric.singleChainTokens.list(8453, { config, filters });

2. Addresses Are Always Lowercase

2. 地址统一为小写

All responses return lowercase addresses. The API accepts any case but normalizes responses to lowercase.

所有响应返回的地址均为小写格式。API接受任意大小写的地址输入，但会将响应统一转换为小写。

3. Pagination Pattern

3. 分页实现方式

javascript

let cursor = null;
do {
  const { tokens, nextCursor } = await hydric.multichainTokens.list({
    config: { cursor, limit: 100 },
  });
  cursor = nextCursor; // null when done
} while (cursor);

javascript

let cursor = null;
do {
  const { tokens, nextCursor } = await hydric.multichainTokens.list({
    config: { cursor, limit: 100 },
  });
  cursor = nextCursor; // 数据全部获取完成后为null
} while (cursor);

4. Error Classes

4. 错误类

Import and check with

instanceof

```
HydricInvalidParamsError
```
- Client-side validation failed
```
HydricUnauthorizedError
```
- API key issue
```
HydricNotFoundError
```
- Specific requested resource doesn't exist
```
HydricRateLimitError
```
- Too many requests for the API Key tier
```
HydricError
```
- Generic error

需导入错误类并通过

instanceof

进行判断：

```
HydricInvalidParamsError
```
- 客户端参数验证失败
```
HydricUnauthorizedError
```
- API密钥相关问题
```
HydricNotFoundError
```
- 请求的特定资源不存在
```
HydricRateLimitError
```
- API密钥请求次数超限
```
HydricError
```
- 通用错误

🧭 Common Workflows

🧭 常见工作流

Workflow 1: Global Token Search

工作流1：全局代币搜索

javascript

// User: "Find USDC everywhere"
const { tokens } = await hydric.multichainTokens.search({ search: "USDC" });
// Each token has: addresses: [{ chainId: 1, address: '0x...' }, ...]

javascript

// 用户需求："查找所有链上的USDC"
const { tokens } = await hydric.multichainTokens.search({ search: "USDC" });
// 每个代币包含：addresses: [{ chainId: 1, address: '0x...' }, ...]

Workflow 2: Chain-Specific List

工作流2：单链代币列表

javascript

// User: "Show me top tokens on Base ordered by tvl"
const { tokens } = await hydric.singleChainTokens.list(8453, {
  config: { orderBy: { field: "tvl", direction: "desc" } },
});

javascript

// 用户需求："展示Base链上按TVL排序的顶级代币"
const { tokens } = await hydric.singleChainTokens.list(8453, {
  config: { orderBy: { field: "tvl", direction: "desc" } },
});

Workflow 3: Basket Discovery

工作流3：代币组合查询

javascript

// User: "Get all stablecoins on Ethereum"
const { basket } = await hydric.tokenBaskets.getSingleChainById({
  chainId: 1,
  basketId: "usd-stablecoins",
});
// basket.tokens = [{ symbol: 'USDC', address: '0x...' }, ...]

javascript

// 用户需求："获取以太坊上的所有稳定币"
const { basket } = await hydric.tokenBaskets.getSingleChainById({
  chainId: 1,
  basketId: "usd-stablecoins",
});
// basket.tokens = [{ symbol: 'USDC', address: '0x...' }, ...]

🛠️ Implementation Checklist

🛠️ 开发检查清单

🔍 Quick Method Lookup

🔍 方法快速查询表

Task	Code
List tokens globally	`hydric.multichainTokens.list({ config, filters })`
List tokens on chain	`hydric.singleChainTokens.list(chainId, { config, filters })`
Search globally	`hydric.multichainTokens.search({ search, config })`
Search on chain	`hydric.singleChainTokens.search(chainId, { search, config })`
Get all baskets	`hydric.tokenBaskets.list()`
Get basket (multi-chain)	`hydric.tokenBaskets.getMultiChainById({ basketId })`
Get basket (single chain)	`hydric.tokenBaskets.getSingleChainById({ chainId, basketId })`

任务	代码示例
获取全局代币列表	`hydric.multichainTokens.list({ config, filters })`
获取单链代币列表	`hydric.singleChainTokens.list(chainId, { config, filters })`
全局代币搜索	`hydric.multichainTokens.search({ search, config })`
单链代币搜索	`hydric.singleChainTokens.search(chainId, { search, config })`
获取所有代币组合	`hydric.tokenBaskets.list()`
获取跨链代币组合	`hydric.tokenBaskets.getMultiChainById({ basketId })`
获取单链代币组合	`hydric.tokenBaskets.getSingleChainById({ chainId, basketId })`

📖 When You Need More

📖 更多资源获取

Full parameter docs: https://docs.hydric.org/sdk-reference/typescript
Docs MCP Server: Use the MCP server at https://docs.hydric.org/mcp for using the docs easily
Source code: https://github.com/hydric-org/gateway-sdk/tree/main/sdks/typescript

TypeScript types: Import from

'@hydric/gateway'

(e.g.,

MultiChainTokenMetadata

)

完整参数文档：https://docs.hydric.org/sdk-reference/typescript
文档MCP服务器：访问https://docs.hydric.org/mcp可更便捷地使用文档
源代码：https://github.com/hydric-org/gateway-sdk/tree/main/sdks/typescript
TypeScript类型定义：从
```
'@hydric/gateway'
```
导入（例如
```
MultiChainTokenMetadata
```
）

🎯 Golden Rules

🎯 黄金法则

Single-chain = singleChainTokens. Always prefer it when the chain is known.
ChainId first for single-chain methods, params object first for multi-chain.
Always lowercase when comparing addresses.
Paginate if you're fetching more than 100 results.
Catch errors with
```
instanceof
```
checks for precise handling if needed.

Use this skill to quickly:

✅ Choose the right resource
✅ Remember method signatures
✅ Recall critical gotchas
✅ Know where to find complete docs

单链需求 = singleChainTokens。当明确区块链时，优先使用该模块。
单链方法需先传chainId，多链方法则先传参数对象。
对比地址时务必使用小写。
如果获取超过100条结果，必须实现分页。
如需精准处理错误，使用instanceof判断错误类型。

借助该技能，你可以快速：

✅ 选择正确的资源模块
✅ 牢记方法签名
✅ 掌握关键注意事项
✅ 知道何处查找完整文档