Trace issuance is upstream. Checkout enforces it.
Trace issuance is upstream. /api/v1/verify returns identity and a recommendation. /api/v1/checkout/sessions enforces the signed mandate. Pre-dispute opens against that record if the order is challenged.
Each primitive is a contract.
Agent Identity
Every KYA agent carries a signed, revocable identity tied to a real business operator. POST /api/v1/verify resolves the agent to the operator behind it and returns a trust_score recommendation. The principal hash and spend scope ride on a signed trace the operator issues upstream, and are enforced when you open the checkout session.
Agent Wallet Auth
The operator issues a signed trace carrying scope, spending cap, audience, and principal hash. POST /api/v1/checkout/sessions validates that trace against a delegated wallet and fails the session with an explicit reason when the transaction falls outside scope — before a card is touched.
Transaction Guard
Policy evaluation splits across two calls at the checkout edge. POST /api/v1/verify returns an accept / review / decline recommendation from trust_score, merchant verify rules, and the agent's configured transaction ceiling. POST /api/v1/checkout/sessions runs the trace-scope, wallet, audience, amount, and MCC checks before money moves.
Bot Classification
Not all automated traffic is a shopping agent. A KYA ID is a registered buyer, not a scraper. Bot classification is a separate signal — it is not what /api/v1/verify or /api/v1/checkout/sessions enforce.
Merchant Verification
Merchants that finished onboarding get an agent-friendly signal the other side can check. That is not merchant KYC. It is the other half of the handshake.
Evidence Log
Verify decisions and checkout sessions keep the decision, trace, and policy-check record together. Those records can be joined with the signed trace when a merchant or operator opens a pre-dispute case — no screenshots, no forensics.
Platform questions.
What is the KnowYourAgent platform?
Two calls at the checkout edge. /api/v1/verify resolves the agent's identity and returns a trust_score recommendation; /api/v1/checkout/sessions validates the signed trace the operator issued upstream and enforces scope, spend cap, wallet, audience, and MCC. The resulting decision and checkout-session records can be referenced later if a pre-dispute workflow is opened.
How does KYA verify an agent's identity?
Each registered agent receives a unique KYA ID tied to a verified business operator. /api/v1/verify resolves that ID to the operator and returns the trust_score recommendation inline with your authorization. The signed trace that carries the principal hash and spend scope is validated separately — when the merchant opens a checkout session against /api/v1/checkout/sessions.
What happens if an agent tries to exceed its spending cap?
/api/v1/checkout/sessions fails the session with an explicit reason code when the transaction exceeds the trace's spend cap or falls outside scope — before the card is touched. The failed session is recorded against the trace id, so the merchant and operator have the exact failure record if they later need to open a pre-dispute case.
Merchants add verify, then checkout-sessions.
Call /api/v1/verify for the recommendation, then open /api/v1/checkout/sessions when you need signed-trace enforcement. Developers work against a stable REST surface from any language that speaks HTTP. Typed SDKs are on the roadmap; the CLI@knowyouragent/cliships today.