TypeScript SDK

Install, configure, and get started with the @grantex/sdk TypeScript SDK.

Installation

Published release: @grantex/sdk@0.6.0. npm integrity, exact-version clean installation, public exports, and a zero-vulnerability consumer audit were verified on 7 September 2026.

npm install @grantex/sdk@0.6.0

The unpinned npm install @grantex/sdk command follows npm’s current latest tag. Keep the exact version above in reproducible builds. See Release Status before upgrading.

SDK 0.6.0 includes PrepaidWalletAgentClient, PrincipalPrepaidWalletClient, and DeveloperPrepaidWalletPolicyClient with safe assignment defaults, layered policy, exact approval, semantic context, and reload governance. Version 0.6.0 also adds EVM payment responses and reconcileReservation() to principal and agent wallet clients. Pair it with @grantex/x402@0.4.0 for opt-in Base USDC 402/sign/retry. External custody remains fail-closed until the operator configures the Base custody/RPC adapter or supplies another verified provider. See x402 Prepaid Wallets and Agent Wallet Governance.

Requirements

• Node.js 18+ (uses native fetch and crypto)
• ESM only — the package ships as "type": "module" with TypeScript NodeNext resolution

Configuration

import { Grantex } from '@grantex/sdk';

const grantex = new Grantex({
  apiKey: process.env.GRANTEX_API_KEY,  // required (or set GRANTEX_API_KEY env var)
  baseUrl: 'https://api.grantex.dev',   // optional, defaults to production
  timeout: 30_000,                       // optional, request timeout in ms
});

Options

apiKey · string · required

Your Grantex API key. Falls back to the GRANTEX_API_KEY environment variable if omitted.

baseUrl · string · default: "https://api.grantex.dev"

Base URL for the Grantex API. Override for self-hosted or local development.

timeout · number · default: "30000"

Request timeout in milliseconds. The SDK uses AbortController to enforce the deadline.

Quick start

The complete authorization flow in one script:

import { Grantex, verifyGrantToken } from '@grantex/sdk';

const grantex = new Grantex({ apiKey: process.env.GRANTEX_API_KEY });

// 1. Register an agent
const agent = await grantex.agents.register({
  name: 'travel-booker',
  description: 'Books flights and hotels on behalf of users',
  scopes: ['calendar:read', 'payments:initiate:max_500', 'email:send'],
});
console.log(agent.did);
// → did:grantex:ag_01HXYZ123abc...

// 2. Request user authorization
const authRequest = await grantex.authorize({
  agentId: agent.id,
  userId: 'user_abc123',
  scopes: ['calendar:read', 'payments:initiate:max_500'],
  expiresIn: '24h',
  redirectUri: 'https://yourapp.com/auth/callback',
});
// Redirect the user to authRequest.consentUrl

// 3. Exchange the authorization code for a grant token
const token = await grantex.tokens.exchange({
  code,                  // from the redirect callback
  agentId: agent.id,
});
console.log(token.grantToken);  // RS256 JWT
console.log(token.scopes);      // ['calendar:read', 'payments:initiate:max_500']

// 4. Verify signature and claims locally after fetching the remote JWKS
const grant = await verifyGrantToken(token.grantToken, {
  jwksUri: 'https://api.grantex.dev/.well-known/jwks.json',
  requiredScopes: ['calendar:read'],
});
console.log(grant.principalId); // 'user_abc123'

// 5. Revoke the token when done
await grantex.tokens.revoke(grant.tokenId);

Available resources

The Grantex client exposes the following sub-clients:

Property	Description	Reference
grantex.agents	Register, list, update, and delete agents	Agents
grantex.tokens	Exchange, verify, and revoke tokens	Tokens
grantex.grants	Manage grants, delegate to sub-agents	Grants
grantex.audit	Log and query the tamper-evident audit trail	Audit
grantex.webhooks	Create and manage webhook endpoints	Webhooks
grantex.policies	Define authorization policies	Policies
grantex.compliance	Compliance summaries, exports, evidence packs	Compliance
grantex.anomalies	Detect and acknowledge anomalies	Anomalies
grantex.billing	Subscription management via Stripe	Billing
grantex.scim	SCIM 2.0 user provisioning	SCIM
grantex.sso	OIDC single sign-on	SSO
grantex.principalSessions	End-user dashboard sessions	Principal Sessions
grantex.vault	Store, retrieve, and exchange service credentials	Vault
grantex.budgets	Per-grant spending budgets and transactions	Budgets
grantex.events	SSE event streaming	Events
grantex.usage	Usage metering and history	Usage
grantex.domains	Custom domain verification	Domains
grantex.webauthn	FIDO2/WebAuthn passkey management	WebAuthn
grantex.credentials	Verifiable Credentials and SD-JWT	Credentials
grantex.passports	MPP agent passport credentials	Passports
grantex.commerce	Commerce V1 / OACP merchant discovery, catalog, consent, passport, payment, checkout, webhooks, and ops	Commerce V1
grantex.dpdp	DPDP Act 2023 compliance — consent, grievances, erasure, exports	DPDP

Standalone exports

These functions can be used without instantiating a Grantex client:

Export	Description	Reference
verifyGrantToken()	Local JWT verification with a JWKS fetch per standalone call	Offline Verification
generatePkce()	Generate PKCE S256 challenge pairs	PKCE
verifyWebhookSignature()	Verify webhook payload signatures	Webhooks

Error handling

All errors extend GrantexError. See the Error Handling reference for the full hierarchy and usage patterns.

Ownership

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