Client for a single managed wallet. Balances, transfers, swaps, spending controls, and x402 payments.

AibankWallet

Client for interacting with a single managed wallet. Obtain an instance via aibank.createWallet() or aibank.getWallet().

const wallet = await aibank.createWallet({ name: "agent-1" });
// or
const wallet = aibank.getWallet("existing-wallet-uuid");

Properties

Property	Type	Description
`id`	string	Wallet UUID

Methods

getBalances()

Fetch token balances across all supported chains.

const balances = await wallet.getBalances();
// {
//   wallet_id: "uuid",
//   balances: [
//     { chain: "base", token: "USDC", balance: "100.00", usd_value: "100.00" },
//     { chain: "ethereum", token: "ETH", balance: "0.05" },
//     { chain: "solana", token: "SOL", balance: "1.5" }
//   ]
// }

Returns: Promise<WalletBalances>

transfer(opts)

Transfer tokens to an external address.

const result = await wallet.transfer({
  chain: "base",
  to: "0xRecipient",
  amount: "10.00",
  currency: "USDC",
});

console.log(result.tx_hash);  // "0xabc..."
console.log(result.status);   // "confirmed"

Parameters:

Property	Type	Description
`chain`	string	`"ethereum"`, `"base"`, or `"solana"`
`to`	string	Recipient address
`amount`	string	Decimal amount (e.g. `"1.00"`)
`currency`	string	Token symbol (`"USDC"`, `"ETH"`, `"SOL"`)

Returns: Promise<TransferResult>

swap(opts)

Swap one token for another on the same chain.

const result = await wallet.swap({
  chain: "base",
  inputToken: "ETH",
  outputToken: "USDC",
  amount: "0.1",
});

Parameters:

Property	Type	Description
`chain`	string	Chain to swap on
`inputToken`	string	Token to sell
`outputToken`	string	Token to buy
`amount`	string	Input amount

Returns: Promise<SwapResult>

getTransactions(opts?)

Retrieve transaction history with optional filters.

const history = await wallet.getTransactions({
  limit: 20,
  chain: "base",
});

// history.transactions - array
// history.pagination - { total, limit, offset, has_more }

Parameters:

Property	Type	Default	Description
`limit`	number	50	Max records (max 200)
`offset`	number	0	Pagination offset
`type`	string	--	Filter by type
`chain`	string	--	Filter by chain

Returns: Promise<TransactionListResult>

getControls()

Fetch current spending controls and usage stats.

const controls = await wallet.getControls();
// controls.controls.daily_limit_usd
// controls.usage_today.spent_usd
// controls.usage_today.remaining_usd

Returns: Promise<SpendingControls>

setControls(controls)

Update spending controls.

await wallet.setControls({
  daily_limit_usd: 200,
  per_tx_limit_usd: 50,
  allowed_addresses: ["0xAddr1", "0xAddr2"],
});

Parameters:

Property	Type	Description
`daily_limit_usd`	number	Max USD per day
`per_tx_limit_usd`	number	Max USD per transaction
`allowed_addresses`	string[]	Address allowlist
`allowed_domains`	string[]	Domain allowlist

Returns: Promise<SpendingControls>

requestFunding(opts)

Request a deposit address for incoming funds.

const funding = await wallet.requestFunding({
  amount: "100.00",
  chain: "base",
  currency: "USDC",
});

console.log(funding.deposit_address);
console.log(funding.message);

Returns: Promise<FundingRequest>

withdraw(opts)

Withdraw tokens to an external address.

const result = await wallet.withdraw({
  chain: "base",
  to: "0xExternal",
  amount: "50.00",
  currency: "USDC",
});

Returns: Promise<WithdrawResult>

x402Fetch(url, init?)

Fetch wrapper that automatically pays HTTP 402 challenges.

When a 402 response is received:

Reads payment requirements from headers (X-Payment-Amount, X-Payment-Recipient, etc.)
Sends a transfer from this wallet
Retries the request with X-Payment proof header

const response = await wallet.x402Fetch(
  "http://localhost:4000/v1/gateway/anthropic/v1/messages",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      model: "claude-sonnet-4-20250514",
      max_tokens: 100,
      messages: [{ role: "user", content: "Hello" }],
    }),
  }
);

const data = await response.json();

Parameters:

Property	Type	Description
`url`	string	Target URL
`init`	RequestInit	Optional fetch init options

Returns: Promise<Response>

If the initial response is not 402, it is returned as-is. If payment headers are missing from the 402 response, the original response is returned without attempting payment.

Type definitions

interface WalletBalances {
  wallet_id: string;
  balances: ChainBalance[];
}

interface ChainBalance {
  chain: string;
  token: string;
  balance: string;
  usd_value?: string;
}

interface TransferResult {
  transaction_id: string;
  tx_hash: string;
  from: string;
  to: string;
  amount: string;
  currency: string;
  chain: string;
  status: "confirmed" | "pending" | "failed";
}

interface TransactionListResult {
  transactions: WalletTransaction[];
  pagination: {
    total: number;
    limit: number;
    offset: number;
    has_more: boolean;
  };
}

AibankWallet

On this page