stillos-kya — Know Your Agent

The trust toll for agent-to-agent commerce. Before your AI agent pays another agent, run one check: is the counterparty sanctioned? Is its wallet a scam/contract/drained? StillOS returns a fail-closed CLEAR / REVIEW / BLOCK verdict — OFAC SDN screen + live on-chain wallet signals — with an Ed25519-signed receipt you can attach to the transaction as proof-of-diligence.

a16z (Big Ideas 2026) calls "Know Your Agent" — signed agent credentials + counterparty trust — the prerequisite for merchants to let agents onto payment rails. This is a working drop-in for it.

Install

npm install stillos-kya

Use — one call

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)

Use — gate an x402 / express route in one line

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
});

What the gate lets through (0.4.2)

kyaGate requires a positive clearance. It does not merely block BLOCK.

Endpoint returns	req.kya.verdict	Gate
{"verdict":"CLEAR"}	CLEAR	passes to your handler
{"verdict":"REVIEW"}	REVIEW	passes, unless blockOnReview: true -> 403
{"verdict":"BLOCK"}	BLOCK	403
402 / 4xx / 5xx / network failure	—	502, fail-closed
200 with no recognized verdict ({}, {"verdict":null}, {"verdict":"UNKNOWN"})	UNKNOWN	502, fail-closed

That last row changed in 0.4.2. Through 0.4.1 the gate asked "is this BLOCK?" rather than "is this CLEAR?", so any 200 carrying no verdict it recognised fell through to your handler with blocked: false. allowed was already computed correctly and simply never consulted. If you were relying on that behaviour, kyaGate({ failOpen: true }) restores it explicitly — as an opt-in, which is the only form it should ever have had.

0.4.2 also stops the MCP server minting a new agent id on every single call. Set STILLOS_KYA_AGENT for a durable identity across restarts; otherwise one id is minted per process. The free tier meters per source IP, so this never affected quota — it affected whether your repeat usage was legible as repeat usage.

Tiers

• Free: 2 checks/agent id/day — unsigned verdict, the answer, for triage.
• Paid ($0.25 USDC via x402, or an API key): the signed, independently-verifiable receipt — the proof-of-diligence that matters in a dispute.

Pricing + full endpoint reference: https://stillosdigitalholdings.com/notary

Past the free tier

Payment support is already installed. x402-fetch and viem ship as optionalDependencies, so npm install stillos-kya installs them for you. There is no second install step. Check it yourself:

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

Paying — pass a signer, not a secret

Preferred, in order. StillOS never receives, stores, or logs your key in any of them:

// 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 });

On a 402 the SDK pays and retries exactly once (MAX_PAYMENT_RETRIES === 1). It refuses to sign for a network, asset, or scheme it does not recognise rather than trusting the challenge blindly.

Agent-readable recovery

With no payment capability configured, kya() throws a KyaHttpError carrying everything an autonomous caller needs to act — branch on err.code, never on message text:

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: '...' }
  }
}

Codes: PAYMENT_REQUIRED · PAYMENT_CAPABILITY_MISSING · PAYMENT_CONSTRUCTION_FAILED · PAYMENT_REJECTED · PAYMENT_UNSUPPORTED · BAD_402 · BAD_REQUEST · SERVER_ERROR.

Security

StillOS never asks for, receives, transmits, or stores your private key. Payment is signed entirely on your side and reaches us only as a standard x402 X-PAYMENT authorization header. Your own wallet pays your own request.

Key material is never placed in an error message, a log line, or telemetry — including when a malformed key fails to parse, where the underlying library's own error text is deliberately suppressed rather than re-thrown.

STILLOS_KYA_WALLET_KEY remains supported for the CLI and for backward compatibility. It is a legacy convenience, not the recommended architecture: prefer fetch or account in code.

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

Why signed matters

An unsigned "looks fine" is worthless if a counterparty later turns out sanctioned or fraudulent. A StillOS signed receipt is cryptographic proof that you screened before you paid — the audit artifact that protects you.