---
title: Balance
description: Check your wallet balance across networks
---

# Balance

The Balance API returns your wallet's combined balance (USDC + credit), on-chain USDC balance, and address information.

## Endpoint

```http
GET /api/balance
```

## Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `network` | string | `base-sepolia` | Blockchain network to check |

### Supported Networks

| Network | Description |
|---------|-------------|
| `base-sepolia` | Base testnet (for development) |
| `base` | Base mainnet (production) |

## Response

```json
{
  "usdcBalance": "50.000000",
  "creditBalance": "5.000000",
  "totalBalance": "55.000000",
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "hasWallet": true,
  "network": "base-sepolia",
  "chainType": "ethereum"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `usdcBalance` | string | On-chain USDC balance |
| `creditBalance` | string | In-app credit balance (`"0"` if no approved credit) |
| `totalBalance` | string | Combined balance (USDC + credit) |
| `address` | string | Your wallet address |
| `hasWallet` | boolean | Whether wallet has been created |
| `network` | string | Network queried |
| `chainType` | string | Chain type (`ethereum` or `solana`) |

## Examples

### Check Default Network Balance

```bash
curl https://api.agnic.ai/api/balance \
  -H "X-Agnic-Token: agnic_tok_YOUR_TOKEN"
```

### Check Mainnet Balance

```bash
curl "https://api.agnic.ai/api/balance?network=base" \
  -H "X-Agnic-Token: agnic_tok_YOUR_TOKEN"
```

### Python Example

```python
import requests

response = requests.get(
    "https://api.agnic.ai/api/balance",
    headers={"X-Agnic-Token": "agnic_tok_YOUR_TOKEN"},
    params={"network": "base-sepolia"}
)

data = response.json()
print(f"Total Balance: ${data['totalBalance']}")
print(f"USDC: ${data['usdcBalance']} | Credit: ${data['creditBalance']}")
print(f"Address: {data['address']}")
```

### JavaScript Example

```javascript
const response = await fetch(
  'https://api.agnic.ai/api/balance?network=base-sepolia',
  {
    headers: {
      'X-Agnic-Token': 'agnic_tok_YOUR_TOKEN'
    }
  }
);

const { totalBalance, usdcBalance, creditBalance, address } = await response.json();
console.log(`Total Balance: $${totalBalance}`);
console.log(`USDC: $${usdcBalance} | Credit: $${creditBalance}`);
console.log(`Address: ${address}`);
```

## Check Balance Before Transaction

```python
import requests

def check_can_afford(amount_usd):
    response = requests.get(
        "https://api.agnic.ai/api/balance",
        headers={"X-Agnic-Token": "agnic_tok_YOUR_TOKEN"}
    )

    balance = float(response.json()["totalBalance"])
    return balance >= amount_usd

# Check if we can afford a $0.50 transaction
if check_can_afford(0.50):
    print("Sufficient balance")
else:
    print("Insufficient balance - please add funds")
```

## Error Responses

### Invalid Network

```json
{
  "error": "invalid_network",
  "error_description": "Network 'invalid' is not supported"
}
```

### No Wallet

```json
{
  "usdcBalance": "0",
  "creditBalance": "5.000000",
  "totalBalance": "5.000000",
  "address": null,
  "hasWallet": false,
  "network": "base-sepolia",
  "chainType": "ethereum"
}
```

<Cards>
  <Card title="Transactions" href="/docs/agnicpay-features/transactions" />
  <Card title="X402 Core Concepts" href="/docs/x402/core-concepts" />
</Cards>