Getting Started

This page is for client-side developers who already have a Hydra App running (see the Setup Guide). It covers what services exist, how to call them, and the few primitive types that show up everywhere.

Want a runnable bot template instead? Skip to the Bot Quickstart.

Available services

Hydra App exposes one gRPC server with the following services. Each has its own dedicated reference page:

172 RPCs in total. The count a given build actually serves is whatever rpc.discover returns — that is authoritative, and this table is a summary of it.

JSON-RPC namespaces match the service names lowercased: app, wallet, pricing, client, asset, blockchain, signer, orderbook, swap, node, liquidity, watchOnlyNode, event, preimage, htlc.

Connecting

Hydra App listens on the port set by settings.server_port in your config (default 5003). Connect with any gRPC client:

import { AppServiceClient } from './proto/AppServiceClientPb'

const client = new AppServiceClient('http://localhost:5003')

No client-side authentication. Hydra App handles auth with the upstream Hydranet services on your behalf — derived from the seed you configured at setup. Your client connects to the local app over plain gRPC with no API keys, no headers, no auth handshake. If you find yourself looking for a "Bearer token" or "API key" parameter, you're looking at the wrong layer — it's all transparent to clients.

Your first call: list active networks

AppService.GetNetworks requires no parameters and confirms the app is up.

import { GetNetworksRequest } from './proto/app_pb'

const response = await client.getNetworks(new GetNetworksRequest(), {})
for (const n of response.getNetworksList()) {
  console.log(`protocol=${n.getProtocol()} id=${n.getId()}`)
}
// → protocol=1 id=0a03cf40   (Bitcoin Signet)
// → protocol=2 id=11155111   (Ethereum Sepolia)
// → protocol=2 id=421614     (Arbitrum Sepolia)

Key concepts

Network

Identifies a blockchain. Two fields only:

Older example code may use chain_id and name — those fields no longer exist. See the Setup Guide's network identifier table.

DecimalString

All monetary amounts are passed as strings to preserve precision. The string is in the asset's human-readable unit, not its smallest unit.

So { value: "0.1" } always means "one-tenth of one whole asset" — never "0.1 satoshis" or "0.1 wei".

Asset and asset IDs

A ticker is never an asset id. "BTC" is a symbol; the id is the zero address.

Amount (for sends)

Used by client.SendTransaction, client.CreateSendTransaction, etc. A oneof:

FeeOption

How a transaction's fee is selected. It is a oneof message, not an enum — exactly one arm is set:

const feeOption = { medium: {} }                       // ✅
const feeOption = { custom: { feeRate: { maxFeePerUnit: { value: '5' },
                                         priorityFeePerUnit: { value: '0' } } } }   // ✅

There is no FeeOption.MEDIUM constant and no priority field. See Common Patterns → Fee structures for the full shape, and blockchain.GetFeeEstimates for current numbers.

The two transaction flows

ClientService exposes two parallel ways to make an on-chain transaction. Pick the one that fits your signing model.

One-shot (Hydra App signs and broadcasts)

SendTransaction      → txid
SendTokenTransaction → txid
BumpTransaction      → txid
SetTokenAllowance    → txid

Use this when Hydra App holds the private key (most bots).

Build → sign → finalize (you sign externally)

CreateSendTransaction              → TransactionRequest
                                       ↓ sign with signer.SignTransaction
                                     SignedTransactionRequest
                                       ↓
                                     FinalizeAndBroadcastTransaction → txid

Use this when you want to inspect the transaction before signing, or when the signing key lives in an external HSM / hardware wallet.

For raw transactions you've already signed entirely outside Hydra (e.g. PSBT workflows), use blockchain.BroadcastRawTransaction instead.

The two trading flows

SwapService has two ways to trade:

A bot starting from cold will almost always use SimpleSwap for the first trade and Swap thereafter.

The two ways to get inbound liquidity

A new node has zero channels. Two options:

For bots, the lease flow is usually simpler — see the Lease API.

Streaming RPCs

Three subscriptions a bot will care about:

Subscribe before you act. If you place an order before subscribing to the market stream, you can miss the fill notification. Same for SimpleSwap — subscribe to SubscribeSimpleSwaps before calling SimpleSwap.

Error handling at a glance

Hydra App returns standard gRPC status codes. For a bot, the practical mental model:

Idempotency caveat: Send* and Open* RPCs are not idempotent — a retry after DEADLINE_EXCEEDED may broadcast twice. Verify first (wallet.GetTransactions, watchOnlyNode.GetPaymentsByHash, SubscribeNodeEvents), or, for order placement, set client_order_id and let the orderbook deduplicate. Per-RPC rules: Errors → Idempotency & Retry Safety.

See 40-errors.md for the full code list and per-RPC error mappings.

Next steps

• Bot Quickstart — runnable trading-bot template
• Common Patterns — fees, amounts, helper functions
• Browser & gRPC-Web Specifics — for browser clients only: manual framing, fetch-based streaming, CORS
• Service references: App · Wallet · Pricing · Client · Asset · Blockchain · Signer · Orderbook · Swap · Node · Lease · Watch-Only Node · Events · HTLC & Preimage