stillos-kya

stillos-kya — 了解你的 Agent

Agent 间交易的信任通行费。 在你的 AI Agent 向另一个 Agent 付款前，先做一项检查：交易对手是否受到制裁？它的钱包是否涉及诈骗、合约风险或资金被盗？StillOS 会返回 fail-closed 的 CLEAR / REVIEW / BLOCK 判定——结合 OFAC SDN 筛查和实时链上钱包信号——并生成一份 Ed25519 签名回执，可附在交易中，作为尽职调查的证明。

a16z（Big Ideas 2026）指出，「了解你的 Agent」——签名的 Agent 凭证加上交易对手信任——是商家允许 Agent 使用支付通道的前提。这是一套可直接接入的实现。

安装

npm install stillos-kya

使用 — 一次调用

const { kya } = require('stillos-kya');

const r = await kya({ name: 'Acme Agent', wallet: '0xabc...' });
if (!r.allowed) throw new Error(`counterparty ${r.verdict}`); // CLEAR | REVIEW | BLOCK
// r.receipt -> { hash, signature, verify }  (signed, verifiable proof-of-screening)

使用 — 一行代码即可为 x402 / express 路由设置门控

const { kyaGate } = require('stillos-kya');

// Every payment through this route runs a counterparty trust-check first.
app.post('/pay-agent', kyaGate({ blockOnReview: false }), async (req, res) => {
  // req.kya = { verdict, allowed, checks, receipt, ... }
  // ...proceed to pay; blocked counterparties never reach here
});

门控放行条件（0.4.2）

kyaGate 要求判定为明确通过，而不仅仅是拦截 BLOCK。

端点返回值	req.kya.verdict	门控结果
{"verdict":"CLEAR"}	CLEAR	放行至你的处理函数
{"verdict":"REVIEW"}	REVIEW	放行，除非设置了 blockOnReview: true -> 403
{"verdict":"BLOCK"}	BLOCK	403
402 / 4xx / 5xx / 网络故障	—	502，fail-closed
200，但没有可识别的判定（{}、{"verdict":null}、{"verdict":"UNKNOWN"}）	UNKNOWN	502，fail-closed

最后一行的行为在 0.4.2 中发生了变化。在 0.4.1 及更早版本中，门控检查的是「是否为 BLOCK」，而不是「是否为 CLEAR」，因此任何 200 响应只要没有包含可识别的判定，就会放行至你的处理函数，并将 blocked: false。allowed 的计算本来就是正确的，只是从未被检查。如果你依赖这种行为，kyaGate({ failOpen: true }) 可以显式恢复它——但这只能作为可选设置，而它也本该一直如此。

0.4.2 还修复了 MCP 服务在每次调用时都会生成新 Agent ID 的问题。设置 STILLOS_KYA_AGENT 可确保 Agent 身份在重启后保持稳定；否则，每个进程会生成一个 ID。免费套餐按来源 IP 计量，因此这不会影响配额，只会影响系统能否将你的重复使用识别为重复使用。

套餐

• 免费： 每个 Agent ID 每天可检查 2 次——提供未签名的判定，即检查结果，用于初步筛查。
• 付费（通过 x402 支付 $0.25 USDC，或使用 API 密钥）： 提供可独立验证的签名回执——这才是发生争议时至关重要的尽职调查证明。

定价和完整端点参考：https://stillosdigitalholdings.com/notary

超出免费套餐后

已内置支付支持。 x402-fetch 和 viem 作为 optionalDependencies 随包提供，因此 npm install stillos-kya 会自动为你安装它们。无需 额外安装。你可以自行检查：

const { paymentCapability } = require('stillos-kya');
paymentCapability(); // { available: true, deps: { 'x402-fetch': true, viem: true }, reason: null }

付款 — 传入签名器，而非密钥

按以下优先顺序使用。StillOS 在任何一种方式下都不会接收、存储或记录你的密钥：

// BEST — you own the whole payment transport. This package never touches a key or signer.
const { wrapFetchWithPayment } = require('x402-fetch');
const payingFetch = wrapFetchWithPayment(fetch, myAccount, 500000n); // 500000 = $0.50 USDC
const r = await kya({ name: 'Acme Agent' }, { fetch: payingFetch });

// GOOD — hand us a signer object; the key stays inside it.
const r = await kya({ name: 'Acme Agent' }, { account: myViemAccount, maxUsd: 0.5 });

// LEGACY — a raw hex private key. Still supported, deliberately last. A raw key in an
// env var is the weakest of these: anything that can read your process env can spend it.
const r = await kya({ name: 'Acme Agent' }, { wallet: process.env.MY_WALLET_KEY });

遇到 402 时，SDK 会完成付款并仅重试一次（MAX_PAYMENT_RETRIES === 1）。对于它不认识的网络、资产或方案，它会拒绝签名，而不会盲目信任挑战内容。

面向 Agent 的错误恢复

如果未配置付款能力，kya() 会抛出一个 KyaHttpError，其中包含自主调用方执行后续操作所需的全部信息——根据 err.code 分支判断，切勿根据消息文本判断：

const { kya, KyaHttpError, CODES } = require('stillos-kya');
try {
  await kya({ name: 'Acme Agent' });
} catch (e) {
  if (e instanceof KyaHttpError && e.code === CODES.PAYMENT_REQUIRED) {
    e.payment;      // { mechanism:'x402', scheme, network, asset, asset_name,
                    //   pay_to, amount_usd, amount_base_units, resource, max_timeout_seconds }
    e.remediation;  // { action:'configure_payment_capability', accepted:[...],
                    //   free_tier_alternative: '...' }
  }
}

错误代码：PAYMENT_REQUIRED · PAYMENT_CAPABILITY_MISSING · PAYMENT_CONSTRUCTION_FAILED · PAYMENT_REJECTED · PAYMENT_UNSUPPORTED · BAD_402 · BAD_REQUEST · SERVER_ERROR。

安全

**StillOS 绝不会索要、接收、传输或存储你的私钥。**付款完全在你这边签名，我们收到的仅是标准的 x402 X-PAYMENT 授权标头。你用自己的钱包支付自己的请求。

密钥材料绝不会出现在错误消息、日志行或遥测数据中——即使格式错误的密钥解析失败也是如此；此时我们会刻意屏蔽底层库自身的错误文本，而不是重新抛出。

STILLOS_KYA_WALLET_KEY 仍受支持，可用于 CLI 和向后兼容。它是旧式便捷方式，并非推荐架构：在代码中优先使用 fetch 或 account。

CLI：STILLOS_KYA_WALLET_KEY=0x... stillos-kya check "Acme Agent"

签名为何重要

如果交易对手后来被发现受到制裁或存在欺诈行为，那么未签名的“看起来没问题”毫无价值。StillOS 签名回执是加密证明，表明你在付款之前进行了筛查——这份审计凭证能保护你。