Get Balances
Retrieve the wallet’s token balances. The response always includes the native token (ETH, SOL, XLM) and USDC.
Method Signature
wallet.balances(tokens?: string[]): Promise<Balances<C>>
Basic Usage
const balances = await wallet.balances();
console.log(balances.nativeToken.amount); // e.g., "1.5" ETH/SOL/XLM
console.log(balances.usdc.amount); // e.g., "100.00"
With Additional Tokens
Query additional token balances by providing contract addresses or token symbols:
const balances = await wallet.balances([
"0x1234567890abcdef1234567890abcdef12345678", // Token contract address
"usdt", // Token symbol
]);
console.log(balances.tokens[0].amount); // First additional token
console.log(balances.tokens[0].symbol); // Token symbol
console.log(balances.tokens[0].decimals); // Token decimals
Balance Response Type
Native token balance (ETH, SOL, or XLM)
Token symbol (e.g., “eth”, “sol”, “xlm”)
Human-readable amount (decimal format)
Raw amount (in smallest unit)
USDC balance (same structure as nativeToken)
Array of additional token balances
Send Tokens
Transfer tokens from the wallet to another address or user.
Method Signature
wallet.send(
to: string | UserLocator,
token: string,
amount: string,
options?: SendTokenTransactionOptions
): Promise<Transaction>
Basic Transfer
const transaction = await wallet.send(
"0xRecipientAddress...",
"usdc",
"100"
);
console.log(transaction.hash); // Transaction hash
console.log(transaction.explorerLink); // Blockchain explorer link
Send to User Locator
Send to a user by email, phone, or user ID:
// Send to email
const tx1 = await wallet.send(
{ email: "[email protected]" },
"usdc",
"50"
);
// Send to phone
const tx2 = await wallet.send(
{ phone: "+1234567890" },
"usdc",
"25"
);
// Send to user ID
const tx3 = await wallet.send(
{ userId: "user_123" },
"eth",
"0.1"
);
Send Native Token
// Send ETH (on EVM chains)
const tx = await wallet.send(
"0xRecipientAddress...",
"eth",
"0.5"
);
// Send SOL (on Solana)
const tx = await wallet.send(
"SolanaAddress...",
"sol",
"2.0"
);
Send Custom Token
Provide a token contract address:
const tx = await wallet.send(
"0xRecipientAddress...",
"0x1234567890abcdef1234567890abcdef12345678", // Token contract
"1000"
);
Transaction Types
Specify the transaction type for different use cases:
const tx = await wallet.send(
"0xRecipientAddress...",
"usdc",
"100",
{
transactionType: "onramp", // or "regulated-transfer" or "direct"
}
);
Prepare-Only Mode
Create a transaction without immediately executing it:
const preparedTx = await wallet.send(
"0xRecipientAddress...",
"usdc",
"100",
{
experimental_prepareOnly: true,
}
);
console.log(preparedTx.transactionId); // Use later with approve()
// Approve and execute later
const completedTx = await wallet.approve({
transactionId: preparedTx.transactionId,
});
Parameters
to
string | UserLocator
required
Recipient address or user locator
{ email: string }
{ phone: string }
{ userId: string }
{ x: string } // X/Twitter handle
{ twitter: string } // Twitter handle
Token to send (address, symbol like “usdc”, or native token like “eth”)
Amount to send in decimal format (e.g., “100” for 100 USDC)
options
SendTokenTransactionOptions
transactionType
'onramp' | 'regulated-transfer' | 'direct'
Type of transaction
If true, creates transaction without executing it
Custom signer locator to use
Approve Transaction or Signature
Approve and execute a previously created transaction or sign a pending signature.
Method Signature
wallet.approve(params: ApproveParams): Promise<Transaction | Signature>
Approve Transaction
const transaction = await wallet.approve({
transactionId: "tx_123abc",
});
console.log(transaction.hash);
Approve Signature (EVM only)
const signature = await wallet.approve({
signatureId: "sig_123abc",
});
console.log(signature.signature);
With Additional Signers
const transaction = await wallet.approve({
transactionId: "tx_123abc",
options: {
additionalSigners: [otherSigner],
},
});
Get Wallet Activity
Retrieve the wallet’s transaction history and events.
Method Signature
wallet.experimental_activity(): Promise<Activity>
Usage
const activity = await wallet.experimental_activity();
console.log(activity.events);
This is an experimental API and may change in future versions.
Get Transactions
Retrieve all transactions for the wallet.
Method Signature
wallet.experimental_transactions(): Promise<GetTransactionsResponse>
Usage
const transactions = await wallet.experimental_transactions();
console.log(transactions);
Get Single Transaction
Retrieve details for a specific transaction by ID.
Method Signature
wallet.experimental_transaction(transactionId: string): Promise<GetTransactionSuccessResponse>
Usage
const transaction = await wallet.experimental_transaction("tx_123abc");
console.log(transaction.status);
console.log(transaction.onChain.txId);
Get NFTs
Retrieve NFTs owned by the wallet.
Method Signature
wallet.experimental_nfts(params: {
perPage: number;
page: number;
}): Promise<NFTsResponse>
Usage
const nfts = await wallet.experimental_nfts({
perPage: 20,
page: 1,
});
console.log(nfts);
This is an experimental API and may change in future versions.
Staging Fund (Testnet Only)
Fund a wallet with USDXM tokens in staging/testnet environments.
Method Signature
wallet.stagingFund(amount: number, chain?: Chain): Promise<FundWalletResponse>
Usage
const response = await wallet.stagingFund(100); // Fund with 100 USDXM
console.log(response);
This method only works in staging/testnet environments and exclusively supports USDXM tokens.
Next Steps
EVM Wallets
Learn about EVM-specific operations
Solana Wallets
Learn about Solana-specific operations
Delegated Signers
Add multiple signers to a wallet
Stellar Wallets
Learn about Stellar-specific operations