# @aifinpay/agent 中文文档

规范地址：https://npmcn.com/package/%40aifinpay/agent/

版本：2\.14\.1
npm 元数据更新时间：2026-11-07T11:21:03.555Z
中文译文更新时间：2026-11-06T08:03:12.764Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.1 MB，148 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：8 个
- 首次发布：2026-05-07T23:20:06.074Z
- 最新版本发布：2026-11-07T11:21:03.381Z
- 近 30 天下载量：4013（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：53（近 12 个月 53 个）

## 中文简介

AiFinPay SDK用于全球代理护照身份和自主AI代理的路线验证的AIFP-1/AIFP-2结算.

## 安装

```sh
npm install @aifinpay/agent
```

也可以使用：`pnpm add @aifinpay/agent`、`yarn add @aifinpay/agent`、`bun add @aifinpay/agent`

## README

# @aifinpay/代理(节点/类型脚本)

签名的AIFP-1 `fetchPaid` 流支持所有者选择的 v1.4 支付链 . 多边形是默认的; 选择另一个带有 `v14.chain`。 。 。 . 客户描述符不是生产批准:付款可用 由已安装的部署登记册、运行时间核查和 后端/商机能力。 运行时间、 签名人、 令牌、 RPC 链和当前 特征检查仍然是强制性的,同时还有持久的广播前期刊和 明确本地天然气预算。 源头建设和测试没有建立现场 接受付款.

本地购买需要新的独立 `nativeUsdPrice` 给POL、ETH、AVAX、, 选定链条上的 BNB 或 XRP 。 稳定币使用独立的被绑符 地址和小数。 美元微单位保持不变; `token_settlement` 绑定 精确6/18-十进制符号单位和每条包含毛额的条与签名的毛 18-十进制符号需要这个元数据; 遗产 6-十进制 引文仍然被接受。 通过 SDK 能力 API 检查流动资产 并安装了部署登记册.

`maxGasWei` 包括核准加结算。 OP链(Base/optimism/Unichain) 包括缓冲L1/操作器估计数; Nitro(Arbitrum/Robinhood)已包含 rPC 估计中母数据气体,所以它被计算一次。 业务方案费用 块签名。 这些是飞行前的估计,而不是包含时间的保证. 目前的管理概况仍可变;接收和回收政策不变. 见 [付款配置和回收](https://npmcn.com/package/%40aifinpay/agent/PAYMENT_RECEIPTS.md)。 。 。 .

### 图片和NEAR部署支助

节点 SDK 生成已安装的 Apto 和 NEAR 部署针 `@aifinpay/deployments` 软件包。 钱包和代理护照已经 为两个家庭提供识别资料。 明确选择部署元数据 :

```ts
import { getAptosDeployment, getNearDeployment, resolveAptosDeployment } from "@aifinpay/agent";

const aptos = getAptosDeployment({ environment: "prod", network: "mainnet" });
const near = getNearDeployment({ environment: "dev", network: "testnet" });
// Selection additionally requires settlementEnabled in the packaged record.
const selected = resolveAptosDeployment({ environment: "prod", network: "mainnet", version: "v1.4" });
```

`get*Deployment` 允许只读检查残疾记录. `resolveAptosDeployment` 财务报告和审定财务报表 `resolveNearDeployment` 否认已废弃的记录, 未知的网络、 环境不匹配和不支持的版本; 无遗留 选择倒置或默认网络 。 Aptos 指针包括模块散列 引用 ABI 文摘和每个网络来源。 近地针包括: • 理事会成员不被视为治理当局. 见 [自动](https://npmcn.com/package/%40aifinpay/deployments/registry/splitter/aptos/README.md) 财务报告和审定财务报表 [没有](https://npmcn.com/package/%40aifinpay/deployments/registry/splitter/near/README.md) 登记册指南.

**Aptos 或 NEAR 不执行付款执行 .** 这些解析器读取 已装入元数据,而不是当前链条状态。 两个家庭都不是EVM `v14.chain`, (中文(简体) ), 财务报告和审定财务报表 `fetchPaid` 无法签署或结清付款。 需要执行支持 后端引文/接收合同,独立核实运行时间/档案检查, 特定链式签名、费用上限和持久回收;登记旗或付款 地址不提供这些.

### 仅用稳定币链

在一个 `stablecoinOnly` (Arc) 气体符号是被钉住的马克币本身: 设定 `v14.asset` 对它, `maxGasWei` 以18-十进制原生单位计,气体 并对照一个余额核对毛额。 测试网链只接受 `network_mode: "test"` 引证. 在一个 `noNativePayment` 链(BOT链) 土生土长的代币只付汽油,没有价格,所以 `v14.asset` 必须指定其名称 被钉住的马克币.

这个 `solanaV14` 选项为 SOL 和经典提供所有者选择的付费访问 SPL资产. 网络与环境 本地的Ed25519付款人, 独立来源 SOL/美元和 `maxFeeLamports` (交易费) **加上全部 非ce/ATA租金**)与EVM选项分离. `v14` 财务报告和审定财务报表 `solanaV14` 一起行动 拒绝。 对照已安装的部署检查可用性 注册和运行时间/后端政策;应用程序配置不能覆盖 一条无法使用的路径.

准确的216字节引文和297字节指令遵循了被包裹的被钉住的IDL. 新的起源/配置/简介/薄荷/非账户证据和未签名的最后信息 在预算预留和当地签署之前进行模拟。 已签名的字节已保存 在单一发送之前。 未知的签名结果从未过期或授权 替换交易。 最终的失败只保留了已证实的失败 费用借项;缺失证明保留了全部保留。 公共历史/配额 明确选择索拉纳集群,绝不披露无记名收据.

### 将代理连接到其所有者的仪表板

时 [https://dash.aifinpay.io (英语)](https://dash.aifinpay.io/) 我的代理人们 根据地址添加代理 挑战。 签名并交回签名:

```ts
const signature = await agent.signDashboardClaim(challenge);
```

`signDashboardClaim` 仅显示 `AiFinPay-claim:polygon:<this address>:<nonce>` 并拒绝任何其他文本。 店主再看经纪人的收支 和收据.

已接受 v1.4 合同模式允许管理员更改配置费 和国库。 飞行前验证当前值;它不会使其永久不变. 见 [收据配置和回收](https://npmcn.com/package/%40aifinpay/agent/PAYMENT_RECEIPTS.md)。 。 。 .

自动人工智能特工的非拘禁支付客户端 [爱芬派](https://aifinpay.io/). AIFP-1包含毛额:付款人总数等于 引用,商家收到99%,AiFinPay收到1%,创建/转介 获得0%。 目前,AIFP-2/x402在协议层充电为0%. 遗产 `/api/b2b` 拆分发票方法已停止。 v1.3 执行器检查 独立提供的部署/运行时针、链条、收费概况、商家 目标与资产。 匹配的运行时间价值本身并不是生产批准; 使用已安装的登记册、能力API、执行测试和CI作为证据, 并不要绕过运行时间检查.

Ed25519键盘是本地生成的 `tweetnacl` 永不离开 你的流程。 SDK只发送一次 SHA-256 + Ed25519 签名 in 页:1 `x-signature` 对 AiFinPay 保护端点进行认证的页眉 .

## 安装

安装已公布的稳定软件包 :

```bash
npm install @aifinpay/agent
```

或构建此源检出 :

```bash
# From the SDK repository root
cd node
npm ci --no-audit --no-fund
npm run build
npm pack
```

在应用程序中安装由此产生的焦油球 :

```bash
npm install /absolute/path/to/sdk/node/aifinpay-agent-<version>.tgz
```

## 快开始

在共享存款地址前装入您已经配置的钱包 :

```ts
import { AiFinPayAgent } from "@aifinpay/agent";

const agent = await AiFinPayAgent.fromEnvironment();
console.log({ evm: agent.evmAddress, solana: agent.solanaAddress });
```

`fromEnvironment()` 是一个 **只装入** 节点API. 它在 此顺序,匹配 MCP :

1.  `SEED_HASH`:一个32字节种子被编码为64个十六进制字符,可选 `0x` 前缀.
2.  `./aifinpay/agents.json` 相对进程工作目录。 设定 `AIFINPAY_AGENTS_FILE` 用于另一个路径 `AIFINPAY_AGENT_ID` 选择时 从多个记录(`{"agents":[{"id":"crawler","seed_hash":"…"}]}`) (中文(简体) ).
3.  `AIFINPAY_AGENT_SECRET`:一个现存的基地58索拉纳秘密.
4.  `~/.aifinpay/agent.json`,或 `AIFINPAY_HOME/agent.json`: 现有的多边方案 键盘。 需要加密键盘 `AIFINPAY_WALLET_PASSPHRASE`。 。 。 .

装入器从不创建或覆盖钱包、打印其密钥或调用 腾讯网. 缺少配置、 无效种子、 模糊的工程文件或 a 解密失败抛出而不是选择新的钱包。 装入任意 `.env` 在调用前的运行时间; 此 API 读取 `process.env` 并且确实 未读 `.env` 文档. `SEED_HEX` 不是一个化名 `SEED_HASH`保密 输入和钱包文件退出聊天、日志和版本控制.

相同的配置输入在进程重新启动后恢复相同的地址 . 明确 `evmPrivateKey` 选项覆盖所衍生的 EVM 身份; 保留 用于回收导入的钱包。 正在装入钱包 自己不支付任何费用 `fetchPaid` 还有支票.

`AiFinPayAgent.fromSeed(seed, { derivationIndex })` 决定性地选择一个 儿童钱包。 每个链条使用自己的版本域,然后是 域的 NUL 分隔符后的小数 UTF-8 索引,然后恢复 种子 。 选择 `derivationIndex` 保存现有地址.

`AiFinPayAgent.new()` 财务报告和审定财务报表 `Agent.new()` 故意制造出新的麻风 钱包。 它们不装入已有的环境变量或键盘 你不要坚持他们所创造的钥匙。 只有在你故意的时候才用 需要新的身份,并会在恢复材料的私人存储之前 资助它。 永远不再重运行 `new()` 以收回现有资助地址.

## 正在装入已存在的密钥页

```ts
import { Agent } from "@aifinpay/agent";

// from solana-keygen JSON file (Node only)
const agent = await Agent.fromKeypairFile("./agent-wallet.json");

// from base58 secret string (works in browser too)
const agent2 = Agent.fromSecretB58("3RvZm7Gw...");
```

## 输入外部 EVM 签名器

`Agent.new()` 财务报告和审定财务报表 `AiFinPayAgent.fromSeed()` 从 探员种子。 将钥匙留在SDK之外——内部的签注,a 硬件支持的密钥, 或未来的销售商适配器—— 插入任何匹配的钱包 页:1 `AgentWallet` 接口通过 `evmWallet` (任何viem语) `LocalAccount` 符合结构条件:

```ts
import { Agent, evmPrivateKeyWallet } from "@aifinpay/agent";

// self-custodial default: the same key `evmPrivateKey` builds internally
const agent = Agent.new({ evmWallet: evmPrivateKeyWallet("0x…") });
```

两个零依赖性适配器覆盖钱包市场的其余部分 相同的接口 :

```ts
import { eip1193Wallet, viemWalletClientWallet } from "@aifinpay/agent";

// MetaMask and any generic EVM browser wallet (async: reads the address
// via eth_requestAccounts)
const injected = Agent.new({ evmWallet: await eip1193Wallet(window.ethereum) });

// Privy, Crossmint, ZeroDev, Coinbase Smart Wallet, custom transports —
// anything that hands out a viem WalletClient with an account
const embedded = Agent.new({ evmWallet: viemWalletClientWallet(walletClient) });
```

服务器侧销售商 SDK( Coinbase CDP 服务器钱包, Circle) 已退出 范围:它们需要供应商API证书,SDK不得持有.

`AgentWallet` 实值 `address` 加号 `signMessage`编号 :`signTypedData`; 已经足够了 用于基于信件的x402授权. `AiFinPayAgent` 还接受 `evmWalletClient` 使用精确的viem客户端进行 签名。 它的账户一定是一个viem `LocalAccount` 与 `signTransaction`数字 : v1.4 符号和日记在 SDK 广播之前精确的生字节 用于回收的独立选择链 RPC。 JSON-RPC/仅限期 智能账户客户对此流被拒绝. 必须配置客户端 用于选定链条。 此选项不能与 `evmWallet` 或者说 `evmPrivateKey`. MCP方案一体化采用同样的选择 当地身份继续提供索拉纳身份和签名.

## X402 认证如何在引擎盖下工作

`Agent.pay(url)` (和 `get`编号 :`post`编号 :`request`)处理AiFinPay-native 402 带有请求的认证(第2版) 对于一个有门的请求 SDK:

1.  402机构一次性携带 `x-nonce`,过期时 `x-nonce-expires-at`, (中文(简体) ), `x-aifinpay-auth-version: 2` 及其申请机构的SHA-256;
2.  除非请求被配置到原产地,否则拒绝签名 经纪人的 `baseUrl`反应来自这个来源, 和身体摘要 与它发送的身体相匹配;
3.  标志,与Ed25519, SHA-256 of `JSON.stringify(["AiFinPay-x402", "v2", nonce, pubkey, origin, METHOD, path+query, bodySha256, expiresAt])` 和基数58编码签名;
4.  用信头重试原请求 :
    -   `x-agent-pubkey: <base58 pubkey>`
    -   `x-nonce: <nonce>`
    -   `x-signature: <base58 sig>`
    -   `x-aifinpay-auth-version: 2`

服务器验证签名, 消耗非ce, 检查代理有 现场直播PDA链上,为资源服务. 已退役的 v1 格式 (单位:千美元)`GET /nonce`, (中文(简体) ), `SHA-256("AiFinPay-x402:{nonce}:{pubkey}")`被拒绝,和 `Agent.authHeaders()` 掷出.

## 隐私

-   **服务器从未看到您的私钥 .** 期间.
-   农斯在使用时被消耗;再玩耐用.
-   付款在公共链上结算——明确选择的EVM网络——并在链上可见.

## 许可证

麻省理工学院.

### 收款授权

AIFP-1收据使用付费钱包签名. 见 [批准和收回付款收据](https://npmcn.com/package/%40aifinpay/agent/PAYMENT_RECEIPTS.md) 复试和恢复,无需第二次转移.

### 一个网关网站保留着它的商人

`fetchPaid` 标出每个网关站点(`https://gateway.aifinpay.io/<slug>`改为: 商人先付了钱 然后钱才动了 之后的402个名字 同一地点的另一个商人扔出 `Aifp1MerchantChangedError` (单位:千美元)`code: "AIFP1_MERCHANT_CHANGED"`在引用任何东西之前。 如果改变是 合法,如该电话;支付网站的重置费:

```ts
await agent.fetchPaid(url, {}, { allowMerchantChange: true });
// or name the merchant you trust; any other one is refused:
await agent.fetchPaid(url, {}, { expectedMerchantId: "mrch_…" });
```

柱子是每个站点的一个文件 `~/.aifinpay/merchant-pins` (或 `AIFINPAY_STATE_DIR`),因此它们能活过重启;通过 `merchantPins` 页:1 特工把他们留在别处 无法读取的指针拒绝支付而不是 重新开始. `resourcePathMode: "direct"` 因为它的缓存 键已命名商号。 网关已失效的解答 `410 gateway_retired`,该投出 `Aifp1GatewayRetiredError` (单位:千美元)`code: "AIFP1_GATEWAY_RETIRED"`)在一次请求后;不重试。 电池 已经持有的被保存.

### 已经支付 : `Aifp1ActiveReceiptError`

在定购后一分钟内, `/v1/quote` 回答同一个付款人 资源,而不是引用,所以重试不能购买 两次 收不到的流程(新流程,或 `fetchPaid` 支付后失败)获得 `Aifp1ActiveReceiptError` (单位:千美元)`code: "AIFP1_ACTIVE_RECEIPT"`,一个子类 `Aifp1QuoteError`) (中文(简体) ). 什么都没有 引用或支付。 名称 `receiptId`, (中文(简体) ), `txRef`, (中文(简体) ), `chain`, (中文(简体) ), `merchantId`, (中文(简体) ), `resource` 财务报告和审定财务报表 `settledAt`; 从回收中收回收据 `onPrepared` 保存为 `txRef`数字 :

```ts
try {
  return await agent.fetchPaid(url, {}, opts);
} catch (e) {
  if (!(e instanceof Aifp1ActiveReceiptError)) throw e;
  const paid = await agent.recoverPaidPayment(savedRecoveryFor(e.txRef));
  return fetch(url, { headers: { "AIFP-Receipt": paid.receipt } });
}
```

不重试 `fetchPaid` 一旦一分钟过了一个新的引文 新买的 没有保存的恢复 `txRef` 收据不能为 已重新发行;再次购买是新的付款和业主的决定.

### 指定支付费用的AI客户端

设定 `framework` 向AI客户端 代理运行, 和每一个请求 支付流动 `AIFP-Agent-Framework: <value>`: 第一个要求 可能答复402, `/v1/quote`, (中文(简体) ), `/v1/pay` 和所付报酬的重试(和 x402 (韩语) `pay()`) (中文(简体) ). 商家仪表板然后显示AI客户端支付了哪些.

```ts
const agent = await AiFinPayAgent.fromEnvironment({ framework: "claude" });
```

接受数值`AGENT_FRAMEWORKS`: `chatgpt`, (中文(简体) ), `claude`, (中文(简体) ), `perplexity`, (中文(简体) ), `gemini`, (中文(简体) ), `cursor`, (中文(简体) ), `openai-agents`, (中文(简体) ), `windsurf`, (中文(简体) ), `codex`, (中文(简体) ), `custom`任意 其他抛出 `AiFinPayError` 当构建代理时。 保持不固定,没有标题是 发送; SDK 从未猜测. 构建后学习客户端的主机 代理通过它每个呼叫: `fetchPaid(url, init, { framework })` 或者说 `recoverPaidPayment(recovery, { framework })`。 。 。 .

### 付款历史

```ts
import { getAgentHistory } from "@aifinpay/agent";
const history = await getAgentHistory({ address: "0x…", source: "transactions" });
// Or { passport: 'AIFP-000000042', network: 'polygon', source: 'receipts' }
```

`transactions` 覆盖有索引的 AiFinPay 多边形定居点,而非任意 钱包传输. `receipts` 包括检验 支付。 跟随 `next_offset` 与 `limit`编号 :`offset`。护照要求 与已部署的已核实的wallet解析器的后端;通过地址和 护照检查他们的匹配。 永远不要通过一个持有者的私钥或API秘密 一个标识符。 公共历史不归还无记名收发凭证.

## 常见问题

### @aifinpay/agent 是什么？

AiFinPay SDK用于全球代理护照身份和自主AI代理的路线验证的AIFP-1/AIFP-2结算\.

### 如何安装 @aifinpay/agent？

在项目目录运行 npm install @aifinpay/agent，或使用 pnpm add / yarn add / bun add。

### @aifinpay/agent 支持 TypeScript 吗？

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

### @aifinpay/agent 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @aifinpay/agent 需要什么版本的 Node\.js？

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

### @aifinpay/agent 可以商用吗？

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

### @aifinpay/agent 的下载量有多少？

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

### @aifinpay/agent 还在维护吗？

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