/ DEVELOPERSREST · Trace JWT · CLI

Verify the agent, then enforce the signed trace at checkout.

Start with /api/v1/verify for identity, trust_score, and reasons. Add /api/v1/checkout/sessions when you need signed-trace enforcement for scope, spend, audience, and merchant policy. API keys are issued from the dashboard. The dashboard limits key creation to the environments assigned to your account.

An agent operator checking a workflow on a tablet beside two monitors
/ Integration workVerify first, then enforce policy.
/ 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 reference lists the available /api/v1 routes used in the workflows above.

/ 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.
POST
/api/v1/checkout/sessions
Evaluate a signed trace and merchant policy before checkout.
GET
/api/v1/checkout/sessions/{id}
Retrieve a checkout-session decision.
POST
/api/v1/checkout/sessions/{id}/confirm
Confirm the authorized checkout result.
POST
/api/v1/checkout/sessions/{id}/cancel
Cancel an open checkout session.
/ 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 records the fields needed to evaluate and review a request. A verification record can include agent identity, merchant context, transaction amount and currency, merchant category, request IP, and the policy result.
/ 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?

Business API requests accept an API key as a Bearer token. API-key management routes use your signed-in dashboard session. Trace tokens (X-KYA-Trace-ID) are Ed25519-signed JWTs minted by /api/v1/trace/generate; they carry transaction authorization and do not replace caller authentication.

Is there a Node or Python SDK?

Not yet. The versioned REST API works with standard HTTP clients. The Quickstart tabs above show raw Node, Python, and cURL requests without a KYA SDK dependency.

How do I add KYA verification to my checkout?

Call /api/v1/verify to get a recommendation. If checkout must enforce signed-trace scope, amount, audience, or merchant policy, create a checkout session with /api/v1/checkout/sessions before you authorize payment.

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.

Request a pilot