Protocol check & merchant verify

Normalization and crypto verification run on the KYI API (kyi/). The SDK only posts the protocol envelope.

Flow

User seals an Abstraxn mandate (authority ceiling).
Agent builds a cart and may create AP2 / VI / ACP+SPT credentials.
Agent calls POST /v1/warrant/decisions with a protocol envelope (or legacy NormalizedAction).
KYI decodes → verifies → Cedar check → ALLOW/DENY + signed receipt.
Agent stops on DENY (KYI does not sit in the payment path).
Merchant/PSP calls POST /v1/warrant/verify with the same cart + mandate_id.

Agent: protocol check

POST /v1/warrant/decisions
x-api-key: <mandate API key>

ACP example

{
  "protocol": "acp",
  "agent_id": "agent_chatgpt_01",
  "domain": "commerce.checkout",
  "session": {
    "currency": "usd",
    "merchant_id": "acct_nike",
    "line_items": [{ "name": "Nike Air", "amount": 9900, "quantity": 1 }]
  },
  "spt": {
    "merchant_id": "acct_nike",
    "allowance": { "max_amount": 9900, "currency": "usd" },
    "expires_at": 1893456000
  }
}

Amounts in ACP/SPT/AP2/VI payment claims are minor units (cents). KYI converts to major units before Cedar (e.g. 9900 → 99.00 USD).

AP2 / VI example

Send a compact SD-JWT and issuer keys:

{
  "protocol": "ap2",
  "agent_id": "agent_chatgpt_01",
  "domain": "commerce.checkout",
  "credential": "<issuer-jwt>~<disclosure>~…",
  "checkout": {
    "checkout_hash": "<same as payment transaction_id>",
    "line_items": [{ "name": "Nike Air", "category": "footwear" }]
  },
  "verification": {
    "jwks": { "keys": [/* issuer JWK */] }
  }
}

Or use "verification": { "jwks_url": "https://issuer.example/.well-known/jwks.json" } (HTTPS only; private hosts blocked). Unsigned AP2/VI payment claims alone are rejected — a verifiable credential string is required.

SDK

import { Warrant } from '@abstraxn/warrant';

const warrant = new Warrant({ apiKey: process.env.WARRANT_MANDATE_API_KEY! });

const { decision, protocol_evidence } = await warrant.checkProtocol({
  protocol: 'acp',
  agent_id: 'agent_chatgpt_01',
  domain: 'commerce.checkout',
  session: { /* … */ },
  spt: { /* … */ },
});

if (decision.verdict !== 'ALLOW') {
  // do not create SPT / complete checkout
}

Merchant: verify (shield)

POST /v1/warrant/verify
x-api-key: <application API key>

Body = same protocol envelope plus mandate_id.

const merchant = new Warrant({ apiKey: process.env.ABSTRAXN_API_KEY! });

const { decision } = await merchant.verify({
  mandate_id: 'mnd_sha256:…',
  protocol: 'acp',
  agent_id: 'agent_chatgpt_01',
  domain: 'commerce.checkout',
  session: { /* same cart */ },
  spt: { /* … */ },
});

What each protocol does today

Protocol	Decode	Crypto
`raw`	Passthrough `NormalizedAction`	n/a
`ap2`	SD-JWT → payment/checkout claims	Issuer JWT (+ optional KB-JWT) via JWKS
`vi`	Same claim map as AP2	Same as AP2
`acp`	Session line items + optional SPT	Structural + expiry / amount / merchant match
`spt`	SPT allowance as proposed charge	Expiry + required fields

Sample files in repo

See kyi/examples/protocol-samples/ for copy-paste curl bodies.

Getting started

Build

Audit & on-chain

Protocol check & merchant verify

Flow

Agent: protocol check

ACP example

AP2 / VI example

SDK

Merchant: verify (shield)

What each protocol does today

Sample files in repo

​Flow

​Agent: protocol check

​ACP example

​AP2 / VI example

​SDK

​Merchant: verify (shield)

​What each protocol does today

​Sample files in repo

​Related

Flow

Agent: protocol check

ACP example

AP2 / VI example

SDK

Merchant: verify (shield)

What each protocol does today

Sample files in repo

Related