MPP Agent Passport

W3C Verifiable Credential for agent identity in machine-to-machine payments via the Machine Payments Protocol (MPP).

Overview

The Machine Payments Protocol (MPP) defines how AI agents pay for services via HTTP 402 flows and streaming sessions. MPP solves payment mechanics but has a structural gap: no identity layer.

When an agent makes an MPP payment, the source field is a wallet address — no human name, no organization, no authorization chain. For low-value API calls this is fine. For B2B procurement and regulated transactions, it’s a compliance blocker.

Grantex fills this gap with the AgentPassportCredential — a W3C VC 2.0 credential that binds agent identity, human delegation, spending limits, and payment categories into a single offline-verifiable document.

The @grantex/mpp package provides both agent-side middleware (attach passports to outgoing requests) and merchant-side verification (validate passports on incoming requests) in a single package.

How It Works

┌──────────────────────────────────────────────────────────────────┐
│  1. Human issues AgentPassportCredential via Grantex             │
│     → W3C VC 2.0 with Ed25519 proof, StatusList2021 revocation  │
│     → Contains: agentDID, humanDID, orgDID, categories, limits  │
└─────────────────────────┬────────────────────────────────────────┘
                          ▼
┌──────────────────────────────────────────────────────────────────┐
│  2. Agent makes MPP request to merchant                          │
│     → Authorization: Payment <mpp-token>                         │
│     → X-Grantex-Passport: <base64url-encoded-vc>                │
└─────────────────────────┬────────────────────────────────────────┘
                          ▼
┌──────────────────────────────────────────────────────────────────┐
│  3. Merchant verifies passport in <50ms (offline-capable)        │
│     → Checks signature, expiry, categories, amount limits        │
│     → Returns VerifiedPassport with full identity chain           │
└─────────────────────────┬────────────────────────────────────────┘
                          ▼
┌──────────────────────────────────────────────────────────────────┐
│  4. Merchant fulfills request — knows exactly who authorized it  │
│     → Audit entry: passportId, agentDID, humanDID, amount        │
└──────────────────────────────────────────────────────────────────┘

AgentPassportCredential Structure

The credential follows the W3C Verifiable Credentials Data Model v2.0:

Field	Type	Description
@context	string[]	["https://www.w3.org/ns/credentials/v2", "https://grantex.dev/contexts/mpp/v1"]
type	string[]	["VerifiableCredential", "AgentPassportCredential"]
id	string	urn:grantex:passport:<ulid>
issuer	string	did:web:grantex.dev
validFrom	string	ISO 8601 issuance timestamp
validUntil	string	ISO 8601 expiry (max 30 days)
credentialSubject.id	string	Agent DID (did:grantex:ag_...)
credentialSubject.humanPrincipal	string	DID of the authorizing human
credentialSubject.organizationDID	string	Org DID (did:web:<domain>)
credentialSubject.grantId	string	Underlying Grantex grant ID
credentialSubject.allowedMPPCategories	string[]	Permitted MPP service categories
credentialSubject.maxTransactionAmount	object	{ amount: number, currency: string }
credentialSubject.paymentRails	string[]	Payment networks (e.g., ["tempo"])
credentialSubject.delegationDepth	number	From grant delegation chain
credentialStatus	object	StatusList2021 revocation entry
proof	object	Ed25519Signature2020

KYA tier

With AGENT_PASSPORT_KYA_TIER_ENABLED=true (default off), an issued passport’s credentialSubject may carry kyaTier:

"kyaTier": {
  "tier": "tier-1",
  "trustMarks": ["urn:grantex:tm:agent.identity"],
  "mappingVersion": "2026-10-pending-scheme-specs"
}

The tier comes from an operator-configured table, AGENT_PASSPORT_KYA_TIER_MAP, that maps registry trust marks to tier labels. The table is empty by default, so no tier is issued until an operator configures one. The card networks’ and wallet schemes’ KYA tier specifications are not yet published; until they are, Grantex defines no tiers of its own and attaches no meaning to a label beyond the mapping. The first table entry whose trust marks the agent’s counted attestations all hold gives the tier. The claim reflects the registry at issuance; read the registry lookup for the agent’s standing now. verifyPassport in @grantex/mpp returns kyaTier when the signed passport carries one, and refuses a malformed one (MALFORMED_CREDENTIAL).

MPP Category Scopes

Each MPP category maps to a Grantex scope. The agent’s grant must include the corresponding scope:

MPP Category	Grantex Scope
inference	payments:mpp:inference
compute	payments:mpp:compute
data	payments:mpp:data
storage	payments:mpp:storage
search	payments:mpp:search
media	payments:mpp:media
delivery	payments:mpp:delivery
browser	payments:mpp:browser
general	payments:mpp:general

Trust Registry

The trust registry is a public endpoint that maps organization DIDs to verified trust records:

curl https://api.grantex.dev/v1/trust-registry/did:web:grantex.dev

{
  "organizationDID": "did:web:grantex.dev",
  "verifiedAt": "2026-03-20T03:11:31.447Z",
  "verificationMethod": "soc2",
  "trustLevel": "soc2",
  "domains": ["grantex.dev"]
}

Trust levels: basic (self-declared), verified (DNS-TXT proof), soc2 (SOC 2 audit verified).

Verification Error Codes

Code	Description
PASSPORT_EXPIRED	Credential validUntil has passed
PASSPORT_REVOKED	StatusList2021 bit is set
INVALID_SIGNATURE	Ed25519/RS256 signature verification failed
UNTRUSTED_ISSUER	Issuer DID not in the trusted issuers list
CATEGORY_MISMATCH	Passport categories don’t cover the required service
AMOUNT_EXCEEDED	Passport max amount below required threshold
MISSING_PASSPORT	No X-Grantex-Passport header provided
MALFORMED_CREDENTIAL	Invalid base64url encoding or missing VC fields

API Endpoints

Method	Endpoint	Auth	Description
POST	/v1/passport/issue	API key	Issue an AgentPassportCredential
GET	/v1/passport/:id	API key	Retrieve passport by ID
POST	/v1/passport/:id/revoke	API key	Revoke passport (flips StatusList2021 bit)
GET	/v1/trust-registry/:orgDID	None	Look up org trust record (public)
GET	/v1/trust-registry	API key; admin key (ADMIN_API_KEY) when TRUST_REGISTRY_ADMIN_LISTING_ENFORCED=true	List all trust records, across developers (operator)

SDK Support

The PassportsClient / PassportsService is available across all three SDKs:

SDK	Access	Since
TypeScript (@grantex/sdk)	client.passports.issue(...)	0.3.3
Python (grantex)	client.passports.issue(...)	0.3.3
Go (grantex-go)	client.Passports.Issue(ctx, ...)	0.1.3

Next Steps

• MPP Integration Guide — step-by-step setup for agents and merchants
• Verifiable Credentials — the underlying VC infrastructure
• DID Infrastructure — how agent DIDs work
• Delegation — multi-agent delegation chains

Ownership

Grantex is owned by Orchestrum Technologies LLP. Inventor and owner: Sanjeev Kumar. Ownership contact: [e-mail] or [e-mail].