Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.grantex.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
Grantex Delegation Token (GDT)

A Grantex Delegation Token is a W3C Verifiable Credential 2.0 that authorizes an AI agent to make payments on behalf of a human principal. It is encoded as a compact JWT signed with Ed25519 (EdDSA algorithm).

​
Token Format

​
JWT Header

{
  "alg": "EdDSA",
  "typ": "JWT"
}

​
JWT Payload

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

​
Claim Definitions

​
Standard JWT Claims

ClaimTypeDescription
issstringIssuer — the principal’s did:key who authorized the delegation
substringSubject — the agent’s did:key being delegated to
iatnumberIssued-at timestamp (Unix epoch seconds)
expnumberExpiration timestamp (Unix epoch seconds)
jtistringUnique token ID (UUID v4) for revocation and audit

​
VC Context

The vc claim follows the W3C Verifiable Credentials Data Model 2.0:
FieldValueDescription
@context["https://www.w3.org/ns/credentials/v2", "https://grantex.dev/v1/x402"]W3C VC 2.0 context + Grantex x402 context
type["VerifiableCredential", "GrantexDelegationToken"]Credential types

​
Credential Subject

FieldTypeDescription
idstringAgent DID (matches JWT sub)
scopestring[]Array of authorized resource:action patterns
spendLimit.amountnumberMaximum spend in the given period
spendLimit.currencystring"USDC" or "USDT"
spendLimit.periodstringRolling period: "1h", "24h", "7d", "30d"
paymentChainstringTarget blockchain (default: "base")
delegationChainstring[]Ordered list of DIDs in the delegation chain

​
Scope Format

Scopes follow the resource:action pattern: 
weather:read      — Read weather data
weather:write     — Write/update weather data
weather:*         — All weather actions (wildcard)
*                 — All resources and actions (full access)

​
Scope Matching Rules

  1. Exact match: weather:read matches weather:read
  2. Action wildcard: weather:* matches weather:read, weather:write, etc.
  3. Global wildcard: * matches everything
  4. No implicit escalation: weather:read does NOT match weather:write

​
Spend Limit Periods

PeriodDurationUse Case
1h1 hourHigh-frequency, low-value APIs
24h24 hoursStandard daily delegation
7d7 daysWeekly batch operations
30d30 daysMonthly budgets

​
Expiry Formats

The expiry parameter accepts:
FormatExampleDescription
Shorthand hours24h24 hours from now
Shorthand days7d7 days from now
ISO 8601 durationPT24H24 hours from now
ISO 8601 durationP7D7 days from now
ISO 8601 datetime2026-03-22T00:00:00ZAbsolute expiry

​
Delegation Chain

The delegationChain field records the full chain of delegation: 
Organization (did:key:z6Mk...org...)
  └── Manager (did:key:z6Mk...mgr...)
       └── Agent (did:key:z6Mk...agent...)
The delegation chain enables audit of the full authorization path.

​
Cryptographic Details

PropertyValue
AlgorithmEdDSA (Ed25519)
Key typeOKP (Octet Key Pair)
CurveEd25519
DID methoddid:key with multicodec prefix 0xed01
Multibase encodingBase58btc (z prefix)
Token encodingCompact JWT serialization

​
Verification Checks

A GDT is considered valid only if ALL of the following pass:
  1. The JWT signature is valid for the issuer’s Ed25519 public key
  2. The exp claim is in the future
  3. The jti is not in the revocation registry
  4. The requested resource matches at least one granted scope
  5. The request amount does not exceed the spend limit
  6. The vc.type array includes both VerifiableCredential and GrantexDelegationToken
  7. The vc.credentialSubject contains valid scope and spend limit data