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.

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

Query Parameters

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

Response

{
    "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.

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

Query Parameters

{
    "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

{
    "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.

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

Query Parameters

{
    "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

{
    "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.

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

Request

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

Response

{
    "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

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

Token Not Found

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

Rate Limit

{
    "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