• Home
• Build
• How To
• Connect your app to a Host

Connect your app to a Host

How you connect to a Host depends on your architecture. A local-first Go app embeds DefraDB and peers with Hosts over libp2p, so it needs connection strings. A direct-query TypeScript app talks to a Host's GraphQL endpoint over HTTP, so it needs an endpoint URL. Both start with the discovery step in Find Views and Hosts, which explains where each value comes from.

A Host client exposes four interfaces:

Public Hosts vary in how they publish these, so always read the actual connection_string and endpoint_address from the registry rather than assuming ports.

Check a Host's health first

Before wiring a Host into your app, check that it is alive and processing data:

curl -s -H "Accept: application/json" http://<host>:8080/health | jq '{status, current_block}'

{
  "status": "healthy",
  "current_block": 25903651
}

The Accept: application/json header asks for the JSON form; a browser gets an HTML status page instead. A healthy status with a recent current_block means the Host is peered and syncing. The same server answers GET /registration with the Host's DID, connection_string, and endpoint_address, which is handy for confirming a Host's identity before you trust its data.

Embedded app (Go)

A local-first app receives pushed data over libp2p, so the connection happens in the app-sdk config. Take the Host's connection_string from the registry:

curl -s http://testnet.shinzo.network:1317/shinzonetwork/host/v1/hosts \
  | jq -r '.hosts[].connection_string'

Add one or more of them to defradb.p2p.bootstrap_peers in your config.yaml:

defradb:
  p2p:
    enabled: true
    bootstrap_peers:
      - "/ip4/34.66.172.230/tcp/9171/p2p/12D3KooWKVCMswzcXYe9kW2z7nSB9YUWjVVLsMbJnBjVPFUQkbQ7"
    listen_addr: "/ip4/127.0.0.1/tcp/9171"

The full multiaddr form /ip4/<ip>/tcp/9171/p2p/<peerID> always works, but it is not required. Bare IPs (34.66.172.230) and ip:port pairs (34.66.172.230:9171) also work, because the client discovers the peer ID during the connection handshake and fills it in for you. Listing several bootstrap peers makes the first connection more reliable, since registered Hosts come and go on a testnet.

Once peered, subscribe to a View and data starts arriving. Subscribe to Views with the app-sdk covers that flow.

Direct-query app (TypeScript)

A direct-query app never peers with anything. It reads the Host's endpoint_address from the registry and POSTs signed GraphQL requests to it:

curl -s http://testnet.shinzo.network:1317/shinzonetwork/host/v1/hosts \
  | jq -r '.hosts[].endpoint_address'

The endpoint already includes the API path, so you POST straight to it:

curl -s -X POST "http://34.66.172.230/api/v0/graphql" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ Erc20Event(limit: 1) { blockNumber } }", "extensions": { ... } }'

View queries carry a signature in the extensions envelope, and one billed query maps to one pool: a request may touch only one View collection, and its pool_address extension names the pool it bills to. When a Host enforces billing, rejections come back as plain errors: 403 if the request signature is missing, stale, or fails verification, and 402 if the signer's query balance is too low. Query your first View builds the signing flow end to end.

Prefer your own Host

Public Hosts are shared infrastructure. If you want guaranteed availability, or you do not want a third party to see your queries at all, you can point everything above at a Host you run yourself. See Use your own infrastructure.

Need help

• For onboarding and technical support, join the Shinzo Discord.
• To report a documentation bug or request a feature, open an issue in the docs repo.
• For a technical issue with the Host client, open an issue in the shinzo-host-client repo.