Balance Endpoints

Overview

Two new endpoints have been added to the Naos Trading API for retrieving wallet balances:

1. GET /api/v1/balance - Get native token balance

2. GET /api/v1/token-balance - Get ERC-20/SPL token balance

Endpoints

1. Get Native Balance

Endpoint: GET /api/v1/balance

Description: Retrieve the native token balance for a wallet address on a specific network.

Parameters:

• walletAddress (string, required): Wallet address (EVM: 0x... or Solana: base58)

• network (string, required): Blockchain network (BASE, ETH, BSC, SOL, etc.)

Response:

{
  "success": true,
  "balance": "125103933760140349",
  "decimals": 18
}

Example:

curl -X GET "http://localhost:3001/api/v1/balance?walletAddress=0xA73CDDdea07E805228Ef6BbbC6216112E3A51723&network=BASE" \
  -H "Authorization: Bearer YOUR_API_KEY"

Native Tokens:

• EVM chains: ETH, BNB, AVAX, etc. (18 decimals)

• Solana: SOL (9 decimals)

Balance Format: The balance is returned in raw token units:

• EVM: wei (divide by 10^18 to get ETH)

• Solana: lamports (divide by 10^9 to get SOL)

2. Get Token Balance

Endpoint: GET /api/v1/token-balance

Description: Retrieve the balance of a specific ERC-20 or SPL token for a wallet address.

Parameters:

• walletAddress (string, required): Wallet address

• tokenAddress (string, required): Token contract address

• network (string, required): Blockchain network

Response:

{
  "success": true,
  "balance": "354749157803150317450",
  "decimals": 18
}

Example:

curl -X GET "http://localhost:3001/api/v1/token-balance?walletAddress=0xA73CDDdea07E805228Ef6BbbC6216112E3A51723&tokenAddress=0xFb31f85A8367210B2e4Ed2360D2dA9Dc2D2Ccc95&network=BASE" \
  -H "Authorization: Bearer YOUR_API_KEY"

Usage in Playground

The playground.ts file now includes helper functions for these endpoints:

import {getBalance, getTokenBalance} from './playground'

await getBalance('0xA73CDDdea07E805228Ef6BbbC6216112E3A51723', 'BASE')

await getTokenBalance(
  '0xA73CDDdea07E805228Ef6BbbC6216112E3A51723',
  '0xFb31f85A8367210B2e4Ed2360D2dA9Dc2D2Ccc95',
  'BASE'
)

Supported Networks

• BASE (8453)

• ETH (1)

• BSC (56)

• ABS (2741)

• AVAX (43114)

• HYPE (999)

• ARB (42161)

• INK (57073)

• STORY (1514)

• XLAYER (196)

• PLASMA (9745)

• UNI (130)

• SOL (Solana)

Error Handling

Missing Parameters:

{
  "success": false,
  "error": "walletAddress is required"
}

Invalid Network:

{
  "success": false,
  "error": "network is required and must be one of: BASE, ETH, BSC, ..."
}

Balance Fetch Failed:

{
  "success": false,
  "error": "Failed to fetch native balance"
}

Implementation Details

Files Created:

• src/trading-suite/api/balance/balance.types.ts - Type definitions

• src/trading-suite/api/balance/balance.schema.ts - Zod schemas and OpenAPI definitions

• src/trading-suite/api/balance/balance.validation.ts - Request validation middleware

• src/trading-suite/api/balance/balance.service.ts - Business logic

• src/trading-suite/api/balance/v1/balance.routes.ts - Express routes

• src/trading-suite/api/balance/v1/balance.swagger.ts - Swagger documentation

Files Modified:

• src/trading-suite/index.ts - Added balance routes

• src/trading-suite/swagger/registry.ts - Registered swagger documentation

• src/trading-suite/playground.ts - Added helper functions

Services Used:

• getCurrentBalanceByNetwork from src/back/utils/balance.service.ts

• getTokenBalance from src/back/ethereum/balance.ape.service.ts

• getPoolInfo from src/back/indexer/pool.indexer.ts

Testing

Run the trading suite server:

pnpm run dev:tradingsuite

Test endpoints:

curl -X GET "http://localhost:3001/api/v1/balance?walletAddress=0xA73CDDdea07E805228Ef6BbbC6216112E3A51723&network=BASE" \
  -H "Authorization: Bearer test-key"

curl -X GET "http://localhost:3001/api/v1/token-balance?walletAddress=0xA73CDDdea07E805228Ef6BbbC6216112E3A51723&tokenAddress=0xFb31f85A8367210B2e4Ed2360D2dA9Dc2D2Ccc95&network=BASE" \
  -H "Authorization: Bearer test-key"

View API documentation:

http://localhost:3001/api-docs