Know Your Agent
Know which agent is calling.
Before you let it in.
AI agents can now buy, book and call APIs on their own. Neptuv lets each agent prove its ERC-8004 identity with a signature, then checks its trust score against your rules — one API call, allow or deny, with the reasons logged.
Its SDK signs the method, URL, body hash, time and a one-time nonce with the wallet registered on ERC-8004.
Your server passes the Neptuv-* headers and a hash of the body to /api/v1/verify.
The signer must be the agent's registered wallet or owner. Old timestamps and reused nonces are refused.
Score, label, checks, age, reports — your policy answers allow or deny, and the decision is logged.
Playground
Sign a request. Then try to break it.
This uses a sandbox agent on Base Sepolia whose key lives on Neptuv's server, so nothing here touches a real agent or wallet.
1 · The agent signs
Playground Agent · eip155:84532:8004The exact text that was signed
2 · Your server asks Neptuv
Three lines on each side
One-file SDKs for Python and JavaScript. Any Ethereum library can sign — viem, ethers, eth-account, a KMS.
If you build agents
# pip install eth-account requests · https://neptuv.xyz/sdk/neptuv.py
from neptuv import sign_request
headers = sign_request(AGENT_WALLET_KEY, "eip155:8453:1203", "POST", url, body)
requests.post(url, data=body, headers={**headers, "Content-Type": "application/json"})// https://neptuv.xyz/sdk/neptuv.js · works with viem or ethers
import { signRequest } from "./neptuv.js";
const headers = await signRequest({ agent: "eip155:8453:1203", method: "POST", url, body,
signMessage: (m) => account.signMessage({ message: m }) });
await fetch(url, { method: "POST", body, headers: { ...headers, "Content-Type": "application/json" } });If you run a platform
from neptuv import Neptuv, require_trusted_agent
neptuv = Neptuv(api_key=os.environ["NEPTUV_API_KEY"])
@app.post("/orders")
@require_trusted_agent(neptuv, min_score=70) # 401 / 403 unless verified and allowed
def create_order():
agent = flask.g.neptuv["agent"]import { neptuvGuard } from "./neptuv.js";
app.use(express.json({ verify: (req, _res, buf) => { req.rawBody = buf; } }));
app.post("/orders", neptuvGuard({ apiKey: process.env.NEPTUV_API_KEY, policyId: 1 }), createOrder);For smart contracts
Trust you can check on-chain
Platform plans can ask for a signed EIP-712 attestation with every verification. Drop Neptuv's verifier contract into your protocol and require a minimum score before an agent can act — no oracle, no API call from the contract.
NeptuvAttestationVerifier verifier = NeptuvAttestationVerifier(VERIFIER);
function act(NeptuvAttestationVerifier.TrustAttestation calldata a, bytes calldata sig) external {
require(a.agentId == agentIdOf[msg.sender], "not this agent"); // bind it to the caller
require(verifier.isTrusted(a, sig, 70), "agent not trusted");
// ...
}Questions
What is Know Your Agent (KYA)?
Know Your Agent is the agent version of KYC: before you let an AI agent buy, book or call your API, you check which agent it is and whether it can be trusted. With Neptuv the agent proves its ERC-8004 identity by signing the request with its registered wallet, and Neptuv checks its trust score against your rules.
Does the agent have to share its private key?
No. The agent signs a short text with its own wallet, the same way you sign in to a website with a crypto wallet. The key never leaves the agent's server, and signing costs no gas.
What stops someone from replaying a signed request?
Each signature covers the exact method, URL, body, a timestamp and a one-time nonce. Neptuv rejects requests older than five minutes and any nonce it has seen before.
Which wallet can sign for an agent?
The agentWallet set on the ERC-8004 Identity Registry, or the agent owner's wallet. Neptuv checks the signer against the registry, so a stolen agent name is useless without the key.
Can a smart contract check Neptuv's answer?
Yes. Platform plans can ask for a signed EIP-712 attestation of an agent's score. A small Solidity contract verifies it on-chain, so contracts can require a minimum trust score without calling Neptuv.