@ agentpos/ core (% 1) (帮助)
每一个 AgentPOS 软件包的共同基础 .
config: Network(testnet默认,主网出闸口),主持人URL,CAIP-2代号,USDC发行商.money:品牌整数类型(UsdcMinor, (中文(简体) ),Stroops),7个小数,没有浮点.rescaleMinor在小单位之间精确地移动一个数量,并拒绝圆形.chain: 网络作为数据。 CAIP-2 标识,aChainProfile每个网络(美联储十进制) 网络,地址检查,探索者链接)和注册铁路包添加到. 斯特拉尔船 内建;usdcOnChain(price, caip2)表示该网络的USDC单元中的目录价格.wallet-proof: 证明商人通过签署非ce控制接收钱包 (护栏一. Stellar使用SEP-53;其他家庭登记其核查人.errors数字 :AgentPOSError { code, message, hint, retryable }带有闭合代码集.adapter/x402: 唯一导入模块@x402/*。资源服务器,路由配置 整数价格、买方客户端、结算 -- > 收款.adapter/rails页:1PaymentRail接口及其登记册(见下文“支付栏”).adapter/ucp, (中文(简体) ),adapter/acp: 发现表面 (skeletons; 第2阶段的 schema验证).adapter/versions: 绑定协议版本和adapterVersion。 。 。 .signer: 工厂local-keypair(钱包基特和密码是预留的插槽).llm:直接-HTTP路由器(Anthropic Messages API,OpenAI-兼容).fiscal数字 :FiscalAdapter接口(插件在别处).
import { resolveConfig, usdc, createResourceServer, buildRouteConfig } from "@agentpos/core";
const cfg = resolveConfig(); // testnet
const server = createResourceServer(cfg);
const route = buildRouteConfig(cfg, { payTo: "G...", amount: usdc("1.25"), reference: "order_1" });
从 npm 安装: Zod 覆盖
@x402/core (x402 SDK 此包包包) 声明 zod@^3,3.x线没有补丁
页:1 全球统一制度A-mrhx-c7xc-m3w5这样 npm audit
在任何安装的工程中报告 @agentpos/core。SDK只使用 Zod API 即
与 zod 4 相同, 此寄存器运行整个测试套件和测试网支付回路
与 zod 4 齐发. 在 SDK 移动之前, 将此添加到您的项目中 package.json数字 :
{ "overrides": { "zod": "^4.6.6" } }
随着pnpm,同样的下去 pnpm.overrides (或 overrides 内 pnpm-workspace.yaml) (中文(简体) ).
支付栏杆
A 类 铁路 一种方式是支付商店。 有两个: x402 / USDC 超过 Stellar
(单位:千美元)org.x402.stellar,在分类账上结算)和 Transbank Webpay / 点击智利的卡片
(单位:千美元)cl.transbank.webpay,在商人自己的收购人处结算. 这个 PaymentRail 接口是
是什么使得第二个是添加而不是重写, 以及下一个是什么(网络代理
证书)也将执行.
import { createTransbankRail, fiatMinor, minorAmount } from "@agentpos/core";
// The merchant's own commerce code and API key: never ours (guardrail 7).
const card = createTransbankRail({
environment: "integration",
commerceCode: process.env.TRANSBANK_COMMERCE_CODE!,
apiKey: process.env.TRANSBANK_API_KEY!,
oneclick: { mallCode: "597055555541", childCommerceCode: "597055555542" },
});
const clp = minorAmount(fiatMinor("14990", 0, "CLP"), "CLP", 0); // whole pesos, no floats
// Webpay Plus: a first purchase. The human pays on Transbank's page; verify reports
// PAYMENT_PENDING until then; settle commits the token exactly once.
const first = await card.quote({ payTo: returnUrl, amount: clp, reference: "cart_1" });
// Oneclick: a repeat purchase on a card the buyer enrolled once. No human step.
const again = card.quoteOneclick({ payTo: "store", amount: clp, reference: "cart_2" });
await card.settle({ mode: "oneclick", username: "buyer-42", tbkUser: "tbk_..." }, again.terms);
卡片结算不产生散列交易: reference 是商店的购买订单,和
获取者的授权代码 raw。 。 。 . fiatMinor(decimal, decimals, currency) 转出
源价格为整数小数(CLP0小数,2美元); fiatDecimals(code) 已经知道
释相.
import { createX402StellarRail, PaymentRailRegistry, usdcAmount, usdc } from "@agentpos/core";
const rails = new PaymentRailRegistry([createX402StellarRail({ config: cfg })]);
const rail = rails.requireSupporting({ currency: "USDC", amount: usdcAmount(usdc("1.25")) });
const quote = await rail.quote({
payTo: "G...",
amount: usdcAmount(usdc("1.25")),
reference: "cart_1",
});
const decision = await rail.verify(paymentPayload, quote.terms); // never moves money
const settlement = await rail.settle(paymentPayload, quote.terms); // { settled, reference: txHash }
5种方法: supports(ctx) (网络、货币和金额界限;纯), quote(input) (术语)
a. 代理人必须满足,对于x402是逐一满足402个付款要求, verify, (中文(简体) ), settle
财务报告和审定财务报表 describe() 用于发现表面.
每条铁路有三项规则:
- 添加一道栏从不改变商店的目录或订单表面. 物品、推车、引文和
订购单与使用的铁路相同;铁路只增加一名付款管理人
发现和在
rail栏. - 钱总是一个小单位的整数 (护栏4):
UsdcMinor,或一个MinorAmount(单位:千美元){ minor: bigint, currency, decimals }用另一种货币定价的铁路。 没有浮点 在接口的任何地方. - 失败者说它是哪一种.
RailFailure.kind实值"rejected"(铁轨说没有); 确定性,绝不重试)或"unavailable"铁路没有应答,只有一条铁路是可试的 (b) 发生故障时可采取行动)。 为了解决问题,preSubmission: true额外意味着请求 6号护卫车厢禁止重新投放其他东西 代码来自 基础适配器不变(PAYMENT_REJECTED, (中文(简体) ),SETTLEMENT_FAILED, (中文(简体) ),FACILITATOR_UNAVAILABLE); 铁道包装器从不给故障重新贴上标签.
PaymentRailRegistry 命令和id-index: list(), (中文(简体) ), get编号 :require, (中文(简体) ), firstSupporting(ctx), (中文(简体) ),
describe()它坚守 无路线政策 - 阈值、优惠和代理规则是
商人的和属于 packages/policy. 铁路标识是固定在
adapter/versions.ts (单位:千美元)PAYMENT_RAIL_IDS, (中文(简体) ), RESERVED_PAYMENT_RAIL_IDS) (中文(简体) ).
脚本 : pnpm e2e:smoke (testnet friendbot + trustline + 支付,打印tx hashes).
网络和钱包链接
核心是中性的,关于一个商店的哪个连锁付款。 网络是 ChainProfile数字 :
import { registerChainProfile, FAMILY_ADDRESS_CHECKS, usdcOnChain, usdc } from "@agentpos/core";
// A rail package registers its network once, at import.
registerChainProfile({
caip2: "eip155:5042002",
family: "eip155",
label: "Arc testnet",
testnet: true,
usdcDecimals: 6,
isValidAddress: FAMILY_ADDRESS_CHECKS.eip155,
});
usdcOnChain(usdc("1.5"), "stellar:pubnet"); // { minor: 15000000n, decimals: 7 }
usdcOnChain(usdc("1.5"), "eip155:5042002"); // { minor: 1500000n, decimals: 6 }
usdcOnChain(usdc("1.2345678"), "eip155:5042002"); // INVALID_AMOUNT: never rounded
连接一个商人钱包从不碰钥匙:商店发出挑战,商号 在他们自己的钱包, 商店验证它.
const challenge = createWalletChallenge({
caip2: "stellar:pubnet",
address: "G...",
domain: "shop.example.com",
});
// ...the merchant signs challenge.message in Freighter (SEP-53)...
await verifyWalletProof(challenge, signatureBase64); // throws WALLET_PROOF_INVALID / _EXPIRED