# @gala-chain/gswap-sdk 中文文档

规范地址：https://npmcn.com/package/%40gala-chain/gswap-sdk/

版本：2\.1\.0
npm 元数据更新时间：2026-11-09T17:42:08.968Z
中文译文更新时间：2026-11-15T21:28:53.713Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40gala-chain/gswap-sdk
原文对照：https://npmcn.com/package/%40gala-chain/gswap-sdk/?lang=original

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

- 包体积（解压后）：2.6 MB，106 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：@gala-chain/gala-core-sdk \>=1\.2\.0 \<2
- 首次发布：2025-07-03T16:06:26.498Z
- 最新版本发布：2026-11-09T17:37:16.633Z
- 近 30 天下载量：4221（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：48（近 12 个月 37 个）

## 中文简介

用于与GSwap互动的源开发工具包.

## 安装

```sh
npm install @gala-chain/gswap-sdk
```

也可以使用：`pnpm add @gala-chain/gswap-sdk`、`yarn add @gala-chain/gswap-sdk`、`bun add @gala-chain/gswap-sdk`

## README

# 扫描 SDK

`@gala-chain/gswap-sdk` 是当前 GalaChain DEX 的 SDK 类型脚本 合同。 它使用交易符号来进行池内操作,符号写入 应用程序提供的签名符,并通过链条提交 网关. 交换请求被排入后期应用程序 .

池由交易符号识别: SDK通过 登记和命令 `token0` 财务报告和审定财务报表 `token1` 使用简单的字符串顺序。 这个 公共表面按责任分类:

-   `gSwap.quoting` 运行只读的精确输入和精确输出模拟.
-   `gSwap.swaps` 提交队列 `RequestTrade` (原始内容存档于2018-10-21). DTOs.
-   `gSwap.pools` 读取池、槽、和复合池快照.
-   `gSwap.positions` 读取位置并提交流动性操作.
-   `gSwap.assets` 读取用户余额; `gSwap.symbols` 解决符号.

全部读取和写入通过配置的互换后端 。 SDK 签名 DTO, 帖子写到特定方法的链道后端路由, 返回 (单位:千美元) `SubmittedTransaction`。交换确认被排队;呼叫 `confirm()` 改为 读取应用的贸易或连锁拒绝。 没有捆绑或套接字 服务员,EIP-712只是一种选择 `BrowserWalletSigner`。 。 。 .

每个签名的DTO携带 `dtoOperation` 目 录(续) (单位:千美元)`asset-channel_basic-asset_GalaChainDex:<Method>`:链条拒绝没有它或带有的DTO 另一通电话,这是签名的一部分。 SDK在签字前就设定了 从同一个地方 表格,用于构建路径;您必须先签名的 DSO `withDtoOperation`) (中文(简体) ). 见 [签名和身份](https://npmcn.com/package/%40gala-chain/gswap-sdk/docs/other/signing-and-identity.md)。 。 。 .

## 安装

```bash
npm install @gala-chain/gswap-sdk @gala-chain/gala-core-sdk
```

`@gala-chain/gala-core-sdk` 是一个对等依赖( 范围为 qx1. 2. 0 < 2): 安装在SDK旁边. 用于钱包或应用程序构建的精确版本 .

## 2.0: 签名移动到@gala-chain/gala-core-sdk

自2.0起,签名、运输、钱包助手和基质反光层都生活在 `@gala-chain/gala-core-sdk`该套件不再出口或再出口: 签 名 (`PrivateKeySigner`, (中文(简体) ), `GalaWalletSigner`, (中文(简体) ), `BrowserWalletSigner`页:1 签名和EIP-712原始、运输适配器、故障视图、 从核心软件包中导入独有的按键助手和钱包助手. `GSwap`, DEX API 和 DEX 错误目录留在此处。 旧的 `@gala-chain/gswap-sdk/wallet` 子路径现在 `@gala-chain/gala-core-sdk/wallet`, (中文(简体) ), 和一些识别资料被重新命名(`isGSwapErrorLike` 实值 `isGalaErrorLike`) (中文(简体) ). 整个旧路径到新路径表是在 [`../gala-core-sdk/MIGRATING-FROM-GSWAP.md`](https://npmcn.com/package/%40gala-chain/gala-core-sdk/MIGRATING-FROM-GSWAP.md)· ; 另见 [从0.x移徙](https://npmcn.com/package/%40gala-chain/gswap-sdk/docs/other/migration-from-0.x.md)。 。 。 .

## 快开始

```typescript
import BigNumber from 'bignumber.js'; // a dependency of the SDK; install it in your own app too
import { GSwap } from '@gala-chain/gswap-sdk';
import { PrivateKeySigner } from '@gala-chain/gala-core-sdk';

const signer = new PrivateKeySigner(process.env.GALACHAIN_PRIVATE_KEY!);
const gSwap = new GSwap({ signer, walletAddress: process.env.GALACHAIN_ADDRESS, env: 'stage' });
const quote = await gSwap.quoting.quoteExactInput('GALA', 'GUSDC', '100');
const tx = await gSwap.swaps.swap('GALA', 'GUSDC', quote.feeTier, {
  exactIn: '100',
  // The least you accept (1% under the quote), not the quote itself: the swap is applied a few
  // seconds later and a bound equal to the quote is rejected whenever the price moves in between.
  amountOutMinimum: new BigNumber(quote.amountOut).multipliedBy('0.99').toFixed(),
});
console.log({ mode: tx.mode, uniqueKey: tx.uniqueKey, transactionId: tx.transactionId });
const applied = await tx.confirm();
console.log(applied.result);
```

这个 `env: 'stage'` 预设目标中转后端,以及 `prod` 目标 生产交换后端( e)`prod` 当 `env` 页:1 所有SDK流量使用互换后端. 使用类密钥, 如 `GALA|Unit|none|none` 当符号不是时 可用; SDK 为您解析已注册符号和命令池符号 . 每次写回一个 `SubmittedTransaction`互换确认 `mode === 'queued'`, (中文(简体) ), `result === undefined`和持久 `uniqueKey`; 调用 `confirm()` 读取其应用结果,或 `swaps.confirmSwap(uniqueKey)` 改为 以后仅从持续的关键中解决问题。 流动性继续 通过重读位置状态确认。 请求 `transactionId` 也许 `null` 当 网关不提供一条.

## 市场数据和领导板

公众阅读,不需要签名人:美元价格`market.getPrices`, 1–500 令牌, 分为请求 后端接受,每个在 确切的id它被要求),价格系列(`market.getPriceSeries`窗口 `1D` `1W` `1M` `1Y` `ALL`),平台量(`market.getVolumeSummary`以及贸易竞争季节和 排名(`leaderboard.getSeasons`, (中文(简体) ), `getCurrentSeason`, (中文(简体) ), `getLeaderboard`, (中文(简体) ), `getCurrentLeaderboard`) (中文(简体) ). 见 [市场数据和领导板](https://npmcn.com/package/%40gala-chain/gswap-sdk/docs/tutorial-basics/market-data.md)。 。 。 .

```typescript
const gala = await gSwap.market.getPrice('GALA$Unit$none$none'); // undefined: no entry
const series = await gSwap.market.getPriceSeries('GALA$Unit$none$none', '1W');
const season = await gSwap.leaderboard.getCurrentSeason(); // null between seasons
```

## Onramper 部件 URL

`gSwap.onramper.generateWidgetUrl(request)` 询问已签名的 Onramper (fiat) 的互换后端 (原始内容存档于2017-10-21) (中文(简体) ). Wife URL. 该路线是公开的:请求没有 `Authorization` 头曰. 一个应用程序 仅此需要构建没有完整客户端的小服务 :

```typescript
import { createOnramper } from '@gala-chain/gswap-sdk';

const onramper = createOnramper({ dexBackendBaseUrl: 'https://dex-backend-prod1.defi.gala.com' });
const url = await onramper.generateWidgetUrl({ walletAddress: '0x…', defaultCrypto: 'gala', mode: 'buy' });
```

## 主机和环境预设

SDK有一个网络边界:互换后端. 不对外公开 GalaChain网关直接主机.

| 预设 | 目标 |
| --- | --- |
| `stage` | 中转后端( 预设套件) `dexBackendBaseUrl`(中文(简体) ) |
| `prod` | `https://dex-backend-prod1.defi.gala.com` |

使用 `dexBackendBaseUrl` 用于测试或私人部署.

## 实时流

`gSwap.stream` 是实时流的客户端( r)`wss://…/ws`,JSON-RPC 2.0):活期互换,流动性 增加/重新移动/收集、池和平衡变化、新池和区块,自动重新连接.

```typescript
import { GSwap } from '@gala-chain/gswap-sdk';

const gSwap = new GSwap({ env: 'stage' });
await gSwap.stream.connect();
await gSwap.stream.subscribeLiquidity((e) => console.log(e.action, e.owner, e.amount0, e.amount1));
```

见 [实时流导](https://npmcn.com/package/%40gala-chain/gswap-sdk/docs/tutorial-basics/realtime-stream.md)。 。 。 .

## 签字人和身份

| 签名 | 计划 | 由链条解决的身份 |
| --- | --- | --- |
| `PrivateKeySigner` | GalaChain 本地签名 | 从私钥取回 |
| `GalaWalletSigner` | 土著 `gala_signChainDto`; 选入 `personal-sign` 需要一个 Gala 钱包建筑, 以标记空 DTO (请参见签名和身份) | 选中账户( E)`0x...`, (中文(简体) ), `eth|...`, (中文(简体) ), `client|...`(中文(简体) ) |
| `BrowserWalletSigner` | EIP-1193 (英语) `personal_sign`; 选入 `{ scheme: 'eip712' }` (单位:千美元)`eth_signTypedData_v4`(中文(简体) ) | 选中的Ethereum 账户 (`eip712` 决议a `client|` (别名) |

签名器由 `@gala-chain/gala-core-sdk`而不是通过这个包裹. 原生签名是服务器密钥和当前Gala钱包的默认. 浏览器钱包 个人签名 : 赤裸的序列式 DTO( 钱包适用) eIP-191 标题),并将该标题作为 DTO 的 `prefix`,这是什么 当它恢复了标志器时,链会预留。 EIP-712正在选入 `BrowserWalletSigner` 页:1 `RequestTrade`, (中文(简体) ), `AddLiquidity`, (中文(简体) ), `RemoveLiquidity` 财务报告和审定财务报表 `CollectPositionFees` (单位:千美元)`CreatePool` 仍然使用个人标志;不是 默认而不是加拉钱包路径的一部分。 见 [签名和身份](https://npmcn.com/package/%40gala-chain/gswap-sdk/docs/other/signing-and-identity.md)。 。 。 .

## 钱包和应用程序整合

SDK核心为平台中性(仅限 `fetch`, (中文(简体) ), `globalThis.crypto` 和船舶 构建钱包或应用程序需要的块,每个块都放在适配器后: `confirmAppliedTrade` (应用结果) 投票次数 `AbortSignal`, (中文(简体) ), `AppliedTradeError`, (中文(简体) ), `PendingSwapStore` (同步) `StorageAdapter`· ; `storageAdapterFromChromeStorage(chrome.storage.local)` 申请延期, `webStorageAdapter(localStorage)` 为网络应用程序, `DexFees` (干伦费引出), `swaps.swapShadow` (暗中交换通过) `X-Shadow`),一个可配置 `uniqueKeyPrefix`,并注入的实时流 `WebSocket` (还有 `apiKey` 页:1 服务器侧客户端). 见 [应用程序和钱包整合](https://npmcn.com/package/%40gala-chain/gswap-sdk/docs/other/app-integration.md)。 。 。 .

错误带有稳定 `code` 和平顶 `params` 应用本地化; `classifyFailure`, (中文(简体) ), `pendingSwapFateFor`, (中文(简体) ), `isNoMarket` 其他决定者回答来自 代码,绝不来自消息文本([处理错误](https://npmcn.com/package/%40gala-chain/gswap-sdk/docs/other/error-handling.md)) (中文(简体) ). App-shell 代码 不能装入 SDK 导入钱包助手 `@gala-chain/gala-core-sdk/wallet` (单位:千美元)[套装大小](https://npmcn.com/package/%40gala-chain/gswap-sdk/docs/other/bundle-size.md)) (中文(简体) ). 票价算术,包括合同 距离规则,在 [勾选和价格数学](https://npmcn.com/package/%40gala-chain/gswap-sdk/docs/other/tick-and-price-math.md)。 。 。 .

## 文档

开始 [开始](https://npmcn.com/package/%40gala-chain/gswap-sdk/docs/getting-started.md),然后遵循教程 页:1 [引用](https://npmcn.com/package/%40gala-chain/gswap-sdk/docs/tutorial-basics/quoting.md), (中文(简体) ), [贸易](https://npmcn.com/package/%40gala-chain/gswap-sdk/docs/tutorial-basics/trading.md) 财务报告和审定财务报表 [流动资金管理](https://npmcn.com/package/%40gala-chain/gswap-sdk/docs/tutorial-basics/liquidity-management.md)。 。 。 .

对于应用程序和钱包: [处理错误](https://npmcn.com/package/%40gala-chain/gswap-sdk/docs/other/error-handling.md) (错误) 目录, `classifyFailure`, 本地化), [应用和钱包集成](https://npmcn.com/package/%40gala-chain/gswap-sdk/docs/other/app-integration.md) (待售存储, 有线选择,签名原始,黑暗交换), [签名和身份](https://npmcn.com/package/%40gala-chain/gswap-sdk/docs/other/signing-and-identity.md), (中文(简体) ), [套装大小](https://npmcn.com/package/%40gala-chain/gswap-sdk/docs/other/bundle-size.md) (单位:千美元) `@gala-chain/gala-core-sdk/wallet` 子路径和外壳安全助手)和 [滴答和价格数学](https://npmcn.com/package/%40gala-chain/gswap-sdk/docs/other/tick-and-price-math.md)中的 API 引用来自 包裹的TSDoc。 Galachain.github.io/gswap-sdk的站点描述了1.x API 只有这个 工作实例如下: `examples/cli`, (中文(简体) ), `examples/full_dex` 财务报告和审定财务报表 `examples/demos` 包(可运行) 互换的脚本,引文,池子,流动性位置,收费,市场数据,领导板和池子 ) (掌声).

## 许可证

这个SDK是在Apache许可证2.0下提供的. GalaTM、GalaChainTM、和 相關標記是Blockchain游戏伙伴公司的商标. 这个软件是 提供“AS IS”,无任何保证.

## 常见问题

### @gala-chain/gswap-sdk 是什么？

用于与GSwap互动的源开发工具包\.

### 如何安装 @gala-chain/gswap-sdk？

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

### @gala-chain/gswap-sdk 支持 TypeScript 吗？

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

### @gala-chain/gswap-sdk 支持 ESM 还是 CommonJS？

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

### @gala-chain/gswap-sdk 可以商用吗？

@gala-chain/gswap-sdk 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @gala-chain/gswap-sdk 的下载量有多少？

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

### @gala-chain/gswap-sdk 还在维护吗？

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