General API
The General API exposes Hydra App's AppService — application-level operations including network discovery, public key retrieval, payment preimage lookup, and referral management.
JSON-RPC namespace: app
Endpoints
The Network type
Most other APIs accept a Network to identify a specific blockchain. It has just two fields:
| Field | Type | Description |
|---|---|---|
protocol | Protocol enum | PROTOCOL_BITCOIN (1) or PROTOCOL_EVM (2) |
id | string | Network identifier — magic bytes (hex) for Bitcoin, decimal chain ID for EVM. Staging values: "0a03cf40" (Bitcoin Signet), "11155111" (Ethereum Sepolia), "421614" (Arbitrum Sepolia). |
See the network identifier table in the Setup Guide for every supported network.
Get Networks
Returns the list of blockchain networks that have been initialized and are currently active in this application instance.
Method: GetNetworks
Parameters: None
Response:
| Field | Type | Description |
|---|---|---|
networks | Network[] | Active networks |
Example Request:
import { AppServiceClient } from './proto/AppServiceClientPb'
import { GetNetworksRequest } from './proto/app_pb'
const client = new AppServiceClient('http://localhost:5001')
const response = await client.getNetworks(new GetNetworksRequest(), {})
response.getNetworksList().forEach(n => {
console.log(`Protocol ${n.getProtocol()} / id ${n.getId()}`)
})
Example Response:
{
"networks": [
{ "protocol": 1, "id": "0a03cf40" },
{ "protocol": 2, "id": "11155111" },
{ "protocol": 2, "id": "421614" }
]
}
Get Public Key
Returns the Ed25519 public key of this application instance. The key uniquely identifies the application and is derived from the user's mnemonic seed. It does not depend on a network.
Method: GetPublicKey
Parameters: None
Response:
| Field | Type | Description |
|---|---|---|
public_key | bytes | Ed25519 public key (32 bytes) |
Example Request:
import { GetPublicKeyRequest } from './proto/app_pb'
const response = await client.getPublicKey(new GetPublicKeyRequest(), {})
const pubkey = response.getPublicKey_asU8()
console.log('Public key (hex):', Buffer.from(pubkey).toString('hex'))
Example Response:
{
"public_key": "AbCdEf0123...="
}
The bytes field is base64 in JSON-RPC; in gRPC it's a raw
bytes.
Get Preimage
Looks up a payment preimage by its hash. Returns the preimage if it has been revealed or registered, or empty if the preimage is not yet known.
Method: GetPreimage
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
payment_hash | bytes | YES | Payment hash to look up (32 bytes) |
Response:
| Field | Type | Description |
|---|---|---|
payment_preimage | bytes (optional) | The preimage (32 bytes), or empty if not yet known |
Example Request:
import { GetPreimageRequest } from './proto/app_pb'
const request = new GetPreimageRequest()
request.setPaymentHash(Buffer.from('a1b2c3...32bytes...', 'hex'))
const response = await client.getPreimage(request, {})
const preimage = response.getPaymentPreimage_asU8()
if (preimage && preimage.length > 0) {
console.log('Preimage:', Buffer.from(preimage).toString('hex'))
} else {
console.log('Preimage not yet known')
}
Example Response:
{ "payment_preimage": "9f8e7d6c..." }
Get Referral
Returns the application's currently configured referrer, if set.
Method: GetReferral
Parameters: None
Response:
| Field | Type | Description |
|---|---|---|
referral_public_key | bytes (optional) | Ed25519 public key of the referrer, or empty if not set |
Example Request:
import { GetReferralRequest } from './proto/app_pb'
const response = await client.getReferral(new GetReferralRequest(), {})
const ref = response.getReferralPublicKey_asU8()
if (ref && ref.length > 0) {
console.log('Referrer:', Buffer.from(ref).toString('hex'))
} else {
console.log('No referrer set')
}
Example Response:
{ "referral_public_key": "abcd1234..." }
Set Referral
Sets the application's referrer.
Method: SetReferral
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
referral_public_key | bytes | YES | Ed25519 public key of the referrer (32 bytes) |
Response:
| Field | Type | Description |
|---|---|---|
referral_public_key | bytes | The stored referrer public key |
Example Request:
import { SetReferralRequest } from './proto/app_pb'
const request = new SetReferralRequest()
request.setReferralPublicKey(Buffer.from('abcd1234...32bytes...', 'hex'))
const response = await client.setReferral(request, {})
console.log('Referrer set:', Buffer.from(response.getReferralPublicKey_asU8()).toString('hex'))
Example Response:
{ "referral_public_key": "abcd1234..." }
Common Workflows
Initialize and discover networks
async function initializeApp(client: AppServiceClient) {
const networks = (await client.getNetworks(new GetNetworksRequest(), {})).getNetworksList()
const pubkey = (await client.getPublicKey(new GetPublicKeyRequest(), {})).getPublicKey_asU8()
return {
publicKey: Buffer.from(pubkey).toString('hex'),
networks: networks.map(n => ({ protocol: n.getProtocol(), id: n.getId() }))
}
}
Protocol Types
| Value | Constant | Description |
|---|---|---|
0 | PROTOCOL_UNSPECIFIED | Invalid default — never use |
1 | PROTOCOL_BITCOIN | Bitcoin mainnet, testnet, signet, regtest |
2 | PROTOCOL_EVM | Ethereum, Arbitrum, Polygon, BSC, etc. |
Common Network IDs
Bitcoin (PROTOCOL_BITCOIN, magic bytes hex)
id | Network |
|---|---|
f9beb4d9 | Bitcoin Mainnet |
0b110907 | Bitcoin Testnet3 |
0a03cf40 | Bitcoin Signet |
fabfb5da | Bitcoin Regtest |
EVM (PROTOCOL_EVM, decimal chain ID)
id | Network |
|---|---|
1 | Ethereum Mainnet |
11155111 | Sepolia Testnet |
137 | Polygon |
42161 | Arbitrum One |
10 | Optimism |
Best Practices
- Cache the network list. Active networks rarely change; refresh on app start.
- Treat the public key as stable. It's derived from the seed and won't change for the application's lifetime.
- Set a referrer once.
SetReferraltypically runs during onboarding, not on every session. - Check
GetPreimageresults for emptiness. A successful response can still mean "not yet known" — it's not an error.