Evernode Host API — Live Network Data

02 — Endpoints

API reference

      Expand
      ▼
    

GET/hostsFiltered host list

Returns a paginated list of hosts matching the specified filters. All parameters optional. Defaults: minXah=5, minEvr=5. Responses include total, hasMore, nextOffset and prevOffset pagination fields.

Parameter	Type	Default	Description
active	boolean	—	Filter by active status
minSlots / maxSlots	integer	—	Available instances range
minRep / maxRep	integer	—	Reputation score range (0–255)
includeUnscored	boolean	false	Include hosts with rep=0
minXah	number	5	Minimum XAH balance
minEvr	number	5	Minimum EVR balance
minLease / maxLease	integer	—	Lease price range in drops
country	string	—	2-letter ISO country code (DE, FR, JP...)
domain	string	—	Partial domain match
version	string	—	Sashimono version (1.0.0, 0.12.1...)
minRam / minDisk	integer	—	Minimum RAM (MB) or disk (MB)
isATransferer	integer	—	0=exclude hosts in transfer mode, 1=only transferring hosts
reputedOnHeartbeat	boolean	—	true=only hosts actively being reputation-tested
minAccumulatedReward	number	—	Minimum lifetime EVR rewards earned
hasDescription	boolean	—	true=only hosts with a description set, false=only hosts without
hasEmail	boolean	—	true=only hosts with an email set, false=only hosts without
hasDomain	boolean	—	true=only hosts with a domain set, false=only hosts without
description_like	string	—	Partial match on description field
hostingType	string	—	cloud, dedicated, vps, residential, unknown
asnOrg	string	—	Partial match on ASN organisation name e.g. OVH, Hetzner, Contabo
includeFlagged	boolean	false	Include flagged/reported hosts in results
fields	string	—	Comma-separated list of fields to return e.g. address,domain,hostReputation
sort	string	—	Shorthand sort e.g. sort=hostReputation:desc (alternative to sortBy + sortDir)
sortBy	string	hostReputation	hostReputation, availableInstances, leaseDrops, xahBalance, evrBalance, ramMb, diskMb, lastHeartbeatIndex, registrationTimestamp, accumulatedReward, lastUpdated
sortDir	string	desc	asc or desc
limit / offset	integer	100 / 0	Pagination

GET/hosts/searchFull text search

Search across domain, email and description fields. Returns hosts sorted by reputation. At least one of q, hasDescription or description_like is required.

Parameter	Type	Default	Description
q	string	—	Search term (min 2 chars) — matches domain, email and description. Optional if hasDescription or description_like provided.
hasDescription	boolean	—	true=only hosts with a description set
description_like	string	—	Partial match on description only
active	boolean	—	Filter by active status
fields	string	—	Comma-separated fields to return
limit	integer	50	Max results (up to 200)

GET/hosts/expiringSilent / stale hosts

Returns active hosts that have not sent a heartbeat within the specified number of hours.

Parameter	Type	Default	Description
hours	integer	24	Silence threshold in hours
fields	string	—	Comma-separated fields to return
limit	integer	50	Max results (up to 200)

GET/hosts/compareCompare multiple hosts

Fetch full data for multiple hosts in a single request, returned in the same order as requested. Max 20 addresses.

Parameter	Type	Default	Description
addresses	string	—	Comma-separated XRPL addresses (max 20)
fields	string	—	Comma-separated fields to return

GET/leaderboardTop hosts by metric

Returns the top N active hosts ranked by the specified metric.

Parameter	Type	Default	Description
metric	string	hostReputation	hostReputation, accumulatedReward, xahBalance, evrBalance, ramMb, diskMb, availableInstances
fields	string	—	Comma-separated fields to return
limit	integer	20	Number of results (max 100)

POST/hosts/batchBulk address lookup

Fetch data for up to 100 hosts in a single POST. Body must be JSON with an addresses array. Optionally include a fields array to limit returned fields.

{ "addresses": ["rXXX...", "rYYY..."], "fields": ["address", "domain", "hostReputation"] }

GET/hosts/:addressSingle host full data

Returns complete data for a single host by XRPL address.

Parameter	Type	Default	Description
fields	string	—	Comma-separated fields to return

GET/hosts/:address/historyHeartbeat history

Returns a time-series of heartbeat snapshots capturing reputation, slots, balances and lease price over time. History accumulates from API v1.2.0 onwards. Supports pagination.

Parameter	Type	Default	Description
limit	integer	100	Number of snapshots to return (max 500)
offset	integer	0	Pagination offset

POST/hosts/:address/reportReport a problematic host

Submit a community report for a host. Reports are scored by severity and contribute to a host's reportScore. When the score reaches 3, the host is automatically flagged and excluded from default results. One report per IP per host per 24 hours. Body must be JSON.

Body field	Type	Required	Description
category	string	yes	peer_port_broken (1), instance_unreachable (1), slow_provision (1), bad_peering (2), fake_specs (2), security_issue (3), other (1) — number is severity weight
reason	string	yes	Description of the issue (min 10 chars, max 500)
evidence	string	no	URL, tx hash, or log excerpt (max 1000 chars)

GET/hosts/:address/reportsView reports for a host

Returns all community reports submitted for a specific host, along with the current reportScore, flagged status, and the score threshold required for flagging. Reporter IPs are not exposed.

GET/hosts/flaggedAll flagged hosts

Returns all hosts that have been flagged — either by community reports reaching the score threshold, or directly by an admin. Ordered by report score descending.

Parameter	Type	Default	Description
fields	string	—	Comma-separated fields to return
limit / offset	integer	100 / 0	Pagination

GET/report-categoriesValid report categories

Returns the list of valid report categories, their severity weights, the score threshold for auto-flagging, and the rolling window in days. Use this to populate submission forms.

GET/hosts/randomRandom host sample

Returns a randomly selected set of hosts matching the given filters. Useful for load distribution without client-side shuffling.

Parameter	Type	Default	Description
count	integer	10	Number of random hosts to return (max 200)
minRep	integer	—	Minimum reputation score
minSlots	integer	—	Minimum available slots
country	string	—	Filter by country code
active	boolean	true	Filter by active status
fields	string	—	Comma-separated fields to return

GET/providersProvider breakdown & centralisation

Returns all ASN providers with host counts, available slots, average reputation, share of active hosts, and flagged host count. Also returns a hosting-type breakdown and an HHI (Herfindahl-Hirschman Index) concentration score. Requires the GeoLite2-ASN database to be loaded — unenriched hosts are excluded.

Parameter	Type	Default	Description
active	boolean	true	Set to false to include inactive hosts in counts

HHI interpretation: below 1,500 = competitive · 1,500–2,500 = moderately concentrated · above 2,500 = highly concentrated.

GET/countriesHost counts by country

Returns all countries with registered hosts, including total host count, active host count and available slots per country.

GET/versionsSashimono version distribution

Returns all active Sashimono versions with host counts.

GET/statsNetwork summary statistics

Network-wide statistics: total and active host counts, available slots, average reputation and balances, top countries, version distribution and count of hosts with descriptions.

GET/healthAPI health check

Returns API status, host count, history snapshot count, last full scan timestamp and whether a scan is currently in progress.

03 — Examples

Query examples

      Expand
      ▼
    

Common queries shown in curl, browser fetch, and Node.js. All examples target https://api.onledger.net

Find active hosts with available slots

The most common query — active hosts with at least one free slot, sorted by reputation.

curl "https://api.onledger.net/hosts?active=true&minSlots=1&limit=20"

const res = await fetch('https://api.onledger.net/hosts?active=true&minSlots=1&limit=20');
const { hosts, total } = await res.json();
console.log(`${total} matching hosts`);
hosts.forEach(h => console.log(h.address, h.availableInstances));

const { hosts } = await fetch('https://api.onledger.net/hosts?active=true&minSlots=1&limit=20').then(r => r.json());
console.log(hosts.map(h => h.address));

Look up a single host

Fetch the complete data object for one host by its XRPL address.

curl "https://api.onledger.net/hosts/rnpkkEEMDSYAg1G6eHWF66kKjrKoAqMbtV"

const address = 'rnpkkEEMDSYAg1G6eHWF66kKjrKoAqMbtV';
const { host } = await fetch(`https://api.onledger.net/hosts/${address}`).then(r => r.json());
console.log(host.domain, host.hostReputation, host.availableInstances);

const address = 'rnpkkEEMDSYAg1G6eHWF66kKjrKoAqMbtV';
const { host } = await fetch(`https://api.onledger.net/hosts/${address}`).then(r => r.json());
console.log(host);

High-reputation hosts only

Filter to hosts with a reputation score above 240 — the upper tier of the 0–255 range.

curl "https://api.onledger.net/hosts?active=true&minRep=240&limit=50"

const { hosts } = await fetch('https://api.onledger.net/hosts?active=true&minRep=240&limit=50').then(r => r.json());
hosts.sort(() => Math.random() - 0.5);
console.log(hosts.slice(0, 10).map(h => h.address));

const { hosts } = await fetch('https://api.onledger.net/hosts?active=true&minRep=240&limit=500').then(r => r.json());
for (let i = hosts.length - 1; i > 0; i--) {
  const j = Math.floor(Math.random() * (i + 1));
  [hosts[i], hosts[j]] = [hosts[j], hosts[i]];
}
console.log(hosts.slice(0, 10).map(h => h.address));

Filter by country

Find active hosts in a specific country, sorted by cheapest lease price.

# New Zealand hosts, cheapest first
curl "https://api.onledger.net/hosts?active=true&country=NZ&sort=leaseDrops:asc"

const { hosts } = await fetch('https://api.onledger.net/hosts?active=true&country=NZ&sort=leaseDrops:asc').then(r => r.json());
console.log(hosts);

const { hosts } = await fetch('https://api.onledger.net/hosts?active=true&country=NZ&sort=leaseDrops:asc').then(r => r.json());
console.log(`Found ${hosts.length} NZ hosts`);

Hosts with sufficient resources

Find hosts meeting minimum hardware requirements before deploying a contract.

# At least 4GB RAM, 20GB disk, 1 free slot
curl "https://api.onledger.net/hosts?active=true&minRam=4096&minDisk=20000&minSlots=1&sort=ramMb:desc"

const { hosts, total } = await fetch('https://api.onledger.net/hosts?active=true&minRam=4096&minDisk=20000&minSlots=1').then(r => r.json());
console.log(`${total} hosts meet requirements`);

const { hosts } = await fetch('https://api.onledger.net/hosts?active=true&minRam=4096&minDisk=20000&minSlots=1&sort=ramMb:desc&limit=50').then(r => r.json());
console.log(hosts.map(h => ({ address: h.address, ram: h.ramMb, disk: h.diskMb })));

Batch lookup by address

POST an array of addresses to fetch up to 100 hosts in a single request — efficient for cluster managers.

curl -X POST "https://api.onledger.net/hosts/batch" \
  -H "Content-Type: application/json" \
  -d '{"addresses":["rXXX","rYYY","rZZZ"]}'

const { hosts } = await fetch('https://api.onledger.net/hosts/batch', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ addresses: ['rXXX', 'rYYY', 'rZZZ'] })
}).then(r => r.json());
console.log(hosts);

const myNodes = ['rXXX', 'rYYY', 'rZZZ'];
const { hosts, found } = await fetch('https://api.onledger.net/hosts/batch', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ addresses: myNodes })
}).then(r => r.json());
console.log(`Found ${found} of ${myNodes.length} hosts`);

Compare multiple hosts

Fetch full data for several hosts in one request — ideal for side-by-side comparison before choosing where to deploy.

curl "https://api.onledger.net/hosts/compare?addresses=rXXX,rYYY,rZZZ"

const addresses = ['rXXX', 'rYYY', 'rZZZ'].join(',');
const { hosts } = await fetch(`https://api.onledger.net/hosts/compare?addresses=${addresses}`).then(r => r.json());
hosts.forEach(h => console.log(h.address, h.hostReputation, h.availableInstances));

const addresses = ['rXXX', 'rYYY', 'rZZZ'];
const { hosts } = await fetch(`https://api.onledger.net/hosts/compare?addresses=${addresses.join(',')}`).then(r => r.json());
console.log(hosts);

Search by domain, email or description

Full text search across operator-provided fields. Use description_like for description-only matching, or hasDescription to find all hosts that have filled one in.

# Broad search across all text fields
curl "https://api.onledger.net/hosts/search?q=onledger&active=true"

# Only hosts with descriptions containing "Frankfurt"
curl "https://api.onledger.net/hosts/search?description_like=Frankfurt&active=true"

# All active hosts that have set a description
curl "https://api.onledger.net/hosts/search?hasDescription=true&active=true"

const { hosts, total } = await fetch('https://api.onledger.net/hosts/search?q=onledger&active=true').then(r => r.json());
console.log(`${total} results`, hosts);

const { hosts, total } = await fetch('https://api.onledger.net/hosts/search?hasDescription=true&active=true&limit=200').then(r => r.json());
console.log(`${total} hosts have descriptions`);
console.log(hosts.map(h => ({ address: h.address, description: h.description })));

Paginate through all hosts

Use the hasMore and nextOffset fields in the response to page through results efficiently.

# Page 1
curl "https://api.onledger.net/hosts?active=true&limit=100&offset=0"
# Use nextOffset from response for page 2
curl "https://api.onledger.net/hosts?active=true&limit=100&offset=100"

async function getAllHosts() {
  let offset = 0, all = [], hasMore = true;
  while (hasMore) {
    const data = await fetch(
      `https://api.onledger.net/hosts?active=true&limit=100&offset=${offset}`
    ).then(r => r.json());
    all = all.concat(data.hosts);
    hasMore = data.hasMore;
    offset  = data.nextOffset;
  }
  return all;
}

async function getAllHosts() {
  let offset = 0, all = [], hasMore = true;
  while (hasMore) {
    const { hosts, hasMore: more, nextOffset } = await fetch(
      `https://api.onledger.net/hosts?active=true&limit=100&offset=${offset}`
    ).then(r => r.json());
    all = all.concat(hosts);
    hasMore = more;
    offset  = nextOffset;
  }
  console.log(`Fetched ${all.length} hosts`);
  return all;
}
getAllHosts();

Top hosts leaderboard

Rank active hosts by reputation, earnings, resources or available slots.

# Top 10 by accumulated EVR rewards
curl "https://api.onledger.net/leaderboard?metric=accumulatedReward&limit=10"

const { hosts, label } = await fetch('https://api.onledger.net/leaderboard?metric=accumulatedReward&limit=10').then(r => r.json());
console.log(label, hosts.map(h => ({ address: h.address, reward: h.accumulatedReward })));

const metrics = ['hostReputation', 'accumulatedReward', 'ramMb'];
const results = await Promise.all(
  metrics.map(m => fetch(`https://api.onledger.net/leaderboard?metric=${m}&limit=5`).then(r => r.json()))
);
results.forEach(r => console.log(r.label, r.hosts.map(h => h.address)));

Host heartbeat history

Track reputation, slots and balance changes over time for a specific host.

curl "https://api.onledger.net/hosts/rnpkkEEMDSYAg1G6eHWF66kKjrKoAqMbtV/history?limit=50"

const address = 'rnpkkEEMDSYAg1G6eHWF66kKjrKoAqMbtV';
const { history } = await fetch(`https://api.onledger.net/hosts/${address}/history?limit=50`).then(r => r.json());
history.forEach(h => console.log(new Date(h.timestamp).toISOString(), h.hostReputation));

const address = 'rnpkkEEMDSYAg1G6eHWF66kKjrKoAqMbtV';
const { history, domain } = await fetch(`https://api.onledger.net/hosts/${address}/history`).then(r => r.json());
console.log(`${domain}: ${history.length} snapshots`);
console.log(history);

04 — Try It

Live query builder

      Collapse
      ▲
    

Build a query and see the live response directly from the API. For advanced filtering see the full endpoint reference above.

Hosting Type ?

Provider ? incl

excl

Min Available Instances

Min Reputation

Min Host XAH ?

Min Host EVR ?

Country

Domain contains

Version

Limit

Has Description ?

Description contains

Sort By

Sort Direction

Include flagged hosts ?

Include unscored (rep=0) ?

Response

Click "Run query" to see live results...

05 — Data Fields

Host object

      Expand
      ▼
    

Every host object returned by the API contains the following fields. Use the fields parameter on any endpoint to limit which fields are returned.

{
  "address":               "rXXX..."          // XRPL address
  "active":                1                  // 1=active, 0=inactive
  "domain":                "host.example.com"  // host domain
  "description":           "My Evernode host"  // operator-provided description (may be null)
  "countryCode":           "NZ"               // ISO 3166-1 alpha-2
  "maxInstances":          3                  // total instances configured
  "activeInstances":       1                  // currently in use
  "availableInstances":    2                  // free slots
  "leaseAmount":           "0.001"            // EVR per moment (1hr)
  "leaseDrops":            1000               // drops (1 EVR = 1,000,000)
  "hostReputation":        252                // 0–255, tested by reputation contract
  "reputedOnHeartbeat":    1                  // 1=reputation measured on heartbeat
  "version":               "1.0.0"            // sashimono version
  "cpuModelName":          "AMD EPYC..."      // CPU model
  "cpuCount":              4                  // allocated CPU cores
  "cpuMHz":                3200               // clock speed MHz
  "cpuMicrosec":           800000             // CPU microseconds allocated per round
  "ramMb":                 8192               // RAM in MB
  "diskMb":                32000              // disk in MB
  "email":                 "host@example.com" // operator contact email (may be null)
  "xahBalance":            34.5               // XAH balance
  "evrBalance":            12.3               // EVR balance
  "accumulatedReward":     "1.23"             // lifetime EVR rewards earned
  "uriTokenId":            "A848FB..."        // NFT token ID for host registration
  "registrationLedger":    12865596           // ledger index when host registered
  "registrationTimestamp": 1705310292         // unix timestamp of registration
  "registrationFee":       500                // EVR paid to register
  "isATransferer":         0                  // 1=host is in transfer mode
  "transferTimestamp":     1747994331         // unix timestamp of last transfer (may be null)
  "supportVoteSent":       0                  // 1=host has sent a governance support vote
  "lastVoteCandidateIdx":  0                  // index of last governance vote candidate
  "lastVoteTimestamp":     1775699062         // unix timestamp of last governance vote (may be null)
  "lastHeartbeatIndex":    1775699062         // unix timestamp of last heartbeat
  "lastUpdated":           1775701701966      // last DB update (ms)
  "asnNumber":             16509              // autonomous system number (null if ASN DB not loaded)
  "asnOrg":                "OVH SAS"          // ASN organisation name
  "hostingType":           "dedicated"        // cloud | dedicated | vps | residential | unknown
  "flagged":               0                  // 1=flagged, excluded from default results
  "flaggedAt":             null               // timestamp when flagged (ms)
  "flagReason":            null               // reason set by admin (if admin-flagged)
  "reportCount":           0                  // number of community reports in last 90 days
  "reportScore":           0                  // cumulative severity score (≥3 triggers auto-flag)
}

// List responses also include pagination metadata:
{
  "total":      2789   // total matching records
  "limit":      5      // page size used
  "offset":     0      // current offset
  "hasMore":    true   // more results available
  "nextOffset": 5      // pass as offset for next page (null if last page)
  "prevOffset": null   // pass as offset for previous page (null if first page)
  "hosts":      [...]  // array of host objects
}

Real-time host
discovery API

Start querying in seconds

API reference

Query examples

Live query builder

Host object

Network centralisation

Report a host

Real-time hostdiscovery API

Start querying in seconds

API reference

Query examples

Live query builder

Host object

Network centralisation

Report a host

Report a host

Real-time host
discovery API