Know Your Agent (KYA): how to verify which AI agent is calling your API

The short answer

Why it's needed now

AI agents increasingly act on their own: they call APIs, compare prices, place orders and pay with standards such as x402. A platform that serves agents faces the same question a bank faces with customers — who is this, and should I let them in? — but with software that can be copied, renamed and redeployed in minutes.

What doesn't work

• User agents and names. Any client can claim to be "Atlas Research". Strings prove nothing.
• IP allow-lists. Agents run on shared cloud infrastructure; an IP says little about who operates the agent.
• API keys alone. A key identifies an account with you, not the agent's public identity or its reputation elsewhere — and every platform has to onboard every agent by hand.

Signed requests tied to an on-chain identity

ERC-8004 gives each agent a permanent ID in an on-chain Identity Registry, with an owner and an optional agentWallet. That wallet becomes the agent's passport: the agent signs a short, fixed-format text describing the request, and anyone can check that the signature came from the wallet the registry lists.

neptuv-agent-auth/1
agent: eip155:8453:1203
method: POST
url: https://api.example.com/orders
timestamp: 1792776609
nonce: Jx2v0vYb6q3Kp1sQwE9z
body-sha256: 13652570e09af237fbe0535b159310fd7ee8d65dca4845528cd51211b8db0deb

Because the text includes the method, the exact URL, a hash of the body, the time and a one-time nonce, a signature can't be reused for another request, replayed later, or attached to a modified body. The private key never leaves the agent, and signing costs no gas.

From identity to a decision

Knowing who is calling is half the job. The other half is deciding whether that agent is good enough for this action. A sensible policy might require:

• a Neptuv Score of at least 60–70, and no Flagged label;
• at least one independent validation for high-value actions;
• an on-chain identity older than 30 days for payments;
• no reports under review from other businesses.

Write the rules once as a policy, and every request gets an allow or deny with reasons — logged, so you can show auditors exactly why each agent was let in.

Adding it to your platform

With Neptuv's one-file SDKs it's a decorator or a middleware:

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)
def create_order():
    ...

Agents that don't sign yet can still be gated by ID with /api/v1/gate, so you can roll KYA out gradually. Try signing and verifying a request in the playground.

On-chain checks

Smart contracts can't call an API, but they can check a signature. Neptuv's signed EIP-712 attestations carry an agent's score, label and an expiry; a few lines of Solidity verify them, so a protocol can require a minimum trust score without trusting an oracle.

Checklist

Keep reading