1️⃣Exchange Listing: API
The developer community recommends using the open-source Rosetta API implementation, currently used by Coinbase, for integrating DeSo on an exchange: https://github.com/deso-protocol/rosetta-deso. This being said, we provide an alternative set of APIs in this document that may be easier to use, and that the DeSo core team plans to support indefinitely.
Now that anyone in the world can run a DeSo 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 DeSo.
This guide will cover all of the API endpoints that are needed in order to list DeSo, 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 DeSo public keys.
Using the Exchange API to transfer DeSo 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 DeSo 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 Diamond signup flow to generate your mnemonic. Note that your seed never leaves your browser when you generate it on diamondapp. 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 DeSo 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, ask for help in the #nodes channel on the official DeSo Discord:
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 DeSo, etc…
DeSo public keys that are encoded with base58 always start with the prefix “BC”. DeSo private keys that are encoded with base58 always start with the prefix “bc” (lower-case).
Example of DeSo 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 DeSo 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 DeSo Public Key
Notes:
This will return the balance in “nanos,” where 1 DeSo = 1,000,000,000 “nanos.” For example, if the balance for this public key was “1 DeSo” 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 DeSo Using a Public/Private Key-Pair
Notes:
This example will fail unless you send DeSo to the
SenderPublicKeyBase58Check
.You can buy DeSo on diamondapp.com and then use the "Send DeSo" page to get some DeSo for testing purposes.
The amount must be specified in "nanos," where 1 DeSo = 1e9 nanos. This example transfers 1 DeSo 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. We recommend providing a value of 1000 for MinFeeRateNanosPerKB. See the Full API Guide section for this endpoint for more detail on that.
Note: This API is strictly for use by exchanges. The diamondapp.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-deso 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 diamondapp.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, DeSo 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 DeSo 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 diamondapp.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 diamondapp.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. o perform operations on spent transaction outputs, one must use the “transaction-info” endpoint instead.
/api/v1/transfer-deso
DeSo can be transferred from one public key to another using this simple API call. To transfer DeSo, one must either provide a public/private key pair.
DeSo recently transitioned from a UTXO model to a balance model and any references to UTXOs in the examples below have been deprecated.
The maximum amount of DeSo 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-deso” 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 DeSo 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 DeSo headers and DeSo blocks, a DeSo node will also sync all of the latest Bitcoin headers to power its built-in decentralized Bitcoin <> DeSo swap mechanism. For this reason, the endpoint also returns information on the node’s best Bitcoin header chain, which is distinct from its DeSo 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