# @circle-fin/provider-gateway-v1 中文文档

规范地址：https://npmcn.com/package/%40circle-fin/provider-gateway-v1/

版本：1\.7\.1
npm 元数据更新时间：2026-11-05T17:18:18.813Z
中文译文更新时间：2026-11-09T16:38:41.409Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40circle-fin/provider-gateway-v1
原文对照：https://npmcn.com/package/%40circle-fin/provider-gateway-v1/?lang=original

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

- 包体积（解压后）：2.4 MB，11 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：13 个
- 首次发布：2026-04-21T22:16:26.940Z
- 最新版本发布：2026-11-05T17:18:18.620Z
- 近 30 天下载量：33415（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：23（近 12 个月 23 个）

## 中文简介

Circle's Gateway v1提供商,用于具有统一平衡管理功能的即时跨链USDC传输

## 安装

```sh
npm install @circle-fin/provider-gateway-v1
```

也可以使用：`pnpm add @circle-fin/provider-gateway-v1`、`yarn add @circle-fin/provider-gateway-v1`、`bun add @circle-fin/provider-gateway-v1`

## README

# 网关 v1 提供者

[![npm version](https://badge.fury.io/js/@circle-fin%2Fprovider-gateway-v1.svg)](https://badge.fury.io/js/@circle-fin%2Fprovider-gateway-v1) [![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![Discord](https://img.shields.io/discord/473781666251538452?label=Discord&logo=discord)](https://discord.com/invite/buildoncircle)

**Circle 的网关 v1 统一平衡套件提供者**

_即时跨链的USDC转移,跨链统一平衡管理._

## 目录

-   [网关 v1 提供者](https://npmcn.com/package/%40circle-fin/provider-gateway-v1/#readme-gateway-v1-provider)
    -   [目录](https://npmcn.com/package/%40circle-fin/provider-gateway-v1/#readme-table-of-contents)
    -   [概览](https://npmcn.com/package/%40circle-fin/provider-gateway-v1/#readme-overview)
        -   [为什么是Gateway v1 提供者?](https://npmcn.com/package/%40circle-fin/provider-gateway-v1/#readme-why-gateway-v1-provider)
    -   [安装](https://npmcn.com/package/%40circle-fin/provider-gateway-v1/#readme-installation)
    -   [快速启动](https://npmcn.com/package/%40circle-fin/provider-gateway-v1/#readme-quick-start)
        -   [备选案文1:统一平衡套件(建议)](https://npmcn.com/package/%40circle-fin/provider-gateway-v1/#readme-option-1-with-unified-balance-kit-recommended)
        -   [备选案文2:直接提供者的使用](https://npmcn.com/package/%40circle-fin/provider-gateway-v1/#readme-option-2-direct-provider-usage)
    -   [特征](https://npmcn.com/package/%40circle-fin/provider-gateway-v1/#readme-features)
    -   [支持的链条](https://npmcn.com/package/%40circle-fin/provider-gateway-v1/#readme-supported-chains)
    -   [用法实例](https://npmcn.com/package/%40circle-fin/provider-gateway-v1/#readme-usage-examples)
        -   [基本业务](https://npmcn.com/package/%40circle-fin/provider-gateway-v1/#readme-basic-operations)
        -   [余额查询](https://npmcn.com/package/%40circle-fin/provider-gateway-v1/#readme-balance-queries)
    -   [处理错误](https://npmcn.com/package/%40circle-fin/provider-gateway-v1/#readme-error-handling)
    -   [支出过程](https://npmcn.com/package/%40circle-fin/provider-gateway-v1/#readme-spend-process)
    -   [与统一平衡套件合并](https://npmcn.com/package/%40circle-fin/provider-gateway-v1/#readme-integration-with-unified-balance-kit)
    -   [发展](https://npmcn.com/package/%40circle-fin/provider-gateway-v1/#readme-development)
    -   [许可证](https://npmcn.com/package/%40circle-fin/provider-gateway-v1/#readme-license)

## 概览

Gateway v1 提供商是 Circle 的 Gateway 协议的强型执行,它能够 **瞬间跨链USDC转让** 对各支持区块链网络实行统一平衡管理.

虽然主要设计为电力 [统一余额套件](https://www.npmjs.com/package/@circle-fin/unified-balance-kit),该提供者也可以使用 **直接在应用程序中** 需要精细控制 Gateway 操作 或想要整合 Gateway 没有完整的 Stablecoin Kits 框架.

### 为什么是Gateway v1 提供者?

-   **\* 即时跨链移动**: 在一个流中从多个源链和目的地取出薄荷
-   **统一平衡模式**: 存款一次,花在任何地方——不等待连锁店之间的终结
-   **QQ Circle 的官方协议**: 用于安全和可靠性的用户圈网关基础设施
-   **\* 类型安全操作**: 建有 TypeScript 严格模式并全面验证
-   **\* 直接融合**: 使用独立或自定义的管弦逻辑

## 安装

```bash
npm install @circle-fin/provider-gateway-v1
# or
yarn add @circle-fin/provider-gateway-v1
```

> **说明**: 默认情况下包含此提供者 [统一余额套件](https://www.npmjs.com/package/@circle-fin/unified-balance-kit)。如果需要进行自定义的Gateway集成,可以导入此提供者.

## 快速启动

### 备选案文1:统一平衡套件(建议)

```typescript
import {
  createUnifiedBalanceKitContext,
  deposit,
  spend,
  getBalances,
} from '@circle-fin/unified-balance-kit'

// Provider included by default
const context = createUnifiedBalanceKitContext()

const result = await deposit(context, {
  from: { adapter, chain: 'Ethereum' },
  amount: '100',
})

const spendResult = await spend(context, {
  amount: '50',
  from: { adapter, allocations: { amount: '50', chain: 'Ethereum' } },
  to: { adapter, chain: 'Base' },
})

const balances = await getBalances(context, { sources: { adapter } })
```

### 备选案文2:直接提供者的使用

```typescript
import { createGatewayV1Provider } from '@circle-fin/provider-gateway-v1'

const provider = createGatewayV1Provider()

// Get supported chains
const chains = provider.getSupportedChains()

// Deposit USDC on a chain
await provider.deposit({
  from: { adapter, chain: 'Ethereum' },
  amount: '100',
  token: 'USDC',
})

// Estimate spend fees
const estimate = await provider.estimateSpend({
  from: {
    adapter,
    allocations: { amount: '100', chain: 'Ethereum' },
  },
  to: { adapter, chain: 'Base' },
  token: 'USDC',
})

// Execute spend (mint on destination)
const result = await provider.spend({
  from: {
    adapter,
    allocations: { amount: '100', chain: 'Ethereum' },
  },
  to: { adapter, chain: 'Base' },
  token: 'USDC',
})

// Query balances
const balances = await provider.getBalances({
  token: 'USDC',
  sources: { adapter, chains: ['Ethereum', 'Base'] },
})
```

## 特征

-   ✅ **存款** - 将USDC存入任何支持链的Gateway账户
-   ✅ **支出(薄荷)** - 从一条或多条链子上拉出 目的地有薄荷
-   ✅ **余额查询** - 合计和每链USDC余额
-   ✅ **代表团** - 为网关账户增加/调离代表
-   ✅ **基金移除** - 启动并全部撤出网关
-   ✅ **多来源支出** - 在一次行动中从多个链中分配金额
-   ✅ **类型安全** - 配有结构化 KitError 处理的完整类型脚本支持

## 支持的链条

提供者支持所有带有Gateway v1配置的链条. 打电话 `getSupportedChains()` 完整名单。 主网的例子包括: **以利亚**, (中文(简体) ), **坐标**, (中文(简体) ), **基础**, (中文(简体) ), **索拉纳**; 测试网实例包括 **伊特鲁姆·塞波利亚**, (中文(简体) ), **塞波利亚基地**, (中文(简体) ), **索拉纳·德夫内**。 。 。 .

```typescript
import { createGatewayV1Provider } from '@circle-fin/provider-gateway-v1'

const provider = createGatewayV1Provider()
const chains = provider.getSupportedChains()
console.log(chains.map((c) => c.name))
```

## 用法实例

### 基本业务

```typescript
const provider = createGatewayV1Provider()

// Deposit
await provider.deposit({
  from: { adapter, chain: 'Ethereum' },
  amount: '100',
  token: 'USDC',
})

// Spend (single source)
const result = await provider.spend({
  from: { adapter, allocations: { amount: '50', chain: 'Ethereum' } },
  to: { adapter, chain: 'Base' },
  token: 'USDC',
})
console.log(result.txHash, result.explorerUrl)

// Spend (multi-source)
const multiResult = await provider.spend({
  from: {
    adapter,
    allocations: [
      { amount: '30', chain: 'Ethereum' },
      { amount: '20', chain: 'Base' },
    ],
  },
  to: { adapter, chain: 'Avalanche' },
  token: 'USDC',
})
```

### 余额查询

```typescript
const provider = createGatewayV1Provider()

// By adapter
const balances = await provider.getBalances({
  token: 'USDC',
  sources: { adapter, chains: ['Ethereum', 'Base'] },
})

// By account address (read-only)
const balancesByAddress = await provider.getBalances({
  token: 'USDC',
  sources: { address: '0x...', chains: ['Ethereum', 'Base'] },
})

// Include pending deposits
const withPending = await provider.getBalances({
  token: 'USDC',
  sources: { adapter },
  includePending: true,
})
```

## 处理错误

提供者抛出结构化 `KitError` 验证和执行失败的实例 :

```typescript
import { createGatewayV1Provider } from '@circle-fin/provider-gateway-v1'
import { isKitError } from '@circle-fin/unified-balance-kit'

const provider = createGatewayV1Provider()

try {
  const result = await provider.spend(params)
  console.log('Success:', result.txHash)
} catch (error) {
  if (isKitError(error)) {
    console.error(`Error ${error.code}: ${error.name}`, error.message)
    if (error.recoverability === 'RESUMABLE' && error.cause?.trace) {
      const { attestation, signature, missingTokenAccounts } = error.cause
        .trace as {
        attestation: string
        signature: string
        missingTokenAccounts?: { tokenAccount: string; mint: string }[]
      }
      if (missingTokenAccounts?.length) {
        // Solana only: create the listed token accounts first, then retry
        // with the same attestation. Retrying now fails the same way.
        throw error
      }
      // Mint failed after transfer—retry with config.retry
      await provider.spend({
        ...params,
        config: { retry: { attestation, signature } },
      })
    }
  }
  throw error
}
```

## 支出过程

Gateway v1 提供者处理全部花 (mint) 流量 :

1.  **估计数** - 从 Gateway API 获取费用估计
2.  **签名** - 为每个源链构建并签署燃烧意图
3.  **获取验证** - 提交经签名的意向,提交API网关,接受证明
4.  **薄荷** - 使用证明书执行目的地链上的薄荷交易

当薄荷步骤在获取证明后失败( 资金锁定), 提供者会扔出一个 `KitError` 与 `recoverability: 'RESUMABLE'` 财务报告和审定财务报表 `attestation`编号 :`signature` 内 `cause.trace`启用 `config.retry` 重新尝试薄荷而不重运行取回.

在索拉纳岛上,薄荷不会创建收款人代币账户. 下面的两个错误都列出缺少的账户 `cause.trace.missingTokenAccounts`如果缺失的账户属于圆形收费接受者,则联系圆形支持.

-   **转移前** (非前导者花费和 `estimateSpend`:提供者在要求证明之前先检查收信人代号账户. 缺少的账户丢出 `VALIDATION_FAILED` `KitError` 这是 `FATAL`。未提交;创建账户,然后调用 `spend` 再来一次.
-   **薄荷时间** (例如关于 `config.retry`: 缺失的账户丢出 `VALIDATION_FAILED` `KitError` 这是 `RESUMABLE`创建账户,然后重试 `config.retry`。在它们存在之前重试失败,错误相同.

## 与统一平衡套件合并

此提供者是专门为 [统一余额套件](https://www.npmjs.com/package/@circle-fin/unified-balance-kit)数字 :

```typescript
import { UnifiedBalanceKit } from '@circle-fin/unified-balance-kit'
import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'

const kit = new UnifiedBalanceKit()
const adapter = createViemAdapterFromPrivateKey({
  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
})

// Monitor gateway events
kit.on('*', (event) => console.log('Event:', event))
kit.on('gateway.deposit.succeeded', (payload) =>
  console.log('Deposit:', payload.data),
)
kit.on('gateway.spend.succeeded', (payload) =>
  console.log('Spend succeeded:', payload.data.txHash),
)

// Execute operations
await kit.deposit({ from: { adapter, chain: 'Ethereum' }, amount: '100' })
const result = await kit.spend({
  amount: '50',
  from: { adapter, allocations: { amount: '50', chain: 'Ethereum' } },
  to: { adapter, chain: 'Base' },
})
```

## 发展

这个包是"稳定币"(Stablecoin Kits monorepo)的一部分.

```bash
# Build
nx build @circle-fin/provider-gateway-v1

# Test
nx test @circle-fin/provider-gateway-v1
```

## 许可证

这个项目根据Apache 2.0许可证获得许可. 联系人 [支助](https://help.circle.com/s/submit-ticket) 详细情况.

* * *

**准备好跨链USDC操作了吗?**

[加入磁盘](https://discord.com/invite/buildoncircle) 二. 支助 [访问我们的救世主](https://help.circle.com/s/submit-ticket)

_由 Circle 创建_

## 常见问题

### @circle-fin/provider-gateway-v1 是什么？

Circle's Gateway v1提供商,用于具有统一平衡管理功能的即时跨链USDC传输

### 如何安装 @circle-fin/provider-gateway-v1？

在项目目录运行 npm install @circle-fin/provider-gateway-v1，或使用 pnpm add / yarn add / bun add。

### @circle-fin/provider-gateway-v1 支持 TypeScript 吗？

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

### @circle-fin/provider-gateway-v1 支持 ESM 还是 CommonJS？

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

### @circle-fin/provider-gateway-v1 需要什么版本的 Node\.js？

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

### @circle-fin/provider-gateway-v1 可以商用吗？

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

### @circle-fin/provider-gateway-v1 的下载量有多少？

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

### @circle-fin/provider-gateway-v1 还在维护吗？

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