General API

The General API exposes Hydra App's AppService — application-level operations including network discovery, public key retrieval, payment preimage lookup, and archive retention.

JSON-RPC namespace: app

Endpoints

• Get Networks
• Get Public Key
• Get Preimage
• Prune Archive

The Network type

Most other APIs accept a Network to identify a specific blockchain. It has just two fields:

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:

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:

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:

Response:

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

Prune Archive

Added 2026-05-26.

Operator-driven retention. Prunes archive-side settled wallet transactions and settled payments on the selected network that fall outside the requested filters. Pending entries are never pruned — only settled history.

Method: PruneArchive

Parameters:

Filters compose intersectively — a row survives only if it satisfies every set filter. With both filters unset, the call is a no-op.

Response:

Example Request:

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

const request = new PruneArchiveRequest()
request.setNetwork({ protocol: 1, id: '0a03cf40' })
request.setMaxAgeSecs(60 * 60 * 24 * 30)   // keep last 30 days
request.setMaxItems(10_000)                 // and at most 10k entries

const response = await client.pruneArchive(request, {})
console.log(`Pruned ${response.getTotalPruned()} rows`)
response.getPerTableMap().forEach((count, table) => {
  console.log(`  ${table}: ${count}`)
})

Example Response:

{
  "total_pruned": 4231,
  "per_table": {
    "wallet_transactions": 2103,
    "payments": 2128
  }
}

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

Common Network IDs

Bitcoin (PROTOCOL_BITCOIN, magic bytes hex)

EVM (PROTOCOL_EVM, decimal chain ID)

Best Practices

1. Cache the network list. Active networks rarely change; refresh on app start.
2. Treat the public key as stable. It's derived from the seed and won't change for the application's lifetime.
3. Check GetPreimage results for emptiness. A successful response can still mean "not yet known" — it's not an error.
4. Use PruneArchive with both filters set. Both unset is a no-op; combining max_age_secs and max_items gives the most predictable retention.

← Back to API Reference | Next: Wallet API →