StackerDB

Endpoints for interacting with StackerDB instances.

Get StackerDB chunk (latest version)

get

http://localhost:20443https://api.mainnet.hiro.sohttps://api.testnet.hiro.so

/v2/stackerdb/{principal}/{contract_name}/{slot_id}

Get the latest version of a chunk of data from a StackerDB instance.

Path parameters

principalstring · min: 28 · max: 170Required

Stacks address (28-41 characters) or a Contract identifier in format {address}.{contract_name} (e.g. SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info). Contract names have a maximum length of 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-infoPattern: ^([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41})|([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127})$

contract_namestring · min: 1 · max: 128Required

Contract name. Must start with a letter and can contain letters, numbers, hyphens, and underscores. Maximum length is 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: get-infoPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$

slot_idintegerRequired

Slot ID

Responses

200

StackerDB chunk data

application/octet-stream

string · binaryOptional

404

Not found

text/plain

500

Internal Server Error

text/plain

get

/v2/stackerdb/{principal}/{contract_name}/{slot_id}

HTTPcURLJavaScriptPython

GET /v2/stackerdb/{principal}/{contract_name}/{slot_id} HTTP/1.1
Host: localhost:20443
Accept: */*

binary

Get StackerDB chunk (specific version)

get

http://localhost:20443https://api.mainnet.hiro.sohttps://api.testnet.hiro.so

/v2/stackerdb/{principal}/{contract_name}/{slot_id}/{slot_version}

Get a specific version of a chunk of data from a StackerDB instance.

Path parameters

principalstring · min: 28 · max: 170Required

Stacks address (28-41 characters) or a Contract identifier in format {address}.{contract_name} (e.g. SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info). Contract names have a maximum length of 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-infoPattern: ^([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41})|([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127})$

contract_namestring · min: 1 · max: 128Required

Contract name. Must start with a letter and can contain letters, numbers, hyphens, and underscores. Maximum length is 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: get-infoPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$

slot_idintegerRequired

Slot ID

slot_versionintegerRequired

Specific slot version

Responses

200

StackerDB chunk data

application/octet-stream

string · binaryOptional

400

Bad request

text/plain

404

Not found

text/plain

500

Internal Server Error

text/plain

get

/v2/stackerdb/{principal}/{contract_name}/{slot_id}/{slot_version}

HTTPcURLJavaScriptPython

GET /v2/stackerdb/{principal}/{contract_name}/{slot_id}/{slot_version} HTTP/1.1
Host: localhost:20443
Accept: */*

binary

Get StackerDB metadata

get

http://localhost:20443https://api.mainnet.hiro.sohttps://api.testnet.hiro.so

/v2/stackerdb/{principal}/{contract_name}

Get metadata about a StackerDB instance, including slot information.

Path parameters

principalstring · min: 28 · max: 170Required

Stacks address (28-41 characters) or a Contract identifier in format {address}.{contract_name} (e.g. SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info). Contract names have a maximum length of 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-infoPattern: ^([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41})|([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127})$

contract_namestring · min: 1 · max: 128Required

Contract name. Must start with a letter and can contain letters, numbers, hyphens, and underscores. Maximum length is 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: get-infoPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$

Responses

200

StackerDB metadata

application/json

slot_idintegerOptional

Slot identifier (unique for each DB instance)

slot_versionintegerOptional

Slot version (a lamport clock)

data_hashstringOptional

Data hash (hex, no 0x prefix)

signaturestringOptional

signature over the above (hex, no 0x prefix)

400

Bad request

text/plain

404

Not found

text/plain

500

Internal Server Error

text/plain

get

/v2/stackerdb/{principal}/{contract_name}

HTTPcURLJavaScriptPython

GET /v2/stackerdb/{principal}/{contract_name} HTTP/1.1
Host: localhost:20443
Accept: */*

[
  {
    "slot_id": 0,
    "slot_version": 1,
    "data_hash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "signature": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  }
]

Write StackerDB chunk

post

http://localhost:20443https://api.mainnet.hiro.sohttps://api.testnet.hiro.so

/v2/stackerdb/{principal}/{contract_name}/chunks

Write a chunk of data to a StackerDB instance.

The request body should contain a JSON object with the chunk data including slot_id, slot_version, signature, and hex-encoded data.

The response indicates whether the chunk was accepted, and if not, provides detailed error information. Note that failed writes return HTTP 200 with accepted: false, not HTTP error codes.

Path parameters

principalstring · min: 28 · max: 170Required

Stacks address (28-41 characters) or a Contract identifier in format {address}.{contract_name} (e.g. SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info). Contract names have a maximum length of 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-infoPattern: ^([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41})|([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127})$

contract_namestring · min: 1 · max: 128Required

Contract name. Must start with a letter and can contain letters, numbers, hyphens, and underscores. Maximum length is 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: get-infoPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$

Body

application/json

slot_idintegerRequired

Slot identifier

slot_versionintegerRequired

Slot version (lamport clock)

sigstringRequired

Hex-encoded signature from the stacker

Pattern: ^[0-9a-f]{130}$

datastringRequired

Hex-encoded chunk data

Pattern: ^[0-9a-f]*$

Responses

200

Chunk submission result (both success and failure cases)

application/json

acceptedbooleanRequired

Whether the chunk was accepted

reasonstring · nullableOptional

JSON-encoded reason for rejection (only present when accepted is false)

codeinteger · nullableOptional

Error code (only present when accepted is false)

400

Bad request

text/plain

404

Not found

text/plain

500

Internal Server Error

text/plain

post

/v2/stackerdb/{principal}/{contract_name}/chunks

HTTPcURLJavaScriptPython

POST /v2/stackerdb/{principal}/{contract_name}/chunks HTTP/1.1
Host: localhost:20443
Content-Type: application/json
Accept: */*
Content-Length: 195

{
  "slot_id": 1,
  "slot_version": 2,
  "sig": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef01",
  "data": "deadbeefcafebabe"
}

{
  "accepted": true,
  "reason": null,
  "metadata": {
    "slot_id": 1,
    "slot_version": 2,
    "data_hash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "signature": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef01"
  },
  "code": null
}

List StackerDB replicas

get

http://localhost:20443https://api.mainnet.hiro.sohttps://api.testnet.hiro.so

/v2/stackerdb/{principal}/{contract_name}/replicas

Get a list of replicas for a StackerDB instance.

Path parameters

principalstring · min: 28 · max: 170Required

Stacks address (28-41 characters) or a Contract identifier in format {address}.{contract_name} (e.g. SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info). Contract names have a maximum length of 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-infoPattern: ^([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41})|([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127})$

contract_namestring · min: 1 · max: 128Required

Contract name. Must start with a letter and can contain letters, numbers, hyphens, and underscores. Maximum length is 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: get-infoPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$

Responses

200

List of StackerDB replicas

application/json

ipstringOptional

portintegerOptional

public_key_hashstringOptional

20-byte public key hash

400

Bad request

text/plain

404

Not found

text/plain

500

Internal Server Error

text/plain

get

/v2/stackerdb/{principal}/{contract_name}/replicas

HTTPcURLJavaScriptPython

GET /v2/stackerdb/{principal}/{contract_name}/replicas HTTP/1.1
Host: localhost:20443
Accept: */*

[
  {
    "ip": "127.0.0.1",
    "port": 20444,
    "public_key_hash": "03abc123..."
  }
]