> For the complete documentation index, see [llms.txt](https://docs.stacks.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stacks.co/reference/api/stacks-blockchain-api/stacker-db.md).
# Stacker DB
Endpoints for interacting with StackerDB instances.
## Get StackerDB chunk (latest version)
> Get the latest version of a chunk of data from a StackerDB instance.
```json
{"openapi":"3.1.0","info":{"title":"Stacks 3.0+ RPC API","version":"1.0.0"},"tags":[{"name":"StackerDB","description":"Endpoints for interacting with StackerDB instances."}],"servers":[{"url":"http://localhost:20443","description":"Local Stacks Node"},{"url":"https://api.mainnet.hiro.so","description":"Hiro Mainnet API"},{"url":"https://api.testnet.hiro.so","description":"Hiro Testnet API"}],"security":[],"paths":{"/v2/stackerdb/{principal}/{contract_name}/{slot_id}":{"get":{"summary":"Get StackerDB chunk (latest version)","tags":["StackerDB"],"operationId":"getStackerDbChunk","description":"Get the latest version of a chunk of data from a StackerDB instance.\n","parameters":[{"name":"principal","in":"path","required":true,"description":"Stacks address (28-41 characters) or a Contract identifier in format `{address}.{contract_name}`\n(e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`).\nContract names have a maximum length of 40 characters for new contracts. Legacy contracts may have names up to 128 characters.\n","schema":{"type":"string","pattern":"^([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41})|([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}\\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127})$","minLength":28,"maxLength":170}},{"name":"contract_name","in":"path","required":true,"description":"Contract name. Must start with a letter and can contain letters, numbers,\nhyphens, and underscores. Maximum length is 40 characters for new contracts.\nLegacy contracts may have names up to 128 characters.\n","schema":{"type":"string","pattern":"^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$","minLength":1,"maxLength":128}},{"name":"slot_id","in":"path","required":true,"description":"Slot ID","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"StackerDB chunk data","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Not found","content":{"text/plain":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"text/plain":{"schema":{"type":"string"}}}}}}}}}
```
## Get StackerDB chunk (specific version)
> Get a specific version of a chunk of data from a StackerDB instance.
```json
{"openapi":"3.1.0","info":{"title":"Stacks 3.0+ RPC API","version":"1.0.0"},"tags":[{"name":"StackerDB","description":"Endpoints for interacting with StackerDB instances."}],"servers":[{"url":"http://localhost:20443","description":"Local Stacks Node"},{"url":"https://api.mainnet.hiro.so","description":"Hiro Mainnet API"},{"url":"https://api.testnet.hiro.so","description":"Hiro Testnet API"}],"security":[],"paths":{"/v2/stackerdb/{principal}/{contract_name}/{slot_id}/{slot_version}":{"get":{"summary":"Get StackerDB chunk (specific version)","tags":["StackerDB"],"operationId":"getStackerDbChunkVersioned","description":"Get a specific version of a chunk of data from a StackerDB instance.\n","parameters":[{"name":"principal","in":"path","required":true,"description":"Stacks address (28-41 characters) or a Contract identifier in format `{address}.{contract_name}`\n(e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`).\nContract names have a maximum length of 40 characters for new contracts. Legacy contracts may have names up to 128 characters.\n","schema":{"type":"string","pattern":"^([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41})|([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}\\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127})$","minLength":28,"maxLength":170}},{"name":"contract_name","in":"path","required":true,"description":"Contract name. Must start with a letter and can contain letters, numbers,\nhyphens, and underscores. Maximum length is 40 characters for new contracts.\nLegacy contracts may have names up to 128 characters.\n","schema":{"type":"string","pattern":"^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$","minLength":1,"maxLength":128}},{"name":"slot_id","in":"path","required":true,"description":"Slot ID","schema":{"type":"integer","minimum":0}},{"name":"slot_version","in":"path","required":true,"description":"Specific slot version","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"StackerDB chunk data","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Bad request","content":{"text/plain":{"schema":{"type":"string"}}}},"404":{"description":"Not found","content":{"text/plain":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"text/plain":{"schema":{"type":"string"}}}}}}}}}
```
## Get StackerDB metadata
> Get metadata about a StackerDB instance, including slot information.
```json
{"openapi":"3.1.0","info":{"title":"Stacks 3.0+ RPC API","version":"1.0.0"},"tags":[{"name":"StackerDB","description":"Endpoints for interacting with StackerDB instances."}],"servers":[{"url":"http://localhost:20443","description":"Local Stacks Node"},{"url":"https://api.mainnet.hiro.so","description":"Hiro Mainnet API"},{"url":"https://api.testnet.hiro.so","description":"Hiro Testnet API"}],"security":[],"paths":{"/v2/stackerdb/{principal}/{contract_name}":{"get":{"summary":"Get StackerDB metadata","tags":["StackerDB"],"operationId":"getStackerDbMetadata","description":"Get metadata about a StackerDB instance, including slot information.\n","parameters":[{"name":"principal","in":"path","required":true,"description":"Stacks address (28-41 characters) or a Contract identifier in format `{address}.{contract_name}`\n(e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`).\nContract names have a maximum length of 40 characters for new contracts. Legacy contracts may have names up to 128 characters.\n","schema":{"type":"string","pattern":"^([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41})|([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}\\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127})$","minLength":28,"maxLength":170}},{"name":"contract_name","in":"path","required":true,"description":"Contract name. Must start with a letter and can contain letters, numbers,\nhyphens, and underscores. Maximum length is 40 characters for new contracts.\nLegacy contracts may have names up to 128 characters.\n","schema":{"type":"string","pattern":"^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$","minLength":1,"maxLength":128}}],"responses":{"200":{"description":"StackerDB metadata","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"slot_id":{"type":"integer","description":"Slot identifier (unique for each DB instance)"},"slot_version":{"type":"integer","description":"Slot version (a lamport clock)"},"data_hash":{"type":"string","description":"Data hash (hex, no 0x prefix)"},"signature":{"type":"string","description":"signature over the above (hex, no 0x prefix)"}}}}}}},"400":{"description":"Bad request","content":{"text/plain":{"schema":{"type":"string"}}}},"404":{"description":"Not found","content":{"text/plain":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"text/plain":{"schema":{"type":"string"}}}}}}}}}
```
## Write StackerDB chunk
> 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.
```json
{"openapi":"3.1.0","info":{"title":"Stacks 3.0+ RPC API","version":"1.0.0"},"tags":[{"name":"StackerDB","description":"Endpoints for interacting with StackerDB instances."}],"servers":[{"url":"http://localhost:20443","description":"Local Stacks Node"},{"url":"https://api.mainnet.hiro.so","description":"Hiro Mainnet API"},{"url":"https://api.testnet.hiro.so","description":"Hiro Testnet API"}],"security":[],"paths":{"/v2/stackerdb/{principal}/{contract_name}/chunks":{"post":{"summary":"Write StackerDB chunk","tags":["StackerDB"],"operationId":"postStackerDbChunk","description":"Write a chunk of data to a StackerDB instance.\n\nThe request body should contain a JSON object with the chunk data including\nslot_id, slot_version, signature, and hex-encoded data.\n\nThe response indicates whether the chunk was accepted, and if not, provides\ndetailed error information. Note that failed writes return HTTP 200 with\naccepted: false, not HTTP error codes.\n","parameters":[{"name":"principal","in":"path","required":true,"description":"Stacks address (28-41 characters) or a Contract identifier in format `{address}.{contract_name}`\n(e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`).\nContract names have a maximum length of 40 characters for new contracts. Legacy contracts may have names up to 128 characters.\n","schema":{"type":"string","pattern":"^([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41})|([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}\\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127})$","minLength":28,"maxLength":170}},{"name":"contract_name","in":"path","required":true,"description":"Contract name. Must start with a letter and can contain letters, numbers,\nhyphens, and underscores. Maximum length is 40 characters for new contracts.\nLegacy contracts may have names up to 128 characters.\n","schema":{"type":"string","pattern":"^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$","minLength":1,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slot_id","slot_version","sig","data"],"properties":{"slot_id":{"type":"integer","minimum":0,"description":"Slot identifier"},"slot_version":{"type":"integer","minimum":0,"description":"Slot version (lamport clock)"},"sig":{"type":"string","description":"Hex-encoded signature from the stacker","pattern":"^[0-9a-f]{130}$"},"data":{"type":"string","description":"Hex-encoded chunk data","pattern":"^[0-9a-f]*$"}}}}}},"responses":{"200":{"description":"Chunk submission result (both success and failure cases)","content":{"application/json":{"schema":{"type":"object","required":["accepted"],"properties":{"accepted":{"type":"boolean","description":"Whether the chunk was accepted"},"reason":{"type":["string","null"],"description":"JSON-encoded reason for rejection (only present when accepted is false)"},"metadata":{"type":["object","null"],"description":"Slot metadata (present on successful acceptance)","properties":{"slot_id":{"type":"integer","minimum":0,"description":"Slot identifier"},"slot_version":{"type":"integer","minimum":0,"description":"Slot version"},"data_hash":{"type":"string","description":"Hex-encoded SHA512/256 hash of the data","pattern":"^[0-9a-f]{64}$"},"signature":{"type":"string","description":"Hex-encoded signature","pattern":"^[0-9a-f]{130}$"}}},"code":{"type":["integer","null"],"description":"Error code (only present when accepted is false)"}}}}}},"400":{"description":"Bad request","content":{"text/plain":{"schema":{"type":"string"}}}},"404":{"description":"Not found","content":{"text/plain":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"text/plain":{"schema":{"type":"string"}}}}}}}}}
```
## List StackerDB replicas
> Get a list of replicas for a StackerDB instance.
```json
{"openapi":"3.1.0","info":{"title":"Stacks 3.0+ RPC API","version":"1.0.0"},"tags":[{"name":"StackerDB","description":"Endpoints for interacting with StackerDB instances."}],"servers":[{"url":"http://localhost:20443","description":"Local Stacks Node"},{"url":"https://api.mainnet.hiro.so","description":"Hiro Mainnet API"},{"url":"https://api.testnet.hiro.so","description":"Hiro Testnet API"}],"security":[],"paths":{"/v2/stackerdb/{principal}/{contract_name}/replicas":{"get":{"summary":"List StackerDB replicas","tags":["StackerDB"],"operationId":"listStackerDbReplicas","description":"Get a list of replicas for a StackerDB instance.\n","parameters":[{"name":"principal","in":"path","required":true,"description":"Stacks address (28-41 characters) or a Contract identifier in format `{address}.{contract_name}`\n(e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`).\nContract names have a maximum length of 40 characters for new contracts. Legacy contracts may have names up to 128 characters.\n","schema":{"type":"string","pattern":"^([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41})|([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}\\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127})$","minLength":28,"maxLength":170}},{"name":"contract_name","in":"path","required":true,"description":"Contract name. Must start with a letter and can contain letters, numbers,\nhyphens, and underscores. Maximum length is 40 characters for new contracts.\nLegacy contracts may have names up to 128 characters.\n","schema":{"type":"string","pattern":"^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$","minLength":1,"maxLength":128}}],"responses":{"200":{"description":"List of StackerDB replicas","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"ip":{"type":"string"},"port":{"type":"integer"},"public_key_hash":{"type":"string","description":"20-byte public key hash"}}}}}}},"400":{"description":"Bad request","content":{"text/plain":{"schema":{"type":"string"}}}},"404":{"description":"Not found","content":{"text/plain":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"text/plain":{"schema":{"type":"string"}}}}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.stacks.co/reference/api/stacks-blockchain-api/stacker-db.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.