openapi: 3.0.2 servers: - url: https://stacks-node-api.mainnet.stacks.co/ description: Mainnet - url: https://stacks-node-api.testnet.stacks.co/ description: Testnet - url: http://localhost:3999/ description: Local info: title: Stacks Blockchain API version: 'STACKS_API_VERSION' description: | Welcome to the API reference overview for the Stacks Blockchain API. Download Postman collection tags: - name: Accounts description: Read-only endpoints to obtain Stacks account details externalDocs: description: Stacks Documentation - Accounts url: https://docs.stacks.co/understand-stacks/accounts - name: Blocks description: Read-only endpoints to obtain Stacks block details - name: Faucets description: Endpoints to request STX or BTC tokens (not possible on Mainnet) - name: Fees description: Read-only endpoints to obtain fee details - name: Fungible Tokens description: Read-only endpoints to obtain fungible token details externalDocs: description: Stacks Documentation - Tokens url: https://docs.stacks.co/write-smart-contracts/tokens - name: Info description: Read-only endpoints to obtain network, Proof-of-Transfer, Stacking, STX token, and node information - name: Microblocks description: Read-only endpoints to obtain microblocks details externalDocs: description: Stacks Documentation - Microblocks url: https://docs.stacks.co/understand-stacks/microblocks - name: Names description: Read-only endpoints realted to the Blockchain Naming System on Stacks externalDocs: description: Stacks Documentation - Blockchain Naming System url: https://docs.stacks.co/build-apps/references/bns - name: Non-Fungible Tokens description: Read-only endpoints to obtain non-fungible token details externalDocs: description: Stacks Documentation - Tokens url: https://docs.stacks.co/write-smart-contracts/tokens - name: Rosetta description: Endpoints to support the Rosetta API open blockchain standard externalDocs: description: Hiro Documentation - Rosetta Support url: https://docs.hiro.so/get-started/stacks-blockchain-api#rosetta-support - name: Search description: Read-only endpoints to search for accounts, blocks, smart contracts, and transactions - name: Smart Contracts description: Read-only endpoints to obtain Clarity smart contract details externalDocs: description: Stacks Documentation - Clarity Smart Contracts url: https://docs.stacks.co/write-smart-contracts/overview - name: Stacking Rewards description: Read-only endpoints to obtain Stacking reward details externalDocs: description: Stacks Documentation - Stacking url: https://docs.stacks.co/understand-stacks/stacking - name: Transactions description: Endpoints to obtain transaction details and to broadcast transactions to the network externalDocs: description: Hiro Documentation - Transactions url: https://docs.hiro.so/get-started/transactions paths: /extended/v1/faucets/stx: parameters: - name: address in: query description: A valid testnet STX address required: true schema: type: string example: ST3M7N9Q9HDRM7RVP1Q26P0EE69358PZZAZD7KMXQ - name: stacking in: query description: Request the amount of STX tokens needed for individual address stacking required: false schema: type: boolean default: false post: summary: Get STX testnet tokens description: | Add 500 STX tokens to the specified testnet address. Testnet STX addresses begin with `ST`. If the `stacking` parameter is set to `true`, the faucet will add the required number of tokens for individual stacking to the specified testnet address. The endpoint returns the transaction ID, which you can use to view the transaction in the [Stacks Explorer](https://explorer.stacks.co/?chain=testnet). The tokens are delivered once the transaction has been included in an anchor block. A common reason for failed faucet transactions is that the faucet has run out of tokens. If you are experiencing failed faucet transactions to a testnet address, you can get help in [Discord](https://stacks.chat). **Note:** This is a testnet only endpoint. This endpoint will not work on the mainnet. tags: - Faucets operationId: run_faucet_stx requestBody: content: application/json: schema: type: object properties: address: description: STX testnet address type: string stacking: description: Use required number of tokens for stacking type: boolean example: address: ST3M7N9Q9HDRM7RVP1Q26P0EE69358PZZAZD7KMXQ stacking: false responses: 200: description: Success content: application/json: schema: $ref: ./api/faucet/run-faucet.schema.json example: $ref: ./api/faucet/run-faucet.example.json 500: description: Faucet call failed /extended/v1/faucets/btc: parameters: - name: address in: query description: A valid testnet BTC address required: true schema: type: string example: 2N4M94S1ZPt8HfxydXzL2P7qyzgVq7MHWts post: summary: Add testnet BTC tokens to address description: | Add 1 BTC token to the specified testnet BTC address. The endpoint returns the transaction ID, which you can use to view the transaction in a testnet Bitcoin block explorer. The tokens are delivered once the transaction has been included in a block. **Note:** This is a testnet only endpoint. This endpoint will not work on the mainnet. tags: - Faucets operationId: run_faucet_btc requestBody: content: application/json: schema: type: object properties: address: description: BTC testnet address type: string example: address: 2N4M94S1ZPt8HfxydXzL2P7qyzgVq7MHWts responses: 200: description: Success content: application/json: schema: $ref: ./api/faucet/run-faucet.schema.json example: $ref: ./api/faucet/run-faucet.example.json 500: description: Faucet call failed /extended/v1/tx: get: summary: Get recent transactions tags: - Transactions operationId: get_transaction_list description: | Retrieves all recently mined transactions If using TypeScript, import typings for this response from our types package: `import type { TransactionResults } from '@stacks/stacks-blockchain-api-types';` parameters: - name: limit in: query description: max number of transactions to fetch required: false schema: type: integer default: 96 maximum: 200 - name: offset in: query description: index of first transaction to fetch required: false schema: type: integer - name: type in: query description: Filter by transaction type required: false schema: type: array items: type: string enum: [coinbase, token_transfer, smart_contract, contract_call, poison_microblock] - name: unanchored in: query description: Include transaction data from unanchored (i.e. unconfirmed) microblocks required: false schema: type: boolean default: false responses: 200: description: List of transactions content: application/json: schema: $ref: ./api/transaction/get-transactions.schema.json example: $ref: ./api/transaction/get-transactions.example.json /extended/v1/tx/mempool: get: summary: Get mempool transactions tags: - Transactions operationId: get_mempool_transaction_list description: Retrieves all transactions that have been recently broadcast to the mempool. These are pending transactions awaiting confirmation. parameters: - name: sender_address in: query description: Filter to only return transactions with this sender address. required: false schema: type: string - name: recipient_address in: query description: Filter to only return transactions with this recipient address (only applicable for STX transfer tx types). required: false schema: type: string - name: address in: query description: Filter to only return transactions with this address as the sender or recipient (recipient only applicable for STX transfer tx types). required: false schema: type: string - name: limit in: query description: max number of mempool transactions to fetch required: false schema: type: integer default: 96 maximum: 200 - name: offset in: query description: index of first mempool transaction to fetch required: false schema: type: integer - name: unanchored in: query description: Include transaction data from unanchored (i.e. unconfirmed) microblocks required: false schema: type: boolean default: false responses: 200: description: List of mempool transactions content: application/json: schema: $ref: ./api/transaction/get-mempool-transactions.schema.json example: $ref: ./api/transaction/get-mempool-transactions.example.json /extended/v1/tx/mempool/dropped: get: summary: Get dropped mempool transactions tags: - Transactions operationId: get_dropped_mempool_transaction_list description: | Retrieves all recently-broadcast transactions that have been dropped from the mempool. Transactions are dropped from the mempool if: * they were stale and awaiting garbage collection or, * were expensive, or * were replaced with a new fee parameters: - name: limit in: query description: max number of mempool transactions to fetch required: false schema: type: integer default: 96 maximum: 200 - name: offset in: query description: index of first mempool transaction to fetch required: false schema: type: integer responses: 200: description: List of dropped mempool transactions content: application/json: schema: $ref: ./api/transaction/get-mempool-transactions.schema.json example: $ref: ./api/transaction/get-mempool-transactions.example.json /extended/v1/tx/multiple: parameters: - name: tx_id in: query description: Array of transaction ids required: true schema: type: array items: type: string - name: event_offset in: query schema: type: integer default: 0 description: The number of events to skip - name: event_limit in: query schema: type: integer default: 96 description: The numbers of events to return - name: unanchored in: query description: Include transaction data from unanchored (i.e. unconfirmed) microblocks required: false schema: type: boolean default: false get: summary: Get list of details for transactions tags: - Transactions operationId: get_tx_list_details description: | Retrieves a list of transactions for a given list of transaction IDs If using TypeScript, import typings for this response from our types package: `import type { Transaction } from '@stacks/stacks-blockchain-api-types';` responses: 200: description: Returns list of transactions with their details for corresponding requested tx_ids. content: application/json: schema: $ref: ./entities/transactions/transaction-list.schema.json example: $ref: ./entities/transactions/transactions-list-detail.example.json 404: description: Could not find any transaction by ID /extended/v1/tx/{tx_id}: parameters: - name: tx_id in: path description: Hash of transaction required: true schema: type: string - name: event_offset in: query schema: type: integer default: 0 description: The number of events to skip - name: event_limit in: query schema: type: integer default: 96 description: The numbers of events to return - name: unanchored in: query description: Include transaction data from unanchored (i.e. unconfirmed) microblocks required: false schema: type: boolean default: false get: summary: Get transaction tags: - Transactions operationId: get_transaction_by_id description: | Retrieves transaction details for a given transaction ID `import type { Transaction } from '@stacks/stacks-blockchain-api-types';` responses: 200: description: Transaction content: application/json: schema: $ref: ./entities/transactions/transaction.schema.json example: $ref: ./entities/transactions/transaction-4-coinbase.example.json 404: description: Cannot find transaction for given ID /extended/v1/tx/{tx_id}/raw: parameters: - name: tx_id in: path description: Hash of transaction required: true schema: type: string get: summary: Get Raw Transaction tags: - Transactions operationId: get_raw_transaction_by_id description: | Retrieves a hex encoded serialized transaction for a given ID responses: 200: description: Hex encoded serialized transaction content: application/json: schema: $ref: ./api/transaction/get-raw-transaction.schema.json example: $ref: ./api/transaction/get-raw-transaction.example.json 404: description: Cannot find transaction for given ID /v2/transactions: post: summary: Broadcast raw transaction tags: - Transactions description: Broadcasts raw transactions on the network. You can use the [@stacks/transactions](https://github.com/blockstack/stacks.js) project to generate a raw transaction payload. operationId: post_core_node_transactions requestBody: content: application/octet-stream: schema: type: string format: binary example: binary format of 00000000010400bed38c2aadffa348931bcb542880ff79d607afec000000000000000000000000000000c800012b0b1fff6cccd0974966dcd665835838f0985be508e1322e09fb3d751eca132c492bda720f9ef1768d14fdabed6127560ba52d5e3ac470dcb60b784e97dc88c9030200000000000516df0ba3e79792be7be5e50a370289accfc8c9e032000000000000303974657374206d656d6f00000000000000000000000000000000000000000000000000 responses: 200: description: Transaction id of successful post of a raw tx to the node's mempool content: text/plain: schema: type: string example: '"e161978626f216b2141b156ade10501207ae535fa365a13ef5d7a7c9310a09f2"' 400: description: Rejections result in a 400 error content: application/json: schema: $ref: ./api/transaction/post-core-node-transactions-error.schema.json example: $ref: ./api/transaction/post-core-node-transactions-error.example.json /extended/v1/microblock: get: summary: Get recent microblocks tags: - Microblocks operationId: get_microblock_list description: Retrieves a list of microblocks. parameters: - name: limit in: query description: Max number of microblocks to fetch required: false schema: type: integer default: 20 maximum: 200 - name: offset in: query description: Index of the first microblock to fetch required: false schema: type: integer responses: 200: description: List of microblocks content: application/json: schema: $ref: ./api/microblocks/get-microblocks.schema.json /extended/v1/microblock/{hash}: parameters: - name: hash in: path description: Hash of the microblock required: true schema: type: string get: summary: Get microblock description: Retrieves a specific microblock by `hash` tags: - Microblocks operationId: get_microblock_by_hash responses: 200: description: Microblock content: application/json: schema: $ref: ./entities/microblocks/microblock.schema.json 404: description: Cannot find microblock with given hash content: application/json: example: $ref: ./api/errors/microblock-not-found.example.json /extended/v1/microblock/unanchored/txs: get: summary: Get the list of current transactions that belong to unanchored microblocks description: Retrieves transactions that have been streamed in microblocks but not yet accepted or rejected in an anchor block tags: - Microblocks operationId: get_unanchored_txs responses: 200: description: Transactions content: application/json: schema: $ref: ./api/microblocks/get-unanchored-txs.schema.json /extended/v1/block: get: summary: Get recent blocks description: Retrieves a list of recently mined blocks tags: - Blocks operationId: get_block_list parameters: - name: limit in: query description: max number of blocks to fetch required: false schema: type: integer default: 20 maximum: 200 - name: offset in: query description: index of first block to fetch required: false schema: type: integer responses: 200: description: List of blocks content: application/json: schema: $ref: ./api/blocks/get-blocks.schema.json example: $ref: ./api/blocks/get-blocks.example.json /extended/v1/block/{hash}: parameters: - name: hash in: path description: Hash of the block required: true schema: type: string get: summary: Get block by hash description: Retrieves block details of a specific block for a given chain height tags: - Blocks operationId: get_block_by_hash responses: 200: description: Block content: application/json: schema: $ref: ./entities/blocks/block.schema.json example: $ref: ./entities/blocks/block.example.json 404: description: Cannot find block with given ID content: application/json: example: $ref: ./api/errors/block-not-found.example.json /extended/v1/block/by_height/{height}: parameters: - name: height in: path description: Height of the block required: true schema: type: number get: summary: Get block by height description: Retrieves block details of a specific block at a given block height tags: - Blocks operationId: get_block_by_height responses: 200: description: Block content: application/json: schema: $ref: ./entities/blocks/block.schema.json example: $ref: ./entities/blocks/block.example.json 404: description: Cannot find block with given height content: application/json: example: $ref: ./api/errors/block-not-found.example.json /extended/v1/block/by_burn_block_hash/{burn_block_hash}: parameters: - name: burn_block_hash in: path description: Hash of the burnchain block required: true schema: type: string get: summary: Get block by burnchain block hash description: Retrieves block details of a specific block for a given burnchain block hash tags: - Blocks operationId: get_block_by_burn_block_hash responses: 200: description: Block content: application/json: schema: $ref: ./entities/blocks/block.schema.json example: $ref: ./entities/blocks/block.example.json 404: description: Cannot find block with given height content: application/json: example: $ref: ./api/errors/block-not-found.example.json /extended/v1/block/by_burn_block_height/{burn_block_height}: parameters: - name: burn_block_height in: path description: Height of the burn chain block required: true schema: type: number get: summary: Get block by burnchain height description: Retrieves block details of a specific block for a given burn chain height tags: - Blocks operationId: get_block_by_burn_block_height responses: 200: description: Block content: application/json: schema: $ref: ./entities/blocks/block.schema.json example: $ref: ./entities/blocks/block.example.json 404: description: Cannot find block with given height content: application/json: example: $ref: ./api/errors/block-not-found.example.json /extended/v1/burnchain/reward_slot_holders: get: summary: Get recent reward slot holders description: Retrieves a list of the Bitcoin addresses that would validly receive Proof-of-Transfer commitments. tags: - Stacking Rewards operationId: get_burnchain_reward_slot_holders parameters: - name: limit in: query description: max number of items to fetch required: false schema: type: integer default: 96 maximum: 250 - name: offset in: query description: index of the first items to fetch required: false schema: type: integer responses: 200: description: List of burnchain reward recipients and amounts content: application/json: schema: $ref: ./api/burnchain/get-reward-slot-holders.schema.json example: $ref: ./api/burnchain/get-reward-slot-holders.example.json /extended/v1/burnchain/reward_slot_holders/{address}: get: summary: Get recent reward slot holder entries for the given address description: Retrieves a list of the Bitcoin addresses that would validly receive Proof-of-Transfer commitments for a given reward slot holder recipient address. tags: - Stacking Rewards operationId: get_burnchain_reward_slot_holders_by_address parameters: - name: address in: path description: Reward slot holder recipient address. Should either be in the native burnchain's format (e.g. B58 for Bitcoin), or if a STX principal address is provided it will be encoded as into the equivalent burnchain format required: true schema: type: string - name: limit in: query description: max number of items to fetch required: false schema: type: integer - name: offset in: query description: index of the first items to fetch required: false schema: type: integer responses: 200: description: List of burnchain reward recipients and amounts content: application/json: schema: $ref: ./api/burnchain/get-reward-slot-holders.schema.json example: $ref: ./api/burnchain/get-reward-slot-holders.example.json /extended/v1/burnchain/rewards: get: summary: Get recent burnchain reward recipients description: Retrieves a list of recent burnchain (e.g. Bitcoin) reward recipients with the associated amounts and block info tags: - Stacking Rewards operationId: get_burnchain_reward_list parameters: - name: limit in: query description: max number of rewards to fetch required: false schema: type: integer default: 96 maximum: 250 - name: offset in: query description: index of first rewards to fetch required: false schema: type: integer responses: 200: description: List of burnchain reward recipients and amounts content: application/json: schema: $ref: ./api/burnchain/get-rewards.schema.json example: $ref: ./api/burnchain/get-rewards.example.json /extended/v1/burnchain/rewards/{address}: get: summary: Get recent burnchain reward for the given recipient description: Retrieves a list of recent burnchain (e.g. Bitcoin) rewards for the given recipient with the associated amounts and block info tags: - Stacking Rewards operationId: get_burnchain_reward_list_by_address parameters: - name: address in: path description: Reward recipient address. Should either be in the native burnchain's format (e.g. B58 for Bitcoin), or if a STX principal address is provided it will be encoded as into the equivalent burnchain format required: true schema: type: string - name: limit in: query description: max number of rewards to fetch required: false schema: type: integer - name: offset in: query description: index of first rewards to fetch required: false schema: type: integer responses: 200: description: List of burnchain reward recipients and amounts content: application/json: schema: $ref: ./api/burnchain/get-rewards.schema.json example: $ref: ./api/burnchain/get-rewards.example.json /extended/v1/burnchain/rewards/{address}/total: get: summary: Get total burnchain rewards for the given recipient description: Retrieves the total burnchain (e.g. Bitcoin) rewards for a given recipient `address` tags: - Stacking Rewards operationId: get_burnchain_rewards_total_by_address parameters: - name: address in: path description: Reward recipient address. Should either be in the native burnchain's format (e.g. B58 for Bitcoin), or if a STX principal address is provided it will be encoded as into the equivalent burnchain format required: true schema: type: string responses: 200: description: List of burnchain reward recipients and amounts content: application/json: schema: $ref: ./entities/burnchain/rewards-total.schema.json example: $ref: ./entities/burnchain/rewards-total.example.json /extended/v1/contract/{contract_id}: get: summary: Get contract info description: Retrieves details of a contract with a given `contract_id` tags: - Smart Contracts operationId: get_contract_by_id responses: 200: description: Contract found content: application/json: schema: $ref: ./entities/transactions/transaction-1-smart-contract.schema.json example: $ref: ./entities/transactions/transaction-1-smart-contract.example.json 404: description: Cannot find contract of given ID parameters: - name: contract_id in: path description: Contract identifier formatted as `.` required: true schema: type: string - name: unanchored in: query description: Include transaction data from unanchored (i.e. unconfirmed) microblocks required: false schema: type: boolean default: false /extended/v1/contract/by_trait: get: summary: Get contracts by trait description: Retrieves a list of contracts based on the following traits listed in JSON format - functions, variables, maps, fungible tokens and non-fungible tokens tags: - Smart Contracts operationId: get_contracts_by_trait responses: 200: description: List of contracts implement given trait content: application/json: schema: $ref: ./api/contract/smart-contract-list-response.schema.json example: $ref: ./api/contract/smart-contract-list-response.example.json parameters: - name: trait_abi in: query description: JSON abi of the trait. required: true schema: type: string - name: limit in: query description: max number of contracts fetch required: false schema: type: integer - name: offset in: query description: index of first contract event to fetch required: false schema: type: integer /extended/v1/contract/{contract_id}/events: get: summary: Get contract events description: Retrieves a list of events that have been triggered by a given `contract_id` tags: - Smart Contracts operationId: get_contract_events_by_id parameters: - name: contract_id in: path description: Contract identifier formatted as `.` required: true schema: type: string - name: limit in: query description: max number of contract events to fetch required: false schema: type: integer - name: offset in: query description: index of first contract event to fetch required: false schema: type: integer - name: unanchored in: query description: Include transaction data from unanchored (i.e. unconfirmed) microblocks required: false schema: type: boolean default: false responses: 200: description: List of events content: application/json: schema: $ref: ./entities/transaction-events/transaction-event.schema.json example: $ref: ./entities/transaction-events/transaction-event-smart-contract-log.example.json /v2/contracts/interface/{contract_address}/{contract_name}: get: summary: Get contract interface description: Retrieves a contract interface with a given `contract_address` and `contract name` tags: - Smart Contracts operationId: get_contract_interface responses: 200: description: Contract interface content: application/json: schema: $ref: ./api/core-node/get-contract-interface.schema.json example: $ref: ./api/core-node/get-contract-interface.example.json parameters: - name: contract_address in: path required: true description: Stacks address schema: type: string - name: contract_name in: path required: true description: Contract name schema: type: string - name: tip in: query schema: type: string description: The Stacks chain tip to query from /v2/map_entry/{contract_address}/{contract_name}/{map_name}: post: summary: Get specific data-map inside a contract tags: - Smart Contracts operationId: get_contract_data_map_entry description: | Attempt to fetch data from a contract data map. The contract is identified with Stacks Address `contract_address` and Contract Name `contract_address` in the URL path. The map is identified with [Map Name]. The key to lookup in the map is supplied via the POST body. This should be supplied as the hex string serialization of the key (which should be a Clarity value). Note, this is a JSON string atom. In the response, `data` is the hex serialization of the map response. Note that map responses are Clarity option types, for non-existent values, this is a serialized none, and for all other responses, it is a serialized (some ...) object. responses: 200: description: Success content: application/json: schema: $ref: ./api/core-node/get-contract-data-map-entry.schema.json example: $ref: ./api/core-node/get-contract-data-map-entry.example.json 400: description: Failed loading data map parameters: - name: contract_address in: path required: true description: Stacks address schema: type: string - name: contract_name in: path required: true description: Contract name schema: type: string - name: map_name in: path required: true description: Map name schema: type: string - name: proof in: query description: Returns object without the proof field when set to 0 schema: type: integer - name: tip in: query schema: type: string description: The Stacks chain tip to query from x-codegen-request-body-name: key requestBody: description: Hex string serialization of the lookup key (which should be a Clarity value) required: true content: application/json: schema: type: string /v2/contracts/source/{contract_address}/{contract_name}: get: summary: Get contract source tags: - Smart Contracts operationId: get_contract_source description: Retrieves the Clarity source code of a given contract, along with the block height it was published in, and the MARF proof for the data responses: 200: description: Success content: application/json: schema: $ref: ./api/core-node/get-contract-source.schema.json example: $ref: ./api/core-node/get-contract-source.example.json parameters: - name: contract_address in: path required: true description: Stacks address schema: type: string - name: contract_name in: path required: true description: Contract name schema: type: string - name: proof in: query description: Returns object without the proof field if set to 0 schema: type: integer - name: tip in: query schema: type: string description: The Stacks chain tip to query from required: false /v2/contracts/call-read/{contract_address}/{contract_name}/{function_name}: post: summary: Call read-only function tags: - Smart Contracts operationId: call_read_only_function description: | Call a read-only public function on a given smart contract. The smart contract and function are specified using the URL path. The arguments and the simulated tx-sender are supplied via the POST body in the following JSON format: responses: 200: description: Success content: application/json: schema: $ref: ./api/contract/post-call-read-only-fn.schema.json examples: success: $ref: ./api/contract/post-call-read-only-fn-success.example.json fail: $ref: ./api/contract/post-call-read-only-fn-fail.example.json parameters: - name: contract_address in: path required: true description: Stacks address schema: type: string - name: contract_name in: path required: true description: Contract name schema: type: string - name: function_name in: path required: true description: Function name schema: type: string - name: tip in: query schema: type: string description: The Stacks chain tip to query from required: false requestBody: description: map of arguments and the simulated tx-sender where sender is either a Contract identifier or a normal Stacks address, and arguments is an array of hex serialized Clarity values. required: true content: application/json: schema: $ref: './entities/contracts/read-only-function-args.schema.json' example: sender: 'SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info' arguments: - '0x0011...' - '0x00231...' /extended/v1/address/{principal}/balances: get: summary: Get account balances description: Retrieves total account balance information for a given Address or Contract Identifier. This includes the balances of STX Tokens, Fungible Tokens and Non-Fungible Tokens for the account. tags: - Accounts operationId: get_account_balance parameters: - name: principal in: path description: Stacks address or a Contract identifier (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`) required: true schema: type: string - name: unanchored in: query description: Include transaction data from unanchored (i.e. unconfirmed) microblocks required: false schema: type: boolean default: false - name: until_block in: query description: returned data representing the state up until that point in time, rather than the current block. required: false schema: type: string responses: 200: description: Success content: application/json: schema: $ref: ./api/address/get-address-balances.schema.json example: $ref: ./api/address/get-address-balances.example.json /extended/v1/address/{principal}/stx: get: summary: Get account STX balance description: Retrieves STX token balance for a given Address or Contract Identifier. tags: - Accounts operationId: get_account_stx_balance parameters: - name: principal in: path description: Stacks address or a Contract identifier (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`) required: true schema: type: string - name: unanchored in: query description: Include transaction data from unanchored (i.e. unconfirmed) microblocks required: false schema: type: boolean default: false - name: until_block in: query description: returned data representing the state up until that point in time, rather than the current block. required: false schema: type: string responses: 200: description: Success content: application/json: schema: $ref: ./api/address/get-address-stx-balance.schema.json example: $ref: ./api/address/get-address-stx-balance.example.json /extended/v1/address/{principal}/transactions: get: summary: Get account transactions description: Retrieves a list of all Transactions for a given Address or Contract Identifier. More information on Transaction types can be found [here](https://docs.stacks.co/understand-stacks/transactions#types). tags: - Accounts operationId: get_account_transactions parameters: - name: principal in: path description: Stacks address or a Contract identifier (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`) required: true schema: type: string - name: limit in: query description: max number of account transactions to fetch required: false schema: type: integer - name: offset in: query description: index of first account transaction to fetch required: false schema: type: integer - name: height in: query description: Filter for transactions only at this given block height required: false schema: type: number - name: unanchored in: query description: Include transaction data from unanchored (i.e. unconfirmed) microblocks required: false schema: type: boolean default: false - name: until_block in: query description: returned data representing the state up until that point in time, rather than the current block. required: false schema: type: string responses: 200: description: Success content: application/json: schema: $ref: ./api/address/get-address-transactions.schema.json example: $ref: ./api/address/get-address-transactions.example.json /extended/v1/address/{principal}/{tx_id}/with_transfers: get: summary: Get account transaction information for specific transaction description: Retrieves transaction details for a given Transcation Id `tx_id`, for a given account or contract Identifier. tags: - Accounts operationId: get_single_transaction_with_transfers parameters: - name: principal in: path description: Stacks address or a contract identifier required: true schema: type: string - name: tx_id in: path description: Transaction id required: true schema: type: string responses: 200: description: Success content: application/json: schema: $ref: ./entities/address/transaction-with-transfers.schema.json example: $ref: ./api/address/get-address-single-transaction-with-transfers.example.json 404: description: Not found content: application/json: example: $ref: ./api/errors/transaction-not-found.example.json /extended/v1/address/{principal}/transactions_with_transfers: get: summary: Get account transactions including STX transfers for each transaction. description: Retrieve all transactions for an account or contract identifier including STX transfers for each transaction. tags: - Accounts operationId: get_account_transactions_with_transfers parameters: - name: principal in: path description: Stacks address or a Contract identifier (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`) required: true schema: type: string - name: limit in: query description: max number of account transactions to fetch required: false schema: type: integer - name: offset in: query description: index of first account transaction to fetch required: false schema: type: integer - name: height in: query description: Filter for transactions only at this given block height required: false schema: type: number - name: unanchored in: query description: Include transaction data from unanchored (i.e. unconfirmed) microblocks required: false schema: type: boolean default: false - name: until_block in: query description: returned data representing the state up until that point in time, rather than the current block. required: false schema: type: string responses: 200: description: Success content: application/json: schema: $ref: ./api/address/get-address-transactions-with-transfers.schema.json example: $ref: ./api/address/get-address-transactions-with-transfers.example.json /extended/v1/address/{principal}/nonces: get: summary: Get the latest nonce used by an account description: Retrieves the latest nonce values used by an account by inspecting the mempool, microblock transactions, and anchored transactions. tags: - Accounts operationId: get_account_nonces parameters: - name: principal in: path description: Stacks address (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0`) required: true schema: type: string responses: 200: description: Success content: application/json: schema: $ref: ./entities/address/address-nonces.schema.json example: $ref: ./entities/address/address-nonces.example.json /extended/v1/address/{principal}/assets: get: summary: Get account assets description: Retrieves a list of all assets events associated with an account or a Contract Identifier. This includes Transfers, Mints. tags: - Accounts operationId: get_account_assets parameters: - name: principal in: path description: Stacks address or a Contract identifier (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`) required: true schema: type: string - name: limit in: query description: max number of account assets to fetch required: false schema: type: integer - name: offset in: query description: index of first account assets to fetch required: false schema: type: integer - name: unanchored in: query description: Include transaction data from unanchored (i.e. unconfirmed) microblocks required: false schema: type: boolean default: false - name: until_block in: query description: returned data representing the state at that point in time, rather than the current block. required: false schema: type: string responses: 200: description: Success content: application/json: schema: $ref: ./api/address/get-address-assets.schema.json example: $ref: ./api/address/get-address-assets.example.json /extended/v1/address/{principal}/stx_inbound: get: summary: Get inbound STX transfers description: | Retrieves a list of STX transfers with memos to the given principal. This includes regular transfers from a stx-transfer transaction type, and transfers from contract-call transactions a the `send-many-memo` bulk sending contract. tags: - Accounts operationId: get_account_inbound parameters: - name: principal in: path description: Stacks address or a Contract identifier (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`) required: true schema: type: string - name: limit in: query description: number of items to return required: false schema: type: integer - name: offset in: query description: number of items to skip required: false schema: type: integer - name: height in: query description: Filter for transfers only at this given block height required: false schema: type: number - name: unanchored in: query description: Include transaction data from unanchored (i.e. unconfirmed) microblocks required: false schema: type: boolean default: false - name: until_block in: query description: returned data representing the state up until that point in time, rather than the current block. required: false schema: type: string responses: 200: description: Success content: application/json: schema: $ref: ./api/address/get-address-stx-inbound.schema.json example: $ref: ./api/address/get-address-stx-inbound.example.json /extended/v1/address/{principal}/nft_events: get: summary: Get nft events description: | Retrieves a list of all nfts owned by an address, contains the clarity value of the identifier of the nft tags: - Accounts operationId: get_account_nft parameters: - name: principal in: path description: Stacks address or a Contract identifier (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`) required: true schema: type: string - name: limit in: query description: number of items to return required: false schema: type: integer - name: offset in: query description: number of items to skip required: false schema: type: integer - name: unanchored in: query description: Include transaction data from unanchored (i.e. unconfirmed) microblocks required: false schema: type: boolean default: false - name: until_block in: query description: returned data representing the state up until that point in time, rather than the current block. required: false schema: type: string responses: 200: description: Success content: application/json: schema: $ref: ./api/address/get-address-nft-events.schema.json example: $ref: ./api/address/get-address-nft-events.example.json /v2/accounts/{principal}: get: summary: Get account info tags: - Accounts operationId: get_account_info description: | Retrieves the account data for a given Account or a Contract Identifier Where balance is the hex encoding of a unsigned 128-bit integer (big-endian), nonce is an unsigned 64-bit integer, and the proofs are provided as hex strings. For non-existent accounts, this does not return a 404 error, rather it returns an object with balance and nonce of 0. parameters: - name: principal in: path description: Stacks address or a Contract identifier (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`) required: true schema: type: string - name: proof in: query description: Returns object without the proof field if set to 0 schema: type: integer - name: tip in: query schema: type: string description: The Stacks chain tip to query from responses: 200: description: Success content: application/json: schema: $ref: ./api/core-node/get-account-data.schema.json example: $ref: ./api/core-node/get-account-data.example.json /v2/fees/transfer: get: summary: Get estimated fee tags: - Fees operationId: get_fee_transfer description: Retrieves an estimated fee rate for STX transfer transactions. This a a fee rate / byte, and is returned as a JSON integer responses: 200: description: Success content: application/json: schema: $ref: ./api/core-node/get-fee-transfer.schema.json example: $ref: ./api/core-node/get-fee-transfer.example.json /v2/info: get: summary: Get Core API info description: Retrieves information about the Core API including the server version tags: - Info operationId: get_core_api_info responses: 200: description: Success content: application/json: schema: $ref: ./api/core-node/get-info.schema.json example: $ref: ./api/core-node/get-info.example.json /extended/v1/status: get: summary: Get Blockchain API status description: Retrieves the current status of the blockchain API, including the server version tags: - Info operationId: get_status responses: 200: description: Success content: application/json: schema: $ref: ./api/info/get-status.schema.json example: $ref: ./api/info/get-status.example.json /extended/v1/info/network_block_times: get: tags: - Info operationId: get_network_block_times summary: Get the network target block time description: Retrieves the target block times for mainnet and testnet. The block time is hardcoded and will change throughout the implementation phases of the testnet. responses: 200: description: Success content: application/json: example: $ref: ./api/info/get-network-block-times.example.json schema: $ref: ./api/info/get-network-block-times.schema.json /extended/v1/info/network_block_time/{network}: get: tags: - Info operationId: get_network_block_time_by_network summary: Get a given network's target block time description: Retrieves the target block time for a given network. The network can be mainnet or testnet. The block time is hardcoded and will change throughout the implementation phases of the testnet. parameters: - in: path name: network required: true schema: type: string enum: [testnet, mainnet] description: Which network to retrieve the target block time of responses: 200: description: Success content: application/json: example: $ref: ./api/info/get-network-block-time-by-network.example.json schema: $ref: ./api/info/get-network-block-time-by-network.schema.json /extended/v1/stx_supply: get: tags: - Info operationId: get_stx_supply summary: Get total and unlocked STX supply description: Retrieves the total and unlocked STX supply. More information on Stacking can be found [here] (https://docs.stacks.co/understand-stacks/stacking). parameters: - in: query name: height required: false schema: type: number description: The block height at which to query supply details from, if not provided then the latest block height is used responses: 200: description: Success content: application/json: example: $ref: ./api/info/get-stx-supply.example.json schema: $ref: ./api/info/get-stx-supply.schema.json /extended/v1/stx_supply/total/plain: get: tags: - Info operationId: get_stx_supply_total_supply_plain summary: Get total STX supply in plain text format description: Retrieves the total supply for STX tokens as plain text. responses: 200: description: success content: text/plain: example: '123.456789' schema: $ref: ./api/info/get-stx-supply-total-plain.schema.json /extended/v1/stx_supply/circulating/plain: get: tags: - Info operationId: get_stx_supply_circulating_plain summary: Get circulating STX supply in plain text format description: Retrieves the STX tokens currently in circulation that have been unlocked as plain text. responses: 200: description: success content: text/plain: example: '123.456789' schema: $ref: ./api/info/get-stx-supply-circulating-plain.schema.json /extended/v1/stx_supply/legacy_format: get: tags: - Info operationId: get_total_stx_supply_legacy_format summary: Get total and unlocked STX supply (results formatted the same as the legacy 1.0 API) description: Retrieves total supply of STX tokens including those currently in circulation that have been unlocked. parameters: - in: query name: height required: false schema: type: number description: The block height at which to query supply details from, if not provided then the latest block height is used responses: 200: description: Success content: application/json: example: $ref: ./api/info/get-stx-supply-legacy-format.example.json schema: $ref: ./api/info/get-stx-supply-legacy-format.schema.json /v2/pox: get: summary: Get Proof-of-Transfer details description: Retrieves Proof-of-Transfer (PoX) information. Can be used for Stacking. tags: - Info operationId: get_pox_info responses: 200: description: Success content: application/json: schema: $ref: ./api/core-node/get-pox.schema.json example: $ref: ./api/core-node/get-pox.example.json /extended/v1/search/{id}: get: summary: Search description: Search blocks, transactions, contracts, or accounts by hash/ID tags: - Search parameters: - in: path name: id required: true schema: type: string description: The hex hash string for a block or transaction, account address, or contract address - in: query name: include_metadata schema: type: boolean description: This includes the detailed data for purticular hash in the response operationId: search_by_id responses: 200: description: Success content: application/json: schema: $ref: ./api/search/search.schema.json example: $ref: ./api/search/search-contract.example.json 404: description: Not found content: application/json: example: $ref: ./api/errors/search-not-found.example.json /rosetta/v1/network/list: post: tags: - Rosetta summary: Get List of Available Networks operationId: rosetta_network_list description: Retrieves a list of NetworkIdentifiers that the Rosetta server supports. responses: 200: description: Success content: application/json: schema: $ref: ./api/rosetta/rosetta-network-list-response.schema.json 400: description: Error content: application/json: schema: $ref: ./entities/rosetta/rosetta-error.schema.json /rosetta/v1/network/options: post: tags: - Rosetta summary: Get Network Options operationId: rosetta_network_options description: | Retrieves the version information and allowed network-specific types for a NetworkIdentifier. Any NetworkIdentifier returned by /network/list should be accessible here. Because options are retrievable in the context of a NetworkIdentifier, it is possible to define unique options for each network. responses: 200: description: Success content: application/json: schema: $ref: ./api/rosetta/rosetta-network-options-response.schema.json 400: description: Error content: application/json: schema: $ref: ./entities/rosetta/rosetta-error.schema.json requestBody: required: true content: application/json: schema: $ref: ./api/rosetta/rosetta-network-options-request.schema.json /rosetta/v1/network/status: post: tags: - Rosetta summary: Get Network Status operationId: rosetta_network_status description: | Retrieves the current status of the network requested. Any NetworkIdentifier returned by /network/list should be accessible here. responses: 200: description: Success content: application/json: schema: $ref: ./api/rosetta/rosetta-network-status-response.schema.json 400: description: Error content: application/json: schema: $ref: ./entities/rosetta/rosetta-error.schema.json requestBody: required: true content: application/json: schema: $ref: ./api/rosetta/rosetta-network-status-request.schema.json /rosetta/v1/account/balance: post: tags: - Rosetta summary: Get an Account Balance operationId: rosetta_account_balance description: | An AccountBalanceRequest is utilized to make a balance request on the /account/balance endpoint. If the block_identifier is populated, a historical balance query should be performed. responses: 200: description: Success content: application/json: schema: $ref: ./api/rosetta/rosetta-account-response.schema.json 400: description: Error content: application/json: schema: $ref: ./entities/rosetta/rosetta-error.schema.json requestBody: required: true content: application/json: schema: $ref: ./api/rosetta/rosetta-account-balance-request.schema.json /rosetta/v1/block: post: tags: - Rosetta summary: Get a Block operationId: rosetta_block description: Retrieves the Block information for a given block identifier including a list of all transactions in the block. responses: 200: description: Success content: application/json: schema: $ref: ./api/rosetta/rosetta-block-response.schema.json 400: description: Error content: application/json: schema: $ref: ./entities/rosetta/rosetta-error.schema.json requestBody: required: true content: application/json: schema: $ref: ./api/rosetta/rosetta-block-request.schema.json /rosetta/v1/block/transaction: post: tags: - Rosetta summary: Get a Block Transaction operationId: rosetta_block_transaction description: Retrieves a Transaction included in a block that is not returned in a BlockResponse. responses: 200: description: Success content: application/json: schema: $ref: ./api/rosetta/rosetta-block-transaction-response.schema.json 400: description: Error content: application/json: schema: $ref: ./entities/rosetta/rosetta-error.schema.json requestBody: required: true content: application/json: schema: $ref: ./api/rosetta/rosetta-block-transaction-request.schema.json /rosetta/v1/mempool: post: tags: - Rosetta summary: Get All Mempool Transactions operationId: rosetta_mempool description: Retrieves a list of transcations currently in the mempool for a given network. responses: 200: description: Success content: application/json: schema: $ref: ./api/rosetta/rosetta-mempool-response.schema.json 400: description: Error content: application/json: schema: $ref: ./entities/rosetta/rosetta-error.schema.json requestBody: required: true content: application/json: schema: $ref: ./api/rosetta/rosetta-mempool-request.schema.json /rosetta/v1/mempool/transaction: post: tags: - Rosetta summary: Get a Mempool Transaction operationId: rosetta_mempool_transaction description: Retrieves transaction details from the mempool for a given transaction id from a given network. responses: 200: description: Success content: application/json: schema: $ref: ./api/rosetta/rosetta-mempool-transaction-response.schema.json 400: description: Error content: application/json: schema: $ref: ./entities/rosetta/rosetta-error.schema.json requestBody: required: true content: application/json: schema: $ref: ./api/rosetta/rosetta-mempool-transaction-request.schema.json /rosetta/v1/construction/derive: post: tags: - Rosetta summary: Derive an AccountIdentifier from a PublicKey operationId: rosetta_construction_derive description: Retrieves the Account Identifier information based on a Public Key for a given network responses: 200: description: Success content: application/json: schema: $ref: ./api/rosetta/rosetta-construction-derive-response.schema.json 400: description: Error content: application/json: schema: $ref: ./entities/rosetta/rosetta-error.schema.json requestBody: required: true content: application/json: schema: $ref: ./api/rosetta/rosetta-construction-derive-request.schema.json /rosetta/v1/construction/hash: post: tags: - Rosetta summary: Get the Hash of a Signed Transaction operationId: rosetta_construction_hash description: Retrieves the network-specific transaction hash for a signed transaction. responses: 200: description: Success content: application/json: schema: $ref: ./api/rosetta/rosetta-construction-hash-response.schema.json 400: description: Error content: application/json: schema: $ref: ./entities/rosetta/rosetta-error.schema.json requestBody: required: true content: application/json: schema: $ref: ./api/rosetta/rosetta-construction-hash-request.schema.json /rosetta/v1/construction/metadata: post: tags: - Rosetta summary: Get Metadata for Transaction Construction operationId: rosetta_construction_metadata description: To Do responses: 200: description: Success content: application/json: schema: $ref: ./api/rosetta/rosetta-construction-metadata-response.schema.json 400: description: Error content: application/json: schema: $ref: ./entities/rosetta/rosetta-error.schema.json requestBody: required: true content: application/json: schema: $ref: ./api/rosetta/rosetta-construction-metadata-request.schema.json /rosetta/v1/construction/parse: post: tags: - Rosetta summary: Parse a Transaction operationId: rosetta_construction_parse description: TODO responses: 200: description: Success content: application/json: schema: $ref: ./api/rosetta/rosetta-construction-parse-response.schema.json 400: description: Error content: application/json: schema: $ref: ./entities/rosetta/rosetta-error.schema.json requestBody: required: true content: application/json: schema: $ref: ./api/rosetta/rosetta-construction-parse-request.schema.json /rosetta/v1/construction/preprocess: post: tags: - Rosetta summary: Create a Request to Fetch Metadata operationId: rosetta_construction_preprocess description: TODO responses: 200: description: Success content: application/json: schema: $ref: ./api/rosetta/rosetta-construction-preprocess-response.schema.json 400: description: Error content: application/json: schema: $ref: ./entities/rosetta/rosetta-error.schema.json requestBody: required: true content: application/json: schema: $ref: ./api/rosetta/rosetta-construction-preprocess-request.schema.json /rosetta/v1/construction/submit: post: tags: - Rosetta summary: Submit a Signed Transaction operationId: rosetta_construction_submit description: Submit a pre-signed transaction to the node. responses: 200: description: Success content: application/json: schema: $ref: ./api/rosetta/rosetta-construction-submit-response.schema.json 400: description: Error content: application/json: schema: $ref: ./entities/rosetta/rosetta-error.schema.json requestBody: required: true content: application/json: schema: $ref: ./api/rosetta/rosetta-construction-submit-request.schema.json /rosetta/v1/construction/payloads: post: tags: - Rosetta summary: Generate an Unsigned Transaction and Signing Payloads operationId: rosetta_construction_payloads description: Generate and unsigned transaction from operations and metadata responses: 200: description: Success content: application/json: schema: $ref: ./api/rosetta/rosetta-construction-payloads-response.schema.json 400: description: Error content: application/json: schema: $ref: ./entities/rosetta/rosetta-error.schema.json requestBody: required: true content: application/json: schema: $ref: ./api/rosetta/rosetta-construction-payloads-request.schema.json /rosetta/v1/construction/combine: post: tags: - Rosetta summary: Create Network Transaction from Signatures operationId: rosetta_construction_combine description: Take unsigned transaction and signature, combine both and return signed transaction responses: 200: description: Success content: application/json: schema: $ref: ./api/rosetta/rosetta-construction-combine-response.schema.json 400: description: Error content: application/json: schema: $ref: ./entities/rosetta/rosetta-error.schema.json requestBody: required: true content: application/json: schema: $ref: ./api/rosetta/rosetta-construction-combine-request.schema.json /v2/prices/namespaces/{tld}: get: summary: Get Namespace Price description: Retrieves the price of a namespace. The `amount` given will be in the smallest possible units of the currency. tags: - Names operationId: get_namespace_price parameters: - name: tld in: path description: the namespace to fetch price for required: true example: id schema: type: string responses: 200: description: Success content: application/json: schema: $ref: ./api/bns/namespace-operations/bns-get-namespace-price-response.schema.json example: $ref: ./api/bns/namespace-operations/bns-get-namespace-price-response.example.json /v2/prices/names/{name}: get: summary: Get Name Price description: Retrieves the price of a name. The `amount` given will be in the smallest possible units of the currency. tags: - Names operationId: get_name_price parameters: - name: name in: path description: the name to query price information for required: true example: muneeb.id schema: type: string responses: 200: description: Success content: application/json: schema: $ref: ./api/bns/name-querying/bns-get-name-price-response.schema.json example: $ref: ./api/bns/name-querying/bns-get-name-price-response.example.json /v1/namespaces: get: summary: Get All Namespaces description: Retrieves a list of all namespaces known to the node. tags: - Names operationId: get_all_namespaces responses: 200: description: Success content: application/json: schema: $ref: ./api/bns/namespace-operations/bns-get-all-namespaces-response.schema.json example: $ref: ./api/bns/namespace-operations/bns-get-all-namespaces-response.example.json /v1/namespaces/{tld}/names: get: summary: Get Namespace Names description: Retrieves a list of names within a given namespace. tags: - Names operationId: get_namespace_names parameters: - name: tld in: path description: the namespace to fetch names from required: true example: id schema: type: string - name: page in: query description: names are returned in pages of size 100, so specify the page number. required: true example: 23 schema: type: integer responses: 200: description: Success content: application/json: schema: $ref: ./api/bns/namespace-operations/bns-get-all-namespaces-names-response.schema.json example: $ref: ./api/bns/namespace-operations/bns-get-all-namespaces-names-response.example.json 400: description: Error content: application/json: schema: $ref: ./api/bns/errors/bns-error.schema.json example: $ref: ./api/bns/errors/bns-invalid-page.example.json 404: description: Error content: application/json: schema: $ref: ./api/bns/errors/bns-error.schema.json example: $ref: ./api/bns/errors/bns-no-such-namespace.example.json /v1/names: get: summary: Get All Names description: Retrieves a list of all names known to the node. tags: - Names operationId: get_all_names parameters: - name: page in: query description: names are returned in pages of size 100, so specify the page number. required: true example: 23 schema: type: integer responses: 200: description: Success content: application/json: schema: $ref: ./api/bns/name-querying/bns-get-all-names-response.schema.json example: $ref: ./api/bns/name-querying/bns-get-all-names-response.example.json 400: description: Error content: application/json: schema: $ref: ./api/bns/errors/bns-error.schema.json example: $ref: ./api/bns/errors/bns-invalid-page.example.json /v1/names/{name}: get: summary: Get Name Details description: Retrieves details of a given name including the `address`, `status` and last transaction id - `last_txid`. tags: - Names operationId: get_name_info parameters: - name: name in: path description: fully-qualified name required: true example: muneeb.id schema: type: string responses: 200: description: Success content: application/json: schema: $ref: ./api/bns/name-querying/bns-get-name-info.response.schema.json example: $ref: ./api/bns/name-querying/bns-get-name-info.response.example.json 400: description: Error content: application/json: schema: $ref: ./api/bns/errors/bns-error.schema.json example: $ref: ./api/bns/errors/bns-invalid-name-subdomain.example.json 404: description: Error content: application/json: schema: $ref: ./api/bns/errors/bns-error.schema.json example: $ref: ./api/bns/errors/bns-no-such-name.example.json /v1/names/{name}/history: get: summary: Get Name History description: Retrieves a history of all blockchain records of a registered name. tags: - Names operationId: get_name_history parameters: - name: name in: path description: name to query required: true example: muneeb.id schema: type: string - name: page in: query description: the page (in 20-entry pages) of the history to fetch required: true example: 0 schema: type: integer responses: 200: description: Success content: application/json: schema: $ref: ./api/bns/name-querying/bns-get-name-history-response.schema.json example: $ref: ./api/bns/name-querying/bns-get-name-history-response.example.json 400: description: Error content: application/json: schema: $ref: ./api/bns/errors/bns-error.schema.json example: $ref: ./api/bns/errors/bns-invalid-page.example.json 404: description: Error content: application/json: schema: $ref: ./api/bns/errors/bns-error.schema.json example: $ref: ./api/bns/errors/bns-no-such-name.example.json /v1/names/{name}/zonefile: get: summary: Get Zone File description: Retrieves a user’s raw zone file. This only works for RFC-compliant zone files. This method returns an error for names that have non-standard zone files. tags: - Names operationId: fetch_zone_file parameters: - name: name in: path description: fully-qualified name required: true example: bar.test schema: type: string responses: 200: description: Success content: application/json: schema: $ref: ./api/bns/manage-names/bns-fetch-zone-file-response.schema.json example: $ref: ./api/bns/manage-names/bns-fetch-zone-file-response.example.json 400: description: Error content: application/json: schema: $ref: ./api/bns/errors/bns-error.schema.json example: $ref: ./api/bns/errors/bns-invalid-name-subdomain.example.json 404: description: Error content: application/json: schema: $ref: ./api/bns/errors/bns-error.schema.json example: $ref: ./api/bns/errors/bns-no-zone-file.example.json /v1/names/{name}/zonefile/{zoneFileHash}: get: summary: Get Historical Zone File description: Retrieves the historical zonefile specified by the username and zone hash. tags: - Names operationId: get_historical_zone_file parameters: - name: name in: path description: fully-qualified name required: true example: muneeb.id schema: type: string - name: zoneFileHash in: path description: zone file hash required: true example: b100a68235244b012854a95f9114695679002af9 schema: type: string responses: 200: description: Success content: application/json: schema: $ref: ./api/bns/name-querying/bns-get-historical-zone-file-response.schema.json example: $ref: ./api/bns/name-querying/bns-get-historical-zone-file-response.example.json 400: description: Error content: application/json: schema: $ref: ./api/bns/errors/bns-error.schema.json example: $ref: ./api/bns/errors/bns-invalid-name-subdomain.example.json 404: description: Error content: application/json: schema: $ref: ./api/bns/errors/bns-error.schema.json example: $ref: ./api/bns/errors/bns-no-zone-file.example.json /v1/addresses/{blockchain}/{address}: get: summary: Get Names Owned by Address description: Retrieves a list of names owned by the address provided. tags: - Names operationId: get_names_owned_by_address parameters: - name: blockchain in: path description: the layer-1 blockchain for the address required: true example: bitcoin schema: type: string - name: address in: path description: the address to lookup required: true example: 1QJQxDas5JhdiXhEbNS14iNjr8auFT96GP schema: type: string responses: 200: description: Success content: application/json: schema: $ref: ./api/bns/name-querying/bns-get-names-owned-by-address-response.schema.json example: $ref: ./api/bns/name-querying/bns-get-names-owned-by-address-response.example.json 404: description: Error content: application/json: schema: $ref: ./api/bns/errors/bns-error.schema.json example: $ref: ./api/bns/errors/bns-unsupported-blockchain.example.json /v1/subdomains: get: summary: Get All Subdomains description: Retrieves a list of all subdomains known to the node. tags: - Names operationId: get_all_subdomains parameters: - name: page in: query description: names are returned in pages of size 100, so specify the page number. required: true example: 3 schema: type: integer responses: 200: description: Success content: application/json: schema: $ref: ./api/bns/name-querying/bns-get-all-subdomains-response.schema.json example: $ref: ./api/bns/name-querying/bns-get-all-subdomains-response.example.json 400: description: Error content: application/json: schema: $ref: ./api/bns/errors/bns-error.schema.json example: $ref: ./api/bns/errors/bns-invalid-page.example.json /v1/subdomains/{txid}: get: summary: Get Subdomain at Transaction description: Retrieves the list of subdomain operations processed by a given transaction. The returned array includes subdomain operations that have not yet been accepted as part of any subdomain’s history (checkable via the accepted field). If the given transaction ID does not correspond to a Stacks transaction that introduced new subdomain operations, and empty array will be returned. tags: - Names operationId: get_subdomain_at_transaction parameters: - name: txid in: path description: transaction id required: true example: d04d708472ea3c147f50e43264efdb1535f71974053126dc4db67b3ac19d41fe schema: type: string responses: 200: description: Success content: application/json: schema: $ref: ./api/bns/name-querying/bns-get-subdomain-at-tx-response.schema.json example: $ref: ./api/bns/name-querying/bns-get-subdomain-at-tx-response.example.json 400: description: Error content: application/json: schema: $ref: ./api/bns/errors/bns-error.schema.json example: $ref: ./api/bns/errors/bns-invalid-tx-id.example.json /extended/v1/tx/block/{block_hash}: get: operationId: get_transactions_by_block_hash summary: Transactions by block hash description: Retrieves a list of all transactions within a block for a given block hash. tags: - Transactions parameters: - name: block_hash in: path description: Hash of block required: true schema: type: string - name: limit in: query description: max number of transactions to fetch required: false schema: type: integer - name: offset in: query description: index of first transaction to fetch required: false schema: type: integer responses: 200: description: List of Transactions content: application/json: schema: $ref: ./api/transaction/get-transactions.schema.json example: $ref: ./api/transaction/get-transactions.example.json /extended/v1/tx/block_height/{height}: get: operationId: get_transactions_by_block_height summary: Transactions by block height description: Retrieves all transactions within a block at a given height tags: - Transactions parameters: - name: height in: path description: Height of block required: true schema: type: integer - name: limit in: query description: max number of transactions to fetch required: false schema: type: integer - name: offset in: query description: index of first transaction to fetch required: false schema: type: integer - name: unanchored in: query description: Include transaction data from unanchored (i.e. unconfirmed) microblocks required: false schema: type: boolean default: false responses: 200: description: List of Transactions content: application/json: schema: $ref: ./api/transaction/get-transactions.schema.json example: $ref: ./api/transaction/get-transactions.example.json /extended/v1/address/{address}/mempool: get: operationId: get_address_mempool_transactions summary: Transactions for address description: Retrieves all transactions for a given address that are currently in mempool tags: - Transactions parameters: - name: address in: path description: Transactions for the address required: true schema: type: string - name: limit in: query description: max number of transactions to fetch required: false schema: type: integer - name: offset in: query description: index of first transaction to fetch required: false schema: type: integer - name: unanchored in: query description: Include transaction data from unanchored (i.e. unconfirmed) microblocks required: false schema: type: boolean default: false responses: 200: description: List of Transactions content: application/json: schema: $ref: ./api/transaction/get-mempool-transactions.schema.json example: $ref: ./api/transaction/get-mempool-transactions.example.json /extended/v1/tokens/ft/metadata: get: operationId: get_ft_metadata_list summary: Fungible tokens metadata list description: Retrieves list of fungible tokens with their metadata. More information on Fungible Tokens on the Stacks blockchain can be found [here](https://docs.stacks.co/write-smart-contracts/tokens#fungible-tokens). tags: - Fungible Tokens parameters: - name: limit in: query description: max number of tokens to fetch required: false schema: type: integer - name: offset in: query description: index of first tokens to fetch required: false schema: type: integer responses: 200: description: List of fungible tokens metadata content: application/json: schema: $ref: ./api/tokens/get-fungible-tokens-metadata-list.schema.json example: $ref: ./api/tokens/get-fungible-tokens-metadata-list.example.schema.json /extended/v1/tokens/nft/metadata: get: operationId: get_nft_metadata_list summary: Non fungible tokens metadata list description: Retrieves a list of non fungible tokens with their metadata. More information on Non-Fungible Tokens on the Stacks blockchain can be found [here](https://docs.stacks.co/write-smart-contracts/tokens#non-fungible-tokens-nfts). tags: - Non-Fungible Tokens parameters: - name: limit in: query description: max number of tokens to fetch required: false schema: type: integer - name: offset in: query description: index of first tokens to fetch required: false schema: type: integer responses: 200: description: List of non fungible tokens metadata content: application/json: schema: $ref: ./api/tokens/get-non-fungible-tokens-metadata-list.schema.json example: $ref: ./api/tokens/get-non-fungible-tokens-metadata-list.example.schema.json /extended/v1/tokens/{contractId}/nft/metadata: get: operationId: get_contract_nft_metadata summary: Non fungible tokens metadata for contract id description: Retrieves metadata for non fungible tokens for a given contract id. More information on Non-Fungible Tokens on the Stacks blockchain can be found [here](https://docs.stacks.co/write-smart-contracts/tokens#non-fungible-tokens-nfts). tags: - Non-Fungible Tokens parameters: - name: contractId in: path description: token's contract id required: true schema: type: string responses: 200: description: Non fungible tokens metadata for contract id content: application/json: schema: $ref: ./entities/tokens/non-fungible-token.schema.json example: $ref: ./entities/tokens/non-fungible-token.schema.example.json /extended/v1/tokens/{contractId}/ft/metadata: get: operationId: get_contract_ft_metadata summary: Fungible tokens metadata for contract id description: Retrieves the metadata for fungible tokens for a given contract id tags: - Fungible Tokens parameters: - name: contractId in: path description: token's contract id required: true schema: type: string responses: 200: description: Fungible tokens metadata for contract id content: application/json: schema: $ref: ./entities/tokens/fungible-token.schema.json example: $ref: ./entities/tokens/fungible-token.schema.example.json /extended/v1/fee_rate: post: operationId: fetch_fee_rate summary: fetch fee rate description: Retrieves estimated fee rate. tags: - Fees responses: 200: description: Transaction fee rate content: application/json: schema: $ref: ./api/info/get-fee-rate-response.schema.json example: $ref: ./api/info/get-fee-rate-response.example.json requestBody: required: true content: application/json: schema: $ref: ./api/info/get-fee-rate-request.schema.json example: $ref: ./api/info/get-fee-rate-request.example.json