stillos-kya

stillos-kya — Know Your Agent

エージェント間取引における信頼の通行料です。 AI エージェントが別のエージェントに支払う前に、1 つ確認します。取引相手は制裁対象になっていないか？ そのウォレットは詐欺・コントラクト・資金流出に関係していないか？ StillOS はフェイルクローズ方式で CLEAR / REVIEW / BLOCK の判定を返します。OFAC SDN スクリーニングとオンチェーンのウォレットシグナルをリアルタイムで確認し、取引に添付してデューデリジェンスの証明にできる Ed25519 署名付きレシートも提供します。

a16z は（Big Ideas 2026）、加盟店がエージェントに決済ネットワークを利用させる前提として、「Know Your Agent」――署名付きエージェント認証情報と取引相手の信頼性――を挙げています。これはすぐに導入できる、実際に動作する実装です。

インストール

npm install stillos-kya

使い方 — 1 回の呼び出し

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 ルートに 1 行でゲートを設定

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、フェイルクローズ
認識できる判定を含まない 200（{}、{"verdict":null}、{"verdict":"UNKNOWN"}）	UNKNOWN	502、フェイルクローズ

最後の行は 0.4.2 で変更されました。0.4.1 までは、ゲートは「これは BLOCK か？」を確認しており、「これは CLEAR か？」を確認していませんでした。そのため、認識できる判定を含まない 200 はすべて、blocked: false のままハンドラーに渡されていました。allowed はすでに正しく計算されていたものの、参照されていなかったのです。この動作に依存していた場合は、kyaGate({ failOpen: true }) を明示的に指定することで復元できます。このようにオプトインにするのが、本来あるべき唯一の形です。

0.4.2 では、MCP サーバーが呼び出しのたびに新しいエージェント ID を発行する問題も解消されました。再起動後も同じ ID を使うには、STILLOS_KYA_AGENT を設定してください。未設定の場合は、プロセスごとに 1 つの ID が発行されます。無料プランの利用量は送信元 IP ごとに計測されるため、クォータには影響しませんでした。影響したのは、繰り返しの利用を繰り返しとして把握できるかどうかです。

プラン

• 無料： エージェント ID あたり 1 日 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 は支払いを行い、厳密に 1 回だけ再試行します（MAX_PAYMENT_RETRIES === 1）。認識できないネットワーク、アセット、スキームへの署名は拒否するため、チャレンジを無条件に信頼することはありません。

エージェントが読み取れるエラーへの対処

決済機能が設定されていない場合、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 の署名付きレシートは、支払いの前に審査を行ったことを証明する暗号学的な証拠であり、お客様を守る監査証跡です。