Stillos Kya MCP server

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.

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

Shortened. The full README is on GitHub.