Server API

The daemon implements JSON RPC, so you can use any RPC client to communicate with it or write your own. A basic request over HTTP would look like this (using testnet4 endpoint)

POST http://127.0.0.1:7224

{
    "jsonrpc": "2.0", 
    "method": "<methodname>", 
    "params": [ .. ],
    "id": 1
}

Get Server Info

getserverinfo retrieve the current state of the spaces daemon

Params None

CLI

space-cli --chain testnet4 getserverinfo

cURL

curl -X POST http://127.0.0.1:7224 \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","method":"getserverinfo","params":[],"id":1}'

Example Response

"chain": "testnet4",
"tip": {
  "hash": "0000000000000040297226f7046d72b63e159f6814009b9d9155331fd0ddec61",
  "height": 41730
}

Get Space

getspace retrieve information about a space:

Params

Name	Type	Description
space	string	Canonical space name e.g. @bitcoin

CLI

space-cli --chain testnet4 getspace @bitcoin

cURL

curl -X POST http://127.0.0.1:7224 \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","method":"getspace","params":["@bitcoin"],"id":1}'

Example Response

Pre-auction

{
  "txid": "",
  "n": 1,
  "name": "@btc",
  "covenant": {
    "type": "bid",
    "burn_increment": 1000,
    "signature": "........",
    "total_burned": 1000,
    "claim_height": null
  },
  "value": 662,
  "script_pubkey": "512027453c85a747cdc411f3b27e1cc475c299f3bb18498316b7c56a977bb4e6b2dd"
}

In Auction

{
  "txid": "ffe0d3a0d9f925efd486d3a3744e8968b41e64100249f55f6c3a85b8bfdcc8c1",
  "n": 51,
  "name": "@axis",
  "covenant": {
    "type": "bid",
    "burn_increment": 1400,
    "signature": "........",
    "total_burned": 1400,
    "claim_height": 56305
  },
  "value": 662,
  "script_pubkey": "512034c032c74d323646bb63930fd8a6b305957e2b46af207362f5d652fdc9dc2115"
}

Claimed

{
  "txid": "f811529d79c9fc808c240a1b5087ba19610c4177a01ffa8047c3cc143cf3eb1a",
  "n": 1,
  "name": "@bitcoin",
  "covenant": {
    "type": "transfer",
    "expire_height": 108439,
    "data": "68656c6c6f20776f726c64"
  },
  "value": 666,
  "script_pubkey": "5120611454515f9fe8c656f80c51de229dc5d9cba9a05d00486b43a1e9033ef6393b"
}

Get Space Owner

getspaceowner retrieves the outpoint of a space:

Params

Name	Type	Description
space	string	Canonical space name e.g. @bitcoin

CLI

only available via JSON-RPC

cURL

curl -X POST http://127.0.0.1:7224 \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","method":"getspaceowner","params":["@bitcoin"],"id":1}'

Example Response Responds with an outpoint with txid:vout format.

f811529d79c9fc808c240a1b5087ba19610c4177a01ffa8047c3cc143cf3eb1a:1

Get Spaceout

getspaceout retrieves a spaceout which are any UTXOs tracked by the spaces protocol not necessarily ones with a space.

Params

Name	Type	Description
outpoint	string	An Outpoint which is a specific output within a transaction using txid:vout format e.g. f811529d79c9fc808c240a1b5087ba19610c4177a01ffa8047c3cc143cf3eb1a:1

CLI

space-cli --chain testnet4 getspaceout "f811529d79c9fc808c240a1b5087ba19610c4177a01ffa8047c3cc143cf3eb1a:1"

cURL

curl -X POST http://127.0.0.1:7224 \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","method":"getspaceout","params":["f811529d79c9fc808c240a1b5087ba19610c4177a01ffa8047c3cc143cf3eb1a:1"],"id":1}'

Example Response

Space UTXO

{
  "n": 1,
  "name": "@bitcoin",
  "covenant": {
    "type": "transfer",
    "expire_height": 108439,
    "data": "68656c6c6f20776f726c64"
  },
  "value": 666,
  "script_pubkey": "5120611454515f9fe8c656f80c51de229dc5d9cba9a05d00486b43a1e9033ef6393b"
}

Other UTXOs

{
  "n": 0,
  "value": 662,
  "script_pubkey": "512065a7b5051fe33239e6ddb0d69e809a74d1702fde541bdf3431c6994b72317f33"
}

Estimate bid

estimatebid estimates the required bid to make it into the auctions phase for the given interval (in 144 block increments)::

Params

Name	Type	Description
target	number	The target interval e.g. specify 0 for the coming rollout, 1 for the day after and so on.

CLI

space-cli --chain testnet4 estimatebid 0

cURL

curl -X POST http://127.0.0.1:7224 \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","method":"estimatebid","params":[0],"id":1}'

Example Response Responds with an amount in Satoshis

2000

Get Rollout

getrollout get spaces rolling out into auctions for the given interval (in 144 block increments):

Params

Name	Type	Description
target	number	The target interval e.g. specify 0 for the coming rollout, 1 for the day after and so on.

CLI

space-cli --chain testnet4 getrollout 0

cURL

curl -X POST http://127.0.0.1:7224 \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","method":"getrollout","params":[0],"id":1}'

Example Response An array of spaces expected to be in auctions within the given target

[
  [
    "@bitcoin",
    1000
  ],
  [
    "@mytestspace",
    1000
  ],

Get Block Meta

getblockmeta Retrieves all transactions relevant to spaces for the given block (requires block indexing to be enabled)

Params

Name	Type	Description
block_hash	string	The block hash as hex string

CLI

only available via JSON-RPC

cURL

curl -X POST http://127.0.0.1:7224 \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","method":"getblockmeta","params":["00000000003a037a98a512ca38147af1d3a21d858596d24f83d65fbf2f6d5131"],"id":1}'

Example Response

{
  "height": 55879,
  "tx_meta": [
    {
      "txid": "394ebef5203c4306c3f7a6d1a5c2058bac130deb24c1d7725094b31d1ff54ea4",
      "spends": [
        {
          "n": 0
        }
      ],
      "creates": [
        {
          "n": 0,
          "value": 662,
          "script_pubkey": "512065a7b5051fe33239e6ddb0d69e809a74d1702fde541bdf3431c6994b72317f33"
        }
      ],
      "updates": []
    },
    {
      "txid": "f811529d79c9fc808c240a1b5087ba19610c4177a01ffa8047c3cc143cf3eb1a",
      "spends": [
        {
          "n": 0
        },
        {
          "n": 1
        },
        {
          "n": 2
        },
        {
          "n": 3
        }
      ],
      "creates": [
        {
          "n": 1,
          "name": "@bitcoin",
          "covenant": {
            "type": "transfer",
            "expire_height": 108439,
            "data": "68656c6c6f20776f726c64"
          },
          "value": 666,
          "script_pubkey": "5120611454515f9fe8c656f80c51de229dc5d9cba9a05d00486b43a1e9033ef6393b"
        }
      ],
      "updates": []
    }
  ]
}

Get Transaction Meta

gettxmeta Retrieves all transactions relevant to spaces for the given block (requires -txindex to be enabled)

Params

Name	Type	Description
txid	string	The transaction id as a hex string

CLI

only available via JSON-RPC

cURL

curl -X POST http://127.0.0.1:7224 \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","method":"gettxmeta","params":["394ebef5203c4306c3f7a6d1a5c2058bac130deb24c1d7725094b31d1ff54ea4"],"id":1}'

Example Response

{
  "txid": "394ebef5203c4306c3f7a6d1a5c2058bac130deb24c1d7725094b31d1ff54ea4",
  "spends": [
    {
      "n": 0
    }
  ],
  "creates": [
    {
      "n": 0,
      "value": 662,
      "script_pubkey": "512065a7b5051fe33239e6ddb0d69e809a74d1702fde541bdf3431c6994b72317f33"
    }
  ],
  "updates": []
}