SDK Reference

SDK Reference

Complete reference for the WalletPilot SDK.

WalletPilot Class

Constructor

import { WalletPilot } from 'walletpilot-sdk';
 
const pilot = new WalletPilot(config: WalletPilotConfig);

WalletPilotConfig

PropertyTypeRequiredDescription
apiKeystringYesYour API key from the dashboard
apiUrlstringNoCustom API URL (default: https://api.walletpilot.dev)
rpcUrlsRecord<number, string>NoCustom RPC URLs per chain ID
debugbooleanNoEnable debug logging
telemetrybooleanNoEnable anonymous telemetry (default: true)

Methods

requestPermission()

Request permission from a user to execute transactions.

const permission = await pilot.requestPermission(options: PermissionRequest): Promise<Permission>

PermissionRequest

PropertyTypeRequiredDescription
spendRecord<string, string>YesSpending limits per token (e.g., { ETH: '0.1' })
contractsstring[]NoAllowed contract addresses or protocol names
chainsnumber[]NoAllowed chain IDs (default: [1])
expirystringNoExpiry duration (e.g., '7d', '24h')

Permission Response

{
  id: string;           // Permission ID
  deepLink: string;     // MetaMask deep link for approval
  qrCode: string;       // QR code data URL
  expiresAt: Date;      // Request expiry time
  status: 'pending' | 'approved' | 'rejected';
}

execute()

Execute a transaction using an approved permission.

const tx = await pilot.execute(intent: TransactionIntent): Promise<Transaction>

TransactionIntent

PropertyTypeRequiredDescription
permissionIdstringYesThe permission ID to use
tostringYesDestination address
valuestringNoETH value to send
datastringNoTransaction calldata
chainIdnumberYesChain ID to execute on

Transaction Response

{
  id: string;           // Internal transaction ID
  hash: string;         // On-chain transaction hash
  chainId: number;
  status: 'pending' | 'confirmed' | 'failed';
  gasUsed?: string;
}

getPermission()

Get details about a permission.

const permission = await pilot.getPermission(permissionId: string): Promise<PermissionDetails>

getPermissionUsage()

Get usage stats for a permission.

const usage = await pilot.getPermissionUsage(permissionId: string): Promise<UsageStats>

UsageStats

{
  spent: Record<string, string>;     // Amount spent per token
  remaining: Record<string, string>; // Remaining allowance per token
  txCount: number;                   // Total transactions executed
}

revokePermission()

Revoke an active permission.

await pilot.revokePermission(permissionId: string): Promise<void>

Supported Chains

ChainChain ID
Ethereum Mainnet1
Polygon137
Arbitrum One42161
Optimism10
Base8453

Error Handling

import { WalletPilotError } from 'walletpilot-sdk';
 
try {
  await pilot.execute(intent);
} catch (error) {
  if (error instanceof WalletPilotError) {
    console.log('Code:', error.code);
    console.log('Message:', error.message);
  }
}

Error Codes

CodeDescription
PERMISSION_DENIEDPermission not approved or revoked
LIMIT_EXCEEDEDTransaction would exceed spending limit
INVALID_CONTRACTContract not in allowlist
EXPIREDPermission has expired
CHAIN_NOT_ALLOWEDChain ID not in permission