/ DEVELOPERSREST · Trace JWT · CLI

Verify an agent in a single call.

One endpoint returns the agent's identity, a trust recommendation, and the reasons behind it. Sandbox keys are issued from the dashboard. Production keys require KYB review.

/ 01Quickstart

From zero to first verification.

Pick a language, paste it into your checkout handler, set KYA_KEY, and call the endpoint before you authorize the payment.

POST /api/v1/verify
curl -X POST https://knowyouragent.xyz/api/v1/verify \
  -H "Authorization: Bearer $KYA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kya_id": "kya_agent_01HX7K...",
    "transaction_context": {
      "amount_cents": 14900,
      "currency":     "USD"
    }
  }'
200 OKrecommendation: accept
{
  "kya_id":          "kya_agent_01HX7K9M2PQR",
  "status":          "active",
  "trust_score":     82,
  "trust_level":     "high",
  "recommendation":  "accept",
  "reasons":         [],
  "operator": {
    "name":     "Example Labs",
    "verified": true
  },
  "verification_id": "kya_ver_01HX7KA9J..."
}

Base URL: https://knowyouragent.xyz/api/v1

/ 02Reference

Endpoints, grouped by primitive.

The surface area is small on purpose. Each endpoint below is live in the Next.js API layer today; planned endpoints get their own changelog entry when they ship.

/ AIDAgent Identity
POST
/api/v1/agents
Register a new agent identity. Requires operator_id.
GET
/api/v1/agents/{id}
Resolve a KYA ID to its current record.
/ TXGTransaction Guard
POST
/api/v1/verify
Run a verification check for an agent request.
POST
/api/v1/trace/generate
Mint an X-KYA-Trace-ID JWT for a transaction.
POST
/api/v1/trace/validate
Validate a trace token signature and claims.
/ MVFMerchant Verification
POST
/api/v1/keys
Issue a merchant or operator API key.
GET
/api/v1/keys
List keys issued to the current account.
DELETE
/api/v1/keys/{id}
Revoke an API key.
/ LOGPre-Dispute & Audit
POST
/api/v1/pre-dispute/alerts
Create a pre-dispute alert for an in-flight transaction.
GET
/api/v1/pre-dispute/alerts
List alerts visible to the caller.
GET
/api/v1/trace
List trace records for a given agent.
/ 03Two sides

One protocol, used from both ends.

/ OPERATOR
You run AI agents.
Register each agent, attach the principal who authorized it, set spend limits, and build a reputation through real transaction outcomes.
/ MERCHANT
You sell online.
Call /api/v1/verify at checkout. Read the recommendation. Store the verification_id against your order record so the decision, score, and reasons are preserved alongside it.
/ 04Scope

What this API does not do.

  • It does not process payments. It returns a signal your payment path can act on.
  • It does not block transactions on your behalf. The decision stays with your system.
  • It does not track end users. It records agent identity and action, nothing more.
/ 05API questions

Frequently asked, answered.

How does the KnowYourAgent verification API work?

Merchants send a POST request to /api/v1/verify with the agent’s kya_id and an optional transaction_context. The API returns a recommendation (accept / review / decline), a trust_score and trust_level, the posted operator identity, the reasons behind the decision, and a verification_id you can store against the order.

What authentication does the KYA API require?

Every request carries a Bearer token in the Authorization header. Merchant and operator keys are scoped separately and are issued from the dashboard after account creation. Trace tokens (X-KYA-Trace-ID) are Ed25519-signed JWTs minted by the /api/v1/trace/generate endpoint.

Is there a Node or Python SDK?

Not yet. We publish the CLI (@knowyouragent/cli) and a stable REST surface. Typed SDKs are on the roadmap; until they ship, the Quickstart tabs above show the raw HTTP calls.

How do I add KYA verification to my checkout?

One POST call to /api/v1/verify before you authorize the payment. Pass the kya_id and a transaction_context with amount_cents. Read the recommendation and decide whether to proceed, escalate to review, or decline.

Integration support

Our engineers will pair with your team on the first verification call, at no charge.

We are onboarding a small group of merchants and operators by hand. That means you get direct access to the people building the protocol, not a support queue.