Wallets

The wallet API is the core of the orbserv SDK. It lets you create and manage agent wallets, query balances, send payments, and browse transaction history.

Creating a wallet

const wallet = await orb.wallet.create(options)

Options

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | name | string | Yes | Human-readable label for the wallet | | chains | Chain[] | Yes | Chains to activate: 'solana', 'base', 'ethereum', 'polygon' | | metadata | Record<string, string> | No | Arbitrary key-value metadata |

Returns: WalletRecord

interface WalletRecord {
  id: string
  name: string
  createdAt: string
  evm: {
    address: string   // 0x...
    chains: Chain[]
  }
  solana: {
    address: string   // base58
  }
  metadata: Record<string, string>
}

Getting a wallet

const agent = await orb.wallet.get(id)

Returns an AgentWallet instance with methods for interacting with the wallet.

const agent = await orb.wallet.get('wlt_abc123')

Listing wallets

const wallets = await orb.wallet.list()
// WalletRecord[]

Returns all wallets associated with your API key, ordered by creation date descending.

AgentWallet methods

After calling orb.wallet.get(id), you receive an AgentWallet instance:

agent.send(params)

Send tokens to an address.

await agent.send({
  to: '0xRecipient...',
  amount: '10.00',
  token: 'USDC',
  chain: 'base',
})

Parameters

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | to | string | Yes | Recipient address | | amount | string | Yes | Decimal string (e.g. '5.00') | | token | 'USDC' \| 'SOL' \| 'ETH' | Yes | Token to send | | chain | Chain | Yes | Chain to send on | | memo | string | No | Optional memo / reference | | spendDecisionId | string | No | Pre-obtained Covenant decision id; skips SDK authorize when provided |

When the SDK is constructed with a covenant config, send() calls the Covenant daemon's POST /spend/authorize before submitting the transfer. See Covenant Spend Authorization.

Returns: TransactionResult

interface TransactionResult {
  txHash: string
  chain: Chain
  status: 'confirmed' | 'pending'
  fee: string
}

agent.balance()

Fetch current token balances across all active chains.

const balances = await agent.balance()

Returns: BalanceResult

interface BalanceResult {
  evm: {
    USDC: string    // decimal string
    ETH: string
  }
  solana: {
    USDC: string
    SOL: string
  }
}

agent.history(options?)

Retrieve transaction history.

const txs = await agent.history({ limit: 25, offset: 0 })

Options

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | limit | number | 20 | Number of records to return (max 100) | | offset | number | 0 | Pagination offset | | chain | Chain | — | Filter by chain |

Returns: Transaction[]

interface Transaction {
  id: string
  type: 'send' | 'receive' | 'x402'
  amount: string
  token: string
  chain: Chain
  to: string
  from: string
  txHash: string
  timestamp: string
  status: 'confirmed' | 'pending' | 'failed'
}

agent.fetch(url, options?)

Make an HTTP request that automatically handles x402 payment challenges. See x402 Auto-pay for full documentation.

const response = await agent.fetch('https://api.example.com/data', {
  method: 'GET',
  maxAmount: '1.00',
})