Wallet API

Query Tempo chain wallet balances, view transactions, and manage CDP wallets

Wallet API

Query wallet balances and transaction history on the Tempo network. Also supports Coinbase Developer Platform (CDP) wallet creation and management.

Get wallet balance

GET /api/wallet?address=0x...

Returns the balance and fee token information for a wallet address on the Tempo network. Connects to mainnet by default, or testnet when the TEMPO_TESTNET environment variable is set to true.

Query parameters

Parameter	Type	Required	Description
address	string	Yes	Wallet address (0x-prefixed)

Response

{
  "address": "0xd8fd0e1dce89beaab924ac68098ddb17613db56f",
  "chain": "Tempo",
  "chainId": 1,
  "testnet": false,
  "feeToken": {
    "address": "0x20c0000000000000000000000000000000000000",
    "balance": "12.50",
    "balanceRaw": "12500000"
  },
  "pathUsd": {
    "address": "0x20c0000000000000000000000000000000000000",
    "balance": "50.00",
    "balanceRaw": "50000000"
  }
}

Field	Type	Description
address	string	The queried wallet address
chain	string	Network name (Tempo or Tempo Testnet)
chainId	number	Chain ID of the connected network
testnet	boolean	Whether the response is from the testnet
feeToken.address	string	Contract address of the user’s configured fee token
feeToken.balance	string	Human-readable fee token balance (6 decimals)
feeToken.balanceRaw	string	Raw fee token balance in smallest units
pathUsd.address	string	pathUSD token contract address
pathUsd.balance	string	Human-readable pathUSD balance (6 decimals)
pathUsd.balanceRaw	string	Raw pathUSD balance in smallest units

Errors

Code	Description
400	Missing address parameter
500	Failed to fetch wallet data from Tempo RPC

Get transaction history

GET /api/wallet/transactions?address=0x...&limit=20

Returns recent transaction history for a wallet address on Tempo. Currently returns a placeholder response with an explorer link while indexer integration is in progress.

Query parameters

Parameter	Type	Required	Description
address	string	Yes	Wallet address (0x-prefixed)
limit	number	No	Maximum number of transactions to return. Defaults to 20.

Response

{
  "address": "0xd8fd0e1dce89beaab924ac68098ddb17613db56f",
  "chain": "Tempo",
  "chainId": 1,
  "currentBlock": "1234567",
  "transactions": [],
  "note": "Transaction history requires indexer integration. Use Tempo block explorer for now.",
  "explorerUrl": "https://explore.tempo.xyz/address/0xd8fd0e1dce89beaab924ac68098ddb17613db56f"
}

Field	Type	Description
address	string	The queried wallet address
chain	string	Network name
chainId	number	Chain ID
currentBlock	string	Latest block number at time of request
transactions	array	List of transactions (currently empty, pending indexer integration)
note	string	Status message about indexer availability
explorerUrl	string	Direct link to the address on Tempo Explorer

When TEMPO_TESTNET is true, the explorer URL points to explore.testnet.tempo.xyz instead of explore.tempo.xyz.

Errors

Code	Description
400	Missing address parameter
500	Failed to fetch transactions

Get CDP wallet address

GET /api/wallet/address

Returns the address of the CDP Agentic Wallet.

Response (authenticated)

{
  "authenticated": true,
  "address": "0x..."
}

Response (not authenticated)

When the CDP wallet address cannot be retrieved, the response includes authenticated: false and needsAuth: true. The remaining fields vary by failure reason:

{
  "authenticated": false,
  "needsAuth": true,
  "message": "Run: npx awal auth login [e-mail]"
}

If the failure is caused by a configuration error, the response includes error and setup fields instead of message:

{
  "authenticated": false,
  "needsAuth": true,
  "error": "Error description",
  "setup": "Install: npx skills add coinbase/agentic-wallet-skills"
}

Create CDP wallet

POST /api/wallet/create

Creates a new wallet using the Coinbase Developer Platform SDK.

Request body

Field	Type	Required	Description
email	string	Yes	Email address for wallet registration

Response

{
  "success": true,
  "walletAddress": "0x...",
  "walletId": "wallet_789",
  "networks": ["base-sepolia", "base"]
}

Errors

Code	Description
400	Email required
500	CDP not configured. Response includes a setup field with configuration instructions. Generic errors include a details field with the error message.

CDP wallet status

GET /api/wallet/cdp

Returns supported chain information for the CDP wallet.

{
  "status": "ok",
  "type": "evm_wallet",
  "supportedChains": ["base", "base-sepolia"]
}

Create CDP wallet client

POST /api/wallet/cdp

Creates a viem wallet client on Base Sepolia.

Request body

Field	Type	Required	Description
privateKey	string	No	Private key (0x-prefixed). A new key is generated if omitted.

Response

{
  "success": true,
  "address": "0x...",
  "network": "base-sepolia"
}

USDC transfer validation

When transferring USDC through the wallet service, the following validation rules apply:

• The transfer amount must be a positive finite number. Values such as NaN, Infinity, negative numbers, and zero are rejected.
• Amounts are rounded to 6 decimal places (USDC precision). If the rounded value equals zero, the transfer is rejected.

These checks run before any on-chain transaction is initiated.

When payments are initiated through the x402 pay action, additional protections apply: a per-payment maximum of $100, recipient address format validation (EVM or Solana), and audit logging of every payment attempt. See the x402 gateway reference for details.