# HTTP API reference
Drand provides a JSON HTTP interface that clients can use to fetch randomness from each drand network running on nodes. If you're using drand in an application, it may be easier and more secure to use one of the client libraries, which will also perform verification of randomness rounds and add additional features like failover, racing, aggregation, and caching.
All that's required is the address of the HTTP interface and way to fetch from HTTP, e.g. curl
.
# Public endpoints
The public League of Entropy (opens new window) HTTP APIs are available at:
- Protocol Labs
- Cloudflare
The chain hash for the League of Entropy drand group is:
8990e7a9aaed2ffed73dbd7092123d6f289930540d7651336225dc172e51b2ce
# /chains
Retrieves the chain hash of every running network a user can interact with. It returns a JSON object with the following structure:
[
"8990e7a9aaed2ffed73dbd7092123d6f289930540d7651336225dc172e51b2ce",
"859504eade86790ad09b2b3474d5e09d1718b549ef7107d7bbd18f5e221765ce",
"8252d7db02664c1f6b20f40c6e8e138704d2acfeb6c5abcc14c77e3a842b2f84",
"515e7366248ca37b1460d23b4f98493c246fbb02851f2a43a710c968a349f8d6"
]
# /{chain-hash}/info
Retrieves the randomness chain information. It returns a JSON object with the following structure:
{
"public_key": "868f005eb8e6e4ca0a47c8a77ceaa5309a47978a7c71bc5cce96366b5d7a569937c529eeda66c7293784a9402801af31",
"period": 30,
"genesis_time": 1595431050,
"hash": "8990e7a9aaed2ffed73dbd7092123d6f289930540d7651336225dc172e51b2ce"
}
public_key
is the distributed public key of the drand groupperiod
is the time in seconds between randomness beacon roundsgenesis_time
is the time in seconds since the Unix Epoch that the group began generating randomnesshash
is the chain hash, which uniquely identifies the drand chain. It is used as a root of trust for validation of the first round of randomness.
# /{chain-hash}/public/latest
Retrives the latest round of randomness. It returns a JSON object with the following structure:
{
"round": 367,
"randomness": "3439d92d58e47d342131d446a3abe264396dd264717897af30525c98408c834f",
"signature": "90957ebc0719f8bfb67640aff8ca219bf9f2c5240e60a8711c968d93370d38f87b38ed234a8c63863eb81f234efce55b047478848c0de025527b3d3476dfe860632c1b799550de50a6b9540463e9fb66c8016b89c04a9f52dabdc988e69463c1",
"previous_signature": "859504eade86790ad09b2b3474d5e09d1718b549ef7107d7bbd18f5e221765ce8252d7db02664c1f6b20f40c6e8e138704d2acfeb6c5abcc14c77e3a842b2f84515e7366248ca37b1460d23b4f98493c246fbb02851f2a43a710c968a349f8d6"
}
round
is an sequentially increasing integer - the randomness round indexrandomness
is a SHA-256 hash of the signaturesignature
is the Boneh-Lynn-Shacham (BLS) signature for this round of randomnessprevious_signature
is the signature of the previous round of randomness
# /{chain-hash}/public/{round}
Retrieves a previous round of randomness identified by the positive integer round
. Note that specifying 0
will retrieve the latest round. It returns a JSON object with the following structure:
{
"round": 367,
"randomness": "3439d92d58e47d342131d446a3abe264396dd264717897af30525c98408c834f",
"signature": "90957ebc0719f8bfb67640aff8ca219bf9f2c5240e60a8711c968d93370d38f87b38ed234a8c63863eb81f234efce55b047478848c0de025527b3d3476dfe860632c1b799550de50a6b9540463e9fb66c8016b89c04a9f52dabdc988e69463c1",
"previous_signature": "859504eade86790ad09b2b3474d5e09d1718b549ef7107d7bbd18f5e221765ce8252d7db02664c1f6b20f40c6e8e138704d2acfeb6c5abcc14c77e3a842b2f84515e7366248ca37b1460d23b4f98493c246fbb02851f2a43a710c968a349f8d6"
}
round
is an sequentially increasing integer - the randomness round indexrandomness
is a SHA-256 hash of the signaturesignature
is the Boneh-Lynn-Shacham (BLS) signature for this round of randomnessprevious_signature
is the signature of the previous round of randomness
Note: For backward-compatibility reasons, paths without chain-hash
could be attended by
the default network in operation.