Grantex x402 — Authorization for Agent Payment Flows

The Gap in x402

x402 carries payment requirements; Grantex can add verifiable authorization context.

! Without Grantex

x402 proves a payment was made, but not that the paying agent was authorized. A compromised agent can drain a wallet by invoking x402-gated APIs with no scope, no limit, no audit trail, and no kill switch.

✓ With Grantex

A configured x402 request can carry a Grantex Delegation Token (GDT) with signed principal, scope, limit, expiry, and delegation claims. The merchant must verify and enforce those claims before serving the protected action.

How It Works

Four steps from delegation to data.

Issue GDT

Principal issues a scoped delegation token: weather:read, $10/day, 24h expiry.

Attach to Request

Agent sends the request with X-Grantex-GDT header containing the signed JWT.

Pay + Verify

API returns 402; the configured payment handler validates settlement and the merchant verifies the GDT before serving the protected response.

Audit Trail

Integrated code can send selected authorization and payment events to the configured logger; the default logger is in-memory and not durable.

Developer Experience

Three APIs cover the entire flow.

Issue a GDT

Agent Fetch

Protect API

import { generateKeyPair, issueGDT } from '@grantex/x402';

const principal = generateKeyPair();
const agent = generateKeyPair();

const gdt = await issueGDT({
  agentDID: agent.did,
  scope: ['weather:read'],
  spendLimit: { amount: 10, currency: 'USDC', period: '24h' },
  expiry: '24h',
  signingKey: principal.privateKey,
});

import { createX402Agent } from '@grantex/x402';

const x402 = createX402Agent({
  gdt: gdtToken,
  paymentHandler: async (details) => {
    // Sign USDC transfer on Base L2
    return await payOnBase(details);
  },
});

// Automatic: 402 -> pay -> retry with GDT
const res = await x402.fetch('https://api.weather.xyz/forecast');

import express from 'express';
import { x402Middleware } from '@grantex/x402';

const app = express();

app.use('/api/weather', x402Middleware({
  requiredScopes: ['weather:read'],
  requiredAmount: 0.001,
  currency: 'USDC',
}));

app.get('/api/weather/forecast', (req, res) => {
  res.json({
    forecast: 'sunny',
    authorizedBy: req.gdt.principalDID,
  });
});

GDT Token Structure

W3C Verifiable Credential 2.0 encoded as a JWT, signed with Ed25519.

{ "iss": "did:key:z6Mk...principal...", "sub": "did:key:z6Mk...agent...", "vc": { "@context": ["https://www.w3.org/ns/credentials/v2"], "type": ["VerifiableCredential", "GrantexDelegationToken"], "credentialSubject": { "scope": ["weather:read"], "spendLimit": { "amount": 10, "currency": "USDC", "period": "24h" }, "paymentChain": "base", "delegationChain": ["did:key:...principal..."] } }, "exp": 1711123200, "jti": "550e8400-e29b-..." }

scope

What APIs the agent can access: weather:read, news:*, etc.

spendLimit

Maximum spend per period: $10 USDC per 24 hours.

delegationChain

Full chain from organization to principal to agent.

paymentChain

Target blockchain for payments: Base L2.

Features

W3C VC 2.0

Standards-compliant Verifiable Credentials for interoperability.

Ed25519 Signatures

Ed25519 signature verification can use cached keys; current revocation state still requires refreshed status material.

Spend Limits

Signed limit claims must be enforced transactionally by the merchant or payment handler; claims alone do not prevent wallet drain.

Revocation Registry

Verification checks token revocation. Use a shared registry when enforcement spans multiple processes or services.

Pluggable Audit Trail

Integrated issuance, verification, rejection, and payment paths can emit events to a configured logger; the default logger is in-memory.

Base L2 Native

The documented example targets USDC on Base L2. Other chains require a compatible payment handler and application-level testing.

Architecture

Grantex × x402