> ## Documentation Index
> Fetch the complete documentation index at: https://raveculture-mintlify-wallet-api-tempo-1774388459.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```http theme={null}
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

```json theme={null}
{
  "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

```http theme={null}
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

```json theme={null}
{
  "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                        |

<Note>When `TEMPO_TESTNET` is `true`, the explorer URL points to `explore.testnet.tempo.xyz` instead of `explore.tempo.xyz`.</Note>

### Errors

| Code | Description                  |
| ---- | ---------------------------- |
| 400  | Missing `address` parameter  |
| 500  | Failed to fetch transactions |

## Get CDP wallet address

```http theme={null}
GET /api/wallet/address
```

Returns the address of the CDP Agentic Wallet.

### Response (authenticated)

```json theme={null}
{
  "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:

```json theme={null}
{
  "authenticated": false,
  "needsAuth": true,
  "message": "Run: npx awal auth login your@email.com"
}
```

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

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

## Create CDP wallet

```http theme={null}
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

```json theme={null}
{
  "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

```http theme={null}
GET /api/wallet/cdp
```

Returns supported chain information for the CDP wallet.

```json theme={null}
{
  "status": "ok",
  "type": "evm_wallet",
  "supportedChains": ["base", "base-sepolia"]
}
```

## Create CDP wallet client

```http theme={null}
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

```json theme={null}
{
  "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.

<Note>When payments are initiated through the [x402 pay action](/api-reference/x402#pay), 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](/api-reference/x402) for details.</Note>