Exchange Listing API
The dev community recommends using the open source Rosetta API implementation for integrating BitClout on an exchange: https://github.com/bitclout/rosetta-bitclout. The other APIs in this doc are less supported than the Rosetta APIs.
Multiple major crypto exchanges have expressed interest in listing BitClout. The dev community is working closely with several of these, but, now that anyone in the world can run a BitClout node, we thought we'd democratize and decentralize this effort by publishing a simple public API that any crypto exchange in the world could follow to integrate BitClout.
This guide will cover all of the API endpoints that are needed in order to list BitClout, with detailed descriptions and examples. This includes:
Setting up a node.
Using the Exchange API to create unlimited public/private key pairs.
Using the Exchange API to check the balance of BitClout public keys.
Using the Exchange API to transfer BitClout between public keys.
Using the Exchange API to query for transactions by transaction ID.
Using the Exchange API to query for transactions by public key.
Using the Exchange API to query for node sync status.
Using the Exchange API to query for block information by height or block hash.
The Quick Start section provides examples of all of the above using the “curl” command. The Full API Guide section provides more detail on each API endpoint shown in the examples.
Note: This API is strictly for use by exchanges. The bitclout.com nodes use in-browser signing such that your seed phrase never leaves your browser (learn more). In contrast, exchanges are typically custodial and so some of these endpoints manipulate seeds on behalf of users.
Quick Start
Generate a Seed Mnemonic
To get started, you need to generate a standard BIP39 mnemonic seed that will be used to generate public/private key pairs. If you don't require that your keys be generated on an air-gapped computer, then you can use the bitclout.com signup flow to generate your mnemonic. Note that your seed never leaves your browser when you generate it on bitclout.com. See Privacy and Security for more details on this process.
If you need your seed to be generated in an offline fashion, then we recommend that you use this tool. Either a 12 or 24-word mnemonic should be fine, and standard Bitcoin mnemonics work as well.
What we will use in our examples:
Mnemonic: arrive mixture refuse loud people robot dolphin scissors lift curve better demand
Passphrase (also known as "ExtraText"): password
Run a Node
All of the commands and examples in this guide will assume that you have a BitClout node running on your local machine. To set one up, simply follow the instructions in the open-source /run repository. If you run into any trouble, the nodes-discussion Discord channel is always available to help you:
Note that the node software is cross-platform and should run on Linux, Mac, and Windows. However, it seems as though people have had the most success with Linux and Mac machines with at least 32GB of RAM and at least 100GB of free disk space.
NOTE: You must set READ_ONLY_MODE
to false in dev.env in order for some API calls to work. However, at the time of this writing, it is not yet recommended to deploy a production node with READ_ONLY_MODE
set to false. This should change shortly, though. Keep an eye on the README for updates.
Check Node Sync Status
This query will return information about a node’s sync status, among other things. See the Full API Guide section for more information.
Notes:
We pipe the command into “python -m json.tool” so that it will “pretty print” but that you can delete this part of the command if you don’t have Python installed.
We are assuming the node is running on the same machine on which we’re doing this query. If the node is running on a different machine then the IP of that machine should be substituted for “localhost.”
Generate a Public/Private Key Pair
This will generate a public/private key-pair that corresponds to index “0” for this account. Each key-pair will map to an index for a particular seed. To generate more key-pairs, simply iterate the “Index” parameter.
Notes:
Under the hood, every public/private key pair maps to derivation path m/44'/0'/0'/0/{index}. Thus they would be identical to what is generated by any Bitcoin wallet using the same mnemonic, passphrase, and derivation path.
The public and private keys returned by this function will be encoded using base58 check encoding described in more detail in the Full API Guide section for this endpoint. For now, all that you need to know is that you can pass the public/private key strings to other API endpoints to check balances, spend BitClout, etc…
BitClout public keys that are encoded with base58 always start with the prefix “BC”. BitClout private keys that are encoded with base58 always start with the prefix “bc” (lower-case).
Example of BitClout public/private key pair returned by this function. Note that Error being empty string means the endpoint succeeded.
We pipe the command into “python -m json.tool” so that it will “pretty print” but that you can delete this if you don’t have Python installed.
Note: This API is strictly for use by exchanges. The bitclout.com nodes use a different API that never receives your seed phrase, and your seed phrase never leaves your browser. In contrast, exchanges are typically custodial and so some of these endpoints manipulate seeds on behalf of users.
Check Balance of BitClout Public Key
Notes:
This will return the balance in “nanos,” where 1 BitClout = 1,000,000,000 “nanos.” For example, if the balance for this public key was “1 BitClout” then this endpoint will return 1,000,000,000 (or 1e9 nanos).
This endpoint also returns UTXO's, but this likely won't be useful to most node operators.
Transfer BitClout Using a Public/Private Key-Pair
Notes:
This example will fail unless you send BitClout to the
SenderPublicKeyBase58Check
.You can buy BitClout on bitclout.com and then use the "Send BitClout" page to get some BitClout for testing purposes.
The amount must be specified in "nanos," where 1 BitClout = 1e9 nanos. This example transfers 1 BitClout from public key
BC1YLgAJ2kZ7Q4fZp7KzK2Mzr9zyuYPaQ1evEWG4s968sChRBPKbSV1
to public keyBC1YLgU67opDhT9bTPsqvue9QmyJLDHRZrSj77cF3P4yYDndmad9Wmx
To do a "dry run" of the transaction without broadcasting it, simply add
DryRun: true
to the params.
Setting “AmountNanos” to a negative value like -1 will send the maximum amount possible.
To implement a UI with a “Max” button, we recommend hitting this endpoint with a negative AmountNanos with DryRun set to true, grabbing the resultant “spend amount,” which will be net of fees, and displaying that to the user.
This endpoint will return information for the transaction created. See the Full API Guide section on this endpoint for more information on what is returned.
A custom “fee rate” can also be set. See the Full API Guide section for this endpoint for more detail on that.
Note: This API is strictly for use by exchanges. The bitclout.com nodes use a different API that never receives your seed phrase, and your seed phrase never leaves your browser. In contrast, exchanges are typically custodial and so some of these endpoints manipulate seeds on behalf of users.
Look Up Transactions for a Public Key
Notes:
A transaction ID is a sha256 hash of a transaction, encoded using base58 check encoding, that uniquely identifies a transaction.
This gets all the transaction IDs for a particular public key ordered from oldest to newest.
To fetch full transactions rather than just the IDs, simply set
IDsOnly
tofalse
rather thantrue
or leave it out of the request entirely.
This endpoint will only work if the node was started with the TXINDEX flag set to true, which is the default.
You must also wait for your
TXINDEX
to generate, which can take a few hours. Grep your logs for UpdateTxIndex to monitor its progress.
See the Full API Guide section for this endpoint to see what information will be returned by this endpoint.
Look Up Transaction Using Transaction ID
Get information for a specific transaction using that transaction’s transaction ID. You can get a transaction ID from other endpoints like the transfer-bitclout endpoint described previously.
Notes:
This is the same endpoint as the one used to lookup the transactions for a public key. When a
PublicKeyBase58Check
param is set, theTransactionIDBase58Check
param is expected to be unset and is ignored.This endpoint will only work if the node was started with the TXINDEX flag set to true, which is the default.
See the Full API Guide section for this endpoint to see what information will be returned by this endpoint.
Get Block For Block Hash or Height
This will return all the information associated with the block at height 10715. If the chain is not synced up to this point, an error will be returned.
Same as the previous example, only queries the block by its hash rather than its height.
For more information, see the Full API Guide section for these endpoints.
Full API Guide
Note: This API is strictly for use by exchanges. The bitclout.com nodes use a different API that never receives your seed phrase, and your seed phrase never leaves your browser. In contrast, exchanges are typically custodial and so some of these endpoints manipulate seeds on behalf of users.
Note: The dev community is also working to complete an integration with Rosetta that will further build on this API.
/api/v1/key-pair
You can generate public/private keypairs with a standard BIP39 mnemonic. Each public/private key pair corresponds to a particular index associated with the mnemonic. This means that index “5” for a particular mnemonic, for example, will always generate the same public/private key pair. An infinite number of public/private key pairs can thus be generated by iterating an index over a particular mnemonic.
All public/private keys are inter-operable as Bitcoin public/private keys. Meaning they represent a point on the secp256k1 curve (same as what is used by Bitcoin).
Under the hood, BitClout takes the BIP39 mnemonic and generates the public/private key pairs using the BIP32 derivation path m/44'/0'/0'/0/{index}, where "index" is the index of the public/private key being generated. This means that BitClout public/private key pair generated by the node will always line up with the public/private key pairs generated by this Ian Coleman tool. An engineer can therefore “sanity check” that things are working by generating a mnemonic using bitclout.com or Ian Coleman, creating a key pair with that mnemonic, and then verifying that the public/private key pairs generated line up with what is shown on bitclout.com or Ian Coleman.
/api/v1/balance
One can check the balance of a particular public key by passing the public key to the following endpoint.
Spent transaction outputs are not returned by this endpoint. To perform operations on spent transaction outputs, one must use the “transaction-info” endpoint instead.
/api/v1/transfer-bitclout
BitClout can be transferred from one public key to another using this simple API call. To transfer BitClout, one must either provide a public/private key pair.
BitClout uses a UTXO model like Bitcoin but BitClout transactions are generally simpler than Bitcoin transactions because BitClout always uses the “from public key” as the “change” public key (meaning that it does not “rotate” keys by default). For example, if a transaction sends 10 BitClout from PubA to PubB with 5 BitClout in “change” and 1 BitClout as a “miner fee,” then the transaction would look as follows:
The maximum amount of BitClout can be sent by specifying a negative amount when calling the endpoint. We recommend running the endpoint once with DryRun
set to true
, inspecting the output, and then running it with DryRun
set to false
, which will actually broadcast the transaction.
/api/v1/transaction-info
If one has a TransactionIDBase58Check, e.g. from calling the “transfer-bitclout” endpoint, one can get the corresponding human-readable “Transaction object” by passing this transaction id to a node. Note that this endpoint will error if TXINDEX
is set to false. If TXINDEX
was passed to the node but it has not finished syncing the blockchain yet, this endpoint may return incomplete results. The /node-info
endpoint can be used to check where a node is in its sync process (generally, syncing takes only a minute or two).
If one has a PublicKeyBase58Check (starts with “BC”), one can get all of the TransactionIDs associated with that public key sorted by oldest to newest (this will include transactions where the address is a sender and a receiver). One can also optionally get the full Transaction objects for all of the transactions in the same call.
/api/v1/node-info
General information about the node’s blockchain and sync state can be queried using this endpoint. The blockchain does a “headers-first” sync, meaning it first downloads all BitClout headers and then downloads all blocks. This means that, when the node is first syncing, the tip of the best “header chain” may be ahead of of its most recently downloaded block. In addition to syncing BitClout headers and BitClout blocks, a BitClout node will also sync all of the latest Bitcoin headers to power its built-in decentralized Bitcoin <> BitClout swap mechanism. For this reason, the endpoint also returns information on the node’s best Bitcoin header chain, which is distinct from its BitClout chain.
/api/v1/block
A block’s information can be queried using either the block hash or height. To get all blocks in the chain, simply query this endpoint by enumerating the heights starting from zero and iterating up to the tip. The tip height and hash can be obtained using the /node-info
endpoint.
Last updated