Getting Started

Welcome to this deployment of Blockstack Core v0.18.0.9. You can read the documentation and make RESTful calls to this node.

Consensus hashc798e2edd63639fcfa3438d50d9ae3b3
Last block seen546957
Last block processed546951

Blockstack Core is open-source software released under a GPLv3 license. The code for this API is available on Github and you can deploy your own nodes by following these instructions.

API Endpoint

Core Node Administration

Blockstack Core’s API module provides a set of API calls for interacting with the node’s configuration. However, most of this section is DEPRECATED in favor of moving configuration state to the Blockstack Browser. Client-side state is managed by blockstack.js.

Ping the node ¶

GET /v1/node/ping
Responses200
Headers
Content-Type: application/json
Body
{
  "status": "alive",
  "version": "0.18.0"
}
Schema
{
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "version": {
      "type": "string"
    }
  },
  "required": [
    "status",
    "version"
  ]
}

Ping the node
GET/v1/node/ping

Ping the Blockstack node to see if it’s alive.

  • Public Endpoint

 

Name Querying

This family of API endpoints deals with querying name information.

Get all names ¶

GET /v1/names?page=23
Responses200
Headers
Content-Type: application/json
Body
[ "aldenquimby.id", "aldeoryn.id",
     "alderete.id", "aldert.id",
     "aldi.id", "aldighieri.id", ... ]
Schema
{
     'type': 'array',
     'items': {
           'type': 'string',
           'pattern': r'^([a-z0-9\\-_.+]{3,37})$',
     }
  }

Get all names
GET/v1/names?page={page}

Fetch a list of all names known to the node.

  • Public Endpoint
URI Parameters
HideShow
page
number (required) Example: 23

names are returned in pages of size 100, so specify the page number.

 

Get all subdomains ¶

GET /v1/subdomains?page=3
Responses200
Headers
Content-Type: application/json
Body
[
      "collegeinfogeek.verified.podcast",
      "collider.verified.podcast",
      "combatandclassics.verified.podcast",
      "combatjack.verified.podcast",
      "comedybangbang.verified.podcast",
      "comedybutton.verified.podcast",
      "commonsense.verified.podcast",
      "concilio002.personal.id", ... ]
Schema
{
     'type': 'array',
     'items': {
           'type': 'string',
           'pattern': r'^([a-z0-9\\-_.+]{3,37})\.([a-z0-9\\-_.+]{3,37})$',
     }
  }

Get all subdomains
GET/v1/subdomains?page={page}

Fetch a list of all names known to the node.

  • Public Endpoint
URI Parameters
HideShow
page
number (required) Example: 3

names are returned in pages of size 100, so specify the page number.

 

Get name info ¶

GET /v1/names/muneeb.id
Responses200
Headers
Content-Type: application/json
Body
{
  "address": "1QJQxDas5JhdiXhEbNS14iNjr8auFT96GP",
  "blockchain": "bitcoin",
  "expire_block": 489247,
  "last_txid": "1edfa419f7b83f33e00830bc9409210da6c6d1db60f99eda10c835aa339cad6b",
  "status": "registered",
  "zonefile": "$ORIGIN muneeb.id\n$TTL 3600\n_http._tcp IN URI 10 1 \"https://blockstack.s3.amazonaws.com/muneeb.id\"\n",
  "zonefile_hash": "b100a68235244b012854a95f9114695679002af9"
}
Schema
{
     'type': 'object',
     'properties': {
       'address': {
           'type': 'string',
           'pattern': r"^([123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]+)$", 
       },
       'blockchain': {
           'type': 'string',
           'pattern': '^bitcoin$',
       },
       'expire_block': {
           'type': 'integer',
           'minimum': 0,
       },
       'last_txid': {
           'type': 'string',
           'pattern': '^[0-9a-fA-F]+$',
       },
       'status': {
           'type': 'string',
           'pattern': '^(registered|revoked)$',
       },
       'zonefile': {
           'anyOf': [
              {
                  'type': 'string',
              },
              {
                  'type': 'object',
                  'properties': {
                      'error': {
                          'type': 'string',
                      },
                  },
              },
           ],
       },
       'zonefile_hash': {
           'type': 'string',
           'pattern': '^[0-9a-fA-F]{20}$`,
       },
     },
     { 'required': 
       [
         'address', 'blockchain', 'last_txid',
         'status', 'zonefile', 'zonefile_hash'
       ]
     }
   }

Get name info
GET/v1/names/{name}

  • Public Endpoint

  • Subdomain Aware

URI Parameters
HideShow
name
string (required) Example: muneeb.id

fully-qualified name

 

Name history ¶

GET /v1/names/muneeb.id/history?page=0
Responses200
Headers
Content-Type: application/json
Body
{
  "373821": [
    {
      "address": "1QJQxDas5JhdiXhEbNS14iNjr8auFT96GP", 
      "block_number": 373821, 
      "consensus_hash": null, 
      "first_registered": 373821, 
      "importer": "76a9143e2b5fdd12db7580fb4d3434b31d4fe9124bd9f088ac", 
      "importer_address": "16firc3qZU97D1pWkyL6ZYwPX5UVnWc82V", 
      "last_creation_op": ";", 
      "last_renewed": 373821, 
      "name": "muneeb.id", 
      "name_hash128": "deb7fe99776122b77925cbf0a24ab6f8", 
      "namespace_block_number": 373601, 
      "namespace_id": "id", 
      "op": ";", 
      "op_fee": 100000.0, 
      "opcode": "NAME_IMPORT", 
      "preorder_block_number": 373821,
     }
   ]
 }
Schema
{
 'type': 'object',
 'patternProperties': {
   '^[0-9]+': {
     'type': 'array',
     'items': {
        'type': 'object',
        'properties': {
            'address': {
                'type': 'string',
                'pattern': r"^([123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]+)$", 
            },
            'base': {
                'type': 'integer',
                'minimum': 0,
                'maximum': 255,
            },
            'buckets': {
                'anyOf': [
                    {
                        'type': 'array',
                        'items': {
                            'type': 'integer',
                            'minItems': 16,
                            'maxItems': 16,
                        },
                    },
                    {
                        'type': 'null',
                    },
                ],
            },
            'block_number': {
                'type': 'integer',
                'minimum': 0,
            },
            'coeff': {
                'anyOf': [
                    {
                        'type': 'integer',
                        'minimum': 0,
                        'maximum': 255,
                    },
                    {
                        'type': 'null'
                    },
                ],
            },
            'consensus_hash': {
                'anyOf': [
                    {
                        'type': 'string',
                        'pattern': '^[0-9a-fA-F]{32}',
                    },
                    {
                        'type': 'null'
                    },
                ],
            },
            'fee': {
                'type': 'integer',
                'minimum': 0,
            },
            'first_registered': {
                'type': 'integer',
                'minimum': 0,
            },
            'history_snapshot': {
                'type': 'boolean',
            },
            'importer': {
                'anyOf': [
                    {
                        'type': 'string',
                        'pattern': r'^76[aA]914[0-9a-fA-F]{40}88[aA][cC]$',
                    },
                    {
                        'type': 'null',
                    },
                ],
            },
            'importer_address': {
                'anyOf': [
                    {
                        'type': 'string',
                        'pattern': r"^([123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]+)$", 
                    },
                    {
                        'type': 'null',
                    },
                ],
            },
            'last_renewed': {
                'type': 'integer',
                'minimum': 0,
            },
            'op': {
                'type': 'string',
                'pattern': '^([>?+~:!&*:;#]{1}|>>|>~|::)$',
            },
            'op_fee': {
                'type': 'number',
            },
            'opcode': {
                'type': 'string',
                'pattern': '^NAME_TRANSFER|NAME_PREORDER|NAME_UPDATE|NAME_REVOKE|NAME_REGISTRATION|NAMESPACE_READY|NAMESPACE_REVEAL|NAMESPACE_PREORDER|NAME_RENEWAL|NAME_IMPORT|ANNOUNCE$'
            },
            'revoked': {
                'type': 'boolean',
            },
            'sender': {
                'type': 'string',
                'pattern': '^([0-9a-fA-F]+)$',
            },
            'sender_pubkey': {
                'anyOf': [
                    {
                        'type': 'string',
                        'pattern': '^([0-9a-fA-F]+)$',
                    },
                    {
                        'type': 'null'
                    },
                ],
            },
            'recipient': {
                'anyOf': [
                    {
                        'type': 'string',
                        'pattern': '^([0-9a-fA-F]+)$',
                    },
                    {
                        'type': 'null'
                    },
                ],
            },
            'recipient_address': {
                'anyOf': [
                    {
                        'type': 'string',
                        'pattern': '^([123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]+)$',
                    },
                    {
                        'type': 'null'
                    },
                ],
            },
            'recipient_pubkey': {
                'anyOf': [
                    {
                        'type': 'string',
                        'pattern': '^([0-9a-fA-F]+)$',
                    },
                    {
                        'type': 'null'
                    },
                ],
            },
            'txid': {
                'type': 'string',
                'pattern': '^([0-9a-fA-F]+)$',
            },
            'value_hash': {
                'anyOf': [
                    {
                        'type': 'string',
                        'pattern': '^([0-9a-fA-F]{40})$',
                    },
                    {
                        'type': 'null',
                    },
                ],
            },
            'vtxindex': {
                'type': 'integer',
                'minimum': 0,
            },
        },
        'required': [
            'op',
            'opcode',
            'txid',
            'vtxindex'
        ],
      }
   }
  }
}

Name history
GET/v1/names/{name}/history?page={page}

Get a history of all blockchain records of a registered name.

  • Public Endpoint

  • Subdomain aware

URI Parameters
HideShow
name
string (required) Example: muneeb.id

name to query

page
integer (required) Example: 0

the page (in 20-entry pages) of the history to fetch

 

Get historical zone file ¶

GET /v1/names/muneeb.id/zonefile/b100a68235244b012854a95f9114695679002af9
Responses200
Headers
Content-Type: application/json
Body
{
  "zonefile": "$ORIGIN muneeb.id\n$TTL 3600\n_http._tcp IN URI 10 1 \"https://blockstack.s3.amazonaws.com/muneeb.id\"\n"
}
Schema
{
       'anyOf': [
          {
              'type': 'object',
              'properties': {
                  'zonefile': { 'type': 'string' },
              },
          },
          {
              'type': 'object',
              'properties': {
                  'error': { 'type': 'string' },
              },
          },
       ],
   }

Get historical zone file
GET/v1/names/{name}/zonefile/{zoneFileHash}

Fetches the historical zonefile specified by the username and zone hash.

  • Public Endpoint

  • Subdomain aware

URI Parameters
HideShow
name
string (required) Example: muneeb.id
zoneFileHash
string (required) Example: b100a68235244b012854a95f9114695679002af9

 

Get names owned by address ¶

GET /v1/addresses/bitcoin/1QJQxDas5JhdiXhEbNS14iNjr8auFT96GP
Responses200
Headers
Content-Type: application/json
Body
{
  "names": [
    "muneeb.id"
  ]
}
Schema
{
       'type': 'object',
       'properties': {
           'names': {
               'type': 'array',
               'items': {
                   'type': 'string',
                   'pattern': '^([a-z0-9\-_.+]{3,37})$',
               },
           },
       },
   }

Get names owned by address
GET/v1/addresses/{blockchain}/{address}

Retrieves a list of names owned by the address provided.

  • Subdomain Aware

  • Public Endpoint

URI Parameters
HideShow
blockchain
string (required) Example: bitcoin

the layer-1 blockchain for the address

address
string (required) Example: 1QJQxDas5JhdiXhEbNS14iNjr8auFT96GP

the address to lookup

 

Price Checks

Get namespace price ¶

GET /v1/prices/namespaces/id
Responses200
Headers
Content-Type: application/json
Body
{
  "satoshis": 4000000000
}
Schema
{
    'type': 'object',
    'properties': {
        'satoshis': {
            'type': 'integer',
            'minimum': 0,
        },
    },
}

Get namespace price
GET/v1/prices/namespaces/{tld}

This endpoint is used to get the price of a namespace. Anyone can create a namespace by following this tutorial.

  • Public Endpoint
URI Parameters
HideShow
tld
string (required) Example: id

namespace to query price for

 

Get name price ¶

GET /v1/prices/names/muneeb.id
Responses200
Headers
Content-Type: application/json
Body
{
  "name_price": {
    "satoshis": 100000,
    "btc": 0.001
  },
  "total_tx_fees": 519209,
  "register_tx_fee": {
    "satoshis": 159110,
    "btc": 0.0015911
  },
  "preorder_tx_fee": {
    "satoshis": 163703,
    "btc": 0.00163703
  },
  "warnings": [
    "Insufficient funds; fees are rough estimates."
  ],
  "total_estimated_cost": {
    "satoshis": 619209,
    "btc": 0.00619209
  },
  "update_tx_fee": {
    "satoshis": 196396,
    "btc": 0.00196396
  }
}
Schema
{
       'type': 'object',
       'properties': {
           'name_price': {
               'type': 'object',
               'properties': {
                   'btc': { 'type': 'number', 'minimum': 0 },
                   'satoshis': { 'type': 'integer', 'minimum': 0 }
               }
           },
           'preorder_tx_fee': {
               'type': 'object',
               'properties': {
                   'btc': { 'type': 'number', 'minimum': 0 },
                   'satoshis': { 'type': 'integer', 'minimum': 0 }
               }
           },
           'register_tx_fee': {
               'type': 'object',
               'properties': {
                   'btc': { 'type': 'number', 'minimum': 0 },
                   'satoshis': { 'type': 'integer', 'minimum': 0 }
               }
           },
           'update_tx_fee': {
               'type': 'object',
               'properties': {
                   'btc': { 'type': 'number', 'minimum': 0 },
                   'satoshis': { 'type': 'integer', 'minimum': 0 }
               }
           },
           'total_estimated_cost': {
               'type': 'object',
               'properties': {
                   'btc': { 'type': 'number', 'minimum': 0 },
                   'satoshis': { 'type': 'integer', 'minimum': 0 }
               }
           },
           'total_tx_fees': {
               'type': 'integer',
               'minimum': 0,
           }
           'name_price': {
               'type': 'object',
               'properties': {
                   'btc': { 'type': 'number', 'minimum': 0 },
                   'satoshis': { 'type': 'integer', 'minimum': 0 }
               }
           },
           'warnings': {
               'type': 'array',
               'items': {
                   'type': 'string',
               },
           },
       },
   }

Get name price
GET/v1/prices/names/{name}

This endpoint is used to get the price of a name. If you are using a public endpoint, you should only rely on the name_price field in the returned JSON blob. Other fields are DEPRECATED, since they are relevant only for estimating the cost of registering a name (which should be done via blockstack.js or the Blockstack Browser).

  • Public Endpoint
URI Parameters
HideShow
name
string (required) Example: muneeb.id

name to query price information for

 

Blockchain Operations

Get consensus hash ¶

GET /v1/blockchains/bitcoin/consensus
Responses200
Headers
Content-Type: application/json
Body
{
  "consensus_hash": "2fcbdf66c350894fe03b42c6a2e8a6ac"
}
Schema
{
    'type': 'object',
    'properties': {
        'consensus_hash': {
            'type': 'string',
            'pattern': '^[0-9a-fA-F]{32}$`,
        },
    },
}

Get consensus hash
GET/v1/blockchains/{blockchainName}/consensus

Get the current Blockstack consensus hash on a blockchain.

  • Public Endpoint
URI Parameters
HideShow
blockchainName
string (required) Example: bitcoin

the given blockchain

 

Get number of names on blockchain ¶

GET /v1/blockchains/bitcoin/name_count?all=true
Responses200401
Headers
Content-Type: application/json
Body
{
  "names_count": 73950
}
Schema
{
    'type': 'object',
    'properties': {
        'names_count': {
            'type': 'integer',
            'minimum': 0,
        },
    },
}
Headers
Content-Type: application/json
Body
{
  "error": "Unsupported blockchain"
}
Schema
{
    'type': 'object',
    'properties': {
        'error': { 'type': 'string' },
    },
},

Get number of names on blockchain
GET/v1/blockchains/{blockchainName}/name_count{?all}

Get the number of names on a blockchain.

  • Public Endpoint
URI Parameters
HideShow
blockchainName
string (required) Example: bitcoin

the given blockchain

all
string (optional) Example: true

include expired names

 

Get number of subdomains on blockchain ¶

GET /v1/blockchains/bitcoin/subdomains_count
Responses200401
Headers
Content-Type: application/json
Body
{
  "names_count": 1646
}
Schema
{
    'type': 'object',
    'properties': {
        'names_count': {
            'type': 'integer',
            'minimum': 0,
        },
    },
}
Headers
Content-Type: application/json
Body
{
  "error": "Unsupported blockchain"
}
Schema
{
    'type': 'object',
    'properties': {
        'error': { 'type': 'string' },
    },
},

Get number of subdomains on blockchain
GET/v1/blockchains/{blockchainName}/subdomains_count

Get the number of subdomains on a blockchain.

  • Public Endpoint
URI Parameters
HideShow
blockchainName
string (required) Example: bitcoin

the given blockchain

 

Get pending transactions ¶

GET /v1/blockchains/bitcoin/pending
Responses200
Headers
Content-Type: application/json
Body
{
  "queues": {}
}
Schema
{
    'type': 'object',
    'properties': {
        'preorder': {
            'type': 'array',
            'items': {
                'type': 'object',
                'properties': {
                    'name': { 'type': 'string', 'pattern': '^([a-z0-9\-_.+]{3,37})$' },
                    'tx_hash': { 'type': 'string', 'pattern': '^[0-9a-fA-F]+$' },
                    'confirmations': { 'type': 'integer', 'minimum': 0 },
                },
            },
        },
        'register': {
            'type': 'array',
            'items': {
                'type': 'object',
                'properties': {
                    'name': { 'type': 'string', 'pattern': '^([a-z0-9\-_.+]{3,37})$' },
                    'tx_hash': { 'type': 'string', 'pattern': '^[0-9a-fA-F]+$' },
                    'confirmations': { 'type': 'integer', 'minimum': 0 },
                },
            },
        },
        'update': {
            'type': 'array',
            'items': {
                'type': 'object',
                'properties': {
                    'name': { 'type': 'string', 'pattern': '^([a-z0-9\-_.+]{3,37})$' },
                    'tx_hash': { 'type': 'string', 'pattern': '^[0-9a-fA-F]+$' },
                    'confirmations': { 'type': 'integer', 'minimum': 0 },
                },
            },
        },
        'transfer': {
            'type': 'array',
            'items': {
                'type': 'object',
                'properties': {
                    'name': { 'type': 'string', 'pattern': '^([a-z0-9\-_.+]{3,37})$' },
                    'tx_hash': { 'type': 'string', 'pattern': '^[0-9a-fA-F]+$' },
                    'confirmations': { 'type': 'integer', 'minimum': 0 },
                },
            },
        },
        'renew': {
            'type': 'array',
            'items': {
                'type': 'object',
                'properties': {
                    'name': { 'type': 'string', 'pattern': '^([a-z0-9\-_.+]{3,37})$' },
                    'tx_hash': { 'type': 'string', 'pattern': '^[0-9a-fA-F]+$' },
                    'confirmations': { 'type': 'integer', 'minimum': 0 },
                },
            },
        },
        'revoke': {
            'type': 'array',
            'items': {
                'type': 'object',
                'properties': {
                    'name': { 'type': 'string', 'pattern': '^([a-z0-9\-_.+]{3,37})$' },
                    'tx_hash': { 'type': 'string', 'pattern': '^[0-9a-fA-F]+$' },
                    'confirmations': { 'type': 'integer', 'minimum': 0 },
                },
            },
        },
        'name_import': {
            'type': 'array',
            'items': {
                'type': 'object',
                'properties': {
                    'name': { 'type': 'string', 'pattern': '^([a-z0-9\-_.+]{3,37})$' },
                    'tx_hash': { 'type': 'string', 'pattern': '^[0-9a-fA-F]+$' },
                    'confirmations': { 'type': 'integer', 'minimum': 0 },
                },
            },
        },
    }
}

Get pending transactions
GET/v1/blockchains/{blockchainName}/pending

Get the current transactions that the node has issued and are still pending.

  • DEPRECATED. Blockstack clients should use blockstack.js to query the blockchain.

  • Public Endpoint

URI Parameters
HideShow
blockchainName
string (required) Example: bitcoin

the given blockchain

 

Namespace Operations

Get all namespaces ¶

GET /v1/namespaces
Responses200
Headers
Content-Type: application/json
Body
{
  "namespaces": [
    ".id"
  ]
}

Get all namespaces
GET/v1/namespaces

  • Public Endpoint

 

Get namespace names ¶

GET /v1/namespaces/id/names?page=23
Responses200
Headers
Content-Type: application/json
Body
[ "aldenquimby.id", "aldeoryn.id", 
     "alderete.id", "aldert.id", 
     "aldi.id", "aldighieri.id", ... ]

Get namespace names
GET/v1/namespaces/{tld}/names?page={page}

Fetch a list of names from the namespace.

  • Public Endpoint
URI Parameters
HideShow
tld
string (required) Example: id

the namespace to fetch names from

page
number (required) Example: 23

names are returned in pages of size 100, so specify the page number.

 

Resolver Endpoints

Lookup User ¶

GET /v1/users/fred
Responses200
Headers
Content-Type: application/json
Body
{
  "fred.id": {
    "owner_address": "1CER5u4QXuqffHjHKrU76iMCsqtJLM5VHu",
    "profile": {
      "@context": "http://schema.org",
      "@type": "Person",
      "account": [
        {
          "@type": "Account",
          "identifier": "fredwilson",
          "placeholder": false,
          "proofType": "http",
          "proofUrl": "https://twitter.com/fredwilson/status/943066895422455809",
          "service": "twitter"
        }
      ],
      "description": "I am a VC",
      "image": [
        {
          "@type": "ImageObject",
          "contentUrl": "https://gaia.blockstack.org/hub/1CER5u4QXuqffHjHKrU76iMCsqtJLM5VHu/0/avatar-0",
          "name": "avatar"
        }
      ],
      "name": "Fred Wilson"
    },
    "public_key": "026c94d1897fa148fa6401247a339b55abd869a3d562fdae8a7fcb9a11f1f846f3",
    "verifications": [
      {
        "identifier": "fredwilson",
        "proof_url": "https://twitter.com/fredwilson/status/943066895422455809",
        "service": "twitter",
        "valid": true
      }
    ],
    "zone_file": {
      "$origin": "fred.id",
      "$ttl": 3600,
      "uri": [
        {
          "name": "_http._tcp",
          "priority": 10,
          "target": "https://gaia.blockstack.org/hub/1CER5u4QXuqffHjHKrU76iMCsqtJLM5VHu/0/profile.json",
          "weight": 1
        }
      ]
    }
  }
}

Lookup User
GET/v1/users/{username}

Lookup and resolver a user’s profile. Defaults to the id namespace. Note that blockstack.js does not rely on this endpoint.

  • Public Only Endpoint

  • Subdomain Aware

  • Legacy Endpoint

URI Parameters
HideShow
username
string (required) Example: fred

username to lookup

 

GET /v1/search?query=wenger
Responses200
Headers
Content-Type: application/json
Body
{
     "results": [
       {
         "fullyQualifiedName": "albertwenger.id",
         "username": "albertwenger",
         "profile": {
           "@type": "Person", 
           "account": [
             {
               "@type": "Account", 
               "identifier": "albertwenger", 
               "proofType": "http", 
               "service": "twitter"
             }, 
             {
               "@type": "Account", 
               "identifier": "albertwenger", 
               "proofType": "http", 
               "service": "facebook"
             }, 
             {
               "@type": "Account", 
               "identifier": "albertwenger", 
               "proofType": "http", 
               "service": "github"
             }, 
             {
               "@type": "Account", 
               "identifier": "1QHDGGLEKK7FZWsBEL78acV9edGCTarqXt", 
               "role": "payment", 
               "service": "bitcoin"
             }
           ], 
           "address": {
             "@type": "PostalAddress", 
             "addressLocality": "New York"
           }, 
           "description": "VC at USV.com", 
           ...
   }

Profile Search
GET/v1/search?query={query}

Searches for a profile using a search string.

  • Public Only Endpoint
URI Parameters
HideShow
query
string (required) Example: wenger

the search query