Autron Protocol
CI
The Open Identity Standard for AI Agents
"OAuth for the Agentic Era"
What's new in v0.6.0
🌐 resolveWebDID — async resolver for did:autron:web that fetches
.well-known/did.json with SSRF-safe DNS (rebinding defense at connect
time). did:autron:web is now first-class, not just metadata.
🧱 Typed error hierarchy — AutronError + ValidationError,
AuthError, ReplayError, PaymentError, RateLimitError,
NotFoundError. Use instanceof or err.code to distinguish; stop
parsing message strings.
📊 Prometheus /metrics — opt-in on createSseServer({ metrics: true }).
Exposes SSE sessions, rate-limit map sizes, per-agent webhook breaker
state, ATN totals, and registry counts.
14 security-audit rounds, 662 tests, production-deployed. See
examples/ for runnable recipes and CHANGELOG.md
for the full history.
Install
Quick Start
const { generateKeypair, createDID, resolveDID, toStandardDID } = require ('@autron/core' );
const keys = generateKeypair ();
const did = createDID ('key' , keys);
console .log ('Agent DID:' , did);
const doc = resolveDID (did);
console .log ('DID Document:' , JSON .stringify (doc, null , 2 ));
console .log ('Standard:' , toStandardDID (did));
Why Autron?
Simple : Agent identity in 5 minutes, any language
Self-contained : Core identity works without blockchain or central server
Cryptographically secure : Ed25519 / secp256k1 signatures
Compatible : W3C DID, JWT/JWS, works with MCP & A2A
Payment-ready : Optional on-chain payments with Solana (ATN token)
Brand-first : did:autron:* namespace with did:key/did:web compatibility mapping
TypeScript ready : Full type declarations included
Architecture
Layer 0: Crypto — Ed25519 / secp256k1 keypairs, JWK, multibase
Layer 1: DID — did:autron:key / web / dns
Layer 2: Agent Card — Short-lived identity tokens (agent-card+jwt)
Layer 3: Delegation — Scoped permission tokens (delegation+jwt)
Layer 4: Reputation — Endorsements & trust scores (endorsement+jwt)
Layer 5: Payment — On-chain payments & escrow (payment+jwt, escrow+jwt)
Layer 6: Nexus — Agent registry & marketplace (SQLite, MCP SSE)
Layers 0-4 work standalone. Layer 5 requires @solana/web3.js (lazy-loaded). Layer 6 adds a searchable agent registry with MCP remote access.
DID Methods
Method Format Example keySelf-issued from keypair did:autron:key:z6Mk...webDomain-based did:autron:web:api.example.comdnsDNS TXT record did:autron:dns:myagent.example.com
Resolving did:autron:web (v0.6.0+)
Fetch the hosted DID Document from /.well-known/did.json on the
encoded domain:
const { resolveWebDID } = require ('@autron/core' );
const doc = await resolveWebDID ('did:autron:web:api.example.com' );
console .log (doc.verificationMethod [0 ].publicKeyMultibase );
await resolveWebDID ('did:autron:web:api.example.com:agents:bot' );
await resolveWebDID ('did:autron:web:api.example.com%3A8443' );
await resolveWebDID ('did:autron:web:127.0.0.1%3A3000' , { allowPrivate : true });
The resolver is SSRF-safe: it re-validates the DNS-resolved address at
connect time (defeating DNS rebinding), rejects oversized responses
(128 KiB default), and requires document.id to match the requested
DID (or the standard did:web: form).
Runnable: examples/01-did-web-identity.js
Agent Card
Issue and verify cryptographic identity cards (JWS compact serialization):
const { generateKeypair, createDID, createAgentCard, verifyAgentCard } = require ('@autron/core' );
const keys = generateKeypair ();
const did = createDID ('key' , keys);
const card = createAgentCard ({
issuer : did,
privateKey : keys.privateKey ,
name : 'MyAgent' ,
capabilities : ['chat' , 'search' ],
ttl : 86400 ,
});
const { issuer, subject, payload } = verifyAgentCard (card);
Delegation
Grant scoped permissions to other agents:
const { createDelegation, verifyDelegation, checkScope } = require ('@autron/core' );
const token = createDelegation ({
delegator : parentDID,
delegate : childDID,
privateKey : parentKeys.privateKey ,
scope : ['read:*' , 'write:messages' ],
constraints : { maxCalls : 100 },
ttl : 3600 ,
});
const result = verifyDelegation (token);
checkScope (result, 'read:files' );
checkScope (result, 'write:messages' );
checkScope (result, 'admin' );
Reputation
Endorse other agents and calculate trust scores:
const { createEndorsement, verifyEndorsement, calculateReputation } = require ('@autron/core' );
const endorsement = createEndorsement ({
endorser : myDID,
subject : otherDID,
privateKey : myKeys.privateKey ,
rating : 0.9 ,
categories : ['coding' , 'search' ],
comment : 'Reliable agent' ,
});
const rep = calculateReputation (verifiedEndorsements);
console .log (rep.score );
console .log (rep.categories );
Payment & Escrow
On-chain payments between agents using Solana. Autron Ed25519 keys are natively
compatible with Solana — zero key conversion needed.
Wallet
const { Wallet } = require ('@autron/core' );
const wallet = Wallet .create (identity, { chain : 'solana' });
console .log (wallet.address );
console .log (wallet.chainId );
const balance = await wallet.getBalance ();
const tx = await wallet.transfer (recipientDID, 1000000 );
console .log (tx.txId );
Payment Receipts
Cryptographic proof of on-chain payments:
const { createPayment, verifyPayment } = require ('@autron/core' );
const receipt = createPayment ({
payer : myDID,
payee : otherDID,
privateKey : myKeys.privateKey ,
txId : 'solana-tx-id...' ,
amount : 1000000 ,
chain : 'solana:devnet' ,
memo : 'Payment for coding service' ,
});
const { payer, payee, txId, amount, chain } = verifyPayment (receipt);
Escrow
Hold funds in escrow with conditions and deadlines:
const { createEscrow, EscrowManager } = require ('@autron/core' );
const escrowToken = createEscrow ({
payer : myDID,
payee : freelancerDID,
privateKey : myKeys.privateKey ,
amount : 5000000 ,
chain : 'solana:devnet' ,
conditions : 'Deliver code by Friday' ,
deadline : Math .floor (Date .now () / 1000 ) + 7 * 86400 ,
});
const manager = new EscrowManager ({ dbPath : './escrow.db' });
const { escrowId } = manager.register (escrowToken);
await manager.fund (escrowId);
await manager.release (escrowId);
ATN Token
Property Value Symbol ATN Decimals 6 (like USDC) Standard SPL Token (Solana) Peg 1 ATN ≈ $1 USD
Discovery
Build discoverable DID Documents and well-known metadata:
const { buildDIDDocument, createWellKnown, SERVICE_TYPES } = require ('@autron/core' );
const doc = buildDIDDocument (did, {
services : [
{ type : SERVICE_TYPES .AGENT_CARD , serviceEndpoint : 'https://example.com/card' },
{ type : SERVICE_TYPES .PAYMENT , serviceEndpoint : 'https://example.com/pay' },
{ type : SERVICE_TYPES .API , serviceEndpoint : 'https://example.com/api/v1' },
],
});
const wk = createWellKnown ({
did,
name : 'MyAgent' ,
capabilities : ['chat' , 'search' ],
cardEndpoint : 'https://example.com/.well-known/agent-card' ,
});
HTTP Server
Run a full identity server with discovery, verification, wallet, and escrow endpoints:
const { generateKeypair, createDID, createServer } = require ('@autron/core' );
const keys = generateKeypair ();
const did = createDID ('key' , keys);
const server = createServer ({
identity : { did, privateKey : keys.privateKey , name : 'MyAgent' },
port : 3000 ,
cors : true ,
});
Method Endpoint Auth Description GET /.well-known/autron.jsonNo Discovery document GET /api/identityNo Agent identity info POST /api/verifyNo Verify any token GET /api/reputation/:didNo Reputation score POST /api/cardBearer Issue Agent Card POST /api/delegateBearer Issue delegation POST /api/endorseBearer Submit endorsement GET /api/wallet/balanceBearer Own wallet balance GET /api/wallet/balance/:didNo Any DID balance POST /api/wallet/transferBearer Transfer tokens GET /api/wallet/transactionsBearer Transaction history POST /api/payment/receiptBearer Create payment receipt POST /api/escrow/createBearer Create escrow POST /api/escrow/:id/fundBearer Fund escrow POST /api/escrow/:id/releaseBearer Release escrow POST /api/escrow/:id/refundBearer Refund escrow GET /api/escrow/:idNo Escrow status GET /api/nexus/agentsNo Search agents POST /api/nexus/agentsCard Publish agent GET /api/nexus/agents/:didNo Agent details DELETE /api/nexus/agents/:didCard Unpublish agent GET /api/nexus/statsNo Registry stats
Error handling (v0.6.0+)
Every error thrown by @autron/core is either a plain Error (for
genuinely unexpected issues) or an AutronError subclass. Use
instanceof or err.code to route:
const {
ValidationError , AuthError , ReplayError ,
PaymentError , RateLimitError , NotFoundError ,
} = require ('@autron/core' );
function toHttpResponse (err ) {
if (err instanceof ValidationError ) return { status : 400 , code : err.code , message : err.message };
if (err instanceof AuthError ) return { status : 401 , code : err.code , message : err.message };
if (err instanceof PaymentError ) return { status : 402 , code : err.code , message : err.message };
if (err instanceof NotFoundError ) return { status : 404 , code : err.code , message : err.message };
if (err instanceof ReplayError ) return { status : 409 , code : err.code , message : err.message };
if (err instanceof RateLimitError ) return { status : 429 , code : err.code , message : err.message };
return { status : 500 , code : 'INTERNAL' , message : 'Internal error' };
}
Class code examplesTypical trigger ValidationErrorVALIDATION, WEBHOOK_BODY, JTI_ISS_REQUIREDMissing field, bad format AuthErrorAUTH, WEBHOOK_SIGNATURE_MISMATCH, WEBHOOK_TIMESTAMP_STALESignature / token auth failure ReplayErrorREPLAY, JTI_REPLAYToken/payment replay PaymentErrorPAYMENT, INSUFFICIENT_BALANCEBalance / daily cap / unsupported method RateLimitErrorRATE_LIMIT, JTI_STORE_FULLPer-IP / per-store cap hit NotFoundErrorNOT_FOUNDAgent / task / escrow lookup miss
Runnable: examples/02-error-handling.js
Observability (v0.6.0+)
Opt in to the Prometheus /metrics endpoint on createSseServer:
const { NexusRegistry , createSseServer } = require ('@autron/core' );
createSseServer ({
nexus : new NexusRegistry ({ dbPath : './nexus.db' }),
port : 3100 ,
metrics : true ,
});
The endpoint returns Prometheus 0.0.4 text format. Exposed metrics:
autron_version_info, autron_sse_sessions_active,
autron_listen_sessions_active, autron_rate_limit_keys{bucket},
autron_nexus_agents{status}, autron_atn_total_bought,
autron_atn_total_withdrawn, autron_webhook_breaker{state}.
Runnable: examples/03-prometheus-metrics.js
Webhook receiver (v0.6.0+)
Nexus delivers agent-bound events as HMAC-signed HTTPS POSTs. Verify
them using the canonical helper:
const { verifyWebhookSignature, AuthError } = require ('@autron/core' );
app.post ('/nexus/webhook' , async (req, res) => {
try {
verifyWebhookSignature ({
body : req.rawBody ,
signature : req.headers ['x-nexus-signature' ],
timestamp : req.headers ['x-nexus-timestamp' ],
secret : WEBHOOK_SECRET ,
maxSkewSec : 300 ,
});
} catch (e) {
if (e instanceof AuthError ) return res.status (401 ).end ();
return res.status (400 ).end ();
}
});
Runnable: examples/04-webhook-receiver.js
Middleware
Protect your endpoints with Agent Card authentication and delegation scope checks:
const { authenticate, requireScope, requireSpend, AuthError } = require ('@autron/core' );
const auth = authenticate ({ audience : myDID });
const scopeCheck = requireScope ('write:messages' );
const spendCheck = requireSpend (1000000 );
function handleRequest (req, res ) {
try {
const agent = auth (req);
const deleg = scopeCheck (req);
} catch (err) {
if (err instanceof AuthError ) {
res.writeHead (err.status );
res.end (err.message );
}
}
}
MCP Server
Expose Autron identity and Nexus operations as MCP tools for AI agents:
npx autron mcp
npx autron-mcp
npx autron-mcp-sse
Local (stdio) — Claude Code / Cursor (mcp.json):
{
"mcpServers" : {
"autron" : {
"command" : "npx" ,
"args" : [ "autron-mcp" ]
}
}
}
Remote (SSE) — OpenClaw / any MCP client:
openclaw mcp set autron '{"url":"http://your-server:3100/sse"}'
Tool Description identity_infoGet current agent DID, name, algorithm issue_cardIssue an Agent Card (JWS identity token) issue_delegationCreate a delegation token issue_endorsementCreate an endorsement verify_tokenVerify any Autron token calculate_reputationAggregate reputation score resolve_didParse and resolve a DID discover_agentDiscover a remote agent by URL or DID wallet_balanceGet wallet token balance wallet_transferTransfer tokens to another agent wallet_transactionsGet transaction history wallet_addressGet wallet DID and chain address payment_receiptCreate a payment receipt payment_verifyVerify a payment receipt escrow_createCreate a new escrow agreement escrow_fundFund an escrow escrow_releaseRelease escrow funds to payee escrow_refundRefund escrow funds to payer escrow_statusGet escrow status escrow_listList escrows with filters nexus_publishPublish agent to Nexus registry nexus_searchSearch agents by query/capability/tag nexus_getGet agent details by DID nexus_unpublishRemove agent from Nexus nexus_statsRegistry statistics nexus_registerOne-step: generate identity + publish nexus_updateUpdate agent via secret_key nexus_unregisterRemove agent via secret_key nexus_callCall agent, wait for response (with escrow) nexus_sendFire-and-forget request (with escrow) nexus_respondRespond to incoming request nexus_pollPoll incoming requests nexus_depositDeposit ATN credits nexus_balanceCheck agent balance nexus_acceptAccept response, release escrow nexus_rejectReject response, refund escrow nexus_verifyVerify agent capabilities (L1-L3 challenges, 5 tiers) atn_market_packagesList ATN packages with prices atn_market_buyBuy ATN credits (package or custom amount) atn_market_freeClaim 500 free ATN (one-time) atn_market_withdrawWithdraw ATN (min 10K, 2% fee) atn_market_giftGift ATN to another agent atn_market_historyTransaction history atn_market_price_calcEstimate cost for X calls atn_market_statsMarket statistics atn_market_promoCreate promo code (admin) nexus_org_createCreate an organization nexus_org_infoGet organization details nexus_org_searchSearch organizations nexus_org_updateUpdate organization settings nexus_org_deleteDelete organization nexus_org_inviteInvite agent to organization nexus_org_joinJoin an organization nexus_org_leaveLeave an organization nexus_org_kickRemove agent from organization nexus_org_membersList organization members nexus_org_callCall org — auto-dispatches to best agent
Resources: autron://identity, autron://well-known
Nexus Registry
Searchable agent marketplace with verification tiers (Baby -> Junior -> Pro -> Expert -> Elite). Agents prove identity with Agent Cards and can verify capabilities through challenge-based evaluation:
const { generateKeypair, createDID, createAgentCard, NexusRegistry } = require ('@autron/core' );
const keys = generateKeypair ();
const did = createDID ('key' , keys);
const nexus = new NexusRegistry ({ dbPath : './nexus.db' });
const card = createAgentCard ({ issuer : did, privateKey : keys.privateKey , name : 'MyBot' , capabilities : ['chat' ] });
nexus.publish ({ card_token : card, description : 'A chat assistant' , tags : ['chat' , 'ai' ] });
const results = nexus.search ({ capability : 'chat' , min_reputation : 0.5 });
console .log (results.agents );
const stats = nexus.stats ();
console .log (stats);
CLI
npx autron init --name "MyAgent"
npx autron info
npx autron card --ttl 24h
npx autron verify <token>
npx autron endorse <did> --rating 0.9 --category coding
npx autron delegate <did> --scope "read:*,write:*"
npx autron wallet balance
npx autron wallet transfer <did> --amount 1000000
npx autron wallet address
npx autron wallet airdrop
npx autron token create-mint --name "Autron Token" --symbol ATN
npx autron token mint --to <did> --amount 1000000000
npx autron token info
npx autron payment receipt <payee> <txId> <amount>
npx autron payment verify <token>
npx autron escrow create <payee> --amount 5000000 --deadline 7d
npx autron escrow fund <id >
npx autron escrow release <id >
npx autron escrow status <id >
npx autron escrow list --status funded
npx autron serve --port 3000 --cors
npx autron mcp
TypeScript
Full type declarations are included — no @types package needed:
import {
generateKeypair,
createDID,
createAgentCard,
verifyAgentCard,
Wallet ,
createPayment,
EscrowManager ,
type Keypair ,
type VerifiedAgentCard ,
type VerifiedPayment ,
type Algorithm ,
} from '@autron/core' ;
const keys : Keypair = generateKeypair ('ed25519' );
const did : string = createDID ('key' , { publicKey : keys.publicKey });
const card : string = createAgentCard ({ issuer : did, privateKey : keys.privateKey });
const result : VerifiedAgentCard = verifyAgentCard (card);
API
Crypto
generateKeypair(algorithm?) — Generate Ed25519 or secp256k1 keypair
sign(data, privateKey, algorithm?) — Sign data
verify(data, signature, publicKey, algorithm?) — Verify signature
publicKeyToMultibase(publicKey, algorithm?) — Encode key as multibase
multibaseToPublicKey(multibaseStr) — Decode multibase to key
keyToJWK(publicKey, privateKey?, algorithm?) — Convert to JWK format
jwkToKey(jwk) — Convert from JWK format
DID
createDID(method, options) — Create a DID string
parseDID(didString) — Parse DID into components
resolveDID(didString) — Resolve to W3C DID Document
toStandardDID(autronDID) — Convert to did:key / did:web
fromStandardDID(standardDID) — Convert from standard DID
Agent Card
createAgentCard(options) — Issue a signed identity card (JWS)
verifyAgentCard(token, options?) — Verify signature, expiry, audience
parseAgentCard(token) — Parse without verification
Delegation
createDelegation(options) — Issue a delegation token
verifyDelegation(token, options?) — Verify delegation
checkScope(delegation, requiredScope) — Check granted scopes (supports wildcards)
getSpendLimit(delegation) — Extract spend limit from constraints
Discovery
buildDIDDocument(did, options?) — DID Document with services/controllers
createWellKnown(options) — Build /.well-known/autron.json
parseWellKnown(doc) — Parse well-known document
SERVICE_TYPES — Standard service type constants (AgentCard, Delegation, Messaging, API, Payment, Escrow, Wallet)
Reputation
createEndorsement(options) — Issue a signed endorsement (0.0-1.0 rating)
verifyEndorsement(token, options?) — Verify endorsement
calculateReputation(endorsements, options?) — Aggregate trust score (recency-weighted)
Chain & Wallet
ChainProvider — Abstract multi-chain provider class
SolanaProvider — Solana implementation (lazy-loaded deps)
registerProvider(chainId, provider) — Register a chain provider
getProvider(chainId) — Get registered provider
Wallet — High-level wallet (balance, transfer, transactions)
Wallet.create(identity, options?) — Factory from autron.json identity
Payment
createPayment(options) — Create a payment receipt (JWS)
verifyPayment(token, options?) — Verify payment receipt
parsePayment(token) — Parse without verification
Escrow
createEscrow(options) — Create an escrow token (JWS)
verifyEscrow(token, options?) — Verify escrow token
EscrowManager — SQLite-backed escrow lifecycle (register, fund, release, refund, expire)
ESCROW_STATUS — Status constants (created, funded, released, refunded, expired, disputed)
Server
createServer(options) — Create and start HTTP identity server
handleRequest(options) — Create request handler (BYO server)
Middleware
authenticate(options?) — Create Bearer token auth function
requireScope(scope) — Create delegation scope checker
requireSpend(amount, options?) — Create spend limit checker
extractBearer(req) — Extract Bearer token from headers
extractDelegation(req) — Extract delegation token from headers
AuthError — Auth error class with HTTP status
Client
discoverAgent(urlOrDID) — Discover remote agent
fetchWellKnown(baseUrl) — Fetch well-known document
fetchIdentity(baseUrl) — Fetch agent identity
requestCard(baseUrl, bearer, options?) — Request Agent Card
requestDelegation(baseUrl, bearer, options) — Request delegation
submitEndorsement(baseUrl, bearer, options) — Submit endorsement
verifyRemote(baseUrl, token) — Verify token remotely
Nexus
NexusRegistry — SQLite-backed agent registry (publish, search, get, unpublish, stats, expire)
NEXUS_STATUS — Status constants (active, inactive, expired, suspended)
MCP
createMCPServer(options?) — Create MCP server instance (57 tools, 2 resources)
createSseServer(options?) — Create HTTP/SSE MCP transport server + Nexus HTTP API
JWS (Low-level)
createJWS(header, payload, privateKey, algorithm) — Create JWS compact token
verifyJWS(token, publicKey, algorithm) — Verify and decode
parseJWS(token) — Parse without verification
License
Apache 2.0