Api
Getting Started
Make your first API calls with TypeScript examples
Overview
The Hydra Dashboard communicates with the Hydra backend via gRPC-Web using Protocol Buffers. This guide will help you understand how to make API calls and structure your requests correctly.
Available Services
The Hydra backend provides several gRPC services:
- AppService: Network and application-level operations
- WalletService: Balance and transaction management
- NodeService: Channel and payment operations
- RentalService: Channel rental operations
- OrderbookService: Market and trading operations
- AssetService: Asset information and queries
- BlockchainService: Blockchain data and fee estimates
- PricingService: Asset pricing and conversions
Making Your First API Call
Example: Getting Networks
import { GetNetworksRequest, GetNetworksResponse } from '@/proto/app'
import { hydraGrpcClient } from '@/services/grpcWebClient'
// Get available networks
const networks = await hydraGrpcClient.getNetworks()
console.log('Available networks:', networks)
// Output: [
// { protocol: Protocol.BITCOIN, id: '0a03cf40' },
// { protocol: Protocol.EVM, id: '11155111' }
// ]
Example: Getting Balances
import { GetBalancesRequest, GetBalancesResponse } from '@/proto/wallet'
// Get balances for a specific network
const balances = await hydraGrpcClient.getBalances(network)
console.log('Balances:', balances)
// Output: {
// balances: [
// {
// assetId: '0x...',
// onchain: {
// usable: { value: '1.5' },
// pending: { value: '0.0' }
// },
// offchain: {
// freeLocal: { value: '0.5' },
// freeRemote: { value: '1.0' }
// }
// }
// ]
// }
Example: Opening a Channel
import { OpenChannelRequest, OpenChannelResponse } from '@/proto/node'
// Open a channel with a peer
const response = await hydraGrpcClient.openChannel(
network, // Network object
'nodeId@host:port', // Peer URL
{
'assetId': {
exact: {
amount: { value: '1.0' } // Amount as DecimalString
}
}
},
'medium' // Fee rate: 'low' | 'medium' | 'high'
)
console.log('Channel opened:', response)
// Output: {
// txid: '0x...',
// channelId: '0x...'
// }
Key Concepts
Networks
A Network identifies which blockchain you're operating on:
interface Network {
protocol: Protocol // BITCOIN = 0, EVM = 1
id: string // Network ID (e.g., '11155111' for Ethereum Sepolia)
}
Assets
Assets are identified by their ID on a specific network:
interface Asset {
id: string // Asset ID (e.g., '0x0000...' for native token)
name: string // Human-readable name
symbol: string // Symbol (e.g., 'ETH', 'BTC')
decimals: number // Decimal places
}
Amounts
All monetary amounts use DecimalString for precision:
interface DecimalString {
value: string // String representation (e.g., '1.5', '0.001')
}
For sending amounts, use SendAmount:
interface SendAmount {
exact?: { amount: DecimalString } // Exact amount
all?: {} // Send all available
}
Next Steps
- Read the Common Patterns guide for complex types
- See the Examples for real-world use cases
- Check the API Reference for quick proto lookup
- Dive into detailed service docs: General, Wallet, Node, etc.