# Assets & Balances API

### Overview

Endpoints for retrieving wallet balances, assets, and NFTs across different networks.

### Get Wallet Balance

Retrieve the native token balance for a wallet.

```bash
GET api.bloclabs.com/v1/wallets/{wallet_id}/balance
```

#### Query Parameters

```json
{
    "currency": "usd"  // Optional: Convert balance to fiat (usd, eur, gbp)
}
```

#### Response

```json
{
    "status": "success",
    "data": {
        "wallet_id": "wallet_xyz123",
        "native_balance": {
            "amount": "1.5",
            "currency": "ETH",
            "usd_value": "3000.00"
        },
        "total_value_usd": "3000.00",
        "last_updated": "2024-03-15T10:00:00Z"
    }
}
```

### Get Wallet Assets

Retrieve all tokens and their balances for a wallet.

```bash
GET api.bloclabs.com/v1/wallets/{wallet_id}/assets
```

#### Query Parameters

```json
{
    "include_zero_balances": false,  // Optional: Include tokens with zero balance
    "include_price": true,          // Optional: Include current token prices
    "currency": "usd",             // Optional: Price conversion currency
    "limit": 10,                   // Optional: Number of results (default: 10)
    "offset": 0                    // Optional: Pagination offset
}
```

#### Response

```json
{
    "status": "success",
    "data": {
        "assets": [
            {
                "token_address": "0x123...abc",
                "symbol": "USDC",
                "name": "USD Coin",
                "decimals": 6,
                "balance": "1000.00",
                "usd_value": "1000.00",
                "token_type": "ERC20",
                "chain_id": 1
            },
            {
                "token_address": "native",
                "symbol": "ETH",
                "name": "Ethereum",
                "decimals": 18,
                "balance": "1.5",
                "usd_value": "3000.00",
                "token_type": "NATIVE",
                "chain_id": 1
            }
        ],
        "pagination": {
            "total": 2,
            "limit": 10,
            "offset": 0
        },
        "total_usd_value": "4000.00"
    }
}
```

### Get Wallet NFTs

Retrieve all NFTs owned by the wallet.

```bash
GET api.bloclabs.com/v1/wallets/{wallet_id}/nfts
```

#### Query Parameters

```json
{
    "collection": "0x789...def",  // Optional: Filter by collection
    "include_metadata": true,     // Optional: Include NFT metadata
    "limit": 10,                 // Optional: Number of results
    "offset": 0                  // Optional: Pagination offset
}
```

#### Response

```json
{
    "status": "success",
    "data": {
        "nfts": [
            {
                "token_id": "1234",
                "collection_address": "0x789...def",
                "collection_name": "Bored Apes",
                "token_standard": "ERC721",
                "metadata": {
                    "name": "Bored Ape #1234",
                    "image": "ipfs://Qm...",
                    "attributes": [
                        {
                            "trait_type": "Background",
                            "value": "Blue"
                        }
                    ]
                },
                "last_transfer_date": "2024-03-15T10:00:00Z",
                "floor_price_eth": "50.5"
            }
        ],
        "pagination": {
            "total": 1,
            "limit": 10,
            "offset": 0
        }
    }
}
```

### Add Custom Token

Add a custom token to track in the wallet.

```bash
POST api.bloclabs.com/v1/wallets/{wallet_id}/tokens
```

#### Request

```json
{
    "token_address": "0x456...def",
    "network": "ethereum",
    "token_standard": "ERC20"  // "ERC20", "ERC721", "ERC1155"
}
```

#### Response

```json
{
    "status": "success",
    "data": {
        "token_address": "0x456...def",
        "symbol": "CUSTOM",
        "name": "Custom Token",
        "decimals": 18,
        "balance": "0.0",
        "token_type": "ERC20",
        "added_at": "2024-03-15T10:00:00Z"
    }
}
```

### Error Responses

#### Invalid Token Address

```json
{
    "status": "error",
    "message": "Invalid token address",
    "code": "INVALID_TOKEN_ADDRESS"
}
```

#### Token Not Found

```json
{
    "status": "error",
    "message": "Token contract not found on network",
    "code": "TOKEN_NOT_FOUND"
}
```

#### Rate Limit

```json
{
    "status": "error",
    "message": "Rate limit exceeded",
    "code": "RATE_LIMIT_EXCEEDED",
    "retry_after": 60
}
```

### Notes

* Balance updates may have a slight delay (up to 30 seconds)
* NFT metadata is cached for performance
* Token prices are updated every minute
* Custom tokens are validated before being added


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bloclabs.com/api/wallet-api/assets-and-balances-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.