openapi: 3.0.2 servers: - url: https://api.mainnet.hiro.so/ description: Mainnet - url: https://api.nakamoto.testnet.hiro.so/ description: Nakamoto Testnet - url: https://api.testnet.hiro.so/ 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](https://docs.hiro.so/stacks-blockchain-api). [Download Postman collection](https://hirosystems.github.io/stacks-blockchain-api/collection.json) 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: Burn Blocks description: Read-only endpoints to obtain burn 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: 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 - name: Mempool description: Endpoints to obtain Mempool information - name: Proof of Transfer description: Endpoints to get information about the Proof of Transfer consensus mechanism 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.hiro.so/?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 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 403: description: BTC Faucet not fully configured content: application/json: schema: type: object properties: error: type: string success: type: boolean example: error: BTC Faucet not fully configured success: false 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 example: 100 - name: offset in: query description: index of first transaction to fetch required: false schema: type: integer example: 42000 - name: type in: query description: Filter by transaction type required: false style: form explode: true schema: type: array example: coinbase items: type: string enum: [coinbase, token_transfer, smart_contract, contract_call, poison_microblock, tenure_change] - name: from_address in: query description: Option to filter results by sender address required: false schema: type: string - name: to_address in: query description: Option to filter results by recipient address required: false schema: type: string - name: sort_by in: query description: Option to sort results by block height, timestamp, or fee required: false schema: type: string enum: [block_height, burn_block_time, fee] example: burn_block_time default: block_height - name: start_time in: query description: Filter by transactions after this timestamp (unix timestamp in seconds) required: false schema: type: integer example: 1704067200 - name: end_time in: query description: Filter by transactions before this timestamp (unix timestamp in seconds) required: false schema: type: integer example: 1706745599 - name: contract_id in: query description: Filter by contract call transactions involving this contract ID required: false schema: type: string example: "SP000000000000000000002Q6VF78.pox-4" - name: function_name in: query description: Filter by contract call transactions involving this function name required: false schema: type: string example: "delegate-stx" - name: nonce in: query description: Filter by transactions with this nonce required: false schema: type: integer example: 123 - name: order in: query description: Option to sort results in ascending or descending order required: false schema: type: string enum: [asc, desc] example: desc default: desc - name: unanchored in: query description: Include transaction data from unanchored (i.e. unconfirmed) microblocks required: false schema: type: boolean example: true 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. If you need to monitor new transactions, we highly recommend subscribing to [WebSockets or Socket.io](https://github.com/hirosystems/stacks-blockchain-api/tree/master/client) for real-time updates. parameters: - name: sender_address in: query description: Filter to only return transactions with this sender address. required: false schema: type: string example: "SP1GPBP8NBRXDRJBFQBV7KMAZX1Z7W2RFWJEH0V10" - 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: order_by in: query description: Option to sort results by transaction age, size, or fee rate. required: false schema: type: string enum: [age, size, fee] example: fee - name: order in: query description: Option to sort results in ascending or descending order. required: false schema: type: string enum: [asc, desc] example: asc - name: limit in: query description: max number of mempool transactions to fetch required: false schema: type: integer default: 20 maximum: 50 example: 20 - name: offset in: query description: index of first mempool transaction to fetch required: false schema: type: integer example: 42000 - name: unanchored in: query description: Include transaction data from unanchored (i.e. unconfirmed) microblocks required: false schema: type: boolean example: true 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/v2/mempool/fees: get: summary: Get mempool transaction fee priorities tags: - Mempool operationId: get_mempool_fee_priorities description: | Returns estimated fee priorities (in micro-STX) for all transactions that are currently in the mempool. Also returns priorities separated by transaction type. responses: 200: description: Mempool fee priorities content: application/json: schema: $ref: ./api/mempool/get-fee-priorities.schema.json example: $ref: ./api/mempool/get-fee-priorities.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 example: 42000 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/mempool/stats: get: summary: Get statistics for mempool transactions tags: - Transactions operationId: get_mempool_transaction_stats description: | Queries for transactions counts, age (by block height), fees (simple average), and size. All results broken down by transaction type and percentiles (p25, p50, p75, p95). responses: 200: description: Statistics for mempool transactions content: application/json: schema: $ref: ./api/transaction/get-mempool-stats.schema.json example: $ref: ./api/transaction/get-mempool-stats.example.json /extended/v1/tx/multiple: parameters: - name: tx_id in: query description: Array of transaction ids required: true style: form explode: true schema: type: array example: [ "0x0a411719e3bfde95f9e227a2d7f8fac3d6c646b1e6cc186db0e2838a2c6cd9c0", "0xfbe6412b46e9db87df991a0d043ff47eb58019f770208cf48e2380337cc31785", "0x178b77678a758d9f29a147d6399315c83d0f1baf114431fbe4d3587aa5fbba6f" ] 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 example: true 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 example: "0x0a411719e3bfde95f9e227a2d7f8fac3d6c646b1e6cc186db0e2838a2c6cd9c0" - 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 example: true 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 example: "0x0a411719e3bfde95f9e227a2d7f8fac3d6c646b1e6cc186db0e2838a2c6cd9c0" 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. If you need to actively monitor new microblocks, we highly recommend subscribing to [WebSockets or Socket.io](https://github.com/hirosystems/stacks-blockchain-api/tree/master/client) for real-time updates. parameters: - name: limit in: query description: Max number of microblocks to fetch required: false schema: type: integer default: 20 maximum: 200 example: 100 - name: offset in: query description: Index of the first microblock to fetch required: false schema: type: integer example: 42000 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 example: "0x3bfcdf84b3012adb544cf0f6df4835f93418c2269a3881885e27b3d58eb82d47" 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/v2/burn-blocks: get: summary: Get burn blocks description: | Retrieves a list of recent burn blocks tags: - Burn Blocks operationId: get_burn_blocks parameters: - name: limit in: query description: max number of burn blocks to fetch required: false schema: type: integer default: 20 maximum: 30 - name: offset in: query description: index of first burn block to fetch required: false schema: type: integer example: 42000 responses: 200: description: List of burn blocks content: application/json: schema: $ref: ./api/blocks/get-burn-blocks.schema.json example: $ref: ./api/blocks/get-burn-blocks.example.json /extended/v2/burn-blocks/{height_or_hash}: get: summary: Get burn block description: Retrieves a single burn block tags: - Burn Blocks operationId: get_burn_block parameters: - name: height_or_hash in: path description: filter by burn block height, hash, or the constant `latest` to filter for the most recent burn block required: true schema: oneOf: - type: integer example: 42000 - type: string example: "0x4839a8b01cfb39ffcc0d07d3db31e848d5adf5279d529ed5062300b9f353ff79" responses: 200: description: Burn block content: application/json: schema: $ref: ./entities/blocks/burn-block.schema.json example: $ref: ./entities/blocks/burn-block.example.json /extended/v2/burn-blocks/{height_or_hash}/blocks: get: summary: Get blocks by burn block description: | Retrieves a list of blocks confirmed by a specific burn block tags: - Blocks operationId: get_blocks_by_burn_block parameters: - name: height_or_hash in: path description: filter by burn block height, hash, or the constant `latest` to filter for the most recent burn block required: true schema: oneOf: - type: integer example: 42000 - type: string example: "0x4839a8b01cfb39ffcc0d07d3db31e848d5adf5279d529ed5062300b9f353ff79" - name: limit in: query description: max number of blocks to fetch required: false schema: type: integer example: 20 - name: offset in: query description: index of first burn block to fetch required: false schema: type: integer example: 0 responses: 200: description: List of blocks content: application/json: schema: $ref: ./api/blocks/get-nakamoto-blocks.schema.json example: $ref: ./api/blocks/get-nakamoto-blocks.example.json /extended/v2/blocks: get: summary: Get blocks description: | Retrieves a list of recently mined blocks tags: - Blocks operationId: get_blocks parameters: - name: limit in: query description: max number of blocks to fetch required: false schema: type: integer example: 20 - name: offset in: query description: index of first burn block to fetch required: false schema: type: integer example: 0 responses: 200: description: List of blocks content: application/json: schema: $ref: ./api/blocks/get-nakamoto-blocks.schema.json example: $ref: ./api/blocks/get-nakamoto-blocks.example.json /extended/v2/blocks/average-times: get: summary: Get average block times description: | Retrieves average block times (in seconds) tags: - Blocks operationId: get_average_block_times responses: 200: description: Average block times (in seconds) content: application/json: schema: $ref: ./api/blocks/get-average-times.schema.json example: $ref: ./api/blocks/get-average-times.example.json /extended/v2/blocks/{height_or_hash}: get: summary: Get block description: | Retrieves a single block tags: - Blocks operationId: get_block parameters: - name: height_or_hash in: path description: filter by block height, hash, index block hash or the constant `latest` to filter for the most recent block required: true schema: oneOf: - type: integer example: 42000 - type: string example: "0x4839a8b01cfb39ffcc0d07d3db31e848d5adf5279d529ed5062300b9f353ff79" responses: 200: description: Block content: application/json: schema: $ref: ./entities/blocks/nakamoto-block.schema.json example: $ref: ./entities/blocks/nakamoto-block.example.json /extended/v2/blocks/{height_or_hash}/transactions: get: summary: Get transactions by block description: | Retrieves transactions confirmed in a single block tags: - Transactions operationId: get_transactions_by_block parameters: - name: height_or_hash in: path description: filter by block height, hash, index block hash or the constant `latest` to filter for the most recent block required: true schema: oneOf: - type: integer example: 42000 - type: string example: "0x4839a8b01cfb39ffcc0d07d3db31e848d5adf5279d529ed5062300b9f353ff79" 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/v2/addresses/{address}/transactions: get: summary: Get address transactions description: | Retrieves a paginated list of confirmed transactions sent or received by a STX address or Smart Contract ID, alongside the total amount of STX sent or received and the number of STX, FT and NFT transfers contained within each transaction. More information on Transaction types can be found [here](https://docs.stacks.co/understand-stacks/transactions#types). tags: - Transactions operationId: get_address_transactions parameters: - name: address in: path description: STX address or Smart Contract ID required: true schema: type: string example: "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0" - name: limit in: query description: Number of transactions to fetch required: false schema: type: integer example: 20 - name: offset in: query description: Index of first transaction to fetch required: false schema: type: integer example: 10 responses: 200: description: Success content: application/json: schema: $ref: ./api/address/get-v2-address-transactions.schema.json example: $ref: ./api/address/get-v2-address-transactions.example.json /extended/v2/addresses/{address}/transactions/{tx_id}/events: get: summary: Get events for an address transaction description: | Retrieves a paginated list of all STX, FT and NFT events concerning a STX address or Smart Contract ID within a specific transaction. tags: - Transactions operationId: get_address_transaction_events parameters: - name: address in: path description: STX address or Smart Contract ID required: true schema: type: string example: "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0" - name: tx_id in: path description: Transaction ID required: true schema: type: string example: "0x0a411719e3bfde95f9e227a2d7f8fac3d6c646b1e6cc186db0e2838a2c6cd9c0" - name: limit in: query description: Number of events to fetch required: false schema: type: integer example: 20 - name: offset in: query description: Index of first event to fetch required: false schema: type: integer example: 10 responses: 200: description: Success content: application/json: schema: $ref: ./api/address/get-address-transaction-events.schema.json example: $ref: ./api/address/get-address-transaction-events.example.json /extended/v2/smart-contracts/status: get: summary: Get smart contracts status description: | Retrieves the deployment status of multiple smart contracts. tags: - Smart Contracts operationId: get_smart_contracts_status parameters: - name: contract_id in: query description: contract ids to fetch status for required: true style: form explode: true schema: type: array example: "SPQZF23W7SEYBFG5JQ496NMY0G7379SRYEDREMSV.Candy" items: type: string responses: 200: description: List of smart contract status content: application/json: schema: $ref: ./api/smart-contracts/get-smart-contracts-status.schema.json example: $ref: ./api/smart-contracts/get-smart-contracts-status.example.json /extended/v2/pox/cycles: get: summary: Get PoX cycles description: Retrieves a list of PoX cycles tags: - Proof of Transfer operationId: get_pox_cycles parameters: - name: limit in: query description: max number of cycles to fetch required: false schema: type: integer default: 20 maximum: 60 - name: offset in: query description: index of first cycle to fetch required: false schema: type: integer example: 20 responses: 200: description: List of cycles content: application/json: schema: $ref: ./api/stacking/get-pox-cycles.schema.json example: $ref: ./api/stacking/get-pox-cycles.example.json /extended/v2/pox/cycles/{cycle_number}: get: summary: Get PoX cycle description: Retrieves details for a PoX cycle tags: - Proof of Transfer operationId: get_pox_cycle parameters: - name: cycle_number in: path description: PoX cycle number required: true schema: type: integer example: 56 responses: 200: description: Details for cycle content: application/json: schema: $ref: ./entities/stacking/pox-cycle.schema.json example: $ref: ./entities/stacking/pox-cycle.example.json /extended/v2/pox/cycles/{cycle_number}/signers: get: summary: Get signers in PoX cycle description: Retrieves a list of signers in a PoX cycle tags: - Proof of Transfer operationId: get_pox_cycle_signers parameters: - name: cycle_number in: path description: PoX cycle number required: true schema: type: integer example: 56 responses: 200: description: List of signers for cycle content: application/json: schema: $ref: ./api/stacking/get-pox-cycle-signers.schema.json example: $ref: ./api/stacking/get-pox-cycle-signers.example.json /extended/v2/pox/cycles/{cycle_number}/signers/{signer_key}: get: summary: Get signer in PoX cycle description: Retrieves details for a signer in a PoX cycle tags: - Proof of Transfer operationId: get_pox_cycle_signer parameters: - name: cycle_number in: path description: PoX cycle number required: true schema: type: integer example: 56 - name: signer_key in: path description: Signer key required: true schema: type: string example: "0x038e3c4529395611be9abf6fa3b6987e81d402385e3d605a073f42f407565a4a3d" responses: 200: description: Details for PoX signer content: application/json: schema: $ref: ./entities/stacking/signer.schema.json example: $ref: ./entities/stacking/signer.example.json /extended/v2/pox/cycles/{cycle_number}/signers/{signer_key}/stackers: get: summary: Get stackers for signer in PoX cycle description: Retrieves a list of stackers for a signer in a PoX cycle tags: - Proof of Transfer operationId: get_pox_cycle_signer_stackers parameters: - name: cycle_number in: path description: PoX cycle number required: true schema: type: integer example: 56 - name: signer_key in: path description: Signer key required: true schema: type: string example: "0x038e3c4529395611be9abf6fa3b6987e81d402385e3d605a073f42f407565a4a3d" responses: 200: description: List of stackers content: application/json: schema: $ref: ./api/stacking/get-pox-cycle-signer-stackers.schema.json example: $ref: ./api/stacking/get-pox-cycle-signer-stackers.example.json /extended/v1/block: get: summary: Get recent blocks deprecated: true description: | **NOTE:** This endpoint is deprecated in favor of [Get blocks](/api/get-blocks). Retrieves a list of recently mined blocks If you need to actively monitor new blocks, we highly recommend subscribing to [WebSockets or Socket.io](https://github.com/hirosystems/stacks-blockchain-api/tree/master/client) for real-time updates. 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: 30 - name: offset in: query description: index of first block to fetch required: false schema: type: integer example: 42000 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 example: "0x4839a8b01cfb39ffcc0d07d3db31e848d5adf5279d529ed5062300b9f353ff79" get: deprecated: true summary: Get block by hash description: | **NOTE:** This endpoint is deprecated in favor of [Get block](/api/get-block). Retrieves block details of a specific block for a given chain height. You can use the hash from your latest block ('get_block_list' API) to get your block details. 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 example: 10000 get: deprecated: true summary: Get block by height description: | **NOTE:** This endpoint is deprecated in favor of [Get block](/api/get-block). 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 example: "0x00000000000000000002bba732926cf68b6eda3e2cdbc2a85af79f10efeeeb10" get: summary: Get block by burnchain block hash deprecated: true description: | **NOTE:** This endpoint is deprecated in favor of [Get blocks](/api/get-blocks). 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 example: 744603 get: summary: Get block by burnchain height deprecated: true description: | **NOTE:** This endpoint is deprecated in favor of [Get blocks](/api/get-blocks). 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 example: 42000 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 example: "36hQtSEXBMevo5chpxhfAGiCTSC34QKgda" - 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 example: 42000 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 example: 42000 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 example: "36hQtSEXBMevo5chpxhfAGiCTSC34QKgda" - 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 example: 42000 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 example: "36hQtSEXBMevo5chpxhfAGiCTSC34QKgda" 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/contracts/smart-contract.schema.json example: $ref: ./entities/contracts/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 example: "SP6P4EJF0VG8V0RB3TQQKJBHDQKEF6NVRD1KZE3C.satoshibles" - name: unanchored in: query description: Include transaction data from unanchored (i.e. unconfirmed) microblocks required: false schema: type: boolean example: true 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 example: 42000 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 example: "SP6P4EJF0VG8V0RB3TQQKJBHDQKEF6NVRD1KZE3C.satoshibles" - 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 example: 42000 - name: unanchored in: query description: Include transaction data from unanchored (i.e. unconfirmed) microblocks required: false schema: type: boolean example: true 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 example: SP6P4EJF0VG8V0RB3TQQKJBHDQKEF6NVRD1KZE3C schema: type: string - name: contract_name in: path required: true description: Contract name schema: type: string example: "satoshibles" - 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 example: "SPSCWDV3RKV5ZRN1FQD84YE1NQFEDJ9R1F4DYQ11" - name: contract_name in: path required: true description: Contract name schema: type: string example: newyorkcitycoin-core-v2 - name: map_name in: path required: true description: Map name schema: type: string example: approved-contracts - 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 example: $ref: ./entities/contracts/get-specific-data-map-inside-contract.example.json /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 example: "SP6P4EJF0VG8V0RB3TQQKJBHDQKEF6NVRD1KZE3C" - name: contract_name in: path required: true description: Contract name schema: type: string example: satoshibles - 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: value: $ref: ./api/contract/post-call-read-only-fn-success.example.json fail: value: $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 example: "SP187Y7NRSG3T9Z9WTSWNEN3XRV1YSJWS81C7JKV7" - name: contract_name in: path required: true description: Contract name schema: type: string example: imaginary-friends-zebras - name: function_name in: path required: true description: Function name schema: type: string example: get-token-uri - 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: $ref: './entities/contracts/read-only-function-args-request-body.example.json' /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 required: true schema: type: string example: "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0" - name: unanchored in: query description: Include transaction data from unanchored (i.e. unconfirmed) microblocks required: false schema: type: boolean example: true 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 example: 60000 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. required: true schema: type: string example: "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0" - name: unanchored in: query description: Include transaction data from unanchored (i.e. unconfirmed) microblocks. required: false schema: type: boolean example: true default: false - name: until_block in: query description: returned data representing the state up until that point in time, rather than the current block. Note - Use either of the query parameters but not both at a time. required: false schema: type: string example: 60000 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: | **NOTE:** This endpoint is deprecated in favor of [Get address transactions](/api/get-address-transactions). 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). If you need to actively monitor new transactions for an address or contract id, we highly recommend subscribing to [WebSockets or Socket.io](https://github.com/hirosystems/stacks-blockchain-api/tree/master/client) for real-time updates. deprecated: true tags: - Accounts operationId: get_account_transactions parameters: - name: principal in: path description: Stacks address or a Contract identifier required: true schema: type: string example: "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0" - name: limit in: query description: max number of account transactions to fetch required: false schema: type: integer example: 42000 - name: offset in: query description: index of first account transaction to fetch required: false schema: type: integer example: 42000 - name: height in: query description: Filter for transactions only at this given block height required: false schema: type: number example: 42000 - name: unanchored in: query description: Include transaction data from unanchored (i.e. unconfirmed) microblocks required: false schema: type: boolean example: true default: false - name: until_block in: query description: returned data representing the state up until that point in time, rather than the current block. Note - Use either of the query parameters but not both at a time. required: false schema: type: string example: 60000 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: | **NOTE:** This endpoint is deprecated in favor of [Get events for an address transaction](/api/get-address-transaction-events). Retrieves transaction details for a given Transaction Id `tx_id`, for a given account or contract Identifier. deprecated: true 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 example: "SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE" - name: tx_id in: path description: Transaction id required: true schema: type: string example: "0x34d79c7cfc2fe525438736733e501a4bf0308a5556e3e080d1e2c0858aad7448" 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. deprecated: true tags: - Accounts operationId: get_account_transactions_with_transfers parameters: - name: principal in: path description: Stacks address or a Contract identifier required: true schema: type: string example: "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0" - name: limit in: query description: max number of account transactions to fetch required: false schema: type: integer example: 20 - name: offset in: query description: index of first account transaction to fetch required: false schema: type: integer example: 10 - name: height in: query description: Filter for transactions only at this given block height required: false schema: type: number example: 66119 - name: unanchored in: query description: Include transaction data from unanchored (i.e. unconfirmed) microblocks required: false schema: type: boolean example: true 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 example: 60000 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 required: true schema: type: string example: "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0" - name: block_height in: query description: Optionally get the nonce at a given block height. required: false schema: type: number example: 66119 - name: block_hash in: query description: Optionally get the nonce at a given block hash. Note - Use either of the query parameters but not both at a time. required: false schema: type: string example: "0x72d53f3cba39e149dcd42708e535bdae03d73e60d2fe853aaf61c0b392f521e9" 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 required: true schema: type: string example: "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0" - name: limit in: query description: max number of account assets to fetch required: false schema: type: integer example: 20 - name: offset in: query description: index of first account assets to fetch required: false schema: type: integer example: 42000 - name: unanchored in: query description: Include transaction data from unanchored (i.e. unconfirmed) microblocks required: false schema: type: boolean example: true default: false - name: until_block in: query description: returned data representing the state at that point in time, rather than the current block. Note - Use either of the query parameters but not both at a time. required: false schema: type: string example: 60000 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 required: true schema: type: string example: "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0" - 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 example: 42000 - 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 example: true default: false - name: until_block in: query description: returned data representing the state up until that point in time, rather than the current block. Note - Use either of the query parameters but not both at a time. required: false schema: type: string example: 60000 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 /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 required: true schema: type: string example: "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0" - 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: get: summary: API status description: Retrieves the running status of the Stacks Blockchain API, including the server version and current chain tip information. 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] example: mainnet description: the target block time for a given network (testnet, mainnet). 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). **Note:** This uses the estimated future total supply for the year 2050. parameters: - in: query name: height required: false schema: type: number example: 200 description: Supply details are queried from specified block height. If the block height is not specified, the latest block height is taken as default value. Note that the `block height` is referred to the stacks blockchain. 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. **Note:** this uses the estimated future total supply for the year 2050. 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. **Note:** this uses the estimated future total supply for the year 2050. parameters: - in: query name: height required: false schema: type: number example: 200 description: Supply details are queried from specified block height. If the block height is not specified, the latest block height is taken as default value. 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 example: "0xcf8b233f19f6c07d2dc1963302d2436efd36e9afac127bf6582824a13961c06d" 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 example: $ref: ./api/rosetta/rosetta-account-network-options-request-body.example.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 example: $ref: ./api/rosetta/rosetta-account-network-options-request-body.example.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 example: $ref: ./api/rosetta/rosetta-account-balance-request-body.example.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 example: $ref: ./api/rosetta/rosetta-block-request-body.example.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 example: $ref: ./api/rosetta/rosetta-block-transaction-request-body.example.json /rosetta/v1/mempool: post: tags: - Rosetta summary: Get All Mempool Transactions operationId: rosetta_mempool description: Retrieves a list of transactions 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 example: $ref: ./api/rosetta/rosetta-account-network-options-request-body.example.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 example: $ref: ./api/rosetta/rosetta-account-identifier-publickey-request-body.example.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 example: $ref: ./api/rosetta/rosetta-hash-signed-transaction-request-schema-body.example.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 example: $ref: ./api/rosetta/rosetta-construction-metadata-request-schema-body.example.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. The examples below are illustrative only. You'll need to use your wallet to generate actual values to use them in the request payload. 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 example: $ref: ./api/rosetta/rosetta-submit-signed-transaction-request.example.json /rosetta/v1/construction/payloads: post: tags: - Rosetta summary: Generate an Unsigned Transaction and Signing Payloads operationId: rosetta_construction_payloads description: Generate an unsigned transaction from operations and metadata. The examples below are illustrative only. You'll need to use your wallet to generate actual values to use them in the request payload. 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 example: $ref: ./api/rosetta/rosetta-submit-unsigned-transaction-unsigned-payloads-request.example.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. The examples below are illustrative only. You'll need to use your wallet to generate actual values to use them in the request payload. 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 example: $ref: ./api/rosetta/rosetta-network-transaction-from-signarures-request.example.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 schema: type: string example: id responses: 200: description: Success content: application/json: schema: $ref: ./api/bns/namespace-operations/bns-get-namespace-price-response.schema.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 schema: type: string example: muneeb.id responses: 200: description: Success content: application/json: schema: $ref: ./api/bns/name-querying/bns-get-name-price-response.schema.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 schema: type: string example: id - name: page in: query description: namespace values are defaulted to page 1 with 100 results. You can query specific page results by using the 'page' query parameter. required: false schema: type: integer example: 22 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 defaulted to page 1 with 100 results. You can query specific page results by using the 'page' query parameter. required: false schema: type: integer example: 22 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 schema: type: string example: muneeb.id 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}/subdomains: get: summary: Get Name Subdomains description: Retrieves the list of subdomains for a specific name tags: - Names operationId: fetch_subdomains_list_for_name parameters: - name: name in: path description: fully-qualified name required: true schema: type: string example: id.blockstack responses: 200: description: Success content: application/json: schema: $ref: ./api/bns/subdomains/subdomains-list.schema.json example: $ref: ./api/bns/subdomains/subdomains-list.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 schema: type: string example: bar.test 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 schema: type: string example: muneeb.id - name: zoneFileHash in: path description: zone file hash required: true schema: type: string example: "b100a68235244b012854a95f9114695679002af9" 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 schema: type: string example: bitcoin - name: address in: path description: the address to lookup required: true schema: type: string example: "1QJQxDas5JhdiXhEbNS14iNjr8auFT96GP" 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 /extended/v1/tx/block/{block_hash}: get: deprecated: true operationId: get_transactions_by_block_hash summary: Transactions by block hash description: | **NOTE:** This endpoint is deprecated in favor of [Get transactions by block](/api/get-transactions-by-block). 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 example: "0x0a83d82a65460a9e711f85a44616350280040b75317dbe486a923c1131b5ff99" - name: limit in: query description: max number of transactions to fetch required: false schema: type: integer example: 10 - name: offset in: query description: index of first transaction to fetch required: false schema: type: integer example: 42000 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: deprecated: true operationId: get_transactions_by_block_height summary: Transactions by block height description: | **NOTE:** This endpoint is deprecated in favor of [Get transactions by block](/api/get-transactions-by-block). 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 example: 66119 - name: limit in: query description: max number of transactions to fetch required: false schema: type: integer example: 10 - name: offset in: query description: index of first transaction to fetch required: false schema: type: integer example: 42000 - name: unanchored in: query description: Include transaction data from unanchored (i.e. unconfirmed) microblocks required: false schema: type: boolean example: true 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 example: "SP197DVH8KTJGX4STM61QN0WJV8Y9QJWXV83ZGNR9" - name: limit in: query description: max number of transactions to fetch required: false schema: type: integer example: 90 - name: offset in: query description: index of first transaction to fetch required: false schema: type: integer example: 42000 - name: unanchored in: query description: Include transaction data from unanchored (i.e. unconfirmed) microblocks required: false schema: type: boolean example: true 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/nft/holdings: get: operationId: get_nft_holdings summary: Non-Fungible Token holdings description: | Retrieves the list of Non-Fungible Tokens owned by the given principal (STX address or Smart Contract ID). Results can be filtered by one or more asset identifiers and can include metadata about the transaction that made the principal own each token. 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: principal in: query description: token owner's STX address or Smart Contract ID required: true schema: type: string example: "SPNWZ5V2TPWGQGVDR6T7B6RQ4XMGZ4PXTEE0VQ0S.marketplace-v3" - name: asset_identifiers in: query description: identifiers of the token asset classes to filter for required: false style: form explode: true schema: type: array example: "SPQZF23W7SEYBFG5JQ496NMY0G7379SRYEDREMSV.Candy::candy" items: type: string - name: limit in: query description: max number of tokens to fetch required: false schema: type: integer default: 50 - name: offset in: query description: index of first tokens to fetch required: false schema: type: integer default: 0 example: 42000 - name: unanchored in: query description: whether or not to include tokens from unconfirmed transactions required: false schema: type: boolean example: true default: false - name: tx_metadata in: query description: whether or not to include the complete transaction metadata instead of just `tx_id`. Enabling this option can affect performance and response times. required: false schema: type: boolean default: false responses: 200: description: List of Non-Fungible Token holdings content: application/json: schema: $ref: ./api/tokens/get-non-fungible-token-holdings.schema.json examples: default: value: $ref: ./api/tokens/get-non-fungible-token-holdings.example.schema.json with transaction metadata: value: $ref: ./api/tokens/get-non-fungible-token-holdings-tx-metadata.example.schema.json /extended/v1/tokens/nft/history: get: operationId: get_nft_history summary: Non-Fungible Token history description: | Retrieves all events relevant to a Non-Fungible Token. Useful to determine the ownership history of a particular asset. 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: asset_identifier in: query description: token asset class identifier required: true schema: type: string example: "SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173.the-explorer-guild::The-Explorer-Guild" - name: value in: query description: hex representation of the token's unique value required: true schema: type: string example: "0x0100000000000000000000000000000803" - name: limit in: query description: max number of events to fetch required: false schema: type: integer default: 50 - name: offset in: query description: index of first event to fetch required: false schema: type: integer default: 0 example: 42000 - name: unanchored in: query description: whether or not to include events from unconfirmed transactions required: false schema: type: boolean default: false example: true - name: tx_metadata in: query description: whether or not to include the complete transaction metadata instead of just `tx_id`. Enabling this option can affect performance and response times. required: false schema: type: boolean default: false responses: 200: description: Non-Fungible Token event history content: application/json: schema: $ref: ./api/tokens/get-non-fungible-token-history.schema.json examples: default: value: $ref: ./api/tokens/get-non-fungible-token-history.example.schema.json with transaction metadata: value: $ref: ./api/tokens/get-non-fungible-token-history-tx-metadata.example.schema.json /extended/v1/tokens/nft/mints: get: operationId: get_nft_mints summary: Non-Fungible Token mints description: | Retrieves all mint events for a Non-Fungible Token asset class. Useful to determine which NFTs of a particular collection have been claimed. 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: asset_identifier in: query description: token asset class identifier required: true schema: type: string example: "SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173.the-explorer-guild::The-Explorer-Guild" - name: limit in: query description: max number of events to fetch required: false schema: type: integer default: 50 - name: offset in: query description: index of first event to fetch required: false schema: type: integer default: 0 example: 42000 - name: unanchored in: query description: whether or not to include events from unconfirmed transactions required: false schema: type: boolean example: true default: false - name: tx_metadata in: query description: whether or not to include the complete transaction metadata instead of just `tx_id`. Enabling this option can affect performance and response times. required: false schema: type: boolean default: false responses: 200: description: Non-Fungible Token mints content: application/json: schema: $ref: ./api/tokens/get-non-fungible-token-mints.schema.json examples: default: value: $ref: ./api/tokens/get-non-fungible-token-mints.example.schema.json with transaction metadata: value: $ref: ./api/tokens/get-non-fungible-token-mints-tx-metadata.example.schema.json /extended/v1/tokens/ft/{token}/holders: get: operationId: get_ft_holders summary: Fungible token holders description: | Retrieves the list of Fungible Token holders for a given token ID. Specify `stx` for the `token` parameter to get the list of STX holders. tags: - Fungible Tokens parameters: - name: token in: path description: fungible token identifier required: true schema: type: string examples: stx: value: stx summary: STX token ft: value: SP3Y2ZSH8P7D50B0VBTSX11S7XSG24M1VB9YFQA4K.token-aeusdc::aeUSDC summary: fungible token responses: 200: description: Fungible Token holders content: application/json: schema: $ref: ./api/tokens/get-ft-holders.schema.json example: $ref: ./api/tokens/get-ft-holders.example.json /extended/v1/fee_rate: post: operationId: fetch_fee_rate summary: Fetch fee rate deprecated: true description: | **NOTE:** This endpoint is deprecated in favor of [Get approximate fees for a given transaction](/api/get-approximate-fees-for-a-given-transaction). 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 /v2/fees/transaction: post: summary: Get approximate fees for a given transaction tags: - Fees description: | Get an estimated fee for the supplied transaction. This estimates the execution cost of the transaction, the current fee rate of the network, and returns estimates for fee amounts. * `transaction_payload` is a hex-encoded serialization of the TransactionPayload for the transaction. * `estimated_len` is an optional argument that provides the endpoint with an estimation of the final length (in bytes) of the transaction, including any post-conditions and signatures If the node cannot provide an estimate for the transaction (e.g., if the node has never seen a contract-call for the given contract and function) or if estimation is not configured on this node, a 400 response is returned. The 400 response will be a JSON error containing a `reason` field which can be one of the following: * `DatabaseError` - this Stacks node has had an internal database error while trying to estimate the costs of the supplied transaction. * `NoEstimateAvailable` - this Stacks node has not seen this kind of contract-call before, and it cannot provide an estimate yet. * `CostEstimationDisabled` - this Stacks node does not perform fee or cost estimation, and it cannot respond on this endpoint. The 200 response contains the following data: * `estimated_cost` - the estimated multi-dimensional cost of executing the Clarity VM on the provided transaction. * `estimated_cost_scalar` - a unitless integer that the Stacks node uses to compare how much of the block limit is consumed by different transactions. This value incorporates the estimated length of the transaction and the estimated execution cost of the transaction. The range of this integer may vary between different Stacks nodes. In order to compute an estimate of total fee amount for the transaction, this value is multiplied by the same Stacks node's estimated fee rate. * `cost_scalar_change_by_byte` - a float value that indicates how much the `estimated_cost_scalar` value would increase for every additional byte in the final transaction. * `estimations` - an array of estimated fee rates and total fees to pay in microSTX for the transaction. This array provides a range of estimates (default: 3) that may be used. Each element of the array contains the following fields: * `fee_rate` - the estimated value for the current fee rates in the network * `fee` - the estimated value for the total fee in microSTX that the given transaction should pay. These values are the result of computing: `fee_rate` x `estimated_cost_scalar`. If the estimated fees are less than the minimum relay fee `(1 ustx x estimated_len)`, then that minimum relay fee will be returned here instead. Note: If the final transaction's byte size is larger than supplied to `estimated_len`, then applications should increase this fee amount by: `fee_rate` x `cost_scalar_change_by_byte` x (`final_size` - `estimated_size`) operationId: post_fee_transaction requestBody: content: application/json: schema: $ref: ./api/core-node/post-fee-transaction.schema.json example: $ref: ./api/core-node/post-fee-transaction.example.json responses: 200: description: Estimated fees for the transaction content: application/json: schema: $ref: ./api/core-node/post-fee-transaction-response.schema.json example: $ref: ./api/core-node/post-fee-transaction-response.example.json /extended/v1/tx/events: get: summary: Transaction Events description: Retrieves the list of events filtered by principal (STX address or Smart Contract ID), transaction id or event types. The list of event types is ('smart_contract_log', 'stx_lock', 'stx_asset', 'fungible_token_asset', 'non_fungible_token_asset'). tags: - Transactions operationId: get_filtered_events parameters: - name: tx_id in: query description: Hash of transaction required: false example: "0x29e25515652dad41ef675bd0670964e3d537b80ec19cf6ca6f1dd65d5bc642c5" schema: type: string - name: address in: query description: Stacks address or a Contract identifier required: false schema: type: string example: "ST1HB64MAJ1MBV4CQ80GF01DZS4T1DSMX20ADCRA4" - name: limit in: query description: number of items to return required: false schema: type: integer example: 100 - name: offset in: query description: number of items to skip required: false schema: type: integer example: 42000 - name: type in: query description: Filter the events on event type required: false style: form explode: true schema: type: array example: stx_lock items: type: string enum: [smart_contract_log, stx_lock, stx_asset, fungible_token_asset, non_fungible_token_asset] responses: 200: description: Success content: application/json: schema: $ref: ./api/transaction/get-transaction-events.schema.json example: $ref: ./api/transaction/get-transaction-events.example.json /extended/beta/stacking/{pool_principal}/delegations: get: summary: Stacking pool members description: Retrieves the list of stacking pool members for a given delegator principal. tags: - Stacking operationId: get_pool_delegations parameters: - name: pool_principal in: path description: Address principal of the stacking pool delegator required: true example: "SPSCWDV3RKV5ZRN1FQD84YE1NQFEDJ9R1F4DYQ11" schema: type: string - name: after_block in: query description: If specified, only delegation events after the given block will be included required: false schema: type: integer - name: unanchored in: query description: whether or not to include Stackers from unconfirmed transactions required: false schema: type: boolean default: false example: true - name: limit in: query description: number of items to return required: false schema: type: integer example: 100 default: 100 maximum: 200 - name: offset in: query description: number of items to skip required: false schema: type: integer example: 300 default: 0 responses: 200: description: Success content: application/json: schema: $ref: ./api/stacking/get-pool-delegations.schema.json example: $ref: ./api/stacking/get-pool-delegations.example.json