@vanterlabs/sdk

TypeScript SDK for Vanter backend integrations.

This package wraps the Developer Docs auth flow into a single API surface:

1. Build org-scoped authenticate URLs for your bot
2. Exchange auth code + auto-provision wallets/roles/session
3. Execute sponsored transactions with short-lived AGENT_JWT

Install

npm install @vanterlabs/sdk

pnpm add @vanterlabs/sdk

yarn add @vanterlabs/sdk

bun add @vanterlabs/sdk

Deno (npm compatibility):

import { VanterClient } from "npm:@vanterlabs/sdk";

Quickstart (TypeScript)

import {
  VanterClient,
  generateAgentKeypair,
  createSponsorExecuteJwtPair,
} from "@vanterlabs/sdk";

const client = new VanterClient({
  gatewayBaseUrl: "https://gateway.vanter.trade", // optional
  appBaseUrl: "https://app.vanter.trade", // optional
  accessKeyId: process.env.VANTER_ACCESS_KEY_ID!,
  accessKeySecret: process.env.VANTER_ACCESS_KEY_SECRET!,
});

// Step 1: share this URL from your bot
const authenticateUrl = client.createAuthenticateUrl({
  organizationId: process.env.VANTER_ORG_ID!,
});

// Step 2: exchange auth code and auto-provision in one call
const keys = await generateAgentKeypair();

const auth = await client.authenticate({
  organizationId: process.env.VANTER_ORG_ID!,
  authCode: process.env.AUTH_CODE!,
  agentPublicKeyBase64: keys.publicKeyBase64,
});

const sessionId = auth.session_id;
const walletId = auth.wallet_id ?? auth.agent_session.wallet_ids[0];
if (!walletId) {
  throw new Error("No wallet_id returned from authenticate");
}

// Optional: recover context later by app_user_id/provider_sub/user_id
const context = await client.resolveAuthenticationContext({
  organizationId: process.env.VANTER_ORG_ID!,
  appUserId: auth.app_user.id,
});

// Step 3: create EVM JWT pair and execute
const { bearerJwt, authorizationJwt } = await createSponsorExecuteJwtPair({
  appId: auth.app.id,
  sessionId,
  walletId,
  privateKeyHex: keys.privateKeyHex,
  ttlSeconds: 60,
});

const execution = await client.executeSponsoredTransaction({
  agentJwt: bearerJwt,
  authorizationJwt,
  walletId,
  chain: "Evm",
  chainId: 8453,
  deadline: Math.floor(Date.now() / 1000) + 120,
  calls: [{
    target: "0x1234567890abcdef1234567890abcdef12345678",
    value: "0",
    data: "0x",
  }],
});

console.log(authenticateUrl, context.session_id, execution);

Runtime Support

• Node.js 18+
• Bun 1+
• Deno 2+ (npm: imports)

The SDK uses fetch, TextEncoder, and WebCrypto-compatible APIs.

Security Notes

• Keep accessKeySecret and agent private keys server-side only.
• Do not embed SDK credentials in browser code.
• Keep AGENT_JWT short-lived and use fresh jti values per request.

API Surface

new VanterClient(options)

• accessKeyId (required)
• accessKeySecret (required)
• gatewayBaseUrl (optional, default https://gateway.vanter.trade)
• appBaseUrl (optional, default https://app.vanter.trade)
• fetch (optional override)

client.createAuthenticateUrl({ organizationId })

Returns https://app.vanter.trade/authenticate/o/:organization_id by default.

client.authenticate({ ... })

Calls POST /api/integrations/:organization_id/authenticate/claim.

By default, provisioning uses the app-level supported_chains and onboarding_role_templates configured in Developer Portal. You can still pass chains and roleTemplates to override per-request when needed.

Returns auth tokens and provisioned/reused context including:

• wallet_id
• session_id
• agent_session
• wallets
• roles
• provisioning.status (new_user or returning_user)

client.resolveAuthenticationContext({ ... })

Calls GET /api/integrations/:organization_id/authenticate/context.

Use this to recover wallet_id and session_id later by appUserId, userId, or providerSub.

client.executeSponsoredTransaction({ ... })

Calls POST /api/integrations/agent/sponsor-execute with app access-key headers and AGENT_JWT bearer token.

For chain: "Evm", also pass a distinct authorizationJwt (different jti) alongside agentJwt.

generateAgentKeypair()

Returns raw Ed25519 keypair in multiple encodings:

• privateKeyHex
• privateKeyRawBase64
• publicKeyBase64

createAgentJwt({ ... })

Creates EdDSA JWT with required claims:

• app_id
• session_id
• wallet_id
• iat, exp, jti

createSponsorExecuteJwtPair({ ... })

Returns two distinct JWTs (bearerJwt, authorizationJwt) for flows requiring dual-token EVM sponsor-execute auth.

createEvmSponsorExecuteJwtPair({ ... }) (deprecated)

Backward-compatible alias for createSponsorExecuteJwtPair({ ... }).