openapi: 3.0.2 servers: - url: https://api.mainnet.hiro.so/ description: Mainnet - url: https://api.testnet.hiro.so/ description: Testnet - url: http://localhost:3999/ description: Local info: title: Stacks Blockchain API version: v7.3.2 description: > Welcome to the API reference overview for the [Stacks Blockchain API](https://docs.hiro.so/get-started/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: Faucets description: Endpoints to request STX or BTC tokens (not possible on Mainnet) - name: Fees description: Read-only endpoints to obtain fee details - name: Fungible Tokens description: Read-only endpoints to obtain fungible token details externalDocs: description: Stacks Documentation - Tokens url: https://docs.stacks.co/write-smart-contracts/tokens - name: Info description: Read-only endpoints to obtain network, Proof-of-Transfer, Stacking, STX token, and node information - name: Microblocks description: Read-only endpoints to obtain microblocks details externalDocs: description: Stacks Documentation - Microblocks url: https://docs.stacks.co/understand-stacks/microblocks - name: Names description: Read-only endpoints realted to the Blockchain Naming System on Stacks externalDocs: description: Stacks Documentation - Blockchain Naming System url: https://docs.stacks.co/build-apps/references/bns - name: Non-Fungible Tokens description: Read-only endpoints to obtain non-fungible token details externalDocs: description: Stacks Documentation - Tokens url: https://docs.stacks.co/write-smart-contracts/tokens - name: Rosetta description: Endpoints to support the Rosetta API open blockchain standard externalDocs: description: Hiro Documentation - Rosetta Support url: https://docs.hiro.so/get-started/stacks-blockchain-api#rosetta-support - name: Search description: Read-only endpoints to search for accounts, blocks, smart contracts, and transactions - name: Smart Contracts description: Read-only endpoints to obtain Clarity smart contract details externalDocs: description: Stacks Documentation - Clarity Smart Contracts url: https://docs.stacks.co/write-smart-contracts/overview - name: Stacking Rewards description: Read-only endpoints to obtain Stacking reward details externalDocs: description: Stacks Documentation - Stacking url: https://docs.stacks.co/understand-stacks/stacking - name: Transactions description: Endpoints to obtain transaction details and to broadcast transactions to the network externalDocs: description: Hiro Documentation - Transactions url: https://docs.hiro.so/get-started/transactions paths: /extended/v1/faucets/stx: parameters: - name: address in: query description: A valid testnet STX address required: true schema: type: string example: ST3M7N9Q9HDRM7RVP1Q26P0EE69358PZZAZD7KMXQ - name: stacking in: query description: Request the amount of STX tokens needed for individual address stacking required: false schema: type: boolean default: false post: summary: Get STX testnet tokens description: > Add 500 STX tokens to the specified testnet address. Testnet STX addresses begin with `ST`. If the `stacking` parameter is set to `true`, the faucet will add the required number of tokens for individual stacking to the specified testnet address. The endpoint returns the transaction ID, which you can use to view the transaction in the [Stacks Explorer](https://explorer.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 requestBody: content: application/json: schema: type: object properties: address: description: STX testnet address type: string stacking: description: Use required number of tokens for stacking type: boolean example: address: ST3M7N9Q9HDRM7RVP1Q26P0EE69358PZZAZD7KMXQ stacking: false responses: "200": description: Success content: application/json: schema: description: POST request that initiates a transfer of tokens to a specified testnet address title: RunFaucetResponse type: object additionalProperties: false required: - success properties: success: type: boolean description: Indicates if the faucet call was successful txId: type: string description: The transaction ID for the faucet call txRaw: type: string description: Raw transaction in hex string representation example: success: true txId: "0xf2f0402f9f4c4d43b382690c4f7b97e24d5ff5dd5c619e3615daa64dca7ef4bc" txRaw: 80800000000400164247d6f2b425ac5771423ae6c80c754f7172b0000000000000003200000000000000b400008537046ff1008368baaa3ff2235122c556b89dad4f9df0639b924cf32a44b866497e49846b24191e711b21faaae96ca0542e4a140168484740b94211cececb3303020000000000051ab52c45b1a7977204f17ac0b6f48306aea2dbb8e9000000000007a12046617563657400000000000000000000000000000000000000000000000000000000 "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: "#/paths/~1extended~1v1~1faucets~1stx/post/responses/200/content/applicat\ ion~1json/schema" example: $ref: "#/paths/~1extended~1v1~1faucets~1stx/post/responses/200/content/applicat\ ion~1json/example" "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 schema: type: array example: coinbase items: type: string enum: - coinbase - token_transfer - smart_contract - contract_call - poison_microblock - name: unanchored in: query description: Include transaction data from unanchored (i.e. unconfirmed) microblocks required: false schema: type: boolean example: true default: false responses: "200": description: List of transactions content: application/json: schema: description: GET request that returns transactions title: TransactionResults type: object required: - results - limit - offset - total additionalProperties: false properties: limit: type: integer maximum: 200 description: The number of transactions to return offset: type: integer description: The number to transactions to skip (starting at `0`) total: type: integer description: The number of transactions available results: type: array items: type: object title: Transaction description: Describes all transaction types on Stacks 2.0 blockchain anyOf: - $ref: "#/paths/~1extended~1v1~1tx~1%7Btx_id%7D/get/responses/200/content/applic\ ation~1json/schema/anyOf/0" - $ref: "#/paths/~1extended~1v1~1tx~1%7Btx_id%7D/get/responses/200/content/applic\ ation~1json/schema/anyOf/1" - $ref: "#/paths/~1extended~1v1~1tx~1%7Btx_id%7D/get/responses/200/content/applic\ ation~1json/schema/anyOf/2" - $ref: "#/paths/~1extended~1v1~1tx~1%7Btx_id%7D/get/responses/200/content/applic\ ation~1json/schema/anyOf/3" - $ref: "#/paths/~1extended~1v1~1tx~1%7Btx_id%7D/get/responses/200/content/applic\ ation~1json/schema/anyOf/4" example: limit: 10 offset: 0 total: 101922 results: - tx_id: "0x20dedbef812e44d712569224411b27324b68ab4667321a4badd5e81ba76bf0eb" nonce: 269 fee_rate: "0" sender_address: SPQXK10DBF5ECAM30XVE3EJA8DNZF3VE0BK4MKV sponsored: false post_condition_mode: deny post_conditions: [] anchor_mode: on_chain_only is_unanchored: false block_hash: "0x28a9e2749b82bdc058776781a5abd5c9a6efed38f05545a8a51152655b8e1f4b" parent_block_hash: "0x3789b75ccfe7f2acf85c3f069fd5b8f95f73aba5332fa618243957d1c\ 017a2a3" block_height: 21709 burn_block_time: 1626286436 burn_block_time_iso: 2021-07-14T18:13:56.000Z canonical: true tx_index: 0 tx_status: success tx_result: hex: "0x0703" repr: (ok true) microblock_hash: "" microblock_sequence: 2147483647 microblock_canonical: true event_count: 0 events: [] tx_type: coinbase coinbase_payload: data: "0x0000000000000000000000000000000000000000000000000000000000000000" /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: 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: description: GET request that returns transactions title: MempoolTransactionListResponse type: object additionalProperties: false required: - results - limit - offset - total properties: limit: type: integer offset: type: integer total: type: integer results: type: array items: type: object title: MempoolTransaction description: Describes all transaction types on Stacks 2.0 blockchain anyOf: - title: MempoolTokenTransferTransaction description: Describes representation of a Type-0 Stacks 2.0 transaction. https://github.com/blockstack/stacks-blockchain/blob/master/sip/sip-005-blocks-and-transactions.md#type-0-transferring-an-asset type: object allOf: - title: AbstractMempoolTransaction description: Abstract transaction. This schema makes up all properties common between all Stacks 2.0 transaction types type: object allOf: - $ref: "#/paths/~1extended~1v1~1tx~1%7Btx_id%7D/get/responses/200/content/applic\ ation~1json/schema/anyOf/0/allOf/0/allOf/0" - required: - tx_status - receipt_time - receipt_time_iso additionalProperties: false properties: tx_status: title: MempoolTransactionStatus description: Status of the transaction type: string enum: - pending - dropped_replace_by_fee - dropped_replace_across_fork - dropped_too_expensive - dropped_stale_garbage_collect receipt_time: type: number description: A unix timestamp (in seconds) indicating when the transaction broadcast was received by the node. receipt_time_iso: type: string description: An ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) timestamp indicating when the transaction broadcast was received by the node. - $ref: "#/paths/~1extended~1v1~1tx~1%7Btx_id%7D/get/responses/200/content/applic\ ation~1json/schema/anyOf/0/allOf/1" - type: object title: MempoolSmartContractTransaction description: Describes representation of a Type-1 Stacks 2.0 transaction. https://github.com/blockstack/stacks-blockchain/blob/master/sip/sip-005-blocks-and-transactions.md#type-1-instantiating-a-smart-contract allOf: - $ref: "#/paths/~1extended~1v1~1tx~1mempool/get/responses/200/content/applicatio\ n~1json/schema/properties/results/items/anyOf/0\ /allOf/0" - $ref: "#/paths/~1extended~1v1~1tx~1%7Btx_id%7D/get/responses/200/content/applic\ ation~1json/schema/anyOf/1/allOf/1" - type: object title: MempoolContractCallTransaction description: "Describes representation of a Type 2 Stacks 2.0 transaction: Contract Call" allOf: - $ref: "#/paths/~1extended~1v1~1tx~1mempool/get/responses/200/content/applicatio\ n~1json/schema/properties/results/items/anyOf/0\ /allOf/0" - $ref: "#/paths/~1extended~1v1~1tx~1%7Btx_id%7D/get/responses/200/content/applic\ ation~1json/schema/anyOf/2/allOf/1" - type: object title: MempoolPoisonMicroblockTransaction description: "Describes representation of a Type 3 Stacks 2.0 transaction: Poison Microblock" allOf: - $ref: "#/paths/~1extended~1v1~1tx~1mempool/get/responses/200/content/applicatio\ n~1json/schema/properties/results/items/anyOf/0\ /allOf/0" - $ref: "#/paths/~1extended~1v1~1tx~1%7Btx_id%7D/get/responses/200/content/applic\ ation~1json/schema/anyOf/3/allOf/1" - type: object title: MempoolCoinbaseTransaction description: "Describes representation of a Type 3 Stacks 2.0 transaction: Poison Microblock" allOf: - $ref: "#/paths/~1extended~1v1~1tx~1mempool/get/responses/200/content/applicatio\ n~1json/schema/properties/results/items/anyOf/0\ /allOf/0" - $ref: "#/paths/~1extended~1v1~1tx~1%7Btx_id%7D/get/responses/200/content/applic\ ation~1json/schema/anyOf/4/allOf/1" example: limit: 96 offset: 0 total: 5 results: - tx_id: "0xb31df5a363dad31723324cb5e0eefa04d491519fd30827a521cbc830114aa50c" tx_status: pending tx_type: token_transfer receipt_time: 1598288370 receipt_time_iso: 2020-08-24T16:59:30.000Z fee_rate: "180" sender_address: STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6 sponsored: false post_condition_mode: deny post_conditions: [] anchor_mode: any token_transfer: recipient_address: ST1GY25DM8RZV4X15X07THRZ2C5NMWPGQWKFGV87F amount: "500000" memo: "0x46617563657400000000000000000000000000000000000000000000000000000000" - tx_id: "0x5bed8e3f801cb4e2c74d2815a092f7c1c6a35f2fce4a80c80ca70848d34cb395" tx_status: pending tx_type: token_transfer receipt_time: 1598282326 receipt_time_iso: 2020-08-24T15:18:46.000Z fee_rate: "180" sender_address: ST1PS1KF93VBY5A1JV7TM66KN046KP3E3761DBSAG sponsored: false post_condition_mode: deny post_conditions: [] anchor_mode: any token_transfer: recipient_address: ST2H33S8SEY27QKEKQKR6S5PECYPKY45CQYGGQR8X amount: "1000" memo: "0x00000000000000000000000000000000000000000000000000000000000000000000" - tx_id: "0x9916036fde08a207e581cdcabc18ff55469861cb81194ab0e3e7c9a02cd5a17c" tx_status: pending tx_type: smart_contract receipt_time: 1598258958 receipt_time_iso: 2020-08-24T08:49:18.000Z fee_rate: "2000" sender_address: ST2R1XSFXYHCSFE426HP45TTD8ZWV9XHX2SRP3XA8 sponsored: false post_condition_mode: deny post_conditions: [] anchor_mode: any smart_contract: contract_id: ST2R1XSFXYHCSFE426HP45TTD8ZWV9XHX2SRP3XA8.test-loans-1 source_code: >- (define-data-var stx-loaned int 0) (define-data-var lockup-period int 0) (define-data-var stx-return int 0) (define-public (get-stx-return (stx uint) (months uint)) (ok (begin (var-set stx-loaned (to-int(stx)) (var-set lockup-period (to-int(months)) (calculate-stx-return) (print (var-get stx-return)) (transfer-to-server) ) ) ) (define-private (calculate-stx-return) (ok (begin (var-set stx-return (- (+ (* (/ (* (var-get stx-loaned) 5) 100) (var-get lockup-period)) (var-get stx-loaned)) 5)) ) ) ) (define-private (transfer-to-server) (begin (unwrap-panic (stx-transfer? (to-uint (var-get stx-loaned)) tx-sender 'ST2R1XSFXYHCSFE426HP45TTD8ZWV9XHX2SRP3XA8)) (ok (to-uint (var-get stx-loaned))) ) ) - tx_id: "0x871fb186c8d6ac6ede2822c71074d9884b593c0d7f2d0d6e8516e615484d7501" tx_status: pending tx_type: smart_contract receipt_time: 1598230365 receipt_time_iso: 2020-08-24T00:52:45.000Z fee_rate: "2000" sender_address: ST1FJGMWPGM1P7N0K3N9QEPZK5H1VDC5YWTVMEAZ1 sponsored: false post_condition_mode: deny post_conditions: [] anchor_mode: any smart_contract: contract_id: ST1FJGMWPGM1P7N0K3N9QEPZK5H1VDC5YWTVMEAZ1.contract-hook-1598230358601 source_code: > ;; ## CUSTOM FUNCTION TO EXTRACT A SUBSTRING (define-read-only (subs (source (buff 10)) (start int) (end int)) (begin (unwrap-panic (if (and (<= 0 start) (<= start 10)) (ok 1) (err "Out of bounds: start"))) (unwrap-panic (if (and (<= 0 end) (<= end 10)) (ok 1) (err "Out of bounds: end"))) (let ((temp1 (fold subs1 source {start: start, end: end, cursor: 1, data: ""}))) (let ((data (get data temp1))) data)))) ;; Call the function to extract the substring between the bounds: ;; (subs "123456789" 2 5) (define-read-only (subs1 (ch (buff 1)) (acc {data: (buff 10), start: int, end: int, cursor: int})) (let ((data (get data acc)) (start (get start acc)) (cursor (get cursor acc)) (end (get end acc))) (let ((temp2 {cursor: (+ 1 cursor), data: (default-to "" (as-max-len? (concat data (if (let ((temp3 start) (temp4 cursor) (temp5 end)) (and (<= temp3 temp4) (<= temp4 temp5))) ch "")) u10))})) {start: (get start acc), end: (get end acc), cursor: (get cursor temp2), data: (get data temp2)}))) - tx_id: "0x66df10d99d3a26018f521d60e9f744b083386c73e47ad39c394d570abee55f1f" tx_status: pending tx_type: smart_contract receipt_time: 1598230066 receipt_time_iso: 2020-08-24T00:47:46.000Z fee_rate: "2000" sender_address: ST1FJGMWPGM1P7N0K3N9QEPZK5H1VDC5YWTVMEAZ1 sponsored: false post_condition_mode: deny post_conditions: [] anchor_mode: any smart_contract: contract_id: ST1FJGMWPGM1P7N0K3N9QEPZK5H1VDC5YWTVMEAZ1.contract-hook-1598230054238 source_code: > (define-read-only (subs1 (ch (buff 1)) (acc {data: (buff 10), start: int, end: int, cursor: int})) (begin (unwrap-panic (if (and (<= 1 (get start acc)) (<= (get start acc) 10)) (ok 1) (err "Out of bounds: start"))) (unwrap-panic (if (and (<= 1 (get end acc)) (<= (get end acc) 10)) (ok 1) (err "Out of bounds: end"))) (unwrap-panic (if (and (<= 1 (get cursor acc)) (<= (get cursor acc) 10)) (ok 1) (err "Out of bounds: cursor"))) (let ((data (get data acc)) (start (get start acc)) (cursor (get cursor acc)) (end (get end acc))) (let ((temp1 {cursor: (+ 1 cursor), data: (default-to "" (as-max-len? (concat data (if (let ((temp2 start) (temp3 cursor) (temp4 end)) (and (<= temp2 temp3) (<= temp3 temp4))) ch "")) u10))})) {start: (get start acc), end: (get end acc), cursor: (get cursor temp1), data: (get data temp1)})))) - tx_id: "0x7402d8e52204d6c8cba7465e159e79750338c3ee31d4fe6ddef1d4d226304b65" nonce: 1 fee_rate: "227" sender_address: SP1HJDP35SSMYP98CG8SHMYHMZDK0A495ZCH6ARYS sponsored: false post_condition_mode: deny post_conditions: - type: stx condition_code: sent_equal_to amount: "88884500" principal: type_id: principal_standard address: SP2J6HSSDYSTM71S0K0KK4YWRKX59JN1AD52M4B59 anchor_mode: any tx_status: pending receipt_time: 1626286631 receipt_time_iso: 2021-07-14T18:17:11.000Z tx_type: contract_call contract_call: contract_id: SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE.send-many-memo function_name: send-many function_signature: (define-public (send-many (recipients (list 200 (tuple (memo (buff 34)) (to principal) (ustx uint)))))) function_args: - hex: "0x0b000000010c00000003046d656d6f020000000e357a62597346716a52336d736b71027\ 46f0516b734e97043840503dc1091661c105d32b7c5c75d0475\ 73747801000000000000000000000000054c4514" repr: (list (tuple (memo 0x357a62597346716a52336d736b71) (to SP2VK9TBG8E20A0YW228PC70GBMSBFHE7BNVMKB57) (ustx u88884500))) name: recipients type: (list 200 (tuple (memo (buff 34)) (to principal) (ustx uint))) /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: "#/paths/~1extended~1v1~1tx~1mempool/get/responses/200/content/applicatio\ n~1json/schema" example: $ref: "#/paths/~1extended~1v1~1tx~1mempool/get/responses/200/content/applicatio\ n~1json/example" /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: description: GET request that returns stats on mempool transactions title: MempoolTransactionStatsResponse type: object additionalProperties: false required: - tx_type_counts - tx_simple_fee_averages - tx_ages - tx_byte_sizes properties: tx_type_counts: type: object description: Number of tranasction in the mempool, broken down by transaction type. additionalProperties: false required: - token_transfer - smart_contract - contract_call - poison_microblock properties: token_transfer: type: number smart_contract: type: number contract_call: type: number poison_microblock: type: number tx_simple_fee_averages: type: object description: The simple mean (average) transaction fee, broken down by transaction type. Note that this does not factor in actual execution costs. The average fee is not a reliable metric for calculating a fee for a new transaction. additionalProperties: false required: - token_transfer - smart_contract - contract_call - poison_microblock properties: token_transfer: type: object additionalProperties: false required: - p25 - p50 - p75 - p95 properties: p25: type: number nullable: true p50: type: number nullable: true p75: type: number nullable: true p95: type: number nullable: true smart_contract: type: object additionalProperties: false required: - p25 - p50 - p75 - p95 properties: p25: type: number nullable: true p50: type: number nullable: true p75: type: number nullable: true p95: type: number nullable: true contract_call: type: object additionalProperties: false required: - p25 - p50 - p75 - p95 properties: p25: type: number nullable: true p50: type: number nullable: true p75: type: number nullable: true p95: type: number nullable: true poison_microblock: type: object additionalProperties: false required: - p25 - p50 - p75 - p95 properties: p25: type: number nullable: true p50: type: number nullable: true p75: type: number nullable: true p95: type: number nullable: true tx_ages: type: object description: The average time (in blocks) that transactions have lived in the mempool. The start block height is simply the current chain-tip of when the attached Stacks node receives the transaction. This timing can be different across Stacks nodes / API instances due to propagation timing differences in the p2p network. additionalProperties: false required: - token_transfer - smart_contract - contract_call - poison_microblock properties: token_transfer: type: object additionalProperties: false required: - p25 - p50 - p75 - p95 properties: p25: type: number nullable: true p50: type: number nullable: true p75: type: number nullable: true p95: type: number nullable: true smart_contract: type: object additionalProperties: false required: - p25 - p50 - p75 - p95 properties: p25: type: number nullable: true p50: type: number nullable: true p75: type: number nullable: true p95: type: number nullable: true contract_call: type: object additionalProperties: false required: - p25 - p50 - p75 - p95 properties: p25: type: number nullable: true p50: type: number nullable: true p75: type: number nullable: true p95: type: number nullable: true poison_microblock: type: object additionalProperties: false required: - p25 - p50 - p75 - p95 properties: p25: type: number nullable: true p50: type: number nullable: true p75: type: number nullable: true p95: type: number nullable: true tx_byte_sizes: type: object description: The average byte size of transactions in the mempool, broken down by transaction type. additionalProperties: false required: - token_transfer - smart_contract - contract_call - poison_microblock properties: token_transfer: type: object additionalProperties: false required: - p25 - p50 - p75 - p95 properties: p25: type: number nullable: true p50: type: number nullable: true p75: type: number nullable: true p95: type: number nullable: true smart_contract: type: object additionalProperties: false required: - p25 - p50 - p75 - p95 properties: p25: type: number nullable: true p50: type: number nullable: true p75: type: number nullable: true p95: type: number nullable: true contract_call: type: object additionalProperties: false required: - p25 - p50 - p75 - p95 properties: p25: type: number nullable: true p50: type: number nullable: true p75: type: number nullable: true p95: type: number nullable: true poison_microblock: type: object additionalProperties: false required: - p25 - p50 - p75 - p95 properties: p25: type: number nullable: true p50: type: number nullable: true p75: type: number nullable: true p95: type: number nullable: true example: tx_type_counts: token_transfer: 130 smart_contract: 2 contract_call: 310 poison_microblock: 0 tx_simple_fee_averages: token_transfer: p25: 3000 p50: 3000 p75: 6000 p95: 401199.9999999995 smart_contract: p25: 837500 p50: 925000 p75: 1012500 p95: 1082500 contract_call: p25: 3000 p50: 10368 p75: 100000 p95: 1000000 poison_microblock: ? p25 ? p50 ? p75 ? p95 tx_ages: token_transfer: p25: 167.5 p50: 45 p75: 1 p95: 0 smart_contract: p25: 185.5 p50: 129 p75: 72.5 p95: 27.30000000000001 contract_call: p25: 189 p50: 127.5 p75: 9.5 p95: 0 poison_microblock: ? p25 ? p50 ? p75 ? p95 tx_byte_sizes: token_transfer: p25: 180 p50: 180 p75: 180 p95: 180 smart_contract: p25: 706.75 p50: 814.5 p75: 922.25 p95: 1008.45 contract_call: p25: 291 p50: 435 p75: 462 p95: 597 poison_microblock: ? p25 ? p50 ? p75 ? p95 /extended/v1/tx/multiple: parameters: - name: tx_id in: query description: Array of transaction ids required: true schema: type: array example: "0x0a411719e3bfde95f9e227a2d7f8fac3d6c646b1e6cc186db0e2838a2c6cd9c0" 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: type: object title: TransactionList additionalProperties: anyOf: - type: object title: TransactionFound description: This object returns transaction for found true additionalProperties: false required: - found - result properties: found: type: boolean enum: - true result: anyOf: - $ref: "#/paths/~1extended~1v1~1tx~1mempool/get/responses/200/content/applicatio\ n~1json/schema/properties/results/items" - $ref: "#/paths/~1extended~1v1~1tx/get/responses/200/content/application~1json/s\ chema/properties/results/items" - type: object title: TransactionNotFound description: This object returns the id for not found transaction additionalProperties: false properties: found: type: boolean enum: - false result: type: object required: - tx_id additionalProperties: false properties: tx_id: type: string required: - found - result example: "0x8911000000000000000000000000000000000000000000000000000000000000": found: true result: tx_id: "0x8911000000000000000000000000000000000000000000000000000000000000" nonce: 0 fee_rate: "1234" sender_address: sender-addr sponsored: true sponsor_address: sponsor-addr post_condition_mode: allow post_conditions: [] anchor_mode: any is_unanchored: false block_hash: "0x0123" parent_block_hash: "0x5678" block_height: 0 burn_block_time: 39486 burn_block_time_iso: 1970-01-01T10:58:06.000Z parent_burn_block_time: 1626122935 parent_burn_block_time_iso: 2021-07-12T20:48:55.000Z canonical: true tx_index: 4 tx_status: success microblock_hash: "" microblock_sequence: 2147483647 microblock_canonical: true event_count: 0 events: [] execution_cost_read_count: 0 execution_cost_read_length: 0 execution_cost_runtime: 0 execution_cost_write_count: 0 execution_cost_write_length: 0 tx_type: coinbase "0x8915000000000000000000000000000000000000000000000000000000000000": found: true result: tx_id: "0x8915000000000000000000000000000000000000000000000000000000000000" nonce: 1000 fee_rate: "1234" sender_address: sender-addr sponsored: true sponsor_address: sponsor-addr post_condition_mode: allow post_conditions: [] anchor_mode: any is_unanchored: false block_hash: "0x0123" parent_block_hash: "0x5678" block_height: 0 burn_block_time: 39486 burn_block_time_iso: 1970-01-01T10:58:06.000Z parent_burn_block_time: 1626122935 parent_burn_block_time_iso: 2021-07-12T20:48:55.000Z canonical: true tx_index: 4 tx_status: success microblock_hash: "" microblock_sequence: 2147483647 microblock_canonical: true event_count: 0 events: [] execution_cost_read_count: 0 execution_cost_read_length: 0 execution_cost_runtime: 0 execution_cost_write_count: 0 execution_cost_write_length: 0 tx_type: coinbase "0x8912000000000000000000000000000000000000000000000000000000000000": found: true result: tx_id: "0x8912000000000000000000000000000000000000000000000000000000000000" nonce: 0 fee_rate: "1234" sender_address: sender-addr sponsored: false post_condition_mode: allow post_conditions: [] anchor_mode: any tx_status: pending receipt_time: 1594307695 receipt_time_iso: 2020-07-09T15:14:55.000Z tx_type: coinbase "0x8914000000000000000000000000000000000000000000000000000000000000": found: false result: tx_id: "0x8914000000000000000000000000000000000000000000000000000000000000" "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: type: object title: Transaction description: Describes all transaction types on Stacks 2.0 blockchain anyOf: - title: TokenTransferTransaction description: Describes representation of a Type-0 Stacks 2.0 transaction. https://github.com/blockstack/stacks-blockchain/blob/master/sip/sip-005-blocks-and-transactions.md#type-0-transferring-an-asset type: object allOf: - title: AbstractTransaction description: Anchored transaction metadata. All mined/anchored Stacks transactions have these properties. type: object allOf: - title: BaseTransaction description: Transaction properties that are available from a raw serialized transactions. These are available for transactions in the mempool as well as mined transactions. type: object required: - tx_id - nonce - fee_rate - sender_address - sponsored - post_condition_mode - post_conditions - anchor_mode additionalProperties: false properties: tx_id: type: string description: Transaction ID nonce: type: integer description: Used for ordering the transactions originating from and paying from an account. The nonce ensures that a transaction is processed at most once. The nonce counts the number of times an account's owner(s) have authorized a transaction. The first transaction from an account will have a nonce value equal to 0, the second will have a nonce value equal to 1, and so on. fee_rate: type: string description: Transaction fee as Integer string (64-bit unsigned integer). sender_address: type: string description: Address of the transaction initiator sponsor_nonce: type: integer sponsored: type: boolean description: Denotes whether the originating account is the same as the paying account sponsor_address: type: string post_condition_mode: title: PostConditionMode description: "" type: string enum: - allow - deny post_conditions: type: array items: title: PostCondition description: Post-conditionscan limit the damage done to a user's assets anyOf: - title: PostConditionStx type: object allOf: - type: object required: - principal additionalProperties: false properties: principal: title: PostConditionPrincipal type: object anyOf: - type: object additionalProperties: false description: Principal Origin required: - type_id properties: type_id: type: string description: String literal of type `PostConditionPrincipalType` enum: - principal_origin - type: object description: Principal Standard required: - type_id - address additionalProperties: false properties: type_id: type: string description: String literal of type `PostConditionPrincipalType` enum: - principal_standard address: type: string - type: object description: Principal Contract required: - type_id - address - contract_name additionalProperties: false properties: type_id: type: string description: String literal of type `PostConditionPrincipalType` enum: - principal_contract address: type: string contract_name: type: string - type: object required: - condition_code - amount - type additionalProperties: false properties: condition_code: title: PostConditionFungibleConditionCode description: A fungible condition code encodes a statement being made for either STX or a fungible token, with respect to the originating account. type: string enum: - sent_equal_to - sent_greater_than - sent_greater_than_or_equal_to - sent_less_than - sent_less_than_or_equal_to amount: type: string type: enum: - stx type: string - title: PostConditionFungible type: object allOf: - type: object required: - principal additionalProperties: false properties: principal: $ref: "#/paths/~1extended~1v1~1tx~1%7Btx_id%7D/get/responses/200/content/applic\ ation~1json/schema/anyOf/0/allO\ f/0/allOf/0/properties/post_con\ ditions/items/anyOf/0/allOf/0/p\ roperties/principal" - type: object required: - condition_code - amount - type - asset additionalProperties: false properties: condition_code: $ref: "#/paths/~1extended~1v1~1tx~1%7Btx_id%7D/get/responses/200/content/applic\ ation~1json/schema/anyOf/0/allO\ f/0/allOf/0/properties/post_con\ ditions/items/anyOf/0/allOf/1/p\ roperties/condition_code" type: enum: - fungible type: string amount: type: string asset: type: object required: - asset_name - contract_address - contract_name additionalProperties: false properties: asset_name: type: string contract_address: type: string contract_name: type: string - title: PostConditionNonFungible type: object allOf: - type: object required: - principal additionalProperties: false properties: principal: $ref: "#/paths/~1extended~1v1~1tx~1%7Btx_id%7D/get/responses/200/content/applic\ ation~1json/schema/anyOf/0/allO\ f/0/allOf/0/properties/post_con\ ditions/items/anyOf/0/allOf/0/p\ roperties/principal" - type: object required: - condition_code - type - asset_value - asset additionalProperties: false properties: condition_code: title: PostConditionNonFungibleConditionCode description: A non-fungible condition code encodes a statement being made about a non-fungible token, with respect to whether or not the particular non-fungible token is owned by the account. type: string enum: - sent - not_sent type: enum: - non_fungible type: string asset_value: type: object additionalProperties: false required: - hex - repr properties: hex: type: string repr: type: string asset: type: object required: - asset_name - contract_address - contract_name additionalProperties: false properties: asset_name: type: string contract_address: type: string contract_name: type: string anchor_mode: title: TransactionAnchorModeType type: string enum: - on_chain_only - off_chain_only - any description: "`on_chain_only`: the transaction MUST be included in an anchored block, `off_chain_only`: the transaction MUST be included in a microblock, `any`: the leader can choose where to include the transaction." - required: - tx_index - block_hash - block_height - burn_block_time - burn_block_time_iso - parent_burn_block_time - parent_burn_block_time_iso - canonical - tx_status - tx_result - events - event_count - parent_block_hash - is_unanchored - microblock_hash - microblock_sequence - microblock_canonical - execution_cost_read_count - execution_cost_read_length - execution_cost_runtime - execution_cost_write_count - execution_cost_write_length additionalProperties: false properties: block_hash: type: string description: Hash of the blocked this transactions was associated with block_height: type: integer description: Height of the block this transactions was associated with burn_block_time: type: integer description: Unix timestamp (in seconds) indicating when this block was mined burn_block_time_iso: type: string description: An ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) timestamp indicating when this block was mined. parent_burn_block_time: type: integer description: Unix timestamp (in seconds) indicating when this parent block was mined parent_burn_block_time_iso: type: string description: An ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) timestamp indicating when this parent block was mined. canonical: type: boolean description: Set to `true` if block corresponds to the canonical chain tip tx_index: type: integer description: Index of the transaction, indicating the order. Starts at `0` and increases with each transaction tx_status: title: TransactionStatus description: Status of the transaction type: string enum: - success - abort_by_response - abort_by_post_condition tx_result: type: object required: - hex - repr description: Result of the transaction. For contract calls, this will show the value returned by the call. For other transaction types, this will return a boolean indicating the success of the transaction. additionalProperties: false properties: hex: type: string description: Hex string representing the value fo the transaction result repr: type: string description: Readable string of the transaction result event_count: type: integer description: Number of transaction events parent_block_hash: type: string description: Hash of the previous block. is_unanchored: type: boolean description: True if the transaction is included in a microblock that has not been confirmed by an anchor block. microblock_hash: type: string description: The microblock hash that this transaction was streamed in. If the transaction was batched in an anchor block (not included within a microblock) then this value will be an empty string. microblock_sequence: type: integer description: The microblock sequence number that this transaction was streamed in. If the transaction was batched in an anchor block (not included within a microblock) then this value will be 2147483647 (0x7fffffff, the max int32 value), this value preserves logical transaction ordering on (block_height, microblock_sequence, tx_index). microblock_canonical: type: boolean description: Set to `true` if microblock is anchored in the canonical chain tip, `false` if the transaction was orphaned in a micro-fork. execution_cost_read_count: type: integer description: Execution cost read count. execution_cost_read_length: type: integer description: Execution cost read length. execution_cost_runtime: type: integer description: Execution cost runtime. execution_cost_write_count: type: integer description: Execution cost write count. execution_cost_write_length: type: integer description: Execution cost write length. events: type: array description: List of transaction events items: $ref: "#/paths/~1extended~1v1~1address~1%7Bprincipal%7D~1assets/get/responses/2\ 00/content/application~1json/schema/propert\ ies/results/items" - title: TokenTransferTransactionMetadata description: Metadata associated with token-transfer type transactions type: object required: - tx_type - token_transfer additionalProperties: false properties: tx_type: type: string enum: - token_transfer token_transfer: type: object required: - recipient_address - amount - memo additionalProperties: false properties: recipient_address: type: string amount: type: string description: Transfer amount as Integer string (64-bit unsigned integer) memo: type: string description: Hex encoded arbitrary message, up to 34 bytes length (should try decoding to an ASCII string) - type: object title: SmartContractTransaction description: Describes representation of a Type-1 Stacks 2.0 transaction. https://github.com/blockstack/stacks-blockchain/blob/master/sip/sip-005-blocks-and-transactions.md#type-1-instantiating-a-smart-contract allOf: - $ref: "#/paths/~1extended~1v1~1tx~1%7Btx_id%7D/get/responses/200/content/applic\ ation~1json/schema/anyOf/0/allOf/0" - type: object title: SmartContractTransactionMetadata description: Metadata associated with a contract-deploy type transaction. https://github.com/blockstack/stacks-blockchain/blob/master/sip/sip-005-blocks-and-transactions.md#type-1-instantiating-a-smart-contract required: - tx_type - smart_contract additionalProperties: false properties: tx_type: type: string enum: - smart_contract smart_contract: type: object additionalProperties: false required: - contract_id - source_code properties: clarity_version: type: number description: The Clarity version of the contract, only specified for versioned contract transactions, otherwise null nullable: true contract_id: type: string description: Contract identifier formatted as `.` source_code: type: string description: Clarity code of the smart contract being deployed - type: object title: ContractCallTransaction description: "Describes representation of a Type 2 Stacks 2.0 transaction: Contract Call" allOf: - $ref: "#/paths/~1extended~1v1~1tx~1%7Btx_id%7D/get/responses/200/content/applic\ ation~1json/schema/anyOf/0/allOf/0" - type: object title: ContractCallTransactionMetadata description: Metadata associated with a contract-call type transaction required: - tx_type - contract_call additionalProperties: false properties: tx_type: type: string enum: - contract_call contract_call: type: object additionalProperties: false required: - contract_id - function_name - function_signature properties: contract_id: type: string description: Contract identifier formatted as `.` function_name: type: string description: Name of the Clarity function to be invoked function_signature: type: string description: Function definition, including function name and type as well as parameter names and types function_args: type: array description: List of arguments used to invoke the function items: type: object additionalProperties: false required: - hex - repr - name - type properties: hex: type: string repr: type: string name: type: string type: type: string - type: object title: PoisonMicroblockTransaction description: "Describes representation of a Type 3 Stacks 2.0 transaction: Poison Microblock" allOf: - $ref: "#/paths/~1extended~1v1~1tx~1%7Btx_id%7D/get/responses/200/content/applic\ ation~1json/schema/anyOf/0/allOf/0" - type: object title: PoisonMicroblockTransactionMetadata description: Metadata associated with a poison-microblock type transaction required: - tx_type - poison_microblock additionalProperties: false properties: tx_type: type: string enum: - poison_microblock poison_microblock: type: object required: - microblock_header_1 - microblock_header_2 additionalProperties: false properties: microblock_header_1: type: string description: Hex encoded microblock header microblock_header_2: type: string description: Hex encoded microblock header - type: object title: CoinbaseTransaction description: "Describes representation of a Type 3 Stacks 2.0 transaction: Poison Microblock" allOf: - $ref: "#/paths/~1extended~1v1~1tx~1%7Btx_id%7D/get/responses/200/content/applic\ ation~1json/schema/anyOf/0/allOf/0" - type: object title: CoinbaseTransactionMetadata description: "Describes representation of a Type 3 Stacks 2.0 transaction: Poison Microblock" required: - tx_type - coinbase_payload additionalProperties: false properties: tx_type: type: string enum: - coinbase coinbase_payload: type: object additionalProperties: false required: - data properties: data: type: string description: Hex encoded 32-byte scratch space for block leader's use alt_recipient: type: string nullable: true description: A principal that will receive the miner rewards for this coinbase transaction. Can be either a standard principal or contract principal. Only specified for `coinbase-to-alt-recipient` transaction types, otherwise null. example: tx_id: "0x5e9f3933e358df6a73fec0d47ce3e1062c20812c129f5294e6f37a8d27c051d9" tx_status: success tx_type: coinbase fee_rate: "0" sender_address: ST3WCQ6S0DFT7YHF53M8JPKGDS1N1GSSR91677XF1 sponsored: false post_condition_mode: deny is_unanchored: false microblock_hash: "" microblock_sequence: 2147483647 microblock_canonical: true block_hash: "0x58412b50266debd0c35b1a20348ad9c0f17e5525fb155a97033256c83c9e2491" block_height: 3231 burn_block_time: 1594230455 canonical: true tx_index: 0 tx_result: hex: "0x03" repr: "true" coinbase_payload: data: "0x0000000000000000000000000000000000000000000000000000000000000000" "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: description: GET raw transaction title: GetRawTransactionResult type: object additionalProperties: false required: - raw_tx properties: raw_tx: type: string description: A hex encoded serialized transaction example: raw_tx: "0x1234" "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: description: GET request that returns transactions title: PostCoreNodeTransactionsError type: object additionalProperties: false required: - error - reason - reason_data - txid properties: error: type: string description: The error reason: type: string description: The reason for the error reason_data: type: object description: More details about the reason txid: type: string description: The relevant transaction id example: error: transaction rejected reason: BadNonce reason_data: actual: 4 expected: 0 is_origin: true principal: ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH txid: caf6fd60ae05b0c2d19ef14ab6a7670b1095d117fa7c80224c74e76214d0a791 /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: description: GET request that returns microblocks additionalProperties: false title: MicroblockListResponse type: object required: - results - limit - offset - total properties: limit: type: integer maximum: 30 description: The number of microblocks to return offset: type: integer description: The number to microblocks to skip (starting at `0`) default: 0 total: type: integer description: The number of microblocks available results: type: array items: title: Microblock description: A microblock type: object required: - canonical - microblock_canonical - microblock_hash - microblock_sequence - microblock_parent_hash - block_height - parent_block_height - parent_block_hash - block_hash - txs - parent_burn_block_time - parent_burn_block_time_iso - parent_burn_block_hash - parent_burn_block_height additionalProperties: false properties: canonical: type: boolean description: Set to `true` if the microblock corresponds to the canonical chain tip. microblock_canonical: type: boolean description: Set to `true` if the microblock was not orphaned in a following anchor block. Defaults to `true` if the following anchor block has not yet been created. microblock_hash: type: string description: The SHA512/256 hash of this microblock. microblock_sequence: type: integer description: A hint to describe how to order a set of microblocks. Starts at 0. microblock_parent_hash: type: string description: The SHA512/256 hash of the previous signed microblock in this stream. block_height: type: integer description: The anchor block height that confirmed this microblock. parent_block_height: type: integer description: The height of the anchor block that preceded this microblock. parent_block_hash: type: string description: The hash of the anchor block that preceded this microblock. parent_burn_block_hash: type: string description: The hash of the Bitcoin block that preceded this microblock. parent_burn_block_time: type: integer description: The block timestamp of the Bitcoin block that preceded this microblock. parent_burn_block_time_iso: type: string description: The ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) formatted block time of the bitcoin block that preceded this microblock. parent_burn_block_height: type: integer description: The height of the Bitcoin block that preceded this microblock. block_hash: type: string description: The hash of the anchor block that confirmed this microblock. This wil be empty for unanchored microblocks nullable: true txs: type: array description: List of transactions included in the microblock items: type: string description: Transaction ID "/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: title: Microblock description: A microblock type: object required: - canonical - microblock_canonical - microblock_hash - microblock_sequence - microblock_parent_hash - block_height - parent_block_height - parent_block_hash - block_hash - txs - parent_burn_block_time - parent_burn_block_time_iso - parent_burn_block_hash - parent_burn_block_height additionalProperties: false properties: canonical: type: boolean description: Set to `true` if the microblock corresponds to the canonical chain tip. microblock_canonical: type: boolean description: Set to `true` if the microblock was not orphaned in a following anchor block. Defaults to `true` if the following anchor block has not yet been created. microblock_hash: type: string description: The SHA512/256 hash of this microblock. microblock_sequence: type: integer description: A hint to describe how to order a set of microblocks. Starts at 0. microblock_parent_hash: type: string description: The SHA512/256 hash of the previous signed microblock in this stream. block_height: type: integer description: The anchor block height that confirmed this microblock. parent_block_height: type: integer description: The height of the anchor block that preceded this microblock. parent_block_hash: type: string description: The hash of the anchor block that preceded this microblock. parent_burn_block_hash: type: string description: The hash of the Bitcoin block that preceded this microblock. parent_burn_block_time: type: integer description: The block timestamp of the Bitcoin block that preceded this microblock. parent_burn_block_time_iso: type: string description: The ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) formatted block time of the bitcoin block that preceded this microblock. parent_burn_block_height: type: integer description: The height of the Bitcoin block that preceded this microblock. block_hash: type: string description: The hash of the anchor block that confirmed this microblock. This wil be empty for unanchored microblocks nullable: true txs: type: array description: List of transactions included in the microblock items: type: string description: Transaction ID "404": description: Cannot find microblock with given hash content: application/json: example: error: cannot find microblock by hash 0xabc123 /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: description: GET request that returns unanchored transactions additionalProperties: false title: UnanchoredTransactionListResponse type: object required: - results - total properties: total: type: integer description: The number of unanchored transactions available results: type: array items: $ref: "#/paths/~1extended~1v1~1tx/get/responses/200/content/application~1json/s\ chema/properties/results/items" /extended/v1/block: get: summary: Get recent blocks description: > 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: description: GET request that returns blocks additionalProperties: false title: BlockListResponse type: object required: - results - limit - offset - total properties: limit: type: integer maximum: 30 description: The number of blocks to return offset: type: integer description: The number to blocks to skip (starting at `0`) default: 0 total: type: integer description: The number of blocks available results: type: array items: title: Block description: A block type: object additionalProperties: false required: - canonical - height - hash - index_block_hash - parent_block_hash - txs - burn_block_time - burn_block_time_iso - burn_block_hash - burn_block_height - miner_txid - parent_microblock_hash - parent_microblock_sequence - microblocks_accepted - microblocks_streamed - execution_cost_read_count - execution_cost_read_length - execution_cost_runtime - execution_cost_write_count - execution_cost_write_length - microblock_tx_count properties: canonical: type: boolean description: Set to `true` if block corresponds to the canonical chain tip height: type: integer description: Height of the block hash: type: string description: Hash representing the block index_block_hash: type: string description: The only hash that can uniquely identify an anchored block or an unconfirmed state trie parent_block_hash: type: string description: Hash of the parent block burn_block_time: type: number description: Unix timestamp (in seconds) indicating when this block was mined. burn_block_time_iso: type: string description: An ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) indicating when this block was mined. burn_block_hash: type: string description: Hash of the anchor chain block burn_block_height: type: integer description: Height of the anchor chain block miner_txid: type: string description: Anchor chain transaction ID parent_microblock_hash: type: string description: The hash of the last streamed block that precedes this block to which this block is to be appended. Not every anchored block will have a parent microblock stream. An anchored block that does not have a parent microblock stream has the parent microblock hash set to an empty string, and the parent microblock sequence number set to -1. parent_microblock_sequence: type: integer description: The hash of the last streamed block that precedes this block to which this block is to be appended. Not every anchored block will have a parent microblock stream. An anchored block that does not have a parent microblock stream has the parent microblock hash set to an empty string, and the parent microblock sequence number set to -1. txs: type: array description: List of transactions included in the block items: type: string description: Transaction ID microblocks_accepted: type: array description: List of microblocks that were accepted in this anchor block. Not every anchored block will have a accepted all (or any) of the previously streamed microblocks. Microblocks that were orphaned are not included in this list. items: type: string description: Microblock hash microblocks_streamed: type: array description: List of microblocks that were streamed/produced by this anchor block's miner. This list only includes microblocks that were accepted in the following anchor block. Microblocks that were orphaned are not included in this list. items: type: string description: Microblock hash execution_cost_read_count: type: integer description: Execution cost read count. execution_cost_read_length: type: integer description: Execution cost read length. execution_cost_runtime: type: integer description: Execution cost runtime. execution_cost_write_count: type: integer description: Execution cost write count. execution_cost_write_length: type: integer description: Execution cost write length. microblock_tx_count: type: object description: List of txs counts in each accepted microblock additionalProperties: type: number example: limit: 1 offset: 0 total: 21707 results: - canonical: true height: 21698 hash: "0x9be3e38eab9c7d094fd51792383c66706838d6392e95bc05cc730b8f7520e352" parent_block_hash: "0x76ee36d1d6c88e56b5c0e80f0d7bc7d3492141faf1b900efb19fcd004\ 57d4654" burn_block_time: 1626281749 burn_block_time_iso: 2021-07-14T16:55:49.000Z burn_block_hash: "0x0000000000000000000ea16f8e906e85ee1cb4dff1e5424e93843b3cec8\ b0bcb" burn_block_height: 691014 miner_txid: "0x118f7122a69441d13e6a3dfd4c3b0f9950be25195bb8126aae7fadea1aa9185d" parent_microblock_hash: "0x54647c277eefe60519b407f2c897749005fdb7f831034135063b\ 2ee43fdacb04" parent_microblock_sequence: 3 txs: - "0x76f58b2eaff65a07a5971b241c4e71fee92ee0f9396809f911f9\ 0839f9004cac" - "0x32972d9052b068f218f6e13451f7aff937099b74bbf95fac7d94\ 02295b1b3941" - "0x8cd30724c02a9cc1d8879a34dc136ebfdb2008420badcfb5947b\ 92f85ebce79b" - "0xf5c1577f42d3753a508101e045dd2dc60491eb0aa552e0ecd0ad\ 37cc697143f4" - "0x35e4c20e2838f999e0cf0b40c5fabce154c2df1912a1074150d2\ 6784c53f7a20" - "0x501eb42b82e5b7a7350b47fa143cd4e90bb46d43e4a7d22830b2\ bf2aa70b7922" microblocks_accepted: - "0x54647c277eefe60519b407f2c897749005fdb7f831034135063b\ 2ee43fdacb04" - "0xdaf61d2b355f35c94cf019af99aeb73d8e7db7301c7cd693a464\ ebd1cfc2228c" - "0xb9e9b308cf9621ecbf66ca7b4689fe384b9b67c4588ec827d816\ 3ab602fb935e" - "0x754562cba6ec243f90485e97778ab472f462fd123ef5b83cc79d\ 8759ca8875f5" microblocks_streamed: - "0x54647c277eefe60519b407f2c897749005fdb7f831034135063b\ 2ee43fdacb04" - "0xdaf61d2b355f35c94cf019af99aeb73d8e7db7301c7cd693a464\ ebd1cfc2228c" - "0xb9e9b308cf9621ecbf66ca7b4689fe384b9b67c4588ec827d816\ 3ab602fb935e" - "0x754562cba6ec243f90485e97778ab472f462fd123ef5b83cc79d\ 8759ca8875f5" "/extended/v1/block/{hash}": parameters: - name: hash in: path description: Hash of the block required: true schema: type: string example: "0x4839a8b01cfb39ffcc0d07d3db31e848d5adf5279d529ed5062300b9f353ff79" get: summary: Get block by hash description: 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: title: Block description: A block type: object additionalProperties: false required: - canonical - height - hash - index_block_hash - parent_block_hash - txs - burn_block_time - burn_block_time_iso - burn_block_hash - burn_block_height - miner_txid - parent_microblock_hash - parent_microblock_sequence - microblocks_accepted - microblocks_streamed - execution_cost_read_count - execution_cost_read_length - execution_cost_runtime - execution_cost_write_count - execution_cost_write_length - microblock_tx_count properties: canonical: type: boolean description: Set to `true` if block corresponds to the canonical chain tip height: type: integer description: Height of the block hash: type: string description: Hash representing the block index_block_hash: type: string description: The only hash that can uniquely identify an anchored block or an unconfirmed state trie parent_block_hash: type: string description: Hash of the parent block burn_block_time: type: number description: Unix timestamp (in seconds) indicating when this block was mined. burn_block_time_iso: type: string description: An ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) indicating when this block was mined. burn_block_hash: type: string description: Hash of the anchor chain block burn_block_height: type: integer description: Height of the anchor chain block miner_txid: type: string description: Anchor chain transaction ID parent_microblock_hash: type: string description: The hash of the last streamed block that precedes this block to which this block is to be appended. Not every anchored block will have a parent microblock stream. An anchored block that does not have a parent microblock stream has the parent microblock hash set to an empty string, and the parent microblock sequence number set to -1. parent_microblock_sequence: type: integer description: The hash of the last streamed block that precedes this block to which this block is to be appended. Not every anchored block will have a parent microblock stream. An anchored block that does not have a parent microblock stream has the parent microblock hash set to an empty string, and the parent microblock sequence number set to -1. txs: type: array description: List of transactions included in the block items: type: string description: Transaction ID microblocks_accepted: type: array description: List of microblocks that were accepted in this anchor block. Not every anchored block will have a accepted all (or any) of the previously streamed microblocks. Microblocks that were orphaned are not included in this list. items: type: string description: Microblock hash microblocks_streamed: type: array description: List of microblocks that were streamed/produced by this anchor block's miner. This list only includes microblocks that were accepted in the following anchor block. Microblocks that were orphaned are not included in this list. items: type: string description: Microblock hash execution_cost_read_count: type: integer description: Execution cost read count. execution_cost_read_length: type: integer description: Execution cost read length. execution_cost_runtime: type: integer description: Execution cost runtime. execution_cost_write_count: type: integer description: Execution cost write count. execution_cost_write_length: type: integer description: Execution cost write length. microblock_tx_count: type: object description: List of txs counts in each accepted microblock additionalProperties: type: number example: canonical: true height: 3275 hash: "0xe77ba8cf6bb7c0e4f64adc83356289ed467d31a22354907b4bb814590058430f" index_block_hash: "0x918697ef63f9d8bdf844c3312b299e72a231cde542f3173f7755bb8c1c\ daf3a7" parent_block_hash: "0x75ab21ef25cbff2caa14c27d830ed7886a4d1522e1b6f9e5dc3b59ccf\ 73ed49f" burn_block_time: 1594233639 burn_block_time_iso: 2020-08-27T16:41:26.000Z burn_block_hash: "0xb154c008df2101023a6d0d54986b3964cee58119eed14f5bed98e15678e\ 18fe2" burn_block_height: 654439 miner_txid: "0xd7d56070277ccd87b42acf0c91f915dd181f9db4cf878a4e95518bc397c240cc" parent_microblock_hash: "0x590a1bb1d7bcbeafce0a9fc8f8a69e369486192d14687fe95fbe\ 4dc1c71d49df" parent_microblock_sequence: 2 txs: - "0x4262db117659d1ca9406970c8f44ffd3d8f11f8e18c591d2e3960f40\ 70107754" - "0x383632cd3b5464dffb684082750fcfaddd1f52625bbb9f884ed8f45d\ 2b1f0547" - "0xc99fe597e44b8bd15a50eec660c6e679a7144a5a8553d214b9d5f140\ 6d278c22" microblocks_accepted: - "0xce0b1a4099d3fc7d5885cc7a3baa952b6d999f9709d0683b98b84359\ 7208231c" - "0x4c0529b6448a5885991c5021bd869cc97f1692c128a98b382729dc96\ 2203c326" - "0x64968846291dfea1015228a9d4bbd60aac81378cd6774b810b08e59e\ 6b0e7494" microblocks_streamed: - "0xb5650ef855f7d90fc146942e85cf9fac3a8c47ec408aca02f3cf9ed7\ c82f6cc6" - "0xeeb9aa5741d84aa0bc5de4f2fbdeae57ae29694479475d45a67ae7bd\ 7e2c98f3" - "0x4f4c368d5f06fdf6065c5bafd9cb37391fddc9c279cfc57be35e4bf8\ ee932cbd" - "0xde2fc8d99872c827f144c752c002d29f9315dfc09472a09572ac7447\ ae623dea" execution_cost_read_count: 2477 execution_cost_read_length: 1659409 execution_cost_runtime: 2520952000 execution_cost_write_count: 608 execution_cost_write_length: 80170 microblock_tx_count: "0xce0b1a4099d3fc7d5885cc7a3baa952b6d999f9709d0683b98b843597208231c": 5 "0x4c0529b6448a5885991c5021bd869cc97f1692c128a98b382729dc962203c326": 6 "0x64968846291dfea1015228a9d4bbd60aac81378cd6774b810b08e59e6b0e7494": 9 "404": description: Cannot find block with given ID content: application/json: example: error: cannot find block by hash 0xabc123 "/extended/v1/block/by_height/{height}": parameters: - name: height in: path description: Height of the block required: true schema: type: number example: 10000 get: summary: Get block by height description: Retrieves block details of a specific block at a given block height tags: - Blocks operationId: get_block_by_height responses: "200": description: Block content: application/json: schema: $ref: "#/paths/~1extended~1v1~1block~1%7Bhash%7D/get/responses/200/content/appl\ ication~1json/schema" example: $ref: "#/paths/~1extended~1v1~1block~1%7Bhash%7D/get/responses/200/content/appl\ ication~1json/example" "404": description: Cannot find block with given height content: application/json: example: $ref: "#/paths/~1extended~1v1~1block~1%7Bhash%7D/get/responses/404/content/appl\ ication~1json/example" "/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 description: Retrieves block details of a specific block for a given burnchain block hash tags: - Blocks operationId: get_block_by_burn_block_hash responses: "200": description: Block content: application/json: schema: $ref: "#/paths/~1extended~1v1~1block~1%7Bhash%7D/get/responses/200/content/appl\ ication~1json/schema" example: $ref: "#/paths/~1extended~1v1~1block~1%7Bhash%7D/get/responses/200/content/appl\ ication~1json/example" "404": description: Cannot find block with given height content: application/json: example: $ref: "#/paths/~1extended~1v1~1block~1%7Bhash%7D/get/responses/404/content/appl\ ication~1json/example" "/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 description: Retrieves block details of a specific block for a given burn chain height tags: - Blocks operationId: get_block_by_burn_block_height responses: "200": description: Block content: application/json: schema: $ref: "#/paths/~1extended~1v1~1block~1%7Bhash%7D/get/responses/200/content/appl\ ication~1json/schema" example: $ref: "#/paths/~1extended~1v1~1block~1%7Bhash%7D/get/responses/200/content/appl\ ication~1json/example" "404": description: Cannot find block with given height content: application/json: example: $ref: "#/paths/~1extended~1v1~1block~1%7Bhash%7D/get/responses/404/content/appl\ ication~1json/example" /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: description: GET request that returns reward slot holders additionalProperties: false title: BurnchainRewardSlotHolderListResponse type: object required: - results - limit - offset - total properties: limit: type: integer maximum: 30 description: The number of items to return offset: type: integer description: The number of items to skip (starting at `0`) default: 0 total: type: integer description: Total number of available items results: type: array items: title: BurnchainRewardSlotHolder description: Reward slot holder on the burnchain type: object additionalProperties: false required: - canonical - burn_block_hash - burn_block_height - address - slot_index properties: canonical: type: boolean description: Set to `true` if block corresponds to the canonical burchchain tip burn_block_hash: type: string description: The hash representing the burnchain block burn_block_height: type: integer description: Height of the burnchain block address: type: string description: The recipient address that validly received PoX commitments, in the format native to the burnchain (e.g. B58 encoded for Bitcoin) slot_index: type: integer description: The index position of the reward entry, useful for ordering when there's more than one slot per burnchain block example: limit: 20 offset: 0 total: 2 results: - canonical: true burn_block_hash: "0x4eaabcd105865e471f697eff5dd5bd85d47ecb5a26a3379d74fae0ae87c\ 40904" burn_block_height: 331 address: 1C56LYirKa3PFXFsvhSESgDy2acEHVAEt6 slot_index: 0 - canonical: true burn_block_hash: "0x4eaabcd105865e471f697eff5dd5bd85d47ecb5a26a3379d74fae0ae87c\ 40904" burn_block_height: 331 address: 1M3bvWB9CRh5BTumeVxtHDEV6W4S2R9AZw slot_index: 0 "/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: "#/paths/~1extended~1v1~1burnchain~1reward_slot_holders/get/responses/200\ /content/application~1json/schema" example: $ref: "#/paths/~1extended~1v1~1burnchain~1reward_slot_holders/get/responses/200\ /content/application~1json/example" /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: description: GET request that returns blocks additionalProperties: false title: BurnchainRewardListResponse type: object required: - results - limit - offset properties: limit: type: integer maximum: 30 description: The number of burnchain rewards to return offset: type: integer description: The number to burnchain rewards to skip (starting at `0`) default: 0 results: type: array items: title: BurnchainReward description: Reward payment made on the burnchain additionalProperties: false type: object required: - canonical - burn_block_hash - burn_block_height - burn_amount - reward_recipient - reward_amount - reward_index properties: canonical: type: boolean description: Set to `true` if block corresponds to the canonical burchchain tip burn_block_hash: type: string description: The hash representing the burnchain block burn_block_height: type: integer description: Height of the burnchain block burn_amount: type: string description: The total amount of burnchain tokens burned for this burnchain block, in the smallest unit (e.g. satoshis for Bitcoin) reward_recipient: type: string description: The recipient address that received the burnchain rewards, in the format native to the burnchain (e.g. B58 encoded for Bitcoin) reward_amount: type: string description: The amount of burnchain tokens rewarded to the recipient, in the smallest unit (e.g. satoshis for Bitcoin) reward_index: type: integer description: The index position of the reward entry, useful for ordering when there's more than one recipient per burnchain block example: limit: 20 offset: 0 results: - canonical: true burn_block_hash: "0x4eaabcd105865e471f697eff5dd5bd85d47ecb5a26a3379d74fae0ae87c\ 40904" burn_block_height: 331 burn_amount: "12000" reward_recipient: 1C56LYirKa3PFXFsvhSESgDy2acEHVAEt6 reward_amount: "5000" reward_index: 0 - canonical: true burn_block_hash: "0x4eaabcd105865e471f697eff5dd5bd85d47ecb5a26a3379d74fae0ae87c\ 40904" burn_block_height: 336 burn_amount: "14000" reward_recipient: 1M3bvWB9CRh5BTumeVxtHDEV6W4S2R9AZw reward_amount: "2000" reward_index: 0 "/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: "#/paths/~1extended~1v1~1burnchain~1rewards/get/responses/200/content/app\ lication~1json/schema" example: $ref: "#/paths/~1extended~1v1~1burnchain~1rewards/get/responses/200/content/app\ lication~1json/example" "/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: title: BurnchainRewardsTotal description: Total burnchain rewards made to a recipient type: object additionalProperties: false required: - reward_recipient - reward_amount properties: reward_recipient: type: string description: The recipient address that received the burnchain rewards, in the format native to the burnchain (e.g. B58 encoded for Bitcoin) reward_amount: type: string description: The total amount of burnchain tokens rewarded to the recipient, in the smallest unit (e.g. satoshis for Bitcoin) example: reward_recipient: 1C56LYirKa3PFXFsvhSESgDy2acEHVAEt6 reward_amount: "18000" "/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: type: object title: SmartContract description: A Smart Contract Detail required: - tx_id - canonical - block_height - source_code - contract_id - abi properties: tx_id: type: string canonical: type: boolean contract_id: type: string block_height: type: integer source_code: type: string abi: type: string additionalProperties: false example: tx_id: "0xb8b822f30a063fda8f9d44a23530a562a1ed93867d5977fbb12b1c284736edbb" canonical: true contract_id: SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.btc-ft-swap block_height: 23131 source_code: "(use-trait fungible-token 'SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE.sip-010-trait-ft-s\ tandard.sip-010-trait) (define-constant expiry u100) (define-map swaps uint {sats: uint, btc-receiver: (buff 40), amount: uint, ft-receiver: (optional principal), ft-sender: principal, when: uint, done: uint, ft: principal}) (define-data-var next-id uint u0) (define-private (find-out (entry {scriptPubKey: (buff 128), value: (buff 8)}) (result {pubscriptkey: (buff 40), out: (optional {scriptPubKey: (buff 128), value: uint})})) (if (is-eq (get scriptPubKey entry) (get pubscriptkey result)) (merge result {out: (some {scriptPubKey: (get scriptPubKey entry), value: (get uint32 (unwrap-panic (contract-call? 'SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.clarity-bitcoin-li\ b-v1 read-uint32 {txbuff: (get value entry), index: u0})))})}) result)) (define-public (get-out-value (tx { version: (buff 4), ins: (list 8 {outpoint: {hash: (buff 32), index: (buff 4)}, scriptSig: (buff 256), sequence: (buff 4)}), outs: (list 8 {value: (buff 8), scriptPubKey: (buff 128)}), locktime: (buff 4)}) (pubscriptkey (buff 40))) (ok (fold find-out (get outs tx) {pubscriptkey: pubscriptkey, out: none}))) ;; create a swap between btc and fungible token (define-public (create-swap (sats uint) (btc-receiver (buff 40)) (amount uint) (ft-receiver (optional principal)) (ft )) (let ((id (var-get next-id))) (asserts! (map-insert swaps id {sats: sats, btc-receiver: btc-receiver, amount: amount, ft-receiver: ft-receiver, ft-sender: tx-sender, when: block-height, done: u0, ft: (contract-of ft)}) ERR_INVALID_ID) (var-set next-id (+ id u1)) (match (contract-call? ft transfer amount tx-sender (as-contract tx-sender) (some 0x636174616d6172616e2073776170)) success (ok id) error (err (* error u1000))))) (define-public (set-ft-receiver (id uint)) (let ((swap (unwrap! (map-get? swaps id) ERR_INVALID_ID))) (if (is-none (get ft-receiver swap)) (begin (asserts! (map-set swaps id (merge swap {ft-receiver: (some tx-sender)})) ERR_NATIVE_FAILURE) (ok true)) ERR_ALREADY_DONE))) ;; any user can cancle the swap after the expiry period (define-public (cancel (id uint) (ft )) (let ((swap (unwrap! (map-get? swaps id) ERR_INVALID_ID))) (asserts! (is-eq (contract-of ft) (get ft swap)) ERR_INVALID_FUNGIBLE_TOKEN) (asserts! (< (+ (get when swap) expiry) block-height) ERR_TOO_EARLY) (asserts! (is-eq (get done swap) u0) ERR_ALREADY_DONE) (asserts! (map-set swaps id (merge swap {done: u1})) ERR_NATIVE_FAILURE) (as-contract (contract-call? ft transfer (get amount swap) tx-sender (get ft-sender swap) (some 0x72657665727420636174616d6172616e2073776170))))) ;; any user can submit a tx that contains the swap (define-public (submit-swap (id uint) (block { version: (buff 4), parent: (buff 32), merkle-root: (buff 32), timestamp: (buff 4), nbits: (buff 4), nonce: (buff 4), height: uint }) (tx {version: (buff 4), ins: (list 8 {outpoint: {hash: (buff 32), index: (buff 4)}, scriptSig: (buff 256), sequence: (buff 4)}), outs: (list 8 {value: (buff 8), scriptPubKey: (buff 128)}), locktime: (buff 4)}) (proof { tx-index: uint, hashes: (list 12 (buff 32)), tree-depth: uint }) (ft )) (let ((swap (unwrap! (map-get? swaps id) ERR_INVALID_ID)) (tx-buff (contract-call? 'SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.clarity-bitcoin-li\ b-v1 concat-tx tx))) (match (contract-call? 'SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.clarity-bitcoin-li\ b-v1 was-tx-mined block tx-buff proof) result (begin (asserts! result ERR_VERIFICATION_FAILED) (asserts! (is-eq (get done swap) u0) ERR_ALREADY_DONE) (match (get out (unwrap! (get-out-value tx (get btc-receiver swap)) ERR_NATIVE_FAILURE)) out (if (>= (get value out) (get sats swap)) (begin (asserts! (is-eq (contract-of ft) (get ft swap)) ERR_INVALID_FUNGIBLE_TOKEN) (asserts! (map-set swaps id (merge swap {done: u1})) ERR_NATIVE_FAILURE) (as-contract (contract-call? ft transfer (get amount swap) tx-sender (unwrap! (get ft-receiver swap) ERR_NO_FT_RECEIVER) (some 0x636174616d6172616e2073776170)))) ERR_TX_VALUE_TOO_SMALL) ERR_TX_NOT_FOR_RECEIVER)) error (err (* error u1000))))) (define-constant ERR_VERIFICATION_FAILED (err u1)) (define-constant ERR_FAILED_TO_PARSE_TX (err u2)) (define-constant ERR_INVALID_ID (err u3)) (define-constant ERR_TOO_EARLY (err u4)) (define-constant ERR_TX_VALUE_TOO_SMALL (err u5)) (define-constant ERR_TX_NOT_FOR_RECEIVER (err u6)) (define-constant ERR_ALREADY_DONE (err u7)) (define-constant ERR_INVALID_FUNGIBLE_TOKEN (err u8)) (define-constant ERR_NO_FT_RECEIVER (err u9)) (define-constant ERR_NATIVE_FAILURE (err u99)) " abi: '{"maps":[{"key":"uint128","name":"swaps","value":{"tuple":[{"name":"amount","type":"uint128"},{"name":"btc-receiver","type":{"buffer":{"length":40}}},{"name":"done","type":"uint128"},{"name":"ft","type":"principal"},{"name":"ft-receiver","type":{"optional":"principal"}},{"name":"ft-sender","type":"principal"},{"name":"sats","type":"uint128"},{"name":"when","type":"uint128"}]}}],"functions":[{"args":[{"name":"entry","type":{"tuple":[{"name":"scriptPubKey","type":{"buffer":{"length":128}}},{"name":"value","type":{"buffer":{"length":8}}}]}},{"name":"result","type":{"tuple":[{"name":"out","type":{"optional":{"tuple":[{"name":"scriptPubKey","type":{"buffer":{"length":128}}},{"name":"value","type":"uint128"}]}}},{"name":"pubscriptkey","type":{"buffer":{"length":40}}}]}}],"name":"find-out","access":"private","outputs":{"type":{"tuple":[{"name":"out","type":{"optional":{"tuple":[{"name":"scriptPubKey","type":{"buffer":{"length":128}}},{"name":"value","type":"uint128"}]}}},{"name":"pubscriptkey","type":{"buffer":{"length":40}}}]}}},{"args":[{"name":"id","type":"uint128"},{"name":"ft","type":"trait_reference"}],"name":"cancel","access":"public","outputs":{"type":{"response":{"ok":"bool","error":"uint128"}}}},{"args":[{"name":"sats","type":"uint128"},{"name":"btc-receiver","type":{"buffer":{"length":40}}},{"name":"amount","type":"uint128"},{"name":"ft-receiver","type":{"optional":"principal"}},{"name":"ft","type":"trait_reference"}],"name":"create-swap","access":"public","outputs":{"type":{"response":{"ok":"uint128","error":"uint128"}}}},{"args":[{"name":"tx","type":{"tuple":[{"name":"ins","type":{"list":{"type":{"tuple":[{"name":"outpoint","type":{"tuple":[{"name":"hash","type":{"buffer":{"length":32}}},{"name":"index","type":{"buffer":{"length":4}}}]}},{"name":"scriptSig","type":{"buffer":{"length":256}}},{"name":"sequence","type":{"buffer":{"length":4}}}]},"length":8}}},{"name":"locktime","type":{"buffer":{"length":4}}},{"name":"outs","type":{"list":{"type":{"tuple":[{"name":"scriptPubKey","type":{"buffer":{"length":128}}},{"name":"value","type":{"buffer":{"length":8}}}]},"length":8}}},{"name":"version","type":{"buffer":{"length":4}}}]}},{"name":"pubscriptkey","type":{"buffer":{"length":40}}}],"name":"get-out-value","access":"public","outputs":{"type":{"response":{"ok":{"tuple":[{"name":"out","type":{"optional":{"tuple":[{"name":"scriptPubKey","type":{"buffer":{"length":128}}},{"name":"value","type":"uint128"}]}}},{"name":"pubscriptkey","type":{"buffer":{"length":40}}}]},"error":"none"}}}},{"args":[{"name":"id","type":"uint128"}],"name":"set-ft-receiver","access":"public","outputs":{"type":{"response":{"ok":"bool","error":"uint128"}}}},{"args":[{"name":"id","type":"uint128"},{"name":"block","type":{"tuple":[{"name":"height","type":"uint128"},{"name":"merkle-root","type":{"buffer":{"length":32}}},{"name":"nbits","type":{"buffer":{"length":4}}},{"name":"nonce","type":{"buffer":{"length":4}}},{"name":"parent","type":{"buffer":{"length":32}}},{"name":"timestamp","type":{"buffer":{"length":4}}},{"name":"version","type":{"buffer":{"length":4}}}]}},{"name":"tx","type":{"tuple":[{"name":"ins","type":{"list":{"type":{"tuple":[{"name":"outpoint","type":{"tuple":[{"name":"hash","type":{"buffer":{"length":32}}},{"name":"index","type":{"buffer":{"length":4}}}]}},{"name":"scriptSig","type":{"buffer":{"length":256}}},{"name":"sequence","type":{"buffer":{"length":4}}}]},"length":8}}},{"name":"locktime","type":{"buffer":{"length":4}}},{"name":"outs","type":{"list":{"type":{"tuple":[{"name":"scriptPubKey","type":{"buffer":{"length":128}}},{"name":"value","type":{"buffer":{"length":8}}}]},"length":8}}},{"name":"version","type":{"buffer":{"length":4}}}]}},{"name":"proof","type":{"tuple":[{"name":"hashes","type":{"list":{"type":{"buffer":{"length":32}},"length":12}}},{"name":"tree-depth","type":"uint128"},{"name":"tx-index","type":"uint128"}]}},{"name":"ft","type":"trait_reference"}],"name":"submit-swap","access":"public","outputs":{"type":{"response":{"ok":"bool","error":"uint128"}}}}],"variables":[{"name":"ERR_ALREADY_DONE","type":{"response":{"ok":"none","error":"uint128"}},"access":"constant"},{"name":"ERR_FAILED_TO_PARSE_TX","type":{"response":{"ok":"none","error":"uint128"}},"access":"constant"},{"name":"ERR_INVALID_FUNGIBLE_TOKEN","type":{"response":{"ok":"none","error":"uint128"}},"access":"constant"},{"name":"ERR_INVALID_ID","type":{"response":{"ok":"none","error":"uint128"}},"access":"constant"},{"name":"ERR_NATIVE_FAILURE","type":{"response":{"ok":"none","error":"uint128"}},"access":"constant"},{"name":"ERR_NO_FT_RECEIVER","type":{"response":{"ok":"none","error":"uint128"}},"access":"constant"},{"name":"ERR_TOO_EARLY","type":{"response":{"ok":"none","error":"uint128"}},"access":"constant"},{"name":"ERR_TX_NOT_FOR_RECEIVER","type":{"response":{"ok":"none","error":"uint128"}},"access":"constant"},{"name":"ERR_TX_VALUE_TOO_SMALL","type":{"response":{"ok":"none","error":"uint128"}},"access":"constant"},{"name":"ERR_VERIFICATION_FAILED","type":{"response":{"ok":"none","error":"uint128"}},"access":"constant"},{"name":"expiry","type":"uint128","access":"constant"},{"name":"next-id","type":"uint128","access":"variable"}],"fungible_tokens":[],"non_fungible_tokens":[]}' "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: description: GET list of contracts title: ContractListResponse type: object required: - results - limit - offset properties: limit: type: integer description: The number of contracts to return offset: type: integer description: The number to contracts to skip (starting at `0`) default: 0 results: type: array items: type: object title: SmartContract description: A Smart Contract Detail required: - tx_id - canonical - block_height - source_code - contract_id - abi properties: tx_id: type: string canonical: type: boolean contract_id: type: string block_height: type: integer source_code: type: string abi: type: string additionalProperties: false additionalProperties: false example: offset: 0 limit: 10 result: - tx_id: "0xb8b822f30a063fda8f9d44a23530a562a1ed93867d5977fbb12b1c284736edbb" canonical: true contract_id: SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.btc-ft-swap block_height: 23131 source_code: "(use-trait fungible-token 'SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE.sip-010-trait-\ ft-standard.sip-010-trait) (define-constant expiry u100) (define-map swaps uint {sats: uint, btc-receiver: (buff 40), amount: uint, ft-receiver: (optional principal), ft-sender: principal, when: uint, done: uint, ft: principal}) (define-data-var next-id uint u0) (define-private (find-out (entry {scriptPubKey: (buff 128), value: (buff 8)}) (result {pubscriptkey: (buff 40), out: (optional {scriptPubKey: (buff 128), value: uint})})) (if (is-eq (get scriptPubKey entry) (get pubscriptkey result)) (merge result {out: (some {scriptPubKey: (get scriptPubKey entry), value: (get uint32 (unwrap-panic (contract-call? 'SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.clarity-bitcoi\ n-lib-v1 read-uint32 {txbuff: (get value entry), index: u0})))})}) result)) (define-public (get-out-value (tx { version: (buff 4), ins: (list 8 {outpoint: {hash: (buff 32), index: (buff 4)}, scriptSig: (buff 256), sequence: (buff 4)}), outs: (list 8 {value: (buff 8), scriptPubKey: (buff 128)}), locktime: (buff 4)}) (pubscriptkey (buff 40))) (ok (fold find-out (get outs tx) {pubscriptkey: pubscriptkey, out: none}))) ;; create a swap between btc and fungible token (define-public (create-swap (sats uint) (btc-receiver (buff 40)) (amount uint) (ft-receiver (optional principal)) (ft )) (let ((id (var-get next-id))) (asserts! (map-insert swaps id {sats: sats, btc-receiver: btc-receiver, amount: amount, ft-receiver: ft-receiver, ft-sender: tx-sender, when: block-height, done: u0, ft: (contract-of ft)}) ERR_INVALID_ID) (var-set next-id (+ id u1)) (match (contract-call? ft transfer amount tx-sender (as-contract tx-sender) (some 0x636174616d6172616e2073776170)) success (ok id) error (err (* error u1000))))) (define-public (set-ft-receiver (id uint)) (let ((swap (unwrap! (map-get? swaps id) ERR_INVALID_ID))) (if (is-none (get ft-receiver swap)) (begin (asserts! (map-set swaps id (merge swap {ft-receiver: (some tx-sender)})) ERR_NATIVE_FAILURE) (ok true)) ERR_ALREADY_DONE))) ;; any user can cancle the swap after the expiry period (define-public (cancel (id uint) (ft )) (let ((swap (unwrap! (map-get? swaps id) ERR_INVALID_ID))) (asserts! (is-eq (contract-of ft) (get ft swap)) ERR_INVALID_FUNGIBLE_TOKEN) (asserts! (< (+ (get when swap) expiry) block-height) ERR_TOO_EARLY) (asserts! (is-eq (get done swap) u0) ERR_ALREADY_DONE) (asserts! (map-set swaps id (merge swap {done: u1})) ERR_NATIVE_FAILURE) (as-contract (contract-call? ft transfer (get amount swap) tx-sender (get ft-sender swap) (some 0x72657665727420636174616d6172616e2073776170))))) ;; any user can submit a tx that contains the swap (define-public (submit-swap (id uint) (block { version: (buff 4), parent: (buff 32), merkle-root: (buff 32), timestamp: (buff 4), nbits: (buff 4), nonce: (buff 4), height: uint }) (tx {version: (buff 4), ins: (list 8 {outpoint: {hash: (buff 32), index: (buff 4)}, scriptSig: (buff 256), sequence: (buff 4)}), outs: (list 8 {value: (buff 8), scriptPubKey: (buff 128)}), locktime: (buff 4)}) (proof { tx-index: uint, hashes: (list 12 (buff 32)), tree-depth: uint }) (ft )) (let ((swap (unwrap! (map-get? swaps id) ERR_INVALID_ID)) (tx-buff (contract-call? 'SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.clarity-bitcoi\ n-lib-v1 concat-tx tx))) (match (contract-call? 'SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.clarity-bitcoi\ n-lib-v1 was-tx-mined block tx-buff proof) result (begin (asserts! result ERR_VERIFICATION_FAILED) (asserts! (is-eq (get done swap) u0) ERR_ALREADY_DONE) (match (get out (unwrap! (get-out-value tx (get btc-receiver swap)) ERR_NATIVE_FAILURE)) out (if (>= (get value out) (get sats swap)) (begin (asserts! (is-eq (contract-of ft) (get ft swap)) ERR_INVALID_FUNGIBLE_TOKEN) (asserts! (map-set swaps id (merge swap {done: u1})) ERR_NATIVE_FAILURE) (as-contract (contract-call? ft transfer (get amount swap) tx-sender (unwrap! (get ft-receiver swap) ERR_NO_FT_RECEIVER) (some 0x636174616d6172616e2073776170)))) ERR_TX_VALUE_TOO_SMALL) ERR_TX_NOT_FOR_RECEIVER)) error (err (* error u1000))))) (define-constant ERR_VERIFICATION_FAILED (err u1)) (define-constant ERR_FAILED_TO_PARSE_TX (err u2)) (define-constant ERR_INVALID_ID (err u3)) (define-constant ERR_TOO_EARLY (err u4)) (define-constant ERR_TX_VALUE_TOO_SMALL (err u5)) (define-constant ERR_TX_NOT_FOR_RECEIVER (err u6)) (define-constant ERR_ALREADY_DONE (err u7)) (define-constant ERR_INVALID_FUNGIBLE_TOKEN (err u8)) (define-constant ERR_NO_FT_RECEIVER (err u9)) (define-constant ERR_NATIVE_FAILURE (err u99)) " abi: '{"maps":[{"key":"uint128","name":"swaps","value":{"tuple":[{"name":"amount","type":"uint128"},{"name":"btc-receiver","type":{"buffer":{"length":40}}},{"name":"done","type":"uint128"},{"name":"ft","type":"principal"},{"name":"ft-receiver","type":{"optional":"principal"}},{"name":"ft-sender","type":"principal"},{"name":"sats","type":"uint128"},{"name":"when","type":"uint128"}]}}],"functions":[{"args":[{"name":"entry","type":{"tuple":[{"name":"scriptPubKey","type":{"buffer":{"length":128}}},{"name":"value","type":{"buffer":{"length":8}}}]}},{"name":"result","type":{"tuple":[{"name":"out","type":{"optional":{"tuple":[{"name":"scriptPubKey","type":{"buffer":{"length":128}}},{"name":"value","type":"uint128"}]}}},{"name":"pubscriptkey","type":{"buffer":{"length":40}}}]}}],"name":"find-out","access":"private","outputs":{"type":{"tuple":[{"name":"out","type":{"optional":{"tuple":[{"name":"scriptPubKey","type":{"buffer":{"length":128}}},{"name":"value","type":"uint128"}]}}},{"name":"pubscriptkey","type":{"buffer":{"length":40}}}]}}},{"args":[{"name":"id","type":"uint128"},{"name":"ft","type":"trait_reference"}],"name":"cancel","access":"public","outputs":{"type":{"response":{"ok":"bool","error":"uint128"}}}},{"args":[{"name":"sats","type":"uint128"},{"name":"btc-receiver","type":{"buffer":{"length":40}}},{"name":"amount","type":"uint128"},{"name":"ft-receiver","type":{"optional":"principal"}},{"name":"ft","type":"trait_reference"}],"name":"create-swap","access":"public","outputs":{"type":{"response":{"ok":"uint128","error":"uint128"}}}},{"args":[{"name":"tx","type":{"tuple":[{"name":"ins","type":{"list":{"type":{"tuple":[{"name":"outpoint","type":{"tuple":[{"name":"hash","type":{"buffer":{"length":32}}},{"name":"index","type":{"buffer":{"length":4}}}]}},{"name":"scriptSig","type":{"buffer":{"length":256}}},{"name":"sequence","type":{"buffer":{"length":4}}}]},"length":8}}},{"name":"locktime","type":{"buffer":{"length":4}}},{"name":"outs","type":{"list":{"type":{"tuple":[{"name":"scriptPubKey","type":{"buffer":{"length":128}}},{"name":"value","type":{"buffer":{"length":8}}}]},"length":8}}},{"name":"version","type":{"buffer":{"length":4}}}]}},{"name":"pubscriptkey","type":{"buffer":{"length":40}}}],"name":"get-out-value","access":"public","outputs":{"type":{"response":{"ok":{"tuple":[{"name":"out","type":{"optional":{"tuple":[{"name":"scriptPubKey","type":{"buffer":{"length":128}}},{"name":"value","type":"uint128"}]}}},{"name":"pubscriptkey","type":{"buffer":{"length":40}}}]},"error":"none"}}}},{"args":[{"name":"id","type":"uint128"}],"name":"set-ft-receiver","access":"public","outputs":{"type":{"response":{"ok":"bool","error":"uint128"}}}},{"args":[{"name":"id","type":"uint128"},{"name":"block","type":{"tuple":[{"name":"height","type":"uint128"},{"name":"merkle-root","type":{"buffer":{"length":32}}},{"name":"nbits","type":{"buffer":{"length":4}}},{"name":"nonce","type":{"buffer":{"length":4}}},{"name":"parent","type":{"buffer":{"length":32}}},{"name":"timestamp","type":{"buffer":{"length":4}}},{"name":"version","type":{"buffer":{"length":4}}}]}},{"name":"tx","type":{"tuple":[{"name":"ins","type":{"list":{"type":{"tuple":[{"name":"outpoint","type":{"tuple":[{"name":"hash","type":{"buffer":{"length":32}}},{"name":"index","type":{"buffer":{"length":4}}}]}},{"name":"scriptSig","type":{"buffer":{"length":256}}},{"name":"sequence","type":{"buffer":{"length":4}}}]},"length":8}}},{"name":"locktime","type":{"buffer":{"length":4}}},{"name":"outs","type":{"list":{"type":{"tuple":[{"name":"scriptPubKey","type":{"buffer":{"length":128}}},{"name":"value","type":{"buffer":{"length":8}}}]},"length":8}}},{"name":"version","type":{"buffer":{"length":4}}}]}},{"name":"proof","type":{"tuple":[{"name":"hashes","type":{"list":{"type":{"buffer":{"length":32}},"length":12}}},{"name":"tree-depth","type":"uint128"},{"name":"tx-index","type":"uint128"}]}},{"name":"ft","type":"trait_reference"}],"name":"submit-swap","access":"public","outputs":{"type":{"response":{"ok":"bool","error":"uint128"}}}}],"variables":[{"name":"ERR_ALREADY_DONE","type":{"response":{"ok":"none","error":"uint128"}},"access":"constant"},{"name":"ERR_FAILED_TO_PARSE_TX","type":{"response":{"ok":"none","error":"uint128"}},"access":"constant"},{"name":"ERR_INVALID_FUNGIBLE_TOKEN","type":{"response":{"ok":"none","error":"uint128"}},"access":"constant"},{"name":"ERR_INVALID_ID","type":{"response":{"ok":"none","error":"uint128"}},"access":"constant"},{"name":"ERR_NATIVE_FAILURE","type":{"response":{"ok":"none","error":"uint128"}},"access":"constant"},{"name":"ERR_NO_FT_RECEIVER","type":{"response":{"ok":"none","error":"uint128"}},"access":"constant"},{"name":"ERR_TOO_EARLY","type":{"response":{"ok":"none","error":"uint128"}},"access":"constant"},{"name":"ERR_TX_NOT_FOR_RECEIVER","type":{"response":{"ok":"none","error":"uint128"}},"access":"constant"},{"name":"ERR_TX_VALUE_TOO_SMALL","type":{"response":{"ok":"none","error":"uint128"}},"access":"constant"},{"name":"ERR_VERIFICATION_FAILED","type":{"response":{"ok":"none","error":"uint128"}},"access":"constant"},{"name":"expiry","type":"uint128","access":"constant"},{"name":"next-id","type":"uint128","access":"variable"}],"fungible_tokens":[],"non_fungible_tokens":[]}' 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: type: object title: TransactionEvent anyOf: - type: object title: TransactionEventSmartContractLog description: Only present in `smart_contract` and `contract_call` tx types. allOf: - title: AbstractTransactionEvent type: object required: - event_index additionalProperties: false properties: event_index: type: integer - type: object required: - event_type - tx_id - contract_log additionalProperties: false properties: event_type: type: string enum: - smart_contract_log tx_id: type: string contract_log: type: object additionalProperties: false required: - contract_id - topic - value properties: contract_id: type: string topic: type: string value: type: object additionalProperties: false required: - hex - repr properties: hex: type: string repr: type: string - type: object title: TransactionEventStxLock description: Only present in `smart_contract` and `contract_call` tx types. allOf: - $ref: "#/paths/~1extended~1v1~1contract~1%7Bcontract_id%7D~1events/get/response\ s/200/content/application~1json/schema/anyOf/0/allOf/\ 0" - type: object required: - event_type - tx_id - stx_lock_event additionalProperties: false properties: event_type: type: string enum: - stx_lock tx_id: type: string stx_lock_event: type: object additionalProperties: false required: - locked_amount - unlock_height - locked_address properties: locked_amount: type: string unlock_height: type: integer locked_address: type: string - type: object title: TransactionEventStxAsset description: Only present in `smart_contract` and `contract_call` tx types. allOf: - $ref: "#/paths/~1extended~1v1~1contract~1%7Bcontract_id%7D~1events/get/response\ s/200/content/application~1json/schema/anyOf/0/allOf/\ 0" - type: object required: - event_type - tx_id - asset additionalProperties: false properties: event_type: type: string enum: - stx_asset tx_id: type: string asset: type: object title: TransactionEventAsset additionalProperties: false properties: asset_event_type: title: TransactionEventAssetType type: string enum: - transfer - mint - burn asset_id: type: string sender: type: string recipient: type: string amount: type: string value: type: string memo: type: string - type: object title: TransactionEventFungibleAsset allOf: - $ref: "#/paths/~1extended~1v1~1contract~1%7Bcontract_id%7D~1events/get/response\ s/200/content/application~1json/schema/anyOf/0/allOf/\ 0" - type: object required: - event_type - tx_id - asset additionalProperties: false properties: event_type: type: string enum: - fungible_token_asset tx_id: type: string asset: type: object additionalProperties: false required: - asset_event_type - asset_id - sender - recipient - amount properties: asset_event_type: type: string asset_id: type: string sender: type: string recipient: type: string amount: type: string - type: object title: TransactionEventNonFungibleAsset allOf: - $ref: "#/paths/~1extended~1v1~1contract~1%7Bcontract_id%7D~1events/get/response\ s/200/content/application~1json/schema/anyOf/0/allOf/\ 0" - type: object required: - event_type - tx_id - asset additionalProperties: false properties: event_type: type: string enum: - non_fungible_token_asset tx_id: type: string asset: type: object additionalProperties: false required: - asset_event_type - asset_id - sender - recipient - value properties: asset_event_type: type: string asset_id: type: string sender: type: string recipient: type: string value: type: object additionalProperties: false required: - hex - repr properties: hex: type: string repr: type: string example: limit: 20 offset: 0 results: - event_index: 1 event_type: smart_contract_log contract_log: contract_id: ST2P7B9G6Y55QWZJ9B93DVSEG5S6Z4PFJHB3XRKHW.hello_world topic: print value: hex: "0x02000000124576656e74212048656c6c6f20776f726c64" repr: '"Event! Hello world"' "/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: description: GET request to get contract interface title: ContractInterfaceResponse type: object additionalProperties: false required: - functions - variables - maps - fungible_tokens - non_fungible_tokens properties: functions: type: array items: type: object description: List of defined methods variables: type: array items: type: object description: List of defined variables maps: type: array items: type: object description: List of defined data-maps fungible_tokens: type: array items: type: object description: List of fungible tokens in the contract non_fungible_tokens: type: array items: type: object description: List of non-fungible tokens in the contract example: functions: - name: get-value access: public args: - name: key type: buffer: length: 32 outputs: type: response: ok: buffer: length: 32 error: int128 - name: set-value access: public args: - name: key type: buffer: length: 32 - name: value type: buffer: length: 32 outputs: type: response: ok: uint128 error: none - name: test-emit-event access: public args: [] outputs: type: response: ok: uint128 error: none - name: test-event-types access: public args: [] outputs: type: response: ok: uint128 error: none variables: - name: recipient type: principal access: constant - name: sender type: principal access: constant maps: - name: store key: - name: key type: buffer: length: 32 value: - name: value type: buffer: length: 32 fungible_tokens: - name: novel-token-19 non_fungible_tokens: - name: hello-nft type: uint128 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: description: Response of get data map entry request title: MapEntryResponse type: object additionalProperties: false required: - data properties: data: type: string description: Hex-encoded string of clarity value. It is always an optional tuple. proof: type: string description: Hex-encoded string of the MARF proof for the data example: data: "0x0a0c000000010a6d6f6e737465722d69640100000000000000000000000000000001" proof: 0x123... "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: "0x0100000000000000000000000000000095" "/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: description: GET request to get contract source title: ContractSourceResponse type: object additionalProperties: false required: - source - publish_height - proof properties: source: type: string publish_height: type: integer proof: type: string example: source: >- (define-constant sender 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) (define-constant recipient 'SM2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQVX8X0G) (define-fungible-token novel-token-19) (begin (ft-mint? novel-token-19 u12 sender)) (begin (ft-transfer? novel-token-19 u2 sender recipient)) (define-non-fungible-token hello-nft uint) (begin (nft-mint? hello-nft u1 sender)) (begin (nft-mint? hello-nft u2 sender)) (begin (nft-transfer? hello-nft u1 sender recipient)) (define-public (test-emit-event) (begin (print "Event! Hello world") (ok u1))) (begin (test-emit-event)) (define-public (test-event-types) (begin (unwrap-panic (ft-mint? novel-token-19 u3 recipient)) (unwrap-panic (nft-mint? hello-nft u2 recipient)) (unwrap-panic (stx-transfer? u60 tx-sender 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) (unwrap-panic (stx-burn? u20 tx-sender)) (ok u1))) (define-map store ((key (buff 32))) ((value (buff 32)))) (define-public (get-value (key (buff 32))) (begin (match (map-get? store ((key key))) entry (ok (get value entry)) (err 0)))) (define-public (set-value (key (buff 32)) (value (buff 32))) (begin (map-set store ((key key)) ((value value))) (ok u1))) publish_height: 3196 proof: 0000001104060000001ec4e... 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: description: GET request to get contract source title: ReadOnlyFunctionSuccessResponse type: object additionalProperties: false required: - okay properties: okay: type: boolean result: type: string cause: type: string examples: success: value: okay: true result: 0x111... fail: value: okay: false cause: Unchecked(PublicFunctionNotReadOnly(... 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: title: ReadOnlyFunctionArgs description: Describes representation of a Type-0 Stacks 2.0 transaction. https://github.com/blockstack/stacks-blockchain/blob/master/sip/sip-005-blocks-and-transactions.md#type-0-transferring-an-asset type: object additionalProperties: false required: - sender - arguments properties: sender: type: string description: The simulated tx-sender arguments: type: array description: An array of hex serialized Clarity values items: type: string example: sender: STM9EQRAB3QAKF8NKTP15WJT7VHH4EWG3DJB4W29 arguments: - "0x0100000000000000000000000000000095" "/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: description: GET request that returns address balances title: AddressBalanceResponse additionalProperties: false type: object required: - stx - fungible_tokens - non_fungible_tokens properties: stx: title: StxBalance type: object additionalProperties: false required: - balance - total_sent - total_received - total_fees_sent - total_miner_rewards_received - lock_tx_id - locked - lock_height - burnchain_lock_height - burnchain_unlock_height properties: balance: type: string total_sent: type: string total_received: type: string total_fees_sent: type: string total_miner_rewards_received: type: string lock_tx_id: type: string description: The transaction where the lock event occurred. Empty if no tokens are locked. locked: type: string description: The amount of locked STX, as string quoted micro-STX. Zero if no tokens are locked. lock_height: type: integer description: The STX chain block height of when the lock event occurred. Zero if no tokens are locked. burnchain_lock_height: type: integer description: The burnchain block height of when the lock event occurred. Zero if no tokens are locked. burnchain_unlock_height: type: integer description: The burnchain block height of when the tokens unlock. Zero if no tokens are locked. fungible_tokens: type: object additionalProperties: anyOf: - title: FtBalance type: object additionalProperties: false required: - balance - total_sent - total_received properties: balance: type: string total_sent: type: string total_received: type: string non_fungible_tokens: type: object additionalProperties: anyOf: - title: NftBalance type: object additionalProperties: false required: - count - total_sent - total_received properties: count: type: string total_sent: type: string total_received: type: string token_offering_locked: description: Token Offering Locked title: AddressTokenOfferingLocked type: object additionalProperties: false required: - total_locked - total_unlocked - unlock_schedule properties: total_locked: type: string description: Micro-STX amount still locked at current block height. total_unlocked: type: string description: Micro-STX amount unlocked at current block height. unlock_schedule: type: array items: description: Unlock schedule amount and block height title: AddressUnlockSchedule type: object additionalProperties: false required: - amount - block_height properties: amount: type: string description: Micro-STX amount locked at this block height. block_height: type: number example: stx: balance: "1000000" total_sent: "0" total_received: "1000000" lock_tx_id: "0xec94e7d20af8979b44d17a0520c126bf742b999a0fc7ddbcbe0ab21b228ecc8c" locked: "50000" lock_height: 100 burnchain_lock_height: 100 burnchain_unlock_height: 200 fungible_tokens: {} non_fungible_tokens: {} "/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: description: GET request that returns address balances title: AddressStxBalanceResponse type: object allOf: - $ref: "#/paths/~1extended~1v1~1address~1%7Bprincipal%7D~1balances/get/responses\ /200/content/application~1json/schema/properties/stx" - type: object additionalProperties: false properties: token_offering_locked: $ref: "#/paths/~1extended~1v1~1address~1%7Bprincipal%7D~1balances/get/responses\ /200/content/application~1json/schema/properties/toke\ n_offering_locked" example: balance: "1000000" total_sent: "0" total_received: "1000000" lock_tx_id: "0xec94e7d20af8979b44d17a0520c126bf742b999a0fc7ddbcbe0ab21b228ecc8c" locked: "50000" lock_height: 100 burnchain_lock_height: 100 burnchain_unlock_height: 200 "/extended/v1/address/{principal}/transactions": get: summary: Get account transactions description: > Retrieves a list of all Transactions for a given Address or Contract Identifier. More information on Transaction types can be found [here](https://docs.stacks.co/understand-stacks/transactions#types). 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. 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: description: GET request that returns account transactions title: AddressTransactionsListResponse type: object additionalProperties: false required: - results - limit - offset - total properties: limit: type: integer maximum: 30 offset: type: integer total: type: integer results: type: array items: type: object anyOf: - $ref: "#/paths/~1extended~1v1~1tx~1mempool/get/responses/200/content/applicatio\ n~1json/schema/properties/results/items" - $ref: "#/paths/~1extended~1v1~1tx/get/responses/200/content/application~1json/s\ chema/properties/results/items" example: limit: 20 offset: 0 total: 4989 results: - tx_id: "0xb16077b94222bc1466396d30df13db460864e85ce929a20aae0a2ac80b31e4e2" tx_status: success tx_type: coinbase fee_rate: "0" sender_address: ST2TJRHDHMYBQ417HFB0BDX430TQA5PXRX6495G1V sponsored: false post_condition_mode: deny block_hash: "0x83f84f814c1b00ddb672d93b97d06c8326f76746d90a979c12b69e54beb73f69" block_height: 5603 burn_block_time: 1594335838 canonical: true is_unanchored: false microblock_hash: "0x590a1bb1d7bcbeafce0a9fc8f8a69e369486192d14687fe95fbe4dc1c71\ d49df" microblock_sequence: 5 microblock_canonical: true tx_index: 0 coinbase_payload: data: "0x0000000000000000000000000000000000000000000000000000000000000000" "/extended/v1/address/{principal}/{tx_id}/with_transfers": get: summary: Get account transaction information for specific transaction description: Retrieves transaction details for a given Transaction Id `tx_id`, for a given account or contract Identifier. tags: - Accounts operationId: get_single_transaction_with_transfers parameters: - name: principal in: path description: Stacks address or a contract identifier required: true schema: type: string 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: title: AddressTransactionWithTransfers description: Transaction with STX transfers for a given address type: object additionalProperties: false required: - tx - stx_sent - stx_received - stx_transfers properties: tx: $ref: "#/paths/~1extended~1v1~1tx/get/responses/200/content/application~1json/s\ chema/properties/results/items" stx_sent: type: string description: Total sent from the given address, including the tx fee, in micro-STX as an integer string. stx_received: type: string description: Total received by the given address in micro-STX as an integer string. stx_transfers: type: array items: type: object additionalProperties: false required: - amount properties: amount: type: string description: Amount transferred in micro-STX as an integer string. sender: type: string description: Principal that sent STX. This is unspecified if the STX were minted. recipient: type: string description: Principal that received STX. This is unspecified if the STX were burned. ft_transfers: type: array items: type: object additionalProperties: false required: - amount - asset_identifier properties: asset_identifier: type: string description: Fungible Token asset identifier. amount: type: string description: Amount transferred as an integer string. This balance does not factor in possible SIP-010 decimals. sender: type: string description: Principal that sent the asset. recipient: type: string description: Principal that received the asset. nft_transfers: type: array items: type: object additionalProperties: false required: - asset_identifier - value properties: asset_identifier: type: string description: Non Fungible Token asset identifier. value: type: object description: Non Fungible Token asset value. additionalProperties: false required: - hex - repr properties: hex: type: string repr: type: string sender: type: string description: Principal that sent the asset. recipient: type: string description: Principal that received the asset. example: tx_id: "0x34d79c7cfc2fe525438736733e501a4bf0308a5556e3e080d1e2c0858aad7448" tx_type: contract_call nonce: 11 fee_rate: "346" sender_address: SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE sponsored: false post_condition_mode: deny tx_status: success block_hash: "0x13d1b4ad35c95bca209397420fb8af104d2929d91993ba056d7a1ca5470095f9" block_height: 3246 burn_block_time: 1613009951 burn_block_time_iso: 2021-02-11T02:19:11.000Z canonical: true is_unanchored: false microblock_hash: "0x590a1bb1d7bcbeafce0a9fc8f8a69e369486192d14687fe95fbe4dc1c71\ d49df" microblock_sequence: 5 microblock_canonical: true tx_index: 1 tx_result: hex: "0x0703" repr: (ok true) post_conditions: - type: stx condition_code: sent_equal_to amount: "350" principal: type_id: principal_standard address: SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE contract_call: contract_id: SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE.send-many-memo function_name: send-many function_signature: (define-public (send-many (recipients (list 200 (tuple (memo (buff 34)) (to principal) (ustx uint)))))) function_args: - hex: "0x0b000000020c00000003046d656d6f020000000966697273746d656d6f02746f05168c0\ 31b2db5895ece0cdfbf76e0b0e8af67226a6f047573747801000000\ 000000000000000000000000960c00000003046d656d6f020000000\ a7365636f6e646d656d6f02746f05168974da696d74a16d0955bc8e\ 55720dfd39e789cf047573747801000000000000000000000000000\ 000c8" repr: (list (tuple (memo 0x66697273746d656d6f) (to SP26066SDPP4NXKGCVYZQDR5GX2QPE8KADZ0YK2J7) (ustx u150)) (tuple (memo 0x7365636f6e646d656d6f) (to SP24Q9PK9DNTA2V89APY8WNBJ1QYKKSW9SWB04RJP) (ustx u200))) name: recipients type: (list 200 (tuple (memo (buff 34)) (to principal) (ustx uint))) events: [] event_count: 4 "404": description: Not found content: application/json: example: error: No matching transaction found "/extended/v1/address/{principal}/transactions_with_transfers": get: summary: Get account transactions including STX transfers for each transaction. description: Retrieve all transactions for an account or contract identifier including STX transfers for each transaction. tags: - Accounts operationId: get_account_transactions_with_transfers parameters: - name: principal in: path description: Stacks address or a Contract identifier 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: description: GET request that returns account transactions title: AddressTransactionsWithTransfersListResponse type: object additionalProperties: false required: - results - limit - offset - total properties: limit: type: integer maximum: 30 offset: type: integer total: type: integer results: type: array items: title: AddressTransactionWithTransfers description: Transaction with STX transfers for a given address type: object additionalProperties: false required: - tx - stx_sent - stx_received - stx_transfers properties: tx: $ref: "#/paths/~1extended~1v1~1tx/get/responses/200/content/application~1json/s\ chema/properties/results/items" stx_sent: type: string description: Total sent from the given address, including the tx fee, in micro-STX as an integer string. stx_received: type: string description: Total received by the given address in micro-STX as an integer string. stx_transfers: type: array items: type: object additionalProperties: false required: - amount properties: amount: type: string description: Amount transferred in micro-STX as an integer string. sender: type: string description: Principal that sent STX. This is unspecified if the STX were minted. recipient: type: string description: Principal that received STX. This is unspecified if the STX were burned. ft_transfers: type: array items: type: object additionalProperties: false required: - amount - asset_identifier properties: asset_identifier: type: string description: Fungible Token asset identifier. amount: type: string description: Amount transferred as an integer string. This balance does not factor in possible SIP-010 decimals. sender: type: string description: Principal that sent the asset. recipient: type: string description: Principal that received the asset. nft_transfers: type: array items: type: object additionalProperties: false required: - asset_identifier - value properties: asset_identifier: type: string description: Non Fungible Token asset identifier. value: type: object description: Non Fungible Token asset value. additionalProperties: false required: - hex - repr properties: hex: type: string repr: type: string sender: type: string description: Principal that sent the asset. recipient: type: string description: Principal that received the asset. example: limit: 20 offset: 0 total: 2 results: - tx: tx_id: "0x34d79c7cfc2fe525438736733e501a4bf0308a5556e3e080d1e2c0858aad7448" tx_type: contract_call nonce: 11 fee_rate: "346" sender_address: SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE sponsored: false post_condition_mode: deny tx_status: success block_hash: "0x13d1b4ad35c95bca209397420fb8af104d2929d91993ba056d7a1ca5470095f9" block_height: 3246 burn_block_time: 1613009951 burn_block_time_iso: 2021-02-11T02:19:11.000Z canonical: true is_unanchored: false microblock_hash: "0x590a1bb1d7bcbeafce0a9fc8f8a69e369486192d14687fe95fbe4dc1c71\ d49df" microblock_sequence: 5 microblock_canonical: true tx_index: 1 tx_result: hex: "0x0703" repr: (ok true) post_conditions: - type: stx condition_code: sent_equal_to amount: "350" principal: type_id: principal_standard address: SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE contract_call: contract_id: SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE.send-many-memo function_name: send-many function_signature: (define-public (send-many (recipients (list 200 (tuple (memo (buff 34)) (to principal) (ustx uint)))))) function_args: - hex: "0x0b000000020c00000003046d656d6f020000000966697273746d656d6f02746f05168c0\ 31b2db5895ece0cdfbf76e0b0e8af67226a6f047573747801\ 000000000000000000000000000000960c00000003046d656\ d6f020000000a7365636f6e646d656d6f02746f05168974da\ 696d74a16d0955bc8e55720dfd39e789cf047573747801000\ 000000000000000000000000000c8" repr: (list (tuple (memo 0x66697273746d656d6f) (to SP26066SDPP4NXKGCVYZQDR5GX2QPE8KADZ0YK2J7) (ustx u150)) (tuple (memo 0x7365636f6e646d656d6f) (to SP24Q9PK9DNTA2V89APY8WNBJ1QYKKSW9SWB04RJP) (ustx u200))) name: recipients type: (list 200 (tuple (memo (buff 34)) (to principal) (ustx uint))) events: [] event_count: 4 stx_sent: "696" stx_received: "0" stx_transfers: - amount: "200" sender: SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE recipient: SP24Q9PK9DNTA2V89APY8WNBJ1QYKKSW9SWB04RJP - amount: "150" sender: SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE recipient: SP26066SDPP4NXKGCVYZQDR5GX2QPE8KADZ0YK2J7 ft_transfers: - amount: "103" asset_identifier: SP466FNC0P7JWTNM2R9T199QRZN1MYEDTAR0KP27.miamicoin-token::miamicoin sender: SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE recipient: SP24Q9PK9DNTA2V89APY8WNBJ1QYKKSW9SWB04RJP nft_transfers: - asset_identifier: SP497E7RX3233ATBS2AB9G4WTHB63X5PBSP5VGAQ.boom-nfts::boom value: hex: "0x00" repr: "0" sender: SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE recipient: SP24Q9PK9DNTA2V89APY8WNBJ1QYKKSW9SWB04RJP - tx: tx_id: "0x628045bff13658396277d618e9a3e4d468a4b3876eff4941d2f13ed88cd7abb7" tx_type: token_transfer nonce: 8 fee_rate: "180" sender_address: SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE sponsored: false post_condition_mode: deny tx_status: success block_hash: "0x2b8599696f64e2456c67b1ab5e63078f99d87bd1d903c37fdcfd73b1890a7551" block_height: 1761 burn_block_time: 1611968237 burn_block_time_iso: 2021-01-30T00:57:17.000Z canonical: true is_unanchored: false microblock_hash: "" microblock_sequence: 2147483647 microblock_canonical: true tx_index: 2 tx_result: hex: "0x0703" repr: (ok true) token_transfer: recipient_address: SPRSM0R2JZWBCZ39NQBARWTMX9TE99K3JK8D5KMX amount: "100000" memo: "0x57656c636f6d6520746f20426f6f6d2e000000000000000000000000000000000000" events: [] event_count: 1 stx_sent: "100180" stx_received: "0" stx_transfers: - amount: "100000" sender: SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE recipient: SPRSM0R2JZWBCZ39NQBARWTMX9TE99K3JK8D5KMX ft_transfers: [] nft_transfers: [] "/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: description: The latest nonce values used by an account by inspecting the mempool, microblock transactions, and anchored transactions title: AddressNonces type: object additionalProperties: false required: - last_mempool_tx_nonce - last_executed_tx_nonce - possible_next_nonce - detected_missing_nonces properties: last_mempool_tx_nonce: type: integer nullable: true description: The latest nonce found within mempool transactions sent by this address. Will be null if there are no current mempool transactions for this address. last_executed_tx_nonce: type: integer nullable: true description: The latest nonce found within transactions sent by this address, including unanchored microblock transactions. Will be null if there are no current transactions for this address. possible_next_nonce: type: integer description: The likely nonce required for creating the next transaction, based on the last nonces seen by the API. This can be incorrect if the API's mempool or transactions aren't fully synchronized, even by a small amount, or if a previous transaction is still propagating through the Stacks blockchain network when this endpoint is called. detected_missing_nonces: type: array description: Nonces that appear to be missing and likely causing a mempool transaction to be stuck. items: type: integer detected_mempool_nonces: type: array description: Nonces currently in mempool for this address. items: type: integer example: last_mempool_tx_nonce: 5 last_executed_tx_nonce: 2 possible_next_nonce: 6 detected_missing_nonces: - 3 - 4 detected_mempool_nonces: [] "/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: description: GET request that returns address assets title: AddressAssetsListResponse type: object additionalProperties: false required: - results - limit - offset - total properties: limit: type: integer maximum: 30 offset: type: integer total: type: integer results: type: array items: type: object title: TransactionEvent anyOf: - $ref: "#/paths/~1extended~1v1~1contract~1%7Bcontract_id%7D~1events/get/response\ s/200/content/application~1json/schema/anyOf/0" - $ref: "#/paths/~1extended~1v1~1contract~1%7Bcontract_id%7D~1events/get/response\ s/200/content/application~1json/schema/anyOf/1" - $ref: "#/paths/~1extended~1v1~1contract~1%7Bcontract_id%7D~1events/get/response\ s/200/content/application~1json/schema/anyOf/2" - $ref: "#/paths/~1extended~1v1~1contract~1%7Bcontract_id%7D~1events/get/response\ s/200/content/application~1json/schema/anyOf/3" - $ref: "#/paths/~1extended~1v1~1contract~1%7Bcontract_id%7D~1events/get/response\ s/200/content/application~1json/schema/anyOf/4" example: limit: 20 offset: 0 total: 0 results: - event_index: 0 event_type: stx_asset tx_id: "0xb31df5a363dad31723324cb5e0eefa04d491519fd30827a521cbc830114aa50c" asset: asset_event_type: transfer sender: STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6 recipient: ST2TJRHDHMYBQ417HFB0BDX430TQA5PXRX6495G1V amount: "500000" "/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: description: GET request that returns a list of inbound STX transfers with a memo title: AddressStxInboundListResponse additionalProperties: false type: object required: - results - limit - offset - total properties: limit: type: integer maximum: 30 offset: type: integer total: type: integer results: type: array items: title: InboundStxTransfer description: A inbound STX transfer with a memo type: object additionalProperties: false required: - sender - amount - memo - block_height - tx_id - transfer_type - tx_index properties: sender: type: string description: Principal that sent this transfer amount: type: string description: Transfer amount in micro-STX as integer string memo: type: string description: Hex encoded memo bytes associated with the transfer block_height: type: number description: Block height at which this transfer occurred tx_id: type: string description: The transaction ID in which this transfer occurred transfer_type: type: string enum: - bulk-send - stx-transfer - stx-transfer-memo description: Indicates if the transfer is from a stx-transfer transaction or a contract-call transaction tx_index: type: number description: Index of the transaction within a block example: limit: 20 offset: 0 total: 0 results: - sender: ST1RZG804V6Y0N4XHQD3ZE2GE3XSCV3VHRKMA3GB0 amount: "123456789" memo: "0x00000000000000000000000000000000000000000000000000000000000000000000" block_height: 12345 tx_id: "0x29e25515652dad41ef675bd0670964e3d537b80ec19cf6ca6f1dd65d5bc642c5" transfer_type: bulk-send tx_index: 3 "/extended/v1/address/{principal}/nft_events": get: summary: Get nft events deprecated: true description: > **NOTE:** This endpoint is deprecated in favor of [Non-Fungible Token holdings](#operation/get_nft_holdings). Retrieves a list of all nfts owned by an address, contains the clarity value of the identifier of the nft. tags: - Accounts operationId: get_account_nft parameters: - name: principal in: path description: Stacks address or a Contract identifier 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: 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: type: object title: AddressNftListResponse additionalProperties: false required: - limit - offset - total - nft_events properties: limit: type: integer offset: type: integer total: type: integer nft_events: type: array items: type: object title: NftEvent additionalProperties: false required: - asset_identifier - value - tx_id - tx_index - event_index - block_height - asset_event_type properties: sender: type: string recipient: type: string asset_identifier: type: string asset_event_type: type: string value: type: object required: - hex - repr description: Identifier of the NFT additionalProperties: false properties: hex: type: string description: Hex string representing the identifier of the NFT repr: type: string description: Readable string of the NFT identifier tx_id: type: string tx_index: type: number block_height: type: number event_index: type: number example: limit: 20 offset: 0 total: 1 nft_events: - sender: none recipient: ST1HB64MAJ1MBV4CQ80GF01DZS4T1DSMX20ADCRA4 asset_identifier: some-asset value: hex: "0x00" repr: "0" "/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: description: GET request for account data title: AccountDataResponse type: object additionalProperties: false required: - balance - locked - unlock_height - nonce - balance_proof - nonce_proof properties: balance: type: string locked: type: string unlock_height: type: integer nonce: type: integer balance_proof: type: string nonce_proof: type: string example: balance: "0x0000000000000000000000000007a120" locked: "0x0000000000000000000000000007a120" unlock_height: 126 nonce: 2867 balance_proof: "0xabce" nonce_proof: "0xabcd" /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: description: GET fee estimates title: CoreNodeFeeResponse type: string additionalProperties: false example: 1 /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: description: GET request that core node information title: CoreNodeInfoResponse type: object additionalProperties: false required: - peer_version - pox_consensus - burn_block_height - stable_pox_consensus - stable_burn_block_height - server_version - network_id - parent_network_id - stacks_tip_height - stacks_tip - stacks_tip_consensus_hash - unanchored_tip - exit_at_block_height properties: peer_version: type: integer description: identifies the version number for the networking communication, this should not change while a node is running, and will only change if there's an upgrade pox_consensus: type: string description: is a hash used to identify the burnchain view for a node. it incorporates bitcoin chain information and PoX information. nodes that disagree on this value will appear to each other as forks. this value will change after every block burn_block_height: type: integer description: latest bitcoin chain height stable_pox_consensus: type: string description: same as burn_consensus, but evaluated at stable_burn_block_height stable_burn_block_height: type: integer description: leftover from stacks 1.0, basically always burn_block_height - 1 server_version: type: string description: is a version descriptor network_id: type: integer description: is similar to peer_version and will be used to differentiate between different testnets. this value will be different between mainnet and testnet. once launched, this value will not change parent_network_id: type: integer description: same as network_id, but for bitcoin stacks_tip_height: type: integer description: the latest Stacks chain height. Stacks forks can occur independent of the Bitcoin chain, that height doesn't increase 1-to-1 with the Bitcoin height stacks_tip: type: string description: the best known block hash for the Stack chain (not including any pending microblocks) stacks_tip_consensus_hash: type: string description: the burn chain (i.e., bitcoin) consensus hash at the time that stacks_tip was mined unanchored_tip: type: string description: the latest microblock hash if any microblocks were processed. if no microblock has been processed for the current block, a 000.., hex array is returned exit_at_block_height: type: integer description: the block height at which the testnet network will be reset. not applicable for mainnet example: peer_version: 385875968 pox_consensus: 17f76e597bab45646956f38dd39573085d72cbc0 burn_block_height: 16 stable_pox_consensus: 8e0561978fc5506b68a589c402dad97e862edb59 stable_burn_block_height: 15 server_version: blockstack-core 0.0.1 => 23.0.0.0 (, release build, linux [x86_64]) network_id: 2147483648 parent_network_id: 3669344250 stacks_tip_height: 15 stacks_tip: b1807a2d3f7f8c7922f7c1d60d7c34145ade05d789640dc7dc9ec1021e07bb54 stacks_tip_consensus_hash: 17f76e597bab45646956f38dd39573085d72cbc0 unanchored_tip: "00000000000000000000000000000000000000000000000000000000000000\ 00" exit_at_block_height: null /extended/v1/status: 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: description: GET blockchain API status title: ServerStatusResponse type: object additionalProperties: false required: - status properties: server_version: type: string description: the server version that is currently running status: type: string description: the current server status pox_v1_unlock_height: type: integer nullable: true pox_v2_unlock_height: type: integer nullable: true chain_tip: title: ChainTip description: Current chain tip information type: object additionalProperties: false required: - block_height - block_hash - index_block_hash - burn_block_height properties: block_height: type: integer description: the current block height block_hash: type: string description: the current block hash index_block_hash: type: string description: the current index block hash microblock_hash: type: string description: the current microblock hash microblock_sequence: type: integer description: the current microblock sequence number burn_block_height: type: integer description: the current burn chain block height example: server_version: stacks-blockchain-api v1.0.7 (master:77b25878) status: ready chain_tip: block_height: 48902 block_hash: "0xa5a2923c405f8356925213bb8c479beb06d3b68ca66dd2b7397b54f8c08c5eac" index_block_hash: "0xf46401bf3cb6a6b6181536b7de414a1fd9e004a6ece99a05de72a781b1\ 7f9819" microblock_hash: "0xec89a572d3583b959e490bc45e0f521b775ed51d7ed13087b6df8eb82cb\ e75d3" microblock_sequence: 0 /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: testnet: target_block_time: 120 mainnet: target_block_time: 600 schema: description: GET request that returns network target block times title: NetworkBlockTimesResponse type: object additionalProperties: false required: - mainnet - testnet properties: mainnet: title: TargetBlockTime type: object additionalProperties: false required: - target_block_time properties: target_block_time: type: integer testnet: $ref: "#/paths/~1extended~1v1~1info~1network_block_times/get/responses/200/cont\ ent/application~1json/schema/properties/mainnet" "/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: target_block_time: 600 schema: $ref: "#/paths/~1extended~1v1~1info~1network_block_times/get/responses/200/cont\ ent/application~1json/schema/properties/mainnet" /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: unlocked_percent: "71.99" total_stx: "1352464600.000000" unlocked_stx: "973705260.219817" block_height: 3210 schema: description: GET request that returns network target block times title: GetStxSupplyResponse type: object additionalProperties: false required: - unlocked_percent - total_stx - unlocked_stx - block_height properties: unlocked_percent: type: string description: String quoted decimal number of the percentage of STX that have unlocked total_stx: type: string description: String quoted decimal number of the total possible number of STX unlocked_stx: type: string description: String quoted decimal number of the STX that have been mined or unlocked block_height: type: integer description: The block height at which this information was queried /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: description: GET request that returns network target block times title: GetStxTotalSupplyPlainResponse type: string /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: description: GET request that returns network target block times title: GetStxCirculatingSupplyPlainResponse type: string /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: unlockedPercent: "71.99" totalStacks: "1352464600.000000" totalStacksFormatted: 1,352,464,600.000000 unlockedSupply: "973705260.219817" unlockedSupplyFormatted: 973,705,260.219817 blockHeight: "665746" schema: description: GET request that returns network target block times title: GetStxSupplyLegacyFormatResponse type: object additionalProperties: false required: - unlockedPercent - totalStacks - totalStacksFormatted - unlockedSupply - unlockedSupplyFormatted - blockHeight properties: unlockedPercent: type: string description: String quoted decimal number of the percentage of STX that have unlocked totalStacks: type: string description: String quoted decimal number of the total possible number of STX totalStacksFormatted: type: string description: Same as `totalStacks` but formatted with comma thousands separators unlockedSupply: type: string description: String quoted decimal number of the STX that have been mined or unlocked unlockedSupplyFormatted: type: string description: Same as `unlockedSupply` but formatted with comma thousands separators blockHeight: type: string description: The block height at which this information was queried /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: description: Get Proof of Transfer (PoX) information title: CoreNodePoxResponse type: object additionalProperties: false required: - contract_id - first_burnchain_block_height - min_amount_ustx - registration_window_length - rejection_fraction - reward_cycle_id - reward_cycle_length - rejection_votes_left_required - total_liquid_supply_ustx properties: contract_id: type: string first_burnchain_block_height: type: integer min_amount_ustx: type: integer registration_window_length: type: integer rejection_fraction: type: integer reward_cycle_id: type: integer reward_cycle_length: type: integer rejection_votes_left_required: type: integer total_liquid_supply_ustx: type: integer example: contract_id: SP000000000000000000002Q6VF78.pox pox_activation_threshold_ustx: 67694186237302 first_burnchain_block_height: 666050 prepare_phase_block_length: 100 reward_phase_block_length: 2000 reward_slots: 4000 rejection_fraction: 25 total_liquid_supply_ustx: 1353883724746042 current_cycle: id: 50 min_threshold_ustx: 100000000000 stacked_ustx: 391056240478955 is_pox_active: true next_cycle: id: 51 min_threshold_ustx: 90000000000 min_increment_ustx: 67694186237 stacked_ustx: 350473977597161 prepare_phase_start_block_height: 773050 blocks_until_prepare_phase: 227 reward_phase_start_block_height: 773150 blocks_until_reward_phase: 327 ustx_until_pox_rejection: 338470931186500 min_amount_ustx: 90000000000 prepare_cycle_length: 100 reward_cycle_id: 50 reward_cycle_length: 2100 rejection_votes_left_required: 338470931186500 next_reward_cycle_in: 327 "/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: type: object title: SearchResult description: complete search result for terms additionalProperties: false anyOf: - type: object title: SearchErrorResult description: Error search result required: - found - result - error additionalProperties: false properties: found: type: boolean description: Indicates if the requested object was found or not default: false result: type: object required: - entity_type additionalProperties: false properties: entity_type: type: string description: Shows the currenty category of entity it is searched in. enum: - standard_address - unknown_hash - contract_address - invalid_term error: type: string - type: object title: SearchSuccessResult description: Search success result additionalProperties: false anyOf: - type: object title: AddressSearchResult description: Address search result required: - found - result additionalProperties: false properties: found: type: boolean description: Indicates if the requested object was found or not default: true result: type: object description: This object carries the search result required: - entity_id - entity_type additionalProperties: false properties: entity_id: type: string description: The id used to search this query. entity_type: type: string enum: - standard_address metadata: type: object anyOf: - description: GET request that returns address balances title: AddressStxBalanceResponse type: object allOf: - $ref: "#/paths/~1extended~1v1~1address~1%7Bprincipal%7D~1balances/get/responses\ /200/content/application~1json/schema\ /properties/stx" - type: object additionalProperties: false properties: token_offering_locked: $ref: "#/paths/~1extended~1v1~1address~1%7Bprincipal%7D~1balances/get/responses\ /200/content/application~1json/sc\ hema/properties/token_offering_lo\ cked" - type: object title: BlockSearchResult description: Block search result required: - found - result additionalProperties: false properties: found: type: boolean description: Indicates if the requested object was found or not default: true result: type: object description: This object carries the search result required: - entity_id - entity_type - block_data additionalProperties: false properties: entity_id: type: string description: The id used to search this query. entity_type: type: string enum: - block_hash block_data: type: object description: Returns basic search result information about the requested id required: - canonical - hash - parent_block_hash - burn_block_time - height additionalProperties: false properties: canonical: type: boolean description: If the block lies within the canonical chain hash: type: string description: Refers to the hash of the block parent_block_hash: type: string burn_block_time: type: integer height: type: integer metadata: $ref: "#/paths/~1extended~1v1~1block/get/responses/200/content/application~1jso\ n/schema/properties/results/items" - type: object title: ContractSearchResult description: Contract search result required: - found - result additionalProperties: false properties: found: type: boolean description: Indicates if the requested object was found or not default: true result: type: object description: This object carries the search result required: - entity_id - entity_type additionalProperties: false properties: entity_id: type: string description: The id used to search this query. entity_type: type: string enum: - contract_address tx_data: type: object description: Returns basic search result information about the requested id additionalProperties: false properties: canonical: type: boolean description: If the transaction lies within the canonical chain block_hash: type: string description: Refers to the hash of the block for searched transaction burn_block_time: type: integer block_height: type: integer tx_type: type: string tx_id: type: string description: Corresponding tx_id for smart_contract metadata: type: object anyOf: - $ref: "#/paths/~1extended~1v1~1tx~1mempool/get/responses/200/content/applicatio\ n~1json/schema/properties/results/items" - $ref: "#/paths/~1extended~1v1~1tx/get/responses/200/content/application~1json/s\ chema/properties/results/items" - type: object title: MempoolTxSearchResult description: Contract search result required: - found - result additionalProperties: false properties: found: type: boolean description: Indicates if the requested object was found or not default: true result: type: object additionalProperties: false description: This object carries the search result required: - entity_id - entity_type - tx_data properties: entity_id: type: string description: The id used to search this query. entity_type: type: string enum: - mempool_tx_id tx_data: type: object additionalProperties: false description: Returns basic search result information about the requested id required: - tx_type properties: tx_type: type: string metadata: $ref: "#/paths/~1extended~1v1~1tx~1mempool/get/responses/200/content/applicatio\ n~1json/schema/properties/results/items" - type: object title: TxSearchResult description: Transaction search result additionalProperties: false required: - found - result properties: found: type: boolean description: Indicates if the requested object was found or not default: true result: type: object description: This object carries the search result required: - entity_id - entity_type - tx_data additionalProperties: false properties: entity_id: type: string description: The id used to search this query. entity_type: type: string enum: - tx_id tx_data: type: object description: Returns basic search result information about the requested id required: - canonical - block_hash - burn_block_time - block_height - tx_type additionalProperties: false properties: canonical: type: boolean description: If the transaction lies within the canonical chain block_hash: type: string description: Refers to the hash of the block for searched transaction burn_block_time: type: integer block_height: type: integer tx_type: type: string metadata: $ref: "#/paths/~1extended~1v1~1tx/get/responses/200/content/application~1json/s\ chema/properties/results/items" example: found: true result: entity_id: ST2P7B9G6Y55QWZJ9B93DVSEG5S6Z4PFJHB3XRKHW.hello_world entity_type: contract_address tx_data: canonical: true block_hash: "0xb076fd3983e63bbf28ae615daa31c5b6084d23ceeb920c54f1ea666244415457" burn_block_time: 1595229199 block_height: 648 tx_type: smart_contract "404": description: Not found content: application/json: example: found: false result: entity_type: unknown_hash error: No block or transaction found with hash "0xabc123" /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: type: object title: RosettaNetworkListResponse description: A NetworkListResponse contains all NetworkIdentifiers that the node can serve information for. required: - network_identifiers additionalProperties: false properties: network_identifiers: type: array description: The network_identifier specifies which network a particular object is associated with. items: type: object title: NetworkIdentifier description: The network_identifier specifies which network a particular object is associated with. required: - blockchain - network additionalProperties: false properties: blockchain: type: string description: Blockchain name network: type: string description: If a blockchain has a specific chain-id or network identifier, it should go in this field. It is up to the client to determine which network-specific identifier is mainnet or testnet. sub_network_identifier: type: object description: In blockchains with sharded state, the SubNetworkIdentifier is required to query some object on a specific shard. This identifier is optional for all non-sharded blockchains. required: - network additionalProperties: false properties: network: type: string description: Network name metadata: type: object description: Meta data from subnetwork identifier required: - producer properties: producer: type: string description: producer "400": description: Error content: application/json: schema: type: object title: RosettaError description: Instead of utilizing HTTP status codes to describe node errors (which often do not have a good analog), rich errors are returned using this object. Both the code and message fields can be individually used to correctly identify an error. Implementations MUST use unique values for both fields. additionalProperties: false required: - code - message - retriable properties: code: type: integer description: Code is a network-specific error code. If desired, this code can be equivalent to an HTTP status code. message: type: string description: Message is a network-specific error message. The message MUST NOT change for a given code. In particular, this means that any contextual information should be included in the details field. retriable: type: boolean description: An error is retriable if the same request may succeed if submitted again. details: type: object description: Often times it is useful to return context specific to the request that caused the error (i.e. a sample of the stack trace or impacted account) in addition to the standard error message. properties: address: type: string error: type: string /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: type: object title: RosettaNetworkOptionsResponse description: NetworkOptionsResponse contains information about the versioning of the node and the allowed operation statuses, operation types, and errors. required: - version - allow additionalProperties: false properties: version: type: object additionalProperties: false description: The Version object is utilized to inform the client of the versions of different components of the Rosetta implementation. required: - rosetta_version - node_version properties: rosetta_version: type: string description: The rosetta_version is the version of the Rosetta interface the implementation adheres to. This can be useful for clients looking to reliably parse responses. node_version: type: string description: The node_version is the canonical version of the node runtime. This can help clients manage deployments. middleware_version: type: string description: When a middleware server is used to adhere to the Rosetta interface, it should return its version here. This can help clients manage deployments. metadata: type: object description: Any other information that may be useful about versioning of dependent services should be returned here. allow: type: object description: Allow specifies supported Operation status, Operation types, and all possible error statuses. This Allow object is used by clients to validate the correctness of a Rosetta Server implementation. It is expected that these clients will error if they receive some response that contains any of the above information that is not specified here. required: - operation_statuses - operation_types - errors - historical_balance_lookup additionalProperties: false properties: operation_statuses: type: array description: All Operation.Status this implementation supports. Any status that is returned during parsing that is not listed here will cause client validation to error. items: type: object title: RosettaOperationStatus description: OperationStatus is utilized to indicate which Operation status are considered successful. required: - status - successful additionalProperties: false properties: status: type: string description: The status is the network-specific status of the operation. successful: type: boolean description: An Operation is considered successful if the Operation.Amount should affect the Operation.Account. Some blockchains (like Bitcoin) only include successful operations in blocks but other blockchains (like Ethereum) include unsuccessful operations that incur a fee. To reconcile the computed balance from the stream of Operations, it is critical to understand which Operation.Status indicate an Operation is successful and should affect an Account. operation_types: type: array description: All Operation.Type this implementation supports. Any type that is returned during parsing that is not listed here will cause client validation to error. items: anyOf: - type: string errors: type: array description: All Errors that this implementation could return. Any error that is returned during parsing that is not listed here will cause client validation to error. items: type: object title: RosettaErrorNoDetails description: Instead of utilizing HTTP status codes to describe node errors (which often do not have a good analog), rich errors are returned using this object. Both the code and message fields can be individually used to correctly identify an error. Implementations MUST use unique values for both fields. required: - code - message - retriable additionalProperties: false properties: code: type: integer description: Code is a network-specific error code. If desired, this code can be equivalent to an HTTP status code. message: type: string description: Message is a network-specific error message. The message MUST NOT change for a given code. In particular, this means that any contextual information should be included in the details field. retriable: type: boolean description: An error is retriable if the same request may succeed if submitted again. historical_balance_lookup: type: boolean description: Any Rosetta implementation that supports querying the balance of an account at any height in the past should set this to true. "400": description: Error content: application/json: schema: $ref: "#/paths/~1rosetta~1v1~1network~1list/post/responses/400/content/applicat\ ion~1json/schema" requestBody: required: true content: application/json: schema: type: object title: RosettaOptionsRequest description: This endpoint returns 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. required: - network_identifier additionalProperties: false properties: network_identifier: $ref: "#/paths/~1rosetta~1v1~1network~1list/post/responses/200/content/applicat\ ion~1json/schema/properties/network_identifiers/items" metadata: type: object example: - network_identifier: blockchain: stacks network: mainnet metadata: {} /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: type: object title: RosettaNetworkStatusResponse description: NetworkStatusResponse contains basic information about the node's view of a blockchain network. It is assumed that any BlockIdentifier.Index less than or equal to CurrentBlockIdentifier.Index can be queried. If a Rosetta implementation prunes historical state, it should populate the optional oldest_block_identifier field with the oldest block available to query. If this is not populated, it is assumed that the genesis_block_identifier is the oldest queryable block. If a Rosetta implementation performs some pre-sync before it is possible to query blocks, sync_status should be populated so that clients can still monitor healthiness. Without this field, it may appear that the implementation is stuck syncing and needs to be terminated. required: - current_block_identifier - current_block_timestamp - genesis_block_identifier - peers properties: current_block_identifier: title: RosettaBlockIdentifier description: The block_identifier uniquely identifies a block in a particular network. allOf: - type: object title: RosettaBlockIdentifierHash description: This is also known as the block hash. additionalProperties: false required: - hash properties: hash: type: string description: This is also known as the block hash. - type: object title: RosettaBlockIdentifierHeight description: This is also known as the block height. additionalProperties: false required: - index properties: index: type: integer description: This is also known as the block height. current_block_timestamp: type: integer description: The timestamp of the block in milliseconds since the Unix Epoch. The timestamp is stored in milliseconds because some blockchains produce blocks more often than once a second. genesis_block_identifier: type: object title: RosettaGenesisBlockIdentifier description: The block_identifier uniquely identifies a block in a particular network. required: - index - hash additionalProperties: false properties: index: type: integer description: This is also known as the block height. hash: type: string description: Block hash oldest_block_identifier: type: object title: RosettaOldestBlockIdentifier description: The block_identifier uniquely identifies a block in a particular network. required: - index - hash additionalProperties: false properties: index: type: integer description: This is also known as the block height. hash: type: string description: Block hash sync_status: type: object title: RosettaSyncStatus description: SyncStatus is used to provide additional context about an implementation's sync status. It is often used to indicate that an implementation is healthy when it cannot be queried until some sync phase occurs. If an implementation is immediately queryable, this model is often not populated. required: - current_index additionalProperties: false properties: current_index: type: integer description: CurrentIndex is the index of the last synced block in the current stage. target_index: type: integer description: TargetIndex is the index of the block that the implementation is attempting to sync to in the current stage. stage: type: string description: Stage is the phase of the sync process. synced: type: boolean description: Synced indicates if an implementation has synced up to the most recent block. peers: type: array description: Peers information items: type: object title: RosettaPeers description: A Peer is a representation of a node's peer. required: - peer_id additionalProperties: false properties: peer_id: type: string description: peer id metadata: type: object description: meta data additionalProperties: false "400": description: Error content: application/json: schema: $ref: "#/paths/~1rosetta~1v1~1network~1list/post/responses/400/content/applicat\ ion~1json/schema" requestBody: required: true content: application/json: schema: type: object title: RosettaStatusRequest description: This endpoint returns the current status of the network requested. Any NetworkIdentifier returned by /network/list should be accessible here. required: - network_identifier additionalProperties: false properties: network_identifier: $ref: "#/paths/~1rosetta~1v1~1network~1list/post/responses/200/content/applicat\ ion~1json/schema/properties/network_identifiers/items" metadata: type: object example: $ref: "#/paths/~1rosetta~1v1~1network~1options/post/requestBody/content/applica\ tion~1json/example" /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: type: object title: RosettaAccountBalanceResponse description: "An AccountBalanceResponse is returned on the /account/balance endpoint. If an account has a balance for each AccountIdentifier describing it (ex: an ERC-20 token balance on a few smart contracts), an account balance request must be made with each AccountIdentifier." required: - block_identifier - balances additionalProperties: false properties: block_identifier: $ref: "#/paths/~1rosetta~1v1~1network~1status/post/responses/200/content/applic\ ation~1json/schema/properties/current_block_identifier" balances: type: array description: A single account balance may have multiple currencies items: type: object title: RosettaAmount additionalProperties: false description: Amount is some Value of a Currency. It is considered invalid to specify a Value without a Currency. required: - value - currency properties: value: type: string description: Value of the transaction in atomic units represented as an arbitrary-sized signed integer. For example, 1 BTC would be represented by a value of 100000000. currency: title: RosettaCurrency type: object additionalProperties: false description: Currency is composed of a canonical Symbol and Decimals. This Decimals value is used to convert an Amount.Value from atomic units (Satoshis) to standard units (Bitcoins). required: - symbol - decimals properties: symbol: type: string description: Canonical symbol associated with a currency. decimals: type: integer description: Number of decimal places in the standard unit representation of the amount. For example, BTC has 8 decimals. Note that it is not possible to represent the value of some currency in atomic units that is not base 10. metadata: type: object description: Any additional information related to the currency itself. For example, it would be useful to populate this object with the contract address of an ERC-20 token. metadata: type: object description: "" coins: type: array description: If a blockchain is UTXO-based, all unspent Coins owned by an account_identifier should be returned alongside the balance. It is highly recommended to populate this field so that users of the Rosetta API implementation don't need to maintain their own indexer to track their UTXOs. items: type: object title: RosettaCoin additionalProperties: false description: If a blockchain is UTXO-based, all unspent Coins owned by an account_identifier should be returned alongside the balance. It is highly recommended to populate this field so that users of the Rosetta API implementation don't need to maintain their own indexer to track their UTXOs. required: - coin_identifier - amount properties: coin_identifier: type: object description: CoinIdentifier uniquely identifies a Coin. required: - identifier additionalProperties: false properties: identifier: type: string description: Identifier should be populated with a globally unique identifier of a Coin. In Bitcoin, this identifier would be transaction_hash:index. amount: $ref: "#/paths/~1rosetta~1v1~1account~1balance/post/responses/200/content/appli\ cation~1json/schema/properties/balances/items" metadata: type: object description: Account-based blockchains that utilize a nonce or sequence number should include that number in the metadata. This number could be unique to the identifier or global across the account address. required: - sequence_number properties: sequence_number: type: integer "400": description: Error content: application/json: schema: $ref: "#/paths/~1rosetta~1v1~1network~1list/post/responses/400/content/applicat\ ion~1json/schema" requestBody: required: true content: application/json: schema: type: object title: RosettaAccountBalanceRequest 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. required: - network_identifier - account_identifier additionalProperties: false properties: network_identifier: $ref: "#/paths/~1rosetta~1v1~1network~1list/post/responses/200/content/applicat\ ion~1json/schema/properties/network_identifiers/items" account_identifier: type: object title: RosettaAccount description: The account_identifier uniquely identifies an account within a network. All fields in the account_identifier are utilized to determine this uniqueness (including the metadata field, if populated). required: - address additionalProperties: false properties: address: type: string description: The address may be a cryptographic public key (or some encoding of it) or a provided username. sub_account: type: object title: RosettaSubAccount description: An account may have state specific to a contract address (ERC-20 token) and/or a stake (delegated balance). The sub_account_identifier should specify which state (if applicable) an account instantiation refers to. required: - address additionalProperties: false properties: address: type: string description: The address may be a cryptographic public key (or some encoding of it) or a provided username. metadata: type: object description: If the SubAccount address is not sufficient to uniquely specify a SubAccount, any other identifying information can be stored here. It is important to note that two SubAccounts with identical addresses but differing metadata will not be considered equal by clients. metadata: type: object description: Blockchains that utilize a username model (where the address is not a derivative of a cryptographic public key) should specify the public key(s) owned by the address in metadata. block_identifier: type: object title: RosettaPartialBlockIdentifier description: When fetching data by BlockIdentifier, it may be possible to only specify the index or hash. If neither property is specified, it is assumed that the client is making a request at the current block. anyOf: - $ref: "#/paths/~1rosetta~1v1~1network~1status/post/responses/200/content/applic\ ation~1json/schema/properties/current_block_identifier/\ allOf/0" - $ref: "#/paths/~1rosetta~1v1~1network~1status/post/responses/200/content/applic\ ation~1json/schema/properties/current_block_identifier/\ allOf/1" - type: object example: network_identifier: blockchain: stacks network: mainnet account_identifier: address: SP2W6477BT5CRWVC5D5RFNPNAR8R2NW63SMMCAWMC metadata: {} /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: type: object title: RosettaBlockResponse additionalProperties: false description: A BlockResponse includes a fully-populated block or a partially-populated block with a list of other transactions to fetch (other_transactions). As a result of the consensus algorithm of some blockchains, blocks can be omitted (i.e. certain block indexes can be skipped). If a query for one of these omitted indexes is made, the response should not include a Block object. It is VERY important to note that blocks MUST still form a canonical, connected chain of blocks where each block has a unique index. In other words, the PartialBlockIdentifier of a block after an omitted block should reference the last non-omitted block. properties: block: type: object title: RosettaBlock description: "Blocks contain an array of Transactions that occurred at a particular BlockIdentifier. A hard requirement for blocks returned by Rosetta implementations is that they MUST be inalterable: once a client has requested and received a block identified by a specific BlockIndentifier, all future calls for that same BlockIdentifier must return the same block contents." required: - block_identifier - parent_block_identifier - timestamp - transactions additionalProperties: false properties: block_identifier: $ref: "#/paths/~1rosetta~1v1~1network~1status/post/responses/200/content/applic\ ation~1json/schema/properties/current_block_identifie\ r" parent_block_identifier: type: object title: RosettaParentBlockIdentifier additionalProperties: false description: The block_identifier uniquely identifies a block in a particular network. required: - index - hash properties: index: type: integer description: This is also known as the block height. hash: type: string description: Block hash timestamp: type: integer description: The timestamp of the block in milliseconds since the Unix Epoch. The timestamp is stored in milliseconds because some blockchains produce blocks more often than once a second. transactions: type: array description: All the transactions in the block items: $ref: "#/paths/~1rosetta~1v1~1block~1transaction/post/responses/200/content/app\ lication~1json/schema/properties/transaction" metadata: type: object description: meta data required: - transactions_root - difficulty properties: transactions_root: type: string description: "" difficulty: type: string description: "" other_transactions: type: array description: "Some blockchains may require additional transactions to be fetched that weren't returned in the block response (ex: block only returns transaction hashes). For blockchains with a lot of transactions in each block, this can be very useful as consumers can concurrently fetch all transactions returned." items: type: object title: OtherTransactionIdentifier description: The transaction_identifier uniquely identifies a transaction in a particular network and block or in the mempool. required: - hash additionalProperties: false properties: hash: type: string description: "Any transactions that are attributable only to a block (ex: a block event) should use the hash of the block as the identifier." "400": description: Error content: application/json: schema: $ref: "#/paths/~1rosetta~1v1~1network~1list/post/responses/400/content/applicat\ ion~1json/schema" requestBody: required: true content: application/json: schema: type: object title: RosettaBlockRequest description: A BlockRequest is utilized to make a block request on the /block endpoint. required: - network_identifier - block_identifier additionalProperties: false properties: network_identifier: $ref: "#/paths/~1rosetta~1v1~1network~1list/post/responses/200/content/applicat\ ion~1json/schema/properties/network_identifiers/items" block_identifier: $ref: "#/paths/~1rosetta~1v1~1account~1balance/post/requestBody/content/applica\ tion~1json/schema/properties/block_identifier" example: network_identifier: blockchain: stacks network: mainnet block_identifier: index: 71107 hash: "0xce7e16561150f3a379845f4e96c3dd8f8396e397495821c9eec6b429391c529c" /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: type: object title: RosettaBlockTransactionResponse description: A BlockTransactionResponse contains information about a block transaction. required: - transaction additionalProperties: false properties: transaction: type: object title: RosettaTransaction description: Transactions contain an array of Operations that are attributable to the same TransactionIdentifier. required: - transaction_identifier - operations additionalProperties: false properties: transaction_identifier: $ref: "#/paths/~1rosetta~1v1~1block~1transaction/post/requestBody/content/appli\ cation~1json/schema/properties/transaction_identifier" operations: type: array description: List of operations items: $ref: "#/paths/~1rosetta~1v1~1construction~1parse/post/responses/200/content/ap\ plication~1json/schema/properties/operations/items" metadata: type: object description: Transactions that are related to other transactions (like a cross-shard transaction) should include the tranaction_identifier of these transactions in the metadata. properties: memo: type: string description: STX token transfer memo. size: type: integer description: The Size lockTime: type: integer description: The locktime "400": description: Error content: application/json: schema: $ref: "#/paths/~1rosetta~1v1~1network~1list/post/responses/400/content/applicat\ ion~1json/schema" requestBody: required: true content: application/json: schema: type: object title: RosettaBlockTransactionRequest description: A BlockTransactionRequest is used to fetch a Transaction included in a block that is not returned in a BlockResponse. required: - network_identifier - block_identifier - transaction_identifier additionalProperties: false properties: network_identifier: $ref: "#/paths/~1rosetta~1v1~1network~1list/post/responses/200/content/applicat\ ion~1json/schema/properties/network_identifiers/items" block_identifier: $ref: "#/paths/~1rosetta~1v1~1account~1balance/post/requestBody/content/applica\ tion~1json/schema/properties/block_identifier" transaction_identifier: type: object title: TransactionIdentifier description: The transaction_identifier uniquely identifies a transaction in a particular network and block or in the mempool. required: - hash additionalProperties: false properties: hash: type: string description: "Any transactions that are attributable only to a block (ex: a block event) should use the hash of the block as the identifier." example: network_identifier: blockchain: stacks network: mainnet block_identifier: hash: "0xce7e16561150f3a379845f4e96c3dd8f8396e397495821c9eec6b429391c529c" transaction_identifier: hash: "0x49354cc7b18dc5296c945a8e89f7d758dac14f1ab38d4c33dfe45ec1765ab339" /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: type: object title: RosettaMempoolResponse description: A MempoolResponse contains all transaction identifiers in the mempool for a particular network_identifier. required: - transaction_identifiers additionalProperties: false properties: transaction_identifiers: type: array description: "" items: $ref: "#/paths/~1rosetta~1v1~1block~1transaction/post/requestBody/content/appli\ cation~1json/schema/properties/transaction_identifier" metadata: type: object "400": description: Error content: application/json: schema: $ref: "#/paths/~1rosetta~1v1~1network~1list/post/responses/400/content/applicat\ ion~1json/schema" requestBody: required: true content: application/json: schema: type: object title: RosettaMempoolRequest description: Get all Transaction Identifiers in the mempool required: - network_identifier additionalProperties: false properties: network_identifier: $ref: "#/paths/~1rosetta~1v1~1network~1list/post/responses/200/content/applicat\ ion~1json/schema/properties/network_identifiers/items" metadata: type: object example: $ref: "#/paths/~1rosetta~1v1~1network~1options/post/requestBody/content/applica\ tion~1json/example" /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: type: object title: RosettaMempoolTransactionResponse description: "A MempoolTransactionResponse contains an estimate of a mempool transaction. It may not be possible to know the full impact of a transaction in the mempool (ex: fee paid)." required: - transaction additionalProperties: false properties: transaction: $ref: "#/paths/~1rosetta~1v1~1block~1transaction/post/responses/200/content/app\ lication~1json/schema/properties/transaction" metadata: type: object "400": description: Error content: application/json: schema: $ref: "#/paths/~1rosetta~1v1~1network~1list/post/responses/400/content/applicat\ ion~1json/schema" requestBody: required: true content: application/json: schema: type: object title: RosettaMempoolTransactionRequest description: A MempoolTransactionRequest is utilized to retrieve a transaction from the mempool. required: - network_identifier - transaction_identifier additionalProperties: false properties: network_identifier: $ref: "#/paths/~1rosetta~1v1~1network~1list/post/responses/200/content/applicat\ ion~1json/schema/properties/network_identifiers/items" transaction_identifier: $ref: "#/paths/~1rosetta~1v1~1block~1transaction/post/requestBody/content/appli\ cation~1json/schema/properties/transaction_identifier" /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: type: object title: RosettaConstructionDeriveResponse description: ConstructionDeriveResponse is returned by the /construction/derive endpoint. additionalProperties: false properties: address: type: string description: "[DEPRECATED by account_identifier in v1.4.4] Address in network-specific format." account_identifier: type: object title: RosettaAccountIdentifier description: The account_identifier uniquely identifies an account within a network. All fields in the account_identifier are utilized to determine this uniqueness (including the metadata field, if populated). required: - address properties: address: type: string description: The address may be a cryptographic public key (or some encoding of it) or a provided username. sub_account: $ref: "#/paths/~1rosetta~1v1~1account~1balance/post/requestBody/content/applica\ tion~1json/schema/properties/account_identifier/prope\ rties/sub_account" metadata: type: object description: Blockchains that utilize a username model (where the address is not a derivative of a cryptographic public key) should specify the public key(s) owned by the address in metadata. metadata: type: object "400": description: Error content: application/json: schema: $ref: "#/paths/~1rosetta~1v1~1network~1list/post/responses/400/content/applicat\ ion~1json/schema" requestBody: required: true content: application/json: schema: type: object title: RosettaConstructionDeriveRequest description: Network is provided in the request because some blockchains have different address formats for different networks required: - network_identifier - public_key additionalProperties: false properties: network_identifier: $ref: "#/paths/~1rosetta~1v1~1network~1list/post/responses/200/content/applicat\ ion~1json/schema/properties/network_identifiers/items" public_key: type: object title: RosettaPublicKey description: PublicKey contains a public key byte array for a particular CurveType encoded in hex. Note that there is no PrivateKey struct as this is NEVER the concern of an implementation. required: - hex_bytes - curve_type additionalProperties: false properties: hex_bytes: type: string description: Hex-encoded public key bytes in the format specified by the CurveType. curve_type: type: string description: CurveType is the type of cryptographic curve associated with a PublicKey. enum: - secp256k1 - edwards25519 metadata: type: object example: network_identifier: blockchain: stacks network: mainnet public_key: hex_bytes: 025c13b2fc2261956d8a4ad07d481b1a3b2cbf93a24f992249a61c3a1c4de79c51 curve_type: secp256k1 metadata: {} /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: type: object title: RosettaConstructionHashResponse description: TransactionIdentifier contains the transaction_identifier of a transaction that was submitted to either /construction/hash or /construction/submit. required: - transaction_identifier additionalProperties: false properties: transaction_identifier: $ref: "#/paths/~1rosetta~1v1~1block~1transaction/post/requestBody/content/appli\ cation~1json/schema/properties/transaction_identifier" metadata: type: object "400": description: Error content: application/json: schema: $ref: "#/paths/~1rosetta~1v1~1network~1list/post/responses/400/content/applicat\ ion~1json/schema" requestBody: required: true content: application/json: schema: type: object title: RosettaConstructionHashRequest description: TransactionHash returns the network-specific transaction hash for a signed transaction. required: - network_identifier - signed_transaction additionalProperties: false properties: network_identifier: $ref: "#/paths/~1rosetta~1v1~1network~1list/post/responses/200/content/applicat\ ion~1json/schema/properties/network_identifiers/items" signed_transaction: type: string description: Signed transaction example: network_identifier: blockchain: stacks network: mainnet signed_transaction: "0x80800000000400539886f96611ba3ba6cef9618f8c78118b37c5be00\ 0000000000000000000000000000b400017a33a91515ef48608a99c6adecd2e\ b258e11534a1acf66348f5678c8e2c8f83d243555ed67a0019d3500df98563c\ a31321c1a675b43ef79f146e322fe08df75103020000000000051a1ae3f911d\ 8f1d46d7416bfbe4b593fd41eac19cb000000000007a1200000000000000000\ 0000000000000000000000000000000000000000000000000000" /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: type: object title: RosettaConstructionMetadataResponse description: The ConstructionMetadataResponse returns network-specific metadata used for transaction construction. Optionally, the implementer can return the suggested fee associated with the transaction being constructed. The caller may use this info to adjust the intent of the transaction or to create a transaction with a different account that can pay the suggested fee. Suggested fee is an array in case fee payment must occur in multiple currencies. required: - metadata additionalProperties: false properties: metadata: type: object properties: account_sequence: type: integer recent_block_hash: type: string suggested_fee: type: array items: $ref: "#/paths/~1rosetta~1v1~1account~1balance/post/responses/200/content/appli\ cation~1json/schema/properties/balances/items" "400": description: Error content: application/json: schema: $ref: "#/paths/~1rosetta~1v1~1network~1list/post/responses/400/content/applicat\ ion~1json/schema" requestBody: required: true content: application/json: schema: type: object title: RosettaConstructionMetadataRequest description: A ConstructionMetadataRequest is utilized to get information required to construct a transaction. The Options object used to specify which metadata to return is left purposely unstructured to allow flexibility for implementers. Optionally, the request can also include an array of PublicKeys associated with the AccountIdentifiers returned in ConstructionPreprocessResponse. required: - network_identifier - options additionalProperties: false properties: network_identifier: $ref: "#/paths/~1rosetta~1v1~1network~1list/post/responses/200/content/applicat\ ion~1json/schema/properties/network_identifiers/items" options: title: RosettaOptions type: object description: The options that will be sent directly to /construction/metadata by the caller. additionalProperties: false properties: sender_address: type: string description: "sender's address " type: type: string description: Type of operation e.g transfer status: type: string description: This value indicates the state of the operations token_transfer_recipient_address: type: string description: Recipient's address amount: type: string description: Amount to be transfered. symbol: type: string description: Currency symbol e.g STX decimals: type: integer description: Number of decimal places gas_limit: type: number description: Maximum price a user is willing to pay. gas_price: type: number description: Cost necessary to perform a transaction on the network suggested_fee_multiplier: type: number description: " A suggested fee multiplier to indicate that the suggested fee should be scaled. This may be used to set higher fees for urgent transactions or to pay lower fees when there is less urgency." max_fee: type: string description: Maximum fee user is willing to pay fee: type: string description: Fee for this transaction size: type: integer description: Transaction approximative size (used to calculate total fee). memo: type: string description: STX token transfer memo. number_of_cycles: type: integer description: Number of cycles when stacking. contract_address: type: string description: Address of the contract to call. contract_name: type: string description: Name of the contract to call. burn_block_height: type: integer description: Set the burnchain (BTC) block for stacking lock to start. delegate_to: type: string description: Delegator address for when calling `delegate-stacking`. pox_addr: type: string description: The reward address for stacking transaction. It should be a valid Bitcoin address public_keys: type: array items: $ref: "#/paths/~1rosetta~1v1~1construction~1derive/post/requestBody/content/app\ lication~1json/schema/properties/public_key" example: network_identifier: blockchain: stacks network: mainnet options: sender_address: SP3Y0BBCCCBFAMYCYN3F35CX9MH1J2GATP53JX3FA type: stack_stx status: success token_transfer_recipient_address: string amount: "500000" symbol: STX decimals: 6 gas_limit: 0 gas_price: 0 suggested_fee_multiplier: 0 max_fee: "12380898" fee: fee size: 260 memo: test.memo number_of_cycles: 0 contract_address: SP112T7BYCNEDCZ9TCYXCXFNJG9WXX5Q5SG6DSBAM contract_name: STX transfer burn_block_height: 0 delegate_to: cb3df38053d132895220b9ce471f6b676db5b9bf0b4adefb55f2118ece2478df01.STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6 pox_addr: 1Xik14zRm29UsyS6DjhYg4iZeZqsDa8D3 public_keys: - hex_bytes: publicKey curve_type: secp256k1 /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: type: object title: RosettaConstructionParseResponse description: RosettaConstructionParseResponse contains an array of operations that occur in a transaction blob. This should match the array of operations provided to /construction/preprocess and /construction/payloads. required: - operations additionalProperties: false properties: operations: type: array items: type: object title: RosettaOperation description: Operations contain all balance-changing information within a transaction. They are always one-sided (only affect 1 AccountIdentifier) and can succeed or fail independently from a Transaction. required: - operation_identifier - type additionalProperties: false properties: operation_identifier: type: object title: RosettaOperationIdentifier description: The operation_identifier uniquely identifies an operation within a transaction. required: - index additionalProperties: false properties: index: type: integer description: The operation index is used to ensure each operation has a unique identifier within a transaction. This index is only relative to the transaction and NOT GLOBAL. The operations in each transaction should start from index 0. To clarify, there may not be any notion of an operation index in the blockchain being described. network_index: type: integer description: Some blockchains specify an operation index that is essential for client use. For example, Bitcoin uses a network_index to identify which UTXO was used in a transaction. network_index should not be populated if there is no notion of an operation index in a blockchain (typically most account-based blockchains). related_operations: type: array description: Restrict referenced related_operations to identifier indexes < the current operation_identifier.index. This ensures there exists a clear DAG-structure of relations. Since operations are one-sided, one could imagine relating operations in a single transfer or linking operations in a call tree. items: title: RosettaRelatedOperation type: object description: Restrict referenced related_operations to identifier indexes < the current operation_identifier.index. This ensures there exists a clear DAG-structure of relations. Since operations are one-sided, one could imagine relating operations in a single transfer or linking operations in a call tree. required: - index additionalProperties: false properties: index: type: integer description: Describes the index of related operation. network_index: type: integer description: Some blockchains specify an operation index that is essential for client use. network_index should not be populated if there is no notion of an operation index in a blockchain (typically most account-based blockchains). type: type: string description: The network-specific type of the operation. Ensure that any type that can be returned here is also specified in the NetworkStatus. This can be very useful to downstream consumers that parse all block data. status: type: string description: The network-specific status of the operation. Status is not defined on the transaction object because blockchains with smart contracts may have transactions that partially apply. Blockchains with atomic transactions (all operations succeed or all operations fail) will have the same status for each operation. account: $ref: "#/paths/~1rosetta~1v1~1account~1balance/post/requestBody/content/applica\ tion~1json/schema/properties/account_identifier" amount: $ref: "#/paths/~1rosetta~1v1~1account~1balance/post/responses/200/content/appli\ cation~1json/schema/properties/balances/items" coin_change: type: object title: RosettaCoinChange description: CoinChange is used to represent a change in state of a some coin identified by a coin_identifier. This object is part of the Operation model and must be populated for UTXO-based blockchains. Coincidentally, this abstraction of UTXOs allows for supporting both account-based transfers and UTXO-based transfers on the same blockchain (when a transfer is account-based, don't populate this model). required: - coin_identifier - coin_action additionalProperties: false properties: coin_identifier: type: object description: CoinIdentifier uniquely identifies a Coin. required: - identifier properties: identifier: type: string description: Identifier should be populated with a globally unique identifier of a Coin. In Bitcoin, this identifier would be transaction_hash:index. coin_action: type: string description: CoinActions are different state changes that a Coin can undergo. When a Coin is created, it is coin_created. When a Coin is spent, it is coin_spent. It is assumed that a single Coin cannot be created or spent more than once. enum: - coin_created - coin_spent metadata: type: object description: Operations Meta Data signers: type: array description: "[DEPRECATED by account_identifier_signers in v1.4.4] All signers (addresses) of a particular transaction. If the transaction is unsigned, it should be empty." items: anyOf: - type: string account_identifier_signers: type: array items: $ref: "#/paths/~1rosetta~1v1~1construction~1derive/post/responses/200/content/a\ pplication~1json/schema/properties/account_identifier" metadata: type: object "400": description: Error content: application/json: schema: $ref: "#/paths/~1rosetta~1v1~1network~1list/post/responses/400/content/applicat\ ion~1json/schema" requestBody: required: true content: application/json: schema: type: object title: RosettaConstructionParseRequest description: Parse is called on both unsigned and signed transactions to understand the intent of the formulated transaction. This is run as a sanity check before signing (after /construction/payloads) and before broadcast (after /construction/combine). required: - network_identifier - signed - transaction additionalProperties: false properties: network_identifier: $ref: "#/paths/~1rosetta~1v1~1network~1list/post/responses/200/content/applicat\ ion~1json/schema/properties/network_identifiers/items" signed: type: boolean description: Signed is a boolean indicating whether the transaction is signed. transaction: type: string description: This must be either the unsigned transaction blob returned by /construction/payloads or the signed transaction blob returned by /construction/combine. /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: type: object title: RosettaConstructionPreprocessResponse additionalProperties: false description: RosettaConstructionPreprocessResponse contains options that will be sent unmodified to /construction/metadata. If it is not necessary to make a request to /construction/metadata, options should be omitted. Some blockchains require the PublicKey of particular AccountIdentifiers to construct a valid transaction. To fetch these PublicKeys, populate required_public_keys with the AccountIdentifiers associated with the desired PublicKeys. If it is not necessary to retrieve any PublicKeys for construction, required_public_keys should be omitted. properties: options: $ref: "#/paths/~1rosetta~1v1~1construction~1metadata/post/requestBody/content/a\ pplication~1json/schema/properties/options" required_public_keys: type: array items: $ref: "#/paths/~1rosetta~1v1~1account~1balance/post/requestBody/content/applica\ tion~1json/schema/properties/account_identifier" "400": description: Error content: application/json: schema: $ref: "#/paths/~1rosetta~1v1~1network~1list/post/responses/400/content/applicat\ ion~1json/schema" requestBody: required: true content: application/json: schema: type: object title: RosettaConstructionPreprocessRequest description: ConstructionPreprocessRequest is passed to the /construction/preprocess endpoint so that a Rosetta implementation can determine which metadata it needs to request for construction required: - network_identifier - operations additionalProperties: false properties: network_identifier: $ref: "#/paths/~1rosetta~1v1~1network~1list/post/responses/200/content/applicat\ ion~1json/schema/properties/network_identifiers/items" operations: type: array items: $ref: "#/paths/~1rosetta~1v1~1construction~1parse/post/responses/200/content/ap\ plication~1json/schema/properties/operations/items" metadata: type: object max_fee: type: array items: type: object title: RosettaMaxFeeAmount description: Amount is some Value of a Currency. It is considered invalid to specify a Value without a Currency. required: - value - currency properties: value: type: string description: Value of the transaction in atomic units represented as an arbitrary-sized signed integer. For example, 1 BTC would be represented by a value of 100000000. currency: $ref: "#/paths/~1rosetta~1v1~1account~1balance/post/responses/200/content/appli\ cation~1json/schema/properties/balances/items/propert\ ies/currency" metadata: type: object description: "" suggested_fee_multiplier: type: integer description: " The caller can also provide a suggested fee multiplier to indicate that the suggested fee should be scaled. This may be used to set higher fees for urgent transactions or to pay lower fees when there is less urgency. It is assumed that providing a very low multiplier (like 0.0001) will never lead to a transaction being created with a fee less than the minimum network fee (if applicable). In the case that the caller provides both a max fee and a suggested fee multiplier, the max fee will set an upper bound on the suggested fee (regardless of the multiplier provided)." /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: type: object title: RosettaConstructionSubmitResponse description: TransactionIdentifier contains the transaction_identifier of a transaction that was submitted to either /construction/submit. required: - transaction_identifier additionalProperties: false properties: transaction_identifier: $ref: "#/paths/~1rosetta~1v1~1block~1transaction/post/requestBody/content/appli\ cation~1json/schema/properties/transaction_identifier" metadata: type: object "400": description: Error content: application/json: schema: $ref: "#/paths/~1rosetta~1v1~1network~1list/post/responses/400/content/applicat\ ion~1json/schema" requestBody: required: true content: application/json: schema: type: object title: RosettaConstructionSubmitRequest description: Submit the transaction in blockchain required: - network_identifier - signed_transaction additionalProperties: false properties: network_identifier: $ref: "#/paths/~1rosetta~1v1~1network~1list/post/responses/200/content/applicat\ ion~1json/schema/properties/network_identifiers/items" signed_transaction: type: string description: Signed transaction example: network_identifier: blockchain: stacks network: mainnet signed_transaction: "0x80800000000400539886f96611ba3ba6cef9618f8c78118b37c5be00\ 0000000000000000000000000000b400017a33a91515ef48608a99c6adecd2e\ b258e11534a1acf66348f5678c8e2c8f83d243555ed67a0019d3500df98563c\ a31321c1a675b43ef79f146e322fe08df75103020000000000051a1ae3f911d\ 8f1d46d7416bfbe4b593fd41eac19cb000000000007a1200000000000000000\ 0000000000000000000000000000000000000000000000000000" /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: type: object title: RosettaConstructionPayloadResponse description: RosettaConstructionPayloadResponse is returned by /construction/payloads. It contains an unsigned transaction blob (that is usually needed to construct the a network transaction from a collection of signatures) and an array of payloads that must be signed by the caller. required: - unsigned_transaction - payloads additionalProperties: false properties: unsigned_transaction: type: string description: This is an unsigned transaction blob (that is usually needed to construct the a network transaction from a collection of signatures) payloads: type: array description: An array of payloads that must be signed by the caller items: type: object title: SigningPayload description: SigningPayload is signed by the client with the keypair associated with an address using the specified SignatureType. SignatureType can be optionally populated if there is a restriction on the signature scheme that can be used to sign the payload. required: - hex_bytes additionalProperties: false properties: address: type: string description: "[DEPRECATED by account_identifier in v1.4.4] The network-specific address of the account that should sign the payload." account_identifier: $ref: "#/paths/~1rosetta~1v1~1account~1balance/post/requestBody/content/applica\ tion~1json/schema/properties/account_identifier" hex_bytes: type: string signature_type: type: string description: SignatureType is the type of a cryptographic signature. enum: - ecdsa - ecdsa_recovery - ed25519 - schnorr_1 - schnorr_poseidon "400": description: Error content: application/json: schema: $ref: "#/paths/~1rosetta~1v1~1network~1list/post/responses/400/content/applicat\ ion~1json/schema" requestBody: required: true content: application/json: schema: type: object title: RosettaConstructionPayloadsRequest description: ConstructionPayloadsRequest is the request to /construction/payloads. It contains the network, a slice of operations, and arbitrary metadata that was returned by the call to /construction/metadata. Optionally, the request can also include an array of PublicKeys associated with the AccountIdentifiers returned in ConstructionPreprocessResponse. required: - network_identifier - operations additionalProperties: false properties: network_identifier: $ref: "#/paths/~1rosetta~1v1~1network~1list/post/responses/200/content/applicat\ ion~1json/schema/properties/network_identifiers/items" operations: type: array items: $ref: "#/paths/~1rosetta~1v1~1construction~1parse/post/responses/200/content/ap\ plication~1json/schema/properties/operations/items" public_keys: type: array items: $ref: "#/paths/~1rosetta~1v1~1construction~1derive/post/requestBody/content/app\ lication~1json/schema/properties/public_key" metadata: type: object properties: account_sequence: type: integer recent_block_hash: type: string example: network_identifier: blockchain: stacks network: mainnet operations: - operation_identifier: index: 0 network_index: 0 related_operations: - index: 0 network_index: 0 type: stack_stx status: success account: address: STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6 metadata: {} /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: type: object title: RosettaConstructionCombineResponse description: RosettaConstructionCombineResponse is returned by /construction/combine. The network payload will be sent directly to the construction/submit endpoint. required: - signed_transaction additionalProperties: false properties: signed_transaction: type: string description: Signed transaction bytes in hex "400": description: Error content: application/json: schema: $ref: "#/paths/~1rosetta~1v1~1network~1list/post/responses/400/content/applicat\ ion~1json/schema" requestBody: required: true content: application/json: schema: type: object title: RosettaConstructionCombineRequest description: RosettaConstructionCombineRequest is the input to the /construction/combine endpoint. It contains the unsigned transaction blob returned by /construction/payloads and all required signatures to create a network transaction. required: - network_identifier - unsigned_transaction - signatures additionalProperties: false properties: network_identifier: $ref: "#/paths/~1rosetta~1v1~1network~1list/post/responses/200/content/applicat\ ion~1json/schema/properties/network_identifiers/items" unsigned_transaction: type: string signatures: type: array items: type: object title: RosettaSignature description: Signature contains the payload that was signed, the public keys of the keypairs used to produce the signature, the signature (encoded in hex), and the SignatureType. PublicKey is often times not known during construction of the signing payloads but may be needed to combine signatures properly. required: - signing_payload - public_key - signature_type - hex_bytes additionalProperties: false properties: signing_payload: $ref: "#/paths/~1rosetta~1v1~1construction~1payloads/post/responses/200/content\ /application~1json/schema/properties/payloads/items" public_key: $ref: "#/paths/~1rosetta~1v1~1construction~1derive/post/requestBody/content/app\ lication~1json/schema/properties/public_key" signature_type: title: SignatureType type: string description: SignatureType is the type of a cryptographic signature. enum: - ecdsa - ecdsa_recovery - ed25519 - schnorr_1 - schnorr_poseidon hex_bytes: type: string example: network_identifier: blockchain: stacks network: mainnet unsigned_transaction: 00000000010400539886f96611ba3ba6cef9618f8c78118b37c5be0000000000000000000000000000006400000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000003020000000000051ab71a091b4b8b7661a661c620966ab6573bc2dcd3000000000007a12074657374207472616e73616374696f6e000000000000000000000000000000000000 signatures: - signing_payload: address: string account_identifier: address: STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6 metadata: {} hex_bytes: string signature_type: ecdsa public_key: hex_bytes: 025c13b2fc2261956d8a4ad07d481b1a3b2cbf93a24f992249a61c3a1c4de79c51 curve_type: secp256k1 signature_type: ecdsa hex_bytes: string "/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: title: BnsGetNamespacePriceResponse description: Fetch price for namespace. additionalProperties: false required: - units - amount type: object properties: units: type: string amount: type: string pattern: ^[0-9]+$ "/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: title: BnsGetNamePriceResponse description: Fetch price for name. additionalProperties: false required: - units - amount type: object properties: units: type: string amount: type: string pattern: ^[0-9]+$ /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: title: BnsGetAllNamespacesResponse description: Fetch a list of all namespaces known to the node. additionalProperties: false required: - namespaces type: object properties: namespaces: type: array items: type: string example: namespaces: - id - helloworld - podcast - graphite - blockstack "/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: title: BnsGetAllNamespacesNamesResponse description: Fetch a list of names from the namespace. type: array items: type: string pattern: ^([a-z0-9-_.+]{3,37})$ example: - aldenquimby.id - aldeoryn.id - alderete.id - aldert.id - aldi.id - aldighieri.id "400": description: Error content: application/json: schema: title: BnsError description: Error type: object additionalProperties: false properties: error: type: string example: error: Invalid page "404": description: Error content: application/json: schema: $ref: "#/paths/~1v1~1namespaces~1%7Btld%7D~1names/get/responses/400/content/app\ lication~1json/schema" example: error: No such namespace /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: title: BnsGetAllNamesResponse description: Fetch a list of all names known to the node. type: array items: type: string pattern: ^([a-z0-9\-_.+]{3,37})$ example: - aldenquimby.id - aldeoryn.id - alderete.id - aldert.id - aldi.id - aldighieri.id "400": description: Error content: application/json: schema: $ref: "#/paths/~1v1~1namespaces~1%7Btld%7D~1names/get/responses/400/content/app\ lication~1json/schema" example: $ref: "#/paths/~1v1~1namespaces~1%7Btld%7D~1names/get/responses/400/content/app\ lication~1json/example" "/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: title: BnsGetNameInfoResponse description: Get name details type: object additionalProperties: false required: - address - blockchain - last_txid - status - zonefile - zonefile_hash properties: address: type: string blockchain: type: string pattern: ^stacks$ expire_block: type: integer minimum: 0 grace_period: type: integer minimum: 0 last_txid: type: string resolver: type: string status: type: string zonefile: type: string zonefile_hash: type: string example: address: 1J3PUxY5uDShUnHRrMyU6yKtoHEUPhKULs blockchain: bitcoin expire_block: 599266 grace_period: false last_txid: 1edfa419f7b83f33e00830bc9409210da6c6d1db60f99eda10c835aa339cad6b renewal_deadline: 604266 resolver: null status: registered zonefile: > $ORIGIN muneeb.id $TTL 3600 _http._tcp IN URI 10 1 "https://gaia.blockstack.org/hub/1J3PUxY5uDShUnHRrMyU6yKtoHEUPhKULs/0/profile.json" zonefile_hash: 37aecf837c6ae9bdc9dbd98a268f263dacd00361 "400": description: Error content: application/json: schema: $ref: "#/paths/~1v1~1namespaces~1%7Btld%7D~1names/get/responses/400/content/app\ lication~1json/schema" example: error: Invalid name or subdomain "404": description: Error content: application/json: schema: $ref: "#/paths/~1v1~1namespaces~1%7Btld%7D~1names/get/responses/400/content/app\ lication~1json/schema" example: error: No such name "/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: title: GetAllSubdomainsInName description: Fetch a list of subdomains in a name. type: array items: type: string pattern: ^([a-z0-9-_.+]{3,37})$ example: - address_test.id.blockstack - previous_subdomain.id.blockstack - subdomain.id.blockstack - zonefile_test.id.blockstack - zone_test.id.blockstack "/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: title: BnsFetchFileZoneResponse description: Fetch 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. anyOf: - type: object additionalProperties: false properties: zonefile: type: string pattern: .+ - type: object additionalProperties: false properties: error: type: string pattern: .+ example: zonefile: > $ORIGIN bar.test $TTL 3600 _https._tcp URI 10 1 "https://gaia.blockstack.org/hub/17Zijx61Sp7SbVfRTdETo7PhizJHYEUxbY/profile.json" "400": description: Error content: application/json: schema: $ref: "#/paths/~1v1~1namespaces~1%7Btld%7D~1names/get/responses/400/content/app\ lication~1json/schema" example: $ref: "#/paths/~1v1~1names~1%7Bname%7D/get/responses/400/content/application~1j\ son/example" "404": description: Error content: application/json: schema: $ref: "#/paths/~1v1~1namespaces~1%7Btld%7D~1names/get/responses/400/content/app\ lication~1json/schema" example: error: No zone file for name "/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: title: BnsFetchHistoricalZoneFileResponse description: Fetches the historical zonefile specified by the username and zone hash. anyOf: - type: object additionalProperties: false properties: zonefile: type: string - type: object additionalProperties: false properties: error: type: string example: title: BnsFetchHistoricalZoneFileResponse description: Fetches the historical zonefile specified by the username and zone hash. anyOf: - type: object properties: zonefile: type: string - type: object properties: error: type: string "400": description: Error content: application/json: schema: $ref: "#/paths/~1v1~1namespaces~1%7Btld%7D~1names/get/responses/400/content/app\ lication~1json/schema" example: $ref: "#/paths/~1v1~1names~1%7Bname%7D/get/responses/400/content/application~1j\ son/example" "404": description: Error content: application/json: schema: $ref: "#/paths/~1v1~1namespaces~1%7Btld%7D~1names/get/responses/400/content/app\ lication~1json/schema" example: $ref: "#/paths/~1v1~1names~1%7Bname%7D~1zonefile/get/responses/404/content/appl\ ication~1json/example" "/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: title: BnsNamesOwnByAddressResponse description: Retrieves a list of names owned by the address provided. additionalProperties: false required: - names type: object properties: names: type: array items: type: string pattern: ^([a-z0-9-_.+]{3,37})$ example: names: - muneeb.id "404": description: Error content: application/json: schema: $ref: "#/paths/~1v1~1namespaces~1%7Btld%7D~1names/get/responses/400/content/app\ lication~1json/schema" example: error: Unsupported blockchain "/extended/v1/tx/block/{block_hash}": get: operationId: get_transactions_by_block_hash summary: Transactions by block hash description: Retrieves a list of all transactions within a block for a given block hash. tags: - Transactions parameters: - name: block_hash in: path description: Hash of block required: true schema: type: string 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: "#/paths/~1extended~1v1~1tx/get/responses/200/content/application~1json/s\ chema" example: $ref: "#/paths/~1extended~1v1~1tx/get/responses/200/content/application~1json/e\ xample" "/extended/v1/tx/block_height/{height}": get: operationId: get_transactions_by_block_height summary: Transactions by block height description: Retrieves all transactions within a block at a given height tags: - Transactions parameters: - name: height in: path description: Height of block required: true schema: type: integer 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: "#/paths/~1extended~1v1~1tx/get/responses/200/content/application~1json/s\ chema" example: $ref: "#/paths/~1extended~1v1~1tx/get/responses/200/content/application~1json/e\ xample" "/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: "#/paths/~1extended~1v1~1tx~1mempool/get/responses/200/content/applicatio\ n~1json/schema" example: $ref: "#/paths/~1extended~1v1~1tx~1mempool/get/responses/200/content/applicatio\ n~1json/example" /extended/v1/tokens/ft/metadata: get: operationId: get_ft_metadata_list summary: Fungible tokens metadata list deprecated: true description: > **NOTE:** This endpoint is deprecated in favor of the [Token Metadata Service](https://github.com/hirosystems/token-metadata-service). Retrieves list of fungible tokens with their metadata. More information on Fungible Tokens on the Stacks blockchain can be found [here](https://docs.stacks.co/write-smart-contracts/tokens#fungible-tokens). tags: - Fungible Tokens parameters: - name: limit in: query description: max number of tokens to fetch. required: false schema: type: integer example: 100 maximum: 200 - name: offset in: query description: index of first tokens to fetch required: false schema: type: integer example: 42000 responses: "200": description: List of fungible tokens metadata content: application/json: schema: description: List of fungible tokens metadata title: FungibleTokensMetadataList type: object additionalProperties: false required: - results - limit - offset - total properties: limit: type: integer maximum: 200 description: The number of tokens metadata to return offset: type: integer description: The number to tokens metadata to skip (starting at `0`) total: type: integer description: The number of tokens metadata available results: type: array items: title: FungibleTokenMetadata type: object additionalProperties: false required: - token_uri - name - description - image_uri - image_canonical_uri - symbol - decimals - tx_id - sender_address properties: token_uri: type: string description: An optional string that is a valid URI which resolves to this token's metadata. Can be empty. name: type: string description: Identifies the asset to which this token represents description: type: string description: Describes the asset to which this token represents image_uri: type: string description: A URI pointing to a resource with mime type image/* representing the asset to which this token represents. The API may provide a URI to a cached resource, dependending on configuration. Otherwise, this can be the same value as the canonical image URI. image_canonical_uri: type: string description: The original image URI specified by the contract. A URI pointing to a resource with mime type image/* representing the asset to which this token represents. Consider making any images at a width between 320 and 1080 pixels and aspect ratio between 1.91:1 and 4:5 inclusive. symbol: type: string description: 'A shorter representation of a token. This is sometimes referred to as a "ticker". Examples: "STX", "COOL", etc. Typically, a token could be referred to as $SYMBOL when referencing it in writing.' decimals: type: number description: The number of decimal places in a token. tx_id: type: string description: Tx id that deployed the contract sender_address: type: string description: principle that deployed the contract example: limit: 1 offset: 0 total: 500 results: - token_uri: https://heystack.xyz/token-metadata.json name: Heystack description: Heystack is a SIP-010-compliant fungible token on the Stacks Blockchain, used on the Heystack app image_uri: https://heystack.xyz/assets/Stacks128w.png image_canonical_uri: https://heystack.xyz/assets/Stacks128w.png tx_id: 0xef2ac1126e16f46843228b1dk4830e19eb7599129e4jf392cab9e65ae83a45c0 sender_address: ST399W7Z9WS0GMSNQGJGME5JAENKN56D65VGMGKGA symbol: HEY decimals: 5 /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 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: description: List of Non-Fungible Token holdings title: NonFungibleTokenHoldingsList type: object required: - results - limit - offset - total additionalProperties: false properties: limit: type: integer maximum: 200 description: The number of Non-Fungible Token holdings to return offset: type: integer description: The number to Non-Fungible Token holdings to skip (starting at `0`) total: type: integer description: The number of Non-Fungible Token holdings available results: type: array items: type: object title: NonFungibleTokenHolding description: Describes the ownership of a Non-Fungible Token additionalProperties: false anyOf: - type: object title: NonFungibleTokenHoldingWithTxId description: Ownership of a Non-Fungible Token required: - asset_identifier - value - tx_id - block_height additionalProperties: false properties: asset_identifier: type: string value: type: object required: - hex - repr description: Non-Fungible Token value additionalProperties: false properties: hex: type: string description: Hex string representing the identifier of the Non-Fungible Token repr: type: string description: Readable string of the Non-Fungible Token identifier block_height: type: number tx_id: type: string - type: object title: NonFungibleTokenHoldingWithTxMetadata description: Ownership of a Non-Fungible Token with transaction metadata required: - asset_identifier - value - tx - block_height additionalProperties: false properties: asset_identifier: type: string value: type: object required: - hex - repr description: Non-Fungible Token value additionalProperties: false properties: hex: type: string description: Hex string representing the identifier of the Non-Fungible Token repr: type: string description: Readable string of the Non-Fungible Token identifier block_height: type: number tx: $ref: "#/paths/~1extended~1v1~1tx/get/responses/200/content/application~1json/s\ chema/properties/results/items" examples: default: value: limit: 50 offset: 0 total: 3 results: - asset_identifier: SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173.the-explorer-guild::The-Explorer-Guild value: hex: "0x0100000000000000000000000000000803" repr: u2051 block_height: 36442 tx_id: "0x12e6f88724d0e630de26c376f172cf1781e25435e2b4ee54d36a949b244e429c" - asset_identifier: SP2BE8TZATXEVPGZ8HAFZYE5GKZ02X0YDKAN7ZTGW.arties::arties value: hex: "0x01000000000000000000000000000004f3" repr: u1267 block_height: 37477 tx_id: "0xddc464c5e20a78dc5ac351913e0d9b9cce76fc955cc4599e0cccad960998f130" - asset_identifier: SP000000000000000000002Q6VF78.bns::names value: hex: "0x0c00000002046e616d65020000000672616661656c096e616d657370616365020000000\ 3627463" repr: (tuple (name 0x72616661656c) (namespace 0x627463)) block_height: 17250 tx_id: "0x0153a41ed24a0e1d32f66ea98338df09f942571ca66359e28bdca79ccd0305cf" with transaction metadata: value: limit: 50 offset: 0 total: 3 results: - asset_identifier: SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173.the-explorer-guild::The-Explorer-Guild value: hex: "0x0100000000000000000000000000000803" repr: u2051 block_height: 36442 tx: tx_id: "0x12e6f88724d0e630de26c376f172cf1781e25435e2b4ee54d36a949b244e429c" nonce: 7 fee_rate: "812000" sender_address: SP3BK1NNSWN719Z6KDW05RBGVS940YCN6X84STYPR sponsored: false post_condition_mode: deny post_conditions: - type: stx condition_code: sent_equal_to amount: "100000000" principal: type_id: principal_standard address: SP3BK1NNSWN719Z6KDW05RBGVS940YCN6X84STYPR anchor_mode: any is_unanchored: false block_hash: "0x8a809916e35577337c3f9812a57d61666fde63932b1bdd1c4d1e2f24fb72d46c" parent_block_hash: "0xacf8dd56e08bd7986a5bae5e0f13d8dca8cb3a2dc5a1c4d739fda3b3b\ 378b01d" block_height: 36442 burn_block_time: 1635994340 burn_block_time_iso: 2021-11-04T02:52:20.000Z parent_burn_block_time: 1635994054 parent_burn_block_time_iso: 2021-11-04T02:47:34.000Z canonical: true tx_index: 4 tx_status: success tx_result: hex: "0x070100000000000000000000000000000803" repr: (ok u2051) microblock_hash: "" microblock_sequence: 2147483647 microblock_canonical: true event_count: 2 events: [] execution_cost_read_count: 14 execution_cost_read_length: 91190 execution_cost_runtime: 92297000 execution_cost_write_count: 3 execution_cost_write_length: 19 tx_type: contract_call contract_call: contract_id: SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173.the-explorer-guild-mint function_name: claim function_signature: (define-public (claim )) - asset_identifier: SP2BE8TZATXEVPGZ8HAFZYE5GKZ02X0YDKAN7ZTGW.arties::arties value: hex: "0x01000000000000000000000000000004f3" repr: u1267 block_height: 37477 tx: tx_id: "0xddc464c5e20a78dc5ac351913e0d9b9cce76fc955cc4599e0cccad960998f130" nonce: 10 fee_rate: "148800" sender_address: SP3BK1NNSWN719Z6KDW05RBGVS940YCN6X84STYPR sponsored: false post_condition_mode: deny post_conditions: - type: stx condition_code: sent_less_than_or_equal_to amount: "98000000" principal: type_id: principal_standard address: SP3BK1NNSWN719Z6KDW05RBGVS940YCN6X84STYPR anchor_mode: any is_unanchored: false block_hash: "0xe69b275471bd199f957d82af1c36114695dbc9aa350e012c6326af4d9e4f3e9c" parent_block_hash: "0xe3f50b1c2ef72d44ee5ab84063f49b5662062a62160c783c1c2cc5ca4\ 24dcdeb" block_height: 37477 burn_block_time: 1636668151 burn_block_time_iso: 2021-11-11T22:02:31.000Z parent_burn_block_time: 1636666649 parent_burn_block_time_iso: 2021-11-11T21:37:29.000Z canonical: true tx_index: 38 tx_status: success tx_result: hex: "0x0703" repr: (ok true) microblock_hash: "0x92cb7e692a486210dc50a380e458cdf93c77d90b69d2a9cf29f09383b8b\ 77937" microblock_sequence: 0 microblock_canonical: true event_count: 5 events: [] execution_cost_read_count: 18 execution_cost_read_length: 6832 execution_cost_runtime: 8339000 execution_cost_write_count: 6 execution_cost_write_length: 22 tx_type: contract_call contract_call: contract_id: SP2BE8TZATXEVPGZ8HAFZYE5GKZ02X0YDKAN7ZTGW.arties function_name: claim function_signature: (define-public (claim )) - asset_identifier: SP000000000000000000002Q6VF78.bns::names value: hex: "0x0c00000002046e616d65020000000672616661656c096e616d657370616365020000000\ 3627463" repr: (tuple (name 0x72616661656c) (namespace 0x627463)) block_height: 17250 tx: tx_id: "0x0153a41ed24a0e1d32f66ea98338df09f942571ca66359e28bdca79ccd0305cf" nonce: 4 fee_rate: "228" sender_address: SP3BK1NNSWN719Z6KDW05RBGVS940YCN6X84STYPR sponsored: false post_condition_mode: deny post_conditions: [] anchor_mode: any is_unanchored: false block_hash: "0xb0a0832ece862e9b0d4a02e5f5ef427b09e9880fd3c834fcf63cb2617eac899c" parent_block_hash: "0xc3a3a6866cd8bd01b80f28d158eb14e0bd6e11d4b3de2f13f15c5c5b3\ 721c4f0" block_height: 17250 burn_block_time: 1622650415 burn_block_time_iso: 2021-06-02T16:13:35.000Z parent_burn_block_time: 1622649808 parent_burn_block_time_iso: 2021-06-02T16:03:28.000Z canonical: true tx_index: 74 tx_status: success tx_result: hex: "0x0703" repr: (ok true) microblock_hash: "" microblock_sequence: 2147483647 microblock_canonical: true event_count: 2 events: [] execution_cost_read_count: 17 execution_cost_read_length: 44630 execution_cost_runtime: 56773000 execution_cost_write_count: 4 execution_cost_write_length: 604 tx_type: contract_call contract_call: contract_id: SP000000000000000000002Q6VF78.bns function_name: name-register function_signature: (define-public (name-register (namespace (buff 20)) (name (buff 48)) (salt (buff 20)) (zonefile-hash (buff 20)))) function_args: - hex: "0x0200000003627463" repr: "0x627463" name: namespace type: (buff 20) - hex: "0x020000000672616661656c" repr: "0x72616661656c" name: name type: (buff 48) - hex: "0x020000001419db1f02d2b7ac9cddc8f98b6065d3fad558dcf4" repr: "0x19db1f02d2b7ac9cddc8f98b6065d3fad558dcf4" name: salt type: (buff 20) - hex: "0x0200000014ab4ef66dae18da2ecfe7826bc7d8eaf0b19950c4" repr: "0xab4ef66dae18da2ecfe7826bc7d8eaf0b19950c4" name: zonefile-hash type: (buff 20) /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: description: List of Non-Fungible Token history events title: NonFungibleTokenHistoryEventList type: object required: - results - limit - offset - total additionalProperties: false properties: limit: type: integer maximum: 200 description: The number of events to return offset: type: integer description: The number to events to skip (starting at `0`) total: type: integer description: The number of events available results: type: array items: type: object title: NonFungibleTokenHistoryEvent description: Describes an event from the history of a Non-Fungible Token additionalProperties: false anyOf: - type: object title: NonFungibleTokenHistoryEventWithTxId description: Non-Fungible Token history event with transaction id required: - event_index - asset_event_type - tx_id additionalProperties: false properties: sender: type: string nullable: true recipient: type: string event_index: type: integer asset_event_type: type: string tx_id: type: string - type: object title: NonFungibleTokenHistoryEventWithTxMetadata description: Non-Fungible Token history event with transaction metadata required: - event_index - asset_event_type - tx additionalProperties: false properties: sender: type: string nullable: true recipient: type: string event_index: type: integer asset_event_type: type: string tx: $ref: "#/paths/~1extended~1v1~1tx/get/responses/200/content/application~1json/s\ chema/properties/results/items" examples: default: value: limit: 50 offset: 0 total: 2 results: - sender: SPZGN4KG2AKNNPEWVXXB6EWN1W9WV1JWMGBVVNK3 recipient: SPNWZ5V2TPWGQGVDR6T7B6RQ4XMGZ4PXTEE0VQ0S.marketplace-v4 event_index: 0 asset_event_type: transfer tx_id: "0x4510e6cff6414747f402126b92e35d90165f9f5e1f2750f50ed2b8e052b25108" - sender: null recipient: SPZGN4KG2AKNNPEWVXXB6EWN1W9WV1JWMGBVVNK3 event_index: 1 asset_event_type: mint tx_id: "0x3ab1ac33ba0a4fb473ee5a2e9d73208a7aceef2d40fea283e3126bda61524ad0" with transaction metadata: value: limit: 50 offset: 0 results: - sender: SPZGN4KG2AKNNPEWVXXB6EWN1W9WV1JWMGBVVNK3 recipient: SPNWZ5V2TPWGQGVDR6T7B6RQ4XMGZ4PXTEE0VQ0S.marketplace-v4 event_index: 0 asset_event_type: transfer tx: tx_id: "0x4510e6cff6414747f402126b92e35d90165f9f5e1f2750f50ed2b8e052b25108" nonce: 44 fee_rate: "143600" sender_address: SPZGN4KG2AKNNPEWVXXB6EWN1W9WV1JWMGBVVNK3 sponsored: false post_condition_mode: deny post_conditions: - type: non_fungible condition_code: sent principal: type_id: principal_standard address: SPZGN4KG2AKNNPEWVXXB6EWN1W9WV1JWMGBVVNK3 asset: contract_name: the-explorer-guild asset_name: The-Explorer-Guild contract_address: SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173 asset_value: hex: "0x01000000000000000000000000000009c5" repr: u2501 anchor_mode: any is_unanchored: false block_hash: "0x236721170b99d5dc0be2e77b5f5e0394ffe49af7862c3e82b91245b50e28d191" parent_block_hash: "0xdf9e6a371ef6706ed9e5362f61981d3e9e1b985acb67495490bacc403\ 91d7372" block_height: 37482 burn_block_time: 1636673415 burn_block_time_iso: 2021-11-11T23:30:15.000Z parent_burn_block_time: 1636672174 parent_burn_block_time_iso: 2021-11-11T23:09:34.000Z canonical: true tx_index: 35 tx_status: success tx_result: hex: "0x0703" repr: (ok true) microblock_hash: "" microblock_sequence: 2147483647 microblock_canonical: true event_count: 1 events: [] execution_cost_read_count: 17 execution_cost_read_length: 50450 execution_cost_runtime: 54533000 execution_cost_write_count: 2 execution_cost_write_length: 685 tx_type: contract_call contract_call: contract_id: SPNWZ5V2TPWGQGVDR6T7B6RQ4XMGZ4PXTEE0VQ0S.marketplace-v4 function_name: list-asset function_signature: (define-public (list-asset (tradables trait_reference) (tradable-id uint) (price uint) (commission uint))) function_args: - hex: "0x061605d06be54b4b9fa14cb9bd464635c0bf5287e313127468652d6578706c6f7265722\ d6775696c64" repr: SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173.the-explorer-guild name: tradables type: trait_reference - hex: "0x01000000000000000000000000000009c5" repr: u2501 name: tradable-id type: uint - hex: "0x0100000000000000000000000005f5e100" repr: u100000000 name: price type: uint - hex: "0x0100000000000000000000000000000064" repr: u100 name: commission type: uint - sender: null recipient: SPZGN4KG2AKNNPEWVXXB6EWN1W9WV1JWMGBVVNK3 event_index: 1 asset_event_type: mint tx: tx_id: "0x3ab1ac33ba0a4fb473ee5a2e9d73208a7aceef2d40fea283e3126bda61524ad0" nonce: 37 fee_rate: "81200" sender_address: SPZGN4KG2AKNNPEWVXXB6EWN1W9WV1JWMGBVVNK3 sponsored: false post_condition_mode: deny post_conditions: - type: stx condition_code: sent_equal_to amount: "100000000" principal: type_id: principal_standard address: SPZGN4KG2AKNNPEWVXXB6EWN1W9WV1JWMGBVVNK3 anchor_mode: any is_unanchored: false block_hash: "0xe90233fb36b6a932de91af1b030723ca71335eed7b0792f2c382a827beb5c2f3" parent_block_hash: "0x3c5657455ed593f16b85619814b10e32040dd13d263f1a423ba04a2c2\ 34f8ee9" block_height: 36776 burn_block_time: 1636211530 burn_block_time_iso: 2021-11-06T15:12:10.000Z parent_burn_block_time: 1636211109 parent_burn_block_time_iso: 2021-11-06T15:05:09.000Z canonical: true tx_index: 15 tx_status: success tx_result: hex: "0x0701000000000000000000000000000009c5" repr: (ok u2501) microblock_hash: "" microblock_sequence: 2147483647 microblock_canonical: true event_count: 2 events: [] execution_cost_read_count: 14 execution_cost_read_length: 91190 execution_cost_runtime: 92297000 execution_cost_write_count: 3 execution_cost_write_length: 19 tx_type: contract_call contract_call: contract_id: SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173.the-explorer-guild-mint function_name: claim function_signature: (define-public (claim )) /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: description: List of Non-Fungible Token mint events for an asset identifier title: NonFungibleTokenMintList type: object required: - results - limit - offset - total additionalProperties: false properties: limit: type: integer maximum: 200 description: The number of mint events to return offset: type: integer description: The number to mint events to skip (starting at `0`) total: type: integer description: The number of mint events available results: type: array items: type: object title: NonFungibleTokenMint description: Describes the minting of a Non-Fungible Token additionalProperties: false anyOf: - type: object title: NonFungibleTokenMintWithTxId description: Non-Fungible Token mint event with transaction id required: - event_index - value - tx_id additionalProperties: false properties: recipient: type: string event_index: type: integer value: type: object required: - hex - repr description: Non-Fungible Token value additionalProperties: false properties: hex: type: string description: Hex string representing the identifier of the Non-Fungible Token repr: type: string description: Readable string of the Non-Fungible Token identifier tx_id: type: string - type: object title: NonFungibleTokenMintWithTxMetadata description: Non-Fungible Token mint event with transaction metadata required: - event_index - value - tx additionalProperties: false properties: recipient: type: string event_index: type: integer value: type: object required: - hex - repr description: Non-Fungible Token value additionalProperties: false properties: hex: type: string description: Hex string representing the identifier of the Non-Fungible Token repr: type: string description: Readable string of the Non-Fungible Token identifier tx: $ref: "#/paths/~1extended~1v1~1tx/get/responses/200/content/application~1json/s\ chema/properties/results/items" examples: default: value: limit: 5 offset: 0 total: 2503 results: - recipient: SP25KJH4N4YNKTVXSWSHDPVCWDFAN2BA4H2VQVN0G event_index: 1 value: hex: "0x01000000000000000000000000000009c7" repr: u2503 tx_id: "0xd5c199447bc5f08d1821350455f4c103ad769976c7a6b745182782d53b5c7922" - recipient: SPZGN4KG2AKNNPEWVXXB6EWN1W9WV1JWMGBVVNK3 event_index: 1 value: hex: "0x01000000000000000000000000000009c5" repr: u2501 tx_id: "0x3ab1ac33ba0a4fb473ee5a2e9d73208a7aceef2d40fea283e3126bda61524ad0" - recipient: SPYZ2K1ZTG8NGKNY8VCX8NDKCGCCE9WZT85AGQR event_index: 1 value: hex: "0x01000000000000000000000000000009c6" repr: u2502 tx_id: "0xaaff669db77380600b069fbd3ba481e5764e3672246f952bdd976cd3528019e8" - recipient: SP2EV985DXEHEB2FKW3Z642R0QWQGXTRDYXNRVCYY event_index: 1 value: hex: "0x01000000000000000000000000000009b6" repr: u2486 tx_id: "0xc416218ed09e2252888a620d89a5e8fdff43188c1c4ef46b6bbc4e1901609ef6" - recipient: SPP1VDQKF2H90QZVRBN0K6Z90EKES9NSMYKXHVGH event_index: 9 value: hex: "0x01000000000000000000000000000009bb" repr: u2491 tx_id: "0xbd272748e0d632f8122126f8b000fa0f84c96f464e6fb91b03bb8b9c5c12ed12" with transaction metadata: value: limit: 5 offset: 0 total: 2503 results: - recipient: SP25KJH4N4YNKTVXSWSHDPVCWDFAN2BA4H2VQVN0G event_index: 1 value: hex: "0x01000000000000000000000000000009c7" repr: u2503 tx: tx_id: "0xd5c199447bc5f08d1821350455f4c103ad769976c7a6b745182782d53b5c7922" nonce: 4 fee_rate: "81200" sender_address: SP25KJH4N4YNKTVXSWSHDPVCWDFAN2BA4H2VQVN0G sponsored: false post_condition_mode: deny post_conditions: - type: stx condition_code: sent_equal_to amount: "100000000" principal: type_id: principal_standard address: SP25KJH4N4YNKTVXSWSHDPVCWDFAN2BA4H2VQVN0G anchor_mode: any is_unanchored: false block_hash: "0xde60b4b100b1828dc6383db869b1e051fe68ac3fb0a72fffaae1b18af3e3c675" parent_block_hash: "0xe90233fb36b6a932de91af1b030723ca71335eed7b0792f2c382a827b\ eb5c2f3" block_height: 36777 burn_block_time: 1636213080 burn_block_time_iso: 2021-11-06T15:38:00.000Z parent_burn_block_time: 1636211530 parent_burn_block_time_iso: 2021-11-06T15:12:10.000Z canonical: true tx_index: 11 tx_status: success tx_result: hex: "0x0701000000000000000000000000000009c7" repr: (ok u2503) microblock_hash: "" microblock_sequence: 2147483647 microblock_canonical: true event_count: 2 events: [] execution_cost_read_count: 14 execution_cost_read_length: 91190 execution_cost_runtime: 92297000 execution_cost_write_count: 3 execution_cost_write_length: 19 tx_type: contract_call contract_call: contract_id: SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173.the-explorer-guild-mint function_name: claim function_signature: (define-public (claim )) - recipient: SPZGN4KG2AKNNPEWVXXB6EWN1W9WV1JWMGBVVNK3 event_index: 1 value: hex: "0x01000000000000000000000000000009c5" repr: u2501 tx: tx_id: "0x3ab1ac33ba0a4fb473ee5a2e9d73208a7aceef2d40fea283e3126bda61524ad0" nonce: 37 fee_rate: "81200" sender_address: SPZGN4KG2AKNNPEWVXXB6EWN1W9WV1JWMGBVVNK3 sponsored: false post_condition_mode: deny post_conditions: - type: stx condition_code: sent_equal_to amount: "100000000" principal: type_id: principal_standard address: SPZGN4KG2AKNNPEWVXXB6EWN1W9WV1JWMGBVVNK3 anchor_mode: any is_unanchored: false block_hash: "0xe90233fb36b6a932de91af1b030723ca71335eed7b0792f2c382a827beb5c2f3" parent_block_hash: "0x3c5657455ed593f16b85619814b10e32040dd13d263f1a423ba04a2c2\ 34f8ee9" block_height: 36776 burn_block_time: 1636211530 burn_block_time_iso: 2021-11-06T15:12:10.000Z parent_burn_block_time: 1636211109 parent_burn_block_time_iso: 2021-11-06T15:05:09.000Z canonical: true tx_index: 15 tx_status: success tx_result: hex: "0x0701000000000000000000000000000009c5" repr: (ok u2501) microblock_hash: "" microblock_sequence: 2147483647 microblock_canonical: true event_count: 2 events: [] execution_cost_read_count: 14 execution_cost_read_length: 91190 execution_cost_runtime: 92297000 execution_cost_write_count: 3 execution_cost_write_length: 19 tx_type: contract_call contract_call: contract_id: SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173.the-explorer-guild-mint function_name: claim function_signature: (define-public (claim )) - recipient: SPYZ2K1ZTG8NGKNY8VCX8NDKCGCCE9WZT85AGQR event_index: 1 value: hex: "0x01000000000000000000000000000009c6" repr: u2502 tx: tx_id: "0xaaff669db77380600b069fbd3ba481e5764e3672246f952bdd976cd3528019e8" nonce: 240 fee_rate: "81200" sender_address: SPYZ2K1ZTG8NGKNY8VCX8NDKCGCCE9WZT85AGQR sponsored: false post_condition_mode: deny post_conditions: - type: stx condition_code: sent_equal_to amount: "100000000" principal: type_id: principal_standard address: SPYZ2K1ZTG8NGKNY8VCX8NDKCGCCE9WZT85AGQR anchor_mode: any is_unanchored: false block_hash: "0xe90233fb36b6a932de91af1b030723ca71335eed7b0792f2c382a827beb5c2f3" parent_block_hash: "0x3c5657455ed593f16b85619814b10e32040dd13d263f1a423ba04a2c2\ 34f8ee9" block_height: 36776 burn_block_time: 1636211530 burn_block_time_iso: 2021-11-06T15:12:10.000Z parent_burn_block_time: 1636211109 parent_burn_block_time_iso: 2021-11-06T15:05:09.000Z canonical: true tx_index: 16 tx_status: success tx_result: hex: "0x0701000000000000000000000000000009c6" repr: (ok u2502) microblock_hash: "" microblock_sequence: 2147483647 microblock_canonical: true event_count: 2 events: [] execution_cost_read_count: 14 execution_cost_read_length: 91190 execution_cost_runtime: 92297000 execution_cost_write_count: 3 execution_cost_write_length: 19 tx_type: contract_call contract_call: contract_id: SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173.the-explorer-guild-mint function_name: claim function_signature: (define-public (claim )) - recipient: SP2EV985DXEHEB2FKW3Z642R0QWQGXTRDYXNRVCYY event_index: 1 value: hex: "0x01000000000000000000000000000009b6" repr: u2486 tx: tx_id: "0xc416218ed09e2252888a620d89a5e8fdff43188c1c4ef46b6bbc4e1901609ef6" nonce: 66 fee_rate: "1110000" sender_address: SP2EV985DXEHEB2FKW3Z642R0QWQGXTRDYXNRVCYY sponsored: false post_condition_mode: deny post_conditions: - type: stx condition_code: sent_equal_to amount: "100000000" principal: type_id: principal_standard address: SP2EV985DXEHEB2FKW3Z642R0QWQGXTRDYXNRVCYY anchor_mode: any is_unanchored: false block_hash: "0x97d152c9de27295ebbecf1c5f89b8f693b868f0759ebaa848fe3ce773d7a6576" parent_block_hash: "0x93391aee7c5241a73dbe905f56856743ec14a0bb679c0dfd1f2bf31da\ a515e13" block_height: 36774 burn_block_time: 1636209852 burn_block_time_iso: 2021-11-06T14:44:12.000Z parent_burn_block_time: 1636209581 parent_burn_block_time_iso: 2021-11-06T14:39:41.000Z canonical: true tx_index: 1 tx_status: success tx_result: hex: "0x0701000000000000000000000000000009b6" repr: (ok u2486) microblock_hash: "0x7c1b380d2cea9c0966a66c35aa90c2ad047ea41aa8ab436d78fb7809491\ 40407" microblock_sequence: 0 microblock_canonical: true event_count: 2 events: [] execution_cost_read_count: 14 execution_cost_read_length: 91190 execution_cost_runtime: 92297000 execution_cost_write_count: 3 execution_cost_write_length: 19 tx_type: contract_call contract_call: contract_id: SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173.the-explorer-guild-mint function_name: claim function_signature: (define-public (claim )) - recipient: SPP1VDQKF2H90QZVRBN0K6Z90EKES9NSMYKXHVGH event_index: 9 value: hex: "0x01000000000000000000000000000009bb" repr: u2491 tx: tx_id: "0xbd272748e0d632f8122126f8b000fa0f84c96f464e6fb91b03bb8b9c5c12ed12" nonce: 45 fee_rate: "166400" sender_address: SPP1VDQKF2H90QZVRBN0K6Z90EKES9NSMYKXHVGH sponsored: false post_condition_mode: deny post_conditions: - type: stx condition_code: sent_equal_to amount: "500000000" principal: type_id: principal_standard address: SPP1VDQKF2H90QZVRBN0K6Z90EKES9NSMYKXHVGH anchor_mode: any is_unanchored: false block_hash: "0x97d152c9de27295ebbecf1c5f89b8f693b868f0759ebaa848fe3ce773d7a6576" parent_block_hash: "0x93391aee7c5241a73dbe905f56856743ec14a0bb679c0dfd1f2bf31da\ a515e13" block_height: 36774 burn_block_time: 1636209852 burn_block_time_iso: 2021-11-06T14:44:12.000Z parent_burn_block_time: 1636209581 parent_burn_block_time_iso: 2021-11-06T14:39:41.000Z canonical: true tx_index: 12 tx_status: success tx_result: hex: "0x0703" repr: (ok true) microblock_hash: "0x7c1b380d2cea9c0966a66c35aa90c2ad047ea41aa8ab436d78fb7809491\ 40407" microblock_sequence: 0 microblock_canonical: true event_count: 10 events: [] execution_cost_read_count: 58 execution_cost_read_length: 139642 execution_cost_runtime: 145197000 execution_cost_write_count: 15 execution_cost_write_length: 95 tx_type: contract_call contract_call: contract_id: SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173.the-explorer-guild-mint function_name: claim-five function_signature: (define-public (claim-five )) /extended/v1/tokens/nft/metadata: get: operationId: get_nft_metadata_list summary: Non fungible tokens metadata list deprecated: true description: > **NOTE:** This endpoint is deprecated in favor of the [Token Metadata Service](https://github.com/hirosystems/token-metadata-service). Retrieves a list of non fungible tokens with their metadata. More information on Non-Fungible Tokens on the Stacks blockchain can be found [here](https://docs.stacks.co/write-smart-contracts/tokens#non-fungible-tokens-nfts). tags: - Non-Fungible Tokens parameters: - name: limit in: query description: max number of tokens to fetch required: false schema: type: integer example: 1 - name: offset in: query description: index of first tokens to fetch required: false schema: type: integer example: 42000 responses: "200": description: List of non fungible tokens metadata content: application/json: schema: description: List of non fungible tokens metadata title: NonFungibleTokensMetadataList additionalProperties: false type: object required: - results - limit - offset - total properties: limit: type: integer maximum: 200 description: The number of tokens metadata to return offset: type: integer description: The number to tokens metadata to skip (starting at `0`) total: type: integer description: The number of tokens metadata available results: type: array items: title: NonFungibleTokenMetadata type: object additionalProperties: false required: - token_uri - name - description - image_uri - image_canonical_uri - tx_id - sender_address properties: token_uri: type: string description: An optional string that is a valid URI which resolves to this token's metadata. Can be empty. name: type: string description: Identifies the asset to which this token represents description: type: string description: Describes the asset to which this token represents image_uri: type: string description: A URI pointing to a resource with mime type image/* representing the asset to which this token represents. The API may provide a URI to a cached resource, dependending on configuration. Otherwise, this can be the same value as the canonical image URI. image_canonical_uri: type: string description: The original image URI specified by the contract. A URI pointing to a resource with mime type image/* representing the asset to which this token represents. Consider making any images at a width between 320 and 1080 pixels and aspect ratio between 1.91:1 and 4:5 inclusive. tx_id: type: string description: Tx id that deployed the contract sender_address: type: string description: principle that deployed the contract example: limit: 1 offset: 0 total: 500 results: - token_uri: https://pool.friedger.de/nft.json name: Friedger Pool description: Enjoying the stacking pool. image_uri: https://pool.friedger.de/nft.webp image_canonical_uri: https://pool.friedger.de/nft.webp tx_id: 0xef2ac1126e16f46843228b1dk4830e19eb7599129e4jf392cab9e65ae83a45c0 sender_address: ST399W7Z9WS0GMSNQGJGME5JAENKN56D65VGMGKGA "/extended/v1/tokens/{contractId}/nft/metadata": get: operationId: get_contract_nft_metadata summary: Non fungible tokens metadata for contract ID deprecated: true description: > **NOTE:** This endpoint is deprecated in favor of the [Token Metadata Service](https://github.com/hirosystems/token-metadata-service). Retrieves metadata for non fungible tokens for a given contract id. More information on Non-Fungible Tokens on the Stacks blockchain can be found [here](https://docs.stacks.co/write-smart-contracts/tokens#non-fungible-tokens-nfts). tags: - Non-Fungible Tokens parameters: - name: contractId in: path description: token's contract id required: true schema: type: string responses: "200": description: Non fungible tokens metadata for contract id content: application/json: schema: title: NonFungibleTokenMetadata type: object additionalProperties: false required: - token_uri - name - description - image_uri - image_canonical_uri - tx_id - sender_address properties: token_uri: type: string description: An optional string that is a valid URI which resolves to this token's metadata. Can be empty. name: type: string description: Identifies the asset to which this token represents description: type: string description: Describes the asset to which this token represents image_uri: type: string description: A URI pointing to a resource with mime type image/* representing the asset to which this token represents. The API may provide a URI to a cached resource, dependending on configuration. Otherwise, this can be the same value as the canonical image URI. image_canonical_uri: type: string description: The original image URI specified by the contract. A URI pointing to a resource with mime type image/* representing the asset to which this token represents. Consider making any images at a width between 320 and 1080 pixels and aspect ratio between 1.91:1 and 4:5 inclusive. tx_id: type: string description: Tx id that deployed the contract sender_address: type: string description: principle that deployed the contract example: token_uri: https://pool.friedger.de/nft.json name: Friedger Pool description: Enjoying the stacking pool. image_uri: https://pool.friedger.de/nft.webp image_canonical_uri: https://pool.friedger.de/nft.webp tx_id: 0xef2ac1126e16f46843228b1dk4830e19eb7599129e4jf392cab9e65ae83a45c0 sender_address: ST399W7Z9WS0GMSNQGJGME5JAENKN56D65VGMGKGA "/extended/v1/tokens/{contractId}/ft/metadata": get: operationId: get_contract_ft_metadata summary: Fungible tokens metadata for contract id deprecated: true description: > **NOTE:** This endpoint is deprecated in favor of the [Token Metadata Service](https://github.com/hirosystems/token-metadata-service). Retrieves the metadata for fungible tokens for a given contract id tags: - Fungible Tokens parameters: - name: contractId in: path description: token's contract id required: true schema: type: string example: SPSCWDV3RKV5ZRN1FQD84YE1NQFEDJ9R1F4DYQ11.newyorkcitycoin-token-v2 responses: "200": description: Fungible tokens metadata for contract id content: application/json: schema: title: FungibleTokenMetadata type: object additionalProperties: false required: - token_uri - name - description - image_uri - image_canonical_uri - symbol - decimals - tx_id - sender_address properties: token_uri: type: string description: An optional string that is a valid URI which resolves to this token's metadata. Can be empty. name: type: string description: Identifies the asset to which this token represents description: type: string description: Describes the asset to which this token represents image_uri: type: string description: A URI pointing to a resource with mime type image/* representing the asset to which this token represents. The API may provide a URI to a cached resource, dependending on configuration. Otherwise, this can be the same value as the canonical image URI. image_canonical_uri: type: string description: The original image URI specified by the contract. A URI pointing to a resource with mime type image/* representing the asset to which this token represents. Consider making any images at a width between 320 and 1080 pixels and aspect ratio between 1.91:1 and 4:5 inclusive. symbol: type: string description: 'A shorter representation of a token. This is sometimes referred to as a "ticker". Examples: "STX", "COOL", etc. Typically, a token could be referred to as $SYMBOL when referencing it in writing.' decimals: type: number description: The number of decimal places in a token. tx_id: type: string description: Tx id that deployed the contract sender_address: type: string description: principle that deployed the contract example: token_uri: https://heystack.xyz/token-metadata.json name: Heystack description: Heystack is a SIP-010-compliant fungible token on the Stacks Blockchain, used on the Heystack app image_uri: https://heystack.xyz/assets/Stacks128w.png image_canonical_uri: https://heystack.xyz/assets/Stacks128w.png tx_id: 0xef2ac1126e16f46843228b1dk4830e19eb7599129e4jf392cab9e65ae83a45c0 sender_address: ST399W7Z9WS0GMSNQGJGME5JAENKN56D65VGMGKGA symbol: HEY decimals: 5 /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](#operation/post_fee_transaction). Retrieves estimated fee rate. tags: - Fees responses: "200": description: Transaction fee rate content: application/json: schema: title: FeeRate description: Get fee rate information. type: object additionalProperties: false required: - fee_rate properties: fee_rate: type: integer example: fee_rate: 360 requestBody: required: true content: application/json: schema: type: object title: FeeRateRequest description: Request to fetch fee for a transaction additionalProperties: false required: - transaction properties: transaction: type: string description: A serialized transaction example: transaction: "0x5e9f3933e358df6a73fec0d47ce3e1062c20812c129f5294e6f37a8d27c051d\ 9" /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: description: POST request for estimated fee title: TransactionFeeEstimateRequest type: object additionalProperties: false required: - transaction_payload properties: transaction_payload: type: string estimated_len: type: integer example: estimated_len: 350 transaction_payload: 021af942874ce525e87f21bbe8c121b12fac831d02f4086765742d696e666f0b7570646174652d696e666f00000000 responses: "200": description: Estimated fees for the transaction content: application/json: schema: description: POST response for estimated fee title: TransactionFeeEstimateResponse type: object additionalProperties: false required: - estimated_cost - estimated_cost_scalar properties: estimated_cost_scalar: type: integer cost_scalar_change_by_byte: type: number estimated_cost: type: object additionalProperties: false required: - read_count - write_count - read_length - write_length - runtime properties: read_count: type: integer read_length: type: integer runtime: type: integer write_count: type: integer write_length: type: integer estimations: type: array items: type: object properties: fee_rate: type: number fee: type: number example: cost_scalar_change_by_byte: 0.00476837158203125 estimated_cost: read_count: 19 read_length: 4814 runtime: 7175000 write_count: 2 write_length: 1020 estimated_cost_scalar: 14 estimations: - fee: 17 fee_rate: 1.2410714285714286 - fee: 125 fee_rate: 8.958333333333332 - fee: 140 fee_rate: 10 /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 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: description: GET event for the given transaction title: TransactionEventsResponse type: object additionalProperties: false required: - results - limit - offset properties: limit: type: integer offset: type: integer results: type: array items: $ref: "#/paths/~1extended~1v1~1address~1%7Bprincipal%7D~1assets/get/responses/2\ 00/content/application~1json/schema/properties/results/\ items" example: limit: 96 offset: 0 events: - event_index: 0 event_type: non_fungible_token_asset tx_id: "0x05ccc123db703a2808afaaf88b6b3240f14391d14fde701bd20d7206c9133af6" asset: asset_event_type: transfer asset_id: ST000000000000000000002AMW42H.bns::names sender: STKVDRCTN8C81T22QHR9PG9GPD3V3WPQYBYFHPT4 recipient: STRWN68C36Z7WTDD1TJERTAZ4SXDRMMDB29M4VNQ value: hex: "0x0c00000002046e616d65020000000a62696c616c7465737435096e616d6573706163650\ 200000003627463" repr: (tuple (name 0x62696c616c7465737435) (namespace 0x627463)) - event_index: 1 event_type: smart_contract_log tx_id: "0x05ccc123db703a2808afaaf88b6b3240f14391d14fde701bd20d7206c9133af6" contract_log: contract_id: ST000000000000000000002AMW42H.bns topic: print value: hex: "0x0c000000010a6174746163686d656e740c00000003106174746163686d656e742d696e6\ 46578010000000000000000000000000000028304686173680200\ 000014b472a266d0bd89c13706a4132ccfb16f7c3b9fcb086d657\ 461646174610c00000004046e616d65020000000a62696c616c74\ 65737435096e616d6573706163650200000003627463026f700d0\ 000000d6e616d652d7472616e736665720974782d73656e646572\ 051a27b6e19aaa1880e842bc709b4130b347b1f2d7f2" repr: (tuple (attachment (tuple (attachment-index u643) (hash 0xb472a266d0bd89c13706a4132ccfb16f7c3b9fcb) (metadata (tuple (name 0x62696c616c7465737435) (namespace 0x627463) (op "name-transfer") (tx-sender STKVDRCTN8C81T22QHR9PG9GPD3V3WPQYBYFHPT4)))))) "/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: description: GET request that returns stacking pool member details for a given pool (delegator) principal additionalProperties: false title: PoolDelegationsResponse type: object required: - results - limit - offset - total properties: limit: type: integer maximum: 200 description: The number of Stackers to return offset: type: integer description: The number to Stackers to skip (starting at `0`) default: 0 total: type: integer description: The total number of Stackers results: type: array items: title: PoolDelegation type: object additionalProperties: false required: - stacker - amount_ustx - block_height - tx_id properties: stacker: type: string description: The principal of the pool member that issued the delegation pox_addr: type: string description: The pox-addr value specified by the stacker in the delegation operation amount_ustx: type: string description: The amount of uSTX delegated by the stacker burn_block_unlock_height: type: integer description: The optional burnchain block unlock height that the stacker may have specified block_height: type: integer description: The block height at which the stacker delegation transaction was mined at tx_id: type: string description: The tx_id of the stacker delegation operation example: limit: 200 offset: 0 total: 2 results: - stacker: SPDGWQ60E1QXTC6E4VHKK0NG34EAX554WDFFFHMF pox_addr: bc1qxhmdufsvnuaaaer4ynz88fspdsxq2h9e9cetdj amount_ustx: "2062697998" burn_block_unlock_height: 781984 block_height: 65917 tx_id: "0x3c81cd26ed172a7e552ed245b8b290abefa4f82dfc610a0091ac91c2eed7f9e6" - stacker: SP7RNXF7YBSS43TECXTHF7W1MAB221WWW8RKPGSN pox_addr: 1Di1YoMov6Ua3gPedfQz7TkP6iTLqbPUzi amount_ustx: "4815793194" block_height: 65910 tx_id: "0x1692cd26ed172a7e552ed245b8b290abefa4f82dfc610a0091ac91c2eed7f9e6"