Grantex

Open-Source AI Agent Authorization and Delegated Access

What OAuth 2.0 is to humans, Grantex is to agents.

Docs | Quickstart | Release JSON | LLM Index | Spec | IETF Draft

Ownership: Grantex is owned by Orchestrum Technologies LLP. Inventor and owner: Sanjeev Kumar. Contact: sanjeev@orchestrum.in or mishra.sanjeev@gmail.com.

What is Grantex?

Grantex is an open-source delegated authorization protocol and reference implementation for AI agents. It gives each agent a verifiable identity and scoped, time-limited, revocable authority from a human or organization, with multi-agent delegation, service-side verification, and audit records.

Grantex complements OAuth 2.0 and MCP: OAuth handles application and user authorization, MCP connects models to tools, and Grantex proves which agent may perform which action for which principal. Use Grantex when an AI agent acts for a person or organization and a relying service must verify exactly what that agent may do.

Agent Prepaid Wallets and x402 v2

Repository source includes principal-controlled prepaid wallets for AI agents. A principal can assign one or multiple wallets, apply assignment, wallet, agent, shared budget-group, principal, and developer controls, constrain recipients, resource origins, actions, merchants, purposes, projects, and cost centers, require an exact human approval, govern reload velocity, and block one assignment, one wallet, or all wallets available to an agent. Authorizations reserve value atomically in PostgreSQL and are bound to the agent's DPoP OAuth identity and the policy-evaluated semantic context.

@grantex/x402 uses official x402 v2 PAYMENT-REQUIRED, PAYMENT-SIGNATURE, and PAYMENT-RESPONSE messages. The old simulated X-Payment-Proof path is not used. sandbox_ledger is implemented end to end; external custody records deliberately fail closed unless a configured provider can verify funding and settlement. The source checkout now includes opt-in Base native USDC EIP-3009 payments with policy-gated signing, verified funding, durable signature retries and finalized-chain reconciliation. Python 0.5.0 and Go v0.3.0 publish the EVM response and reconciliation APIs; neither adds an automatic HTTP payment wrapper. Published TypeScript 0.6.0 and x402 0.4.0 include the opt-in automatic Base 402/sign/retry flow. All four releases are registry verified. See the Base USDC custody guide, including the limit that blocking cannot recall an already issued on-chain signature.

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

const walletAgent = new PrepaidWalletAgentClient({ oauthClient, accessToken });
const x402 = createX402Agent({
  authorizePayment: walletAgent.x402Authorizer,
  // walletId is optional; omit it for policy-based wallet selection.
});

const logicalPaymentId = 'order_01JZ8Y6Q2M4N7P9T';
const response = await x402.fetch('https://merchant.example/paid-resource', {
  // The merchant uses this header to recover a response lost after settlement.
  headers: { 'Idempotency-Key': logicalPaymentId },
  // Grantex uses this option to recover a reservation response lost before settlement.
  idempotencyKey: logicalPaymentId,
});

For side-effecting resources, the merchant must durably cache the business result under Idempotency-Key. Grantex settlement is idempotent, but a settled payment authorization cannot be verified or execute protected work a second time.

The OAuth grant must include wallet:spend and the exact merchant action scope advertised as extra.grantexScope; wallet assignment policy can restrict that human-approved authority but cannot add to it.

Where Grantex fits

Grantex owns delegated agent identity, semantic spend policy, cross-wallet budgets, exact approvals, atomic reservations, stop controls, and audit. An AgenticOrg deployment or another agent runtime owns orchestration and the human interaction. The wallet issuer or custodian remains responsible for KYC/KYB, AML and sanctions controls, custody, network authorization, MCC/geography/card controls, settlement, FX, refunds, disputes, fraud, and reconciliation. The merchant remains responsible for server-trusted price/payee data, order idempotency, settlement gating, and delivery of the paid result.

See Agent Wallet Governance for the complete responsibility matrix, policy composition, exact approval protocol, and honest residual gap list.

The managed clients are implemented in registry-verified @grantex/sdk@0.6.0, @grantex/x402@0.4.0, Python grantex==0.5.0, and Go v0.3.0. External custody, principal notification delivery, and merchant result idempotency remain operator responsibilities. See the x402 integration guide, wallet lifecycle, and production-readiness guide.

Self-hosted prepaid-wallet dependencies

Running the auth-service does not provision every dependency needed for a real-money product. Self-hosting operators must explicitly provide and test:

• PostgreSQL migrations 091_agent_prepaid_wallets.sql and 092_layered_wallet_spend_controls.sql, backups, restore, and reconciliation for the append-only wallet ledger and policy decisions;
• HTTPS ingress for the exact OAuth audience, including /v1/prepaid-wallets and /v1/prepaid-wallets/** (a static-host 404 breaks agent wallet access even while the origin service is healthy);
• a provider-specific custody, funding, settlement, webhook-deduplication, and recovery adapter before using external wallets; without one, Grantex deliberately returns 503 CUSTODY_ADAPTER_UNAVAILABLE;
• an SSE/WebSocket notification bridge for reload events when a principal must be notified by email, SMS, Slack, WhatsApp, or another external channel; no built-in wallet-email delivery is claimed;
• a merchant-side durable result cache keyed by the HTTP Idempotency-Key for side effects after settlement;
• independent security, provider, reconciliation, incident-response, and applicable legal/regulatory review.

The server deployment and each SDK release are separate. Registry consumers should verify an exact version before installing it rather than inferring availability from repository manifests. The production-readiness guide contains the full hosting checklist and a maintainer-only PowerShell publication runbook.

Supply-chain and license controls

The security workflow audits every tracked npm lockfile, every tracked Python project and requirements surface, and all three Go modules. Dependabot coverage is checked against the repository manifests, external GitHub Actions and container images are pinned to immutable digests, and unreviewed npm license identifiers fail CI. Run npm run audit:supply-chain and npm run audit:python locally before a release.

Apache-2.0 covers Grantex source, not third-party dependencies. See THIRD_PARTY_NOTICES.md for the current Sharp/libvips LGPL and caniuse-lite CC-BY distribution notes, and the supply-chain security guide for the operator checklist. This inventory is an engineering control, not a legal non-infringement opinion; distributors must review the exact artifacts they ship.

OAuth Agent Grants Profile