Skip to main content
MAIN CHAIN

Main Chain REST API

Public mainnet base URL: https://blockchain.elastos.io/api/v1/

A self-hosted ELA full node exposes this REST API on port 20334 (mainnet default). You can query blocks, transactions, balances, and UTXOs with ordinary GET requests. The examples below use http://localhost:20334 as the base; replace that host with https://blockchain.elastos.io (no trailing path beyond /api/v1/...) when calling the public explorer API.

Responses are JSON objects with:

FieldMeaning
DescHuman-readable status (e.g. "Success")
ErrorNumeric error code; 0 means success
ResultPayload (type varies by endpoint)

GET /api/v1/node/connectioncount​

Returns how many peer nodes this node is connected to.

curl http://localhost:20334/api/v1/node/connectioncount
{
  "Desc": "Success",
  "Error": 0,
  "Result": 5
}

GET /api/v1/node/state​

Returns runtime status: build label (Compile), synced Height, protocol Version, listening ports (Port, PRCPort, RestPort, WSPort), counts, flags, and a Neighbors array (peer id, height, relay, connection state, NetAddress, etc.).

curl http://localhost:20334/api/v1/node/state
{
  "Desc": "Success",
  "Error": 0,
  "Result": {
    "Compile": "v0.9.0",
    "ID": 557625380943624900,
    "HexID": "0x7bd15545ce2fac4",
    "Height": 188850,
    "Version": 0,
    "Services": 0,
    "Relay": true,
    "TxnCnt": 84511,
    "RxTxnCnt": 21119,
    "Port": 20338,
    "PRCPort": 20336,
    "RestPort": 20334,
    "WSPort": 20335,
    "OpenPort": 20866,
    "OpenService": false,
    "Neighbors": [
      {
        "ID": 5225904035618466119,
        "HexID": "0x488624084951a947",
        "Height": 188850,
        "Services": 0,
        "Relay": true,
        "External": false,
        "State": "ESTABLISH",
        "NetAddress": "203.0.113.10:20338"
      }
    ]
  }
}

GET /api/v1/block/height​

Returns the current block height of the chain tip as known by this node.

curl http://localhost:20334/api/v1/block/height
{
  "Desc": "Success",
  "Error": 0,
  "Result": 1000
}

GET /api/v1/block/hash/{height}​

Returns the block hash at the given height. Replace {height} with a non-negative integer.

curl http://localhost:20334/api/v1/block/hash/123
{
  "Desc": "Success",
  "Error": 0,
  "Result": "b9450e180aba1a96a93003be1ba775499577f856bb17a82177e74ae4d94db3fb"
}

GET /api/v1/block/details/height/{height}​

Returns full block metadata and transactions for the block at {height}. The Result includes hash, confirmations, size, merkleroot, tx (array of full transaction objects), time, nonce, bits, difficulty, chainwork, previousblockhash, nextblockhash, auxpow (merged-mining data when present), and related fields.

curl http://localhost:20334/api/v1/block/details/height/123
{
  "Desc": "Success",
  "Error": 0,
  "Result": {
    "hash": "b9450e180aba1a96a93003be1ba775499577f856bb17a82177e74ae4d94db3fb",
    "confirmations": 188784,
    "strippedsize": 498,
    "size": 498,
    "weight": 1992,
    "height": 123,
    "version": 0,
    "versionhex": "00000000",
    "merkleroot": "3ce4c09723a6c241749098d7416bad64f2439920a8a8afdf19dac895cb946634",
    "tx": [
      {
        "txid": "3ce4c09723a6c241749098d7416bad64f2439920a8a8afdf19dac895cb946634",
        "hash": "3ce4c09723a6c241749098d7416bad64f2439920a8a8afdf19dac895cb946634",
        "size": 192,
        "vsize": 192,
        "version": 0,
        "locktime": 123,
        "vin": [
          {
            "txid": "0000000000000000000000000000000000000000000000000000000000000000",
            "vout": 65535,
            "sequence": 4294967295
          }
        ],
        "vout": [
          {
            "value": "1.50684931",
            "n": 0,
            "address": "8VYXVxKKSAxkmRrfmGpQR2Kc66XhG6m3ta",
            "assetid": "a3d0eaa466df74983b5d7c543de6904f4c9418ead5ffd6d25814234a96db37b0",
            "outputlock": 0
          },
          {
            "value": "3.51598174",
            "n": 1,
            "address": "8VYXVxKKSAxkmRrfmGpQR2Kc66XhG6m3ta",
            "assetid": "a3d0eaa466df74983b5d7c543de6904f4c9418ead5ffd6d25814234a96db37b0",
            "outputlock": 0
          }
        ],
        "blockhash": "b9450e180aba1a96a93003be1ba775499577f856bb17a82177e74ae4d94db3fb",
        "confirmations": 188784,
        "time": 1513940099,
        "blocktime": 1513940099,
        "type": 0,
        "payloadversion": 4,
        "payload": {
          "CoinbaseData": "ELA"
        },
        "attributes": [
          {
            "usage": 0,
            "data": "2a92922b60b3e537"
          }
        ],
        "programs": []
      }
    ],
    "time": 1513940099,
    "mediantime": 1513940099,
    "nonce": 0,
    "bits": 520095999,
    "difficulty": "1",
    "chainwork": "0002e16f",
    "previousblockhash": "7f6effc4e37b0a29e1079d32f6e373e6a962d6531a4e9e5310433dd97709b2a4",
    "nextblockhash": "7cc40920292d89be189e63112f0d4f1ffc0b48cd9e17df0181035f7f0a27b1ba",
    "auxpow": "01000000010000000000000000000000000000000000000000000000000000000000000000000000002cfabe6d6d..."
  }
}

GET /api/v1/block/details/hash/{hash}​

Same block payload as by height, but keyed by full block hash. For this route, tx is often a list of transaction id strings only (not expanded transaction objects).

curl http://localhost:20334/api/v1/block/details/hash/b9450e180aba1a96a93003be1ba775499577f856bb17a82177e74ae4d94db3fb
{
  "Desc": "Success",
  "Error": 0,
  "Result": {
    "hash": "b9450e180aba1a96a93003be1ba775499577f856bb17a82177e74ae4d94db3fb",
    "confirmations": 188788,
    "strippedsize": 498,
    "size": 498,
    "weight": 1992,
    "height": 123,
    "version": 0,
    "versionhex": "00000000",
    "merkleroot": "3ce4c09723a6c241749098d7416bad64f2439920a8a8afdf19dac895cb946634",
    "tx": [
      "3ce4c09723a6c241749098d7416bad64f2439920a8a8afdf19dac895cb946634"
    ],
    "time": 1513940099,
    "mediantime": 1513940099,
    "nonce": 0,
    "bits": 520095999,
    "difficulty": "1",
    "chainwork": "0002e173",
    "previousblockhash": "7f6effc4e37b0a29e1079d32f6e373e6a962d6531a4e9e5310433dd97709b2a4",
    "nextblockhash": "7cc40920292d89be189e63112f0d4f1ffc0b48cd9e17df0181035f7f0a27b1ba",
    "auxpow": "01000000010000000000000000000000000000000000000000000000000000000000000000000000002cfabe6d6d..."
  }
}

GET /api/v1/block/transactions/height/{height}​

Returns the block hash, height, and an array of transaction ids for that block.

curl http://localhost:20334/api/v1/block/transactions/height/16000
{
  "Desc": "Success",
  "Error": 0,
  "Result": {
    "Hash": "3fe8b94a27cccbbcd4a6675e1f3df62f0571fc847abf6488d7fff6e522d96862",
    "Height": 16000,
    "Transactions": [
      "5c0a30ad3764e6524803ac673d552af59acac910cea36f1678d5b0ae03c67078",
      "73d201de3cc1ccce92d6edff03cf4d1741c6ab99118dce37f7027eec4a5b3e93"
    ]
  }
}

GET /api/v1/transaction/{txid}​

Returns full transaction details for {txid}: vin, vout (values, addresses, assetid), blockhash, confirmations, type, payload, programs, etc.

curl http://localhost:20334/api/v1/transaction/5c0a30ad3764e6524803ac673d552af59acac910cea36f1678d5b0ae03c67078
{
  "Desc": "Success",
  "Error": 0,
  "Result": {
    "txid": "5c0a30ad3764e6524803ac673d552af59acac910cea36f1678d5b0ae03c67078",
    "hash": "5c0a30ad3764e6524803ac673d552af59acac910cea36f1678d5b0ae03c67078",
    "size": 192,
    "vsize": 192,
    "version": 0,
    "locktime": 16000,
    "vin": [
      {
        "txid": "0000000000000000000000000000000000000000000000000000000000000000",
        "vout": 65535,
        "sequence": 4294967295
      }
    ],
    "vout": [
      {
        "value": "1.50686389",
        "n": 0,
        "address": "8VYXVxKKSAxkmRrfmGpQR2Kc66XhG6m3ta",
        "assetid": "a3d0eaa466df74983b5d7c543de6904f4c9418ead5ffd6d25814234a96db37b0",
        "outputlock": 0
      },
      {
        "value": "3.51601576",
        "n": 1,
        "address": "8VYXVxKKSAxkmRrfmGpQR2Kc66XhG6m3ta",
        "assetid": "a3d0eaa466df74983b5d7c543de6904f4c9418ead5ffd6d25814234a96db37b0",
        "outputlock": 0
      }
    ],
    "blockhash": "3fe8b94a27cccbbcd4a6675e1f3df62f0571fc847abf6488d7fff6e522d96862",
    "confirmations": 172872,
    "time": 1515940214,
    "blocktime": 1515940214,
    "type": 0,
    "payloadversion": 4,
    "payload": {
      "CoinbaseData": "ELA"
    },
    "attributes": [
      {
        "usage": 0,
        "data": "c9a7a12d61c446d4"
      }
    ],
    "programs": []
  }
}

GET /api/v1/transactionpool​

Returns transactions currently in the mempool. Result is an array of transaction objects (shape similar to /transaction/{txid}; fields such as confirmations are typically zero while unconfirmed).

curl http://localhost:20334/api/v1/transactionpool
{
  "Desc": "Success",
  "Error": 0,
  "Result": [
    {
      "txid": "95d3bb263167581f2291de0ece4927ac8f5c2a9b10e448fa362e70cf6a11dfe5",
      "hash": "95d3bb263167581f2291de0ece4927ac8f5c2a9b10e448fa362e70cf6a11dfe5",
      "size": 368,
      "vsize": 368,
      "version": 0,
      "locktime": 173080,
      "vin": [
        {
          "txid": "1254a20e4a80274fdd477d13c7ebf8895b71ec6f2609c1f94f4e2601cfca019d",
          "vout": 0,
          "sequence": 0
        }
      ],
      "vout": [
        {
          "value": "0.32300000",
          "n": 0,
          "address": "EeYC12CizLnApy9SDu9PW6jy2WCVZX5rHA",
          "assetid": "a3d0eaa466df74983b5d7c543de6904f4c9418ead5ffd6d25814234a96db37b0",
          "outputlock": 0
        }
      ],
      "blockhash": "",
      "confirmations": 0,
      "time": 0,
      "blocktime": 0,
      "type": 5,
      "payloadversion": 0,
      "payload": {},
      "attributes": [],
      "programs": [
        {
          "code": "2102776f2ad3fc822caa976bf0a83eb33cf4047518c9b6d411603be4a864b24acb4bac",
          "parameter": "406ef85b364b2d57a1369516ff334b16560068ae2947b9c9baa1a1f756802cc0d0ec659ed14dd73ec9af1ae1c6706304072ae40551ba4bbe8c2473f0ed6a8182e0"
        }
      ]
    }
  ]
}

GET /api/v1/asset/balances/{address}​

Returns the total spendable balance for {address} as a decimal string (ELA units).

curl http://localhost:20334/api/v1/asset/balances/EgHPRhodCsDKuDBPApCK3KLayiBomrJrbH
{
  "Desc": "Success",
  "Error": 0,
  "Result": "20.84298920"
}

GET /api/v1/asset/utxos/{address}​

Returns UTXOs grouped by asset. Each element has AssetId, AssetName, and Utxo: an array of { Txid, Index, Value } (value as string).

curl http://localhost:20334/api/v1/asset/utxos/EgHPRhodCsDKuDBPApCK3KLayiBomrJrbH
{
  "Desc": "Success",
  "Error": 0,
  "Result": [
    {
      "AssetId": "a3d0eaa466df74983b5d7c543de6904f4c9418ead5ffd6d25814234a96db37b0",
      "AssetName": "ELA",
      "Utxo": [
        {
          "Txid": "c8d4dc984da78c878b9dab752c077b41a98f6e67e5ee6b04cc3d45cb4f42b81b",
          "Index": 1,
          "Value": "0.09956920"
        },
        {
          "Txid": "0b219b2b5b836dfa6acb10fad653fadd384494df3f6710ce168c6055106d101b",
          "Index": 0,
          "Value": "20.74342000"
        }
      ]
    }
  ]
}

GET /api/v1/confirm/details/height/{height}​

Returns BPoS confirmation metadata for the block at {height}: blockhash, sponsor (producer public key hex), viewoffset, and votes (signer, accept).

curl http://localhost:20334/api/v1/confirm/details/height/123
{
  "Desc": "Success",
  "Error": 0,
  "Result": {
    "blockhash": "65fd07f4069a1ca6833d38e0baa9b0b4a9bac35131feb5c363bd2fb99f8d06d8",
    "sponsor": "024ac1cdf73e3cbe88843b2d7279e6afdc26fc71d221f28cfbecbefb2a48d48304",
    "viewoffset": 0,
    "votes": [
      {
        "signer": "024babfecea0300971a6f0ad13b27519faff0ef595faf9490dc1f5f4d6e6d7f3fb",
        "accept": true
      },
      {
        "signer": "024ac1cdf73e3cbe88843b2d7279e6afdc26fc71d221f28cfbecbefb2a48d48304",
        "accept": true
      },
      {
        "signer": "0274fe9f165574791f74d5c4358415596e408b704be9003f51a25e90fd527660b5",
        "accept": true
      }
    ]
  }
}

GET /api/v1/confirm/details/hash/{hash}​

Same confirmation payload as by height, using the block hash instead of height.

curl http://localhost:20334/api/v1/confirm/details/hash/65fd07f4069a1ca6833d38e0baa9b0b4a9bac35131feb5c363bd2fb99f8d06d8
{
  "Desc": "Success",
  "Error": 0,
  "Result": {
    "blockhash": "65fd07f4069a1ca6833d38e0baa9b0b4a9bac35131feb5c363bd2fb99f8d06d8",
    "sponsor": "024ac1cdf73e3cbe88843b2d7279e6afdc26fc71d221f28cfbecbefb2a48d48304",
    "viewoffset": 0,
    "votes": [
      {
        "signer": "024babfecea0300971a6f0ad13b27519faff0ef595faf9490dc1f5f4d6e6d7f3fb",
        "accept": true
      },
      {
        "signer": "0274fe9f165574791f74d5c4358415596e408b704be9003f51a25e90fd527660b5",
        "accept": true
      }
    ]
  }
}

POST /api/v1/transaction​

Broadcasts a signed raw transaction. Request body must be JSON:

{
  "Action": "sendrawtransaction",
  "data": "<hex-encoded signed transaction>"
}

On success, Result is the new transaction id (hex string).

curl -X POST http://localhost:20334/api/v1/transaction \
  -H "Content-Type: application/json" \
  -d '{"Action":"sendrawtransaction","data":"020001001335353737303036373931393437373739343130010faf7e6f2f43ebdc2723e50014280d4cdac1975f9f883dc57e60aa7e96047b5401000000000002b037db964a231458d2d6ffd5ea18944c4f90e63d547c5d3b9874df66a4ead0a300e1f505000000000000000021132c86ebad33299ecc15dff410d4b0a76b4f9e17b037db964a231458d2d6ffd5ea18944c4f90e63d547c5d3b9874df66a4ead0a3a02bb459e4050000000000002136c6f2ad6785cef94fab1216b776add14bd756a850ab0100014140cbd0fb92a390dcd802ecef745091045ccb3033f097e6a42cc18822b000360e48d1a09388db077ca9c7cfc889c0eca427ca1f5f05490658a854f752ea1fb57b7c2321032f4540e915134f38ba24cdc08621ad7f5b8b62db36843ae8fa9422c047a04be8ac"}'
{
  "Desc": "Success",
  "Error": 0,
  "Result": "2e8d51bdbba82af7a7ed334cb0fb60ad9a5da7e5170f9d2509023f3ed3cce1d0"
}

Produce the data hex with ela-cli (or your wallet/SDK): for example ela-cli wallet buildtx to create an unsigned transaction, then ela-cli wallet signtx -f <file.txn> to sign; the tool outputs the raw hex to submit in data.

Resources​