kylefang/stacks-blockchain-api
1
0
Fork 0
mirror of https://github.com/alexgo-io/stacks-blockchain-api.git synced 2026-01-12 16:53:19 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
gh-pages
stacks-blockchain-api/openapi.resolved.yaml

9182 lines
403 KiB
YAML
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

openapi: 3.0.2
servers:
- url: https://stacks-node-api.mainnet.stacks.co/
description: Mainnet
- url: https://stacks-node-api.testnet.stacks.co/
description: Testnet
- url: http://localhost:3999/
description: Local
info:
title: Stacks Blockchain API
version: v1.0.6
description: >
Welcome to the API reference overview for the <a
href="https://docs.hiro.so/get-started/stacks-blockchain-api">Stacks
Blockchain API</a>.
<a href="/collection.json" download="stacks-api-collection.json">Download Postman collection</a>
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: STX address
required: true
schema:
type: string
- name: stacking
in: query
description: Request the amount of STX needed for stacking
required: false
schema:
type: boolean
default: false
post:
summary: Get STX tokens
description: Retrieves STX tokens into you TestNet STX address.
tags:
- Faucets
operationId: run_faucet_stx
responses:
"200":
description: Success
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema#
description: POST request that runs the faucet
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: Failed to run faucet
/extended/v1/faucets/btc:
parameters:
- name: address
in: query
description: BTC address
required: true
schema:
type: string
post:
summary: Get BTC tokens
description: Retrieves BTC tokens into your TestNet BTC address.
tags:
- Faucets
operationId: run_faucet_btc
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"
"500":
description: Failed to run faucet
/extended/v1/tx:
get:
summary: Get recent transactions
tags:
- Transactions
operationId: get_transaction_list
description: >
Retrieves all recently mined transactions
If using TypeScript, import typings for this response from our types package:
`import type { TransactionResults } from '@stacks/stacks-blockchain-api-types';`
parameters:
- name: limit
in: query
description: max number of transactions to fetch
required: false
schema:
type: integer
default: 96
maximum: 200
- name: offset
in: query
description: index of first transaction to fetch
required: false
schema:
type: integer
- name: type
in: query
description: Filter by transaction type
required: false
schema:
type: array
items:
type: string
enum:
- coinbase
- token_transfer
- smart_contract
- contract_call
- poison_microblock
- name: unanchored
in: query
description: Include transaction data from unanchored (i.e. unconfirmed)
microblocks
required: false
schema:
type: boolean
default: false
responses:
"200":
description: List of transactions
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema#
description: GET request that returns transactions
title: TransactionResults
type: object
required:
- results
- limit
- offset
- total
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:
$schema: http://json-schema.org/draft-07/schema#
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.
parameters:
- name: sender_address
in: query
description: Filter to only return transactions with this sender address.
required: false
schema:
type: string
- name: recipient_address
in: query
description: Filter to only return transactions with this recipient address
(only applicable for STX transfer tx types).
required: false
schema:
type: string
- name: address
in: query
description: Filter to only return transactions with this address as the sender
or recipient (recipient only applicable for STX transfer tx types).
required: false
schema:
type: string
- name: limit
in: query
description: max number of mempool transactions to fetch
required: false
schema:
type: integer
default: 96
maximum: 200
- name: offset
in: query
description: index of first mempool transaction to fetch
required: false
schema:
type: integer
- name: unanchored
in: query
description: Include transaction data from unanchored (i.e. unconfirmed)
microblocks
required: false
schema:
type: boolean
default: false
responses:
"200":
description: List of mempool transactions
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema#
description: GET request that returns transactions
title: MempoolTransactionListResponse
type: object
required:
- results
- limit
- offset
- total
properties:
limit:
type: integer
offset:
type: integer
total:
type: integer
results:
type: array
items:
$schema: http://json-schema.org/draft-07/schema#
type: object
title: MempoolTransaction
description: Describes all transaction types on Stacks 2.0 blockchain
anyOf:
- $schema: http://json-schema.org/draft-07/schema#
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:
- $schema: http://json-schema.org/draft-07/schema#
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~1contract~1%7Bcontract_id%7D/get/responses/200/co\
ntent/application~1json/schema/allOf/0/allO\
f/0"
- required:
- tx_status
- receipt_time
- receipt_time_iso
additionalProperties: false
properties:
tx_status:
$schema: http://json-schema.org/draft-07/schema#
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"
- $schema: http://json-schema.org/draft-07/schema#
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~1contract~1%7Bcontract_id%7D/get/responses/200/co\
ntent/application~1json/schema/allOf/1"
- $schema: http://json-schema.org/draft-07/schema#
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"
- $schema: http://json-schema.org/draft-07/schema#
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"
- $schema: http://json-schema.org/draft-07/schema#
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
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/multiple:
parameters:
- name: tx_id
in: query
description: Array of transaction ids
required: true
schema:
type: array
items:
type: string
- name: event_offset
in: query
schema:
type: integer
default: 0
description: The number of events to skip
- name: event_limit
in: query
schema:
type: integer
default: 96
description: The numbers of events to return
- name: unanchored
in: query
description: Include transaction data from unanchored (i.e. unconfirmed) microblocks
required: false
schema:
type: boolean
default: false
get:
summary: Get list of details for transactions
tags:
- Transactions
operationId: get_tx_list_details
description: >
Retrieves a list of transactions for a given list of transaction IDs
If using TypeScript, import typings for this response from our types package:
`import type { Transaction } from '@stacks/stacks-blockchain-api-types';`
responses:
"200":
description: Returns list of transactions with their details for corresponding
requested tx_ids.
content:
application/json:
schema:
$schema: http://json-schema.org/draft-04/schema#
type: object
title: TransactionList
additionalProperties:
anyOf:
- $schema: http://json-schema.org/draft-04/schema#
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"
- $schema: http://json-schema.org/draft-04/schema#
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
- name: event_offset
in: query
schema:
type: integer
default: 0
description: The number of events to skip
- name: event_limit
in: query
schema:
type: integer
default: 96
description: The numbers of events to return
- name: unanchored
in: query
description: Include transaction data from unanchored (i.e. unconfirmed) microblocks
required: false
schema:
type: boolean
default: false
get:
summary: Get transaction
tags:
- Transactions
operationId: get_transaction_by_id
description: >
Retrieves transaction details for a given transaction ID
`import type { Transaction } from '@stacks/stacks-blockchain-api-types';`
responses:
"200":
description: Transaction
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema#
type: object
title: Transaction
description: Describes all transaction types on Stacks 2.0 blockchain
anyOf:
- $schema: http://json-schema.org/draft-07/schema#
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:
- $ref: "#/paths/~1extended~1v1~1contract~1%7Bcontract_id%7D/get/responses/200/co\
ntent/application~1json/schema/allOf/0"
- $schema: http://json-schema.org/draft-07/schema#
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)
- $schema: http://json-schema.org/draft-07/schema#
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~1contract~1%7Bcontract_id%7D/get/responses/200/co\
ntent/application~1json/schema/allOf/0"
- $ref: "#/paths/~1extended~1v1~1contract~1%7Bcontract_id%7D/get/responses/200/co\
ntent/application~1json/schema/allOf/1"
- $schema: http://json-schema.org/draft-07/schema#
type: object
title: ContractCallTransaction
description: "Describes representation of a Type 2 Stacks 2.0 transaction:
Contract Call"
allOf:
- $ref: "#/paths/~1extended~1v1~1contract~1%7Bcontract_id%7D/get/responses/200/co\
ntent/application~1json/schema/allOf/0"
- $schema: http://json-schema.org/draft-07/schema#
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
`<principaladdress>.<contract_name>`
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
- $schema: http://json-schema.org/draft-07/schema#
type: object
title: PoisonMicroblockTransaction
description: "Describes representation of a Type 3 Stacks 2.0 transaction:
Poison Microblock"
allOf:
- $ref: "#/paths/~1extended~1v1~1contract~1%7Bcontract_id%7D/get/responses/200/co\
ntent/application~1json/schema/allOf/0"
- $schema: http://json-schema.org/draft-07/schema#
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
- $schema: http://json-schema.org/draft-07/schema#
type: object
title: CoinbaseTransaction
description: "Describes representation of a Type 3 Stacks 2.0 transaction:
Poison Microblock"
allOf:
- $ref: "#/paths/~1extended~1v1~1contract~1%7Bcontract_id%7D/get/responses/200/co\
ntent/application~1json/schema/allOf/0"
- $schema: http://json-schema.org/draft-07/schema#
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
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
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:
$schema: http://json-schema.org/draft-07/schema#
description: GET raw transaction
title: GetRawTransactionResult
type: object
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:
$schema: http://json-schema.org/draft-07/schema#
description: GET request that returns transactions
title: PostCoreNodeTransactionsError
type: object
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.
parameters:
- name: limit
in: query
description: Max number of microblocks to fetch
required: false
schema:
type: integer
default: 20
maximum: 200
- name: offset
in: query
description: Index of the first microblock to fetch
required: false
schema:
type: integer
responses:
"200":
description: List of microblocks
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/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:
$schema: http://json-schema.org/draft-07/schema#
title: Microblock
description: A microblock
type: object
required:
- canonical
- microblock_canonical
- microblock_hash
- microblock_sequence
- microblock_parent_hash
- parent_index_block_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
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:
$schema: http://json-schema.org/draft-07/schema#
title: Microblock
description: A microblock
type: object
required:
- canonical
- microblock_canonical
- microblock_hash
- microblock_sequence
- microblock_parent_hash
- parent_index_block_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:
$schema: http://json-schema.org/draft-07/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
tags:
- Blocks
operationId: get_block_list
parameters:
- name: limit
in: query
description: max number of blocks to fetch
required: false
schema:
type: integer
default: 20
maximum: 200
- name: offset
in: query
description: index of first block to fetch
required: false
schema:
type: integer
responses:
"200":
description: List of blocks
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/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:
$schema: http://json-schema.org/draft-07/schema#
title: Block
description: A block
type: object
required:
- canonical
- height
- 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
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
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.
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
get:
summary: Get block by hash
description: Retrieves block details of a specific block for a given chain height
tags:
- Blocks
operationId: get_block_by_hash
responses:
"200":
description: Block
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema#
title: Block
description: A block
type: object
required:
- canonical
- height
- 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
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
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.
example:
canonical: true
height: 3275
hash: "0xe77ba8cf6bb7c0e4f64adc83356289ed467d31a22354907b4bb814590058430f"
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
"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
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
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
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
responses:
"200":
description: List of burnchain reward recipients and amounts
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/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:
$schema: http://json-schema.org/draft-07/schema#
title: BurnchainRewardSlotHolder
description: Reward slot holder on the burnchain
type: object
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
- name: limit
in: query
description: max number of items to fetch
required: false
schema:
type: integer
- name: offset
in: query
description: index of the first items to fetch
required: false
schema:
type: integer
responses:
"200":
description: List of burnchain reward recipients and amounts
content:
application/json:
schema:
$ref: "#/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
responses:
"200":
description: List of burnchain reward recipients and amounts
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/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:
$schema: http://json-schema.org/draft-07/schema#
title: BurnchainReward
description: Reward payment made on the burnchain
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
- name: limit
in: query
description: max number of rewards to fetch
required: false
schema:
type: integer
- name: offset
in: query
description: index of first rewards to fetch
required: false
schema:
type: integer
responses:
"200":
description: List of burnchain reward recipients and amounts
content:
application/json:
schema:
$ref: "#/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
responses:
"200":
description: List of burnchain reward recipients and amounts
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema#
title: BurnchainRewardsTotal
description: Total burnchain rewards made to a recipient
type: object
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:
$schema: http://json-schema.org/draft-07/schema#
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:
- $schema: http://json-schema.org/draft-07/schema#
title: AbstractTransaction
description: Anchored transaction metadata. All mined/anchored Stacks
transactions have these properties.
type: object
allOf:
- $schema: http://json-schema.org/draft-07/schema#
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
sponsored:
type: boolean
description: Denotes whether the originating account is the same as the paying
account
sponsor_address:
type: string
post_condition_mode:
$schema: http://json-schema.org/draft-07/schema#
title: PostConditionMode
description: ""
type: string
enum:
- allow
- deny
post_conditions:
type: array
items:
$schema: http://json-schema.org/draft-07/schema#
title: PostCondition
description: Post-conditionscan limit the damage done to a user's assets
anyOf:
- $schema: http://json-schema.org/draft-07/schema#
title: PostConditionStx
type: object
allOf:
- type: object
required:
- principal
properties:
principal:
$schema: http://json-schema.org/draft-07/schema#
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
properties:
condition_code:
$schema: http://json-schema.org/draft-07/schema#
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
- $schema: http://json-schema.org/draft-07/schema#
title: PostConditionFungible
type: object
allOf:
- type: object
required:
- principal
properties:
principal:
$ref: "#/paths/~1extended~1v1~1contract~1%7Bcontract_id%7D/get/responses/200/co\
ntent/application~1json/schema/allO\
f/0/allOf/0/properties/post_conditi\
ons/items/anyOf/0/allOf/0/propertie\
s/principal"
- type: object
required:
- condition_code
- amount
- type
- asset
properties:
condition_code:
$ref: "#/paths/~1extended~1v1~1contract~1%7Bcontract_id%7D/get/responses/200/co\
ntent/application~1json/schema/allO\
f/0/allOf/0/properties/post_conditi\
ons/items/anyOf/0/allOf/1/propertie\
s/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
- $schema: http://json-schema.org/draft-07/schema#
title: PostConditionNonFungible
type: object
allOf:
- type: object
required:
- principal
properties:
principal:
$ref: "#/paths/~1extended~1v1~1contract~1%7Bcontract_id%7D/get/responses/200/co\
ntent/application~1json/schema/allO\
f/0/allOf/0/properties/post_conditi\
ons/items/anyOf/0/allOf/0/propertie\
s/principal"
- type: object
required:
- condition_code
- type
- asset_value
- asset
properties:
condition_code:
$schema: http://json-schema.org/draft-07/schema#
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:
$schema: http://json-schema.org/draft-07/schema#
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:
$schema: http://json-schema.org/draft-07/schema#
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/properties/\
results/items"
- $schema: http://json-schema.org/draft-07/schema#
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:
contract_id:
type: string
description: Contract identifier formatted as
`<principaladdress>.<contract_name>`
source_code:
type: string
description: Clarity code of the smart contract being deployed
example:
tx_id: "0x8122b7ae041120ddc9e2f8108e165912e40ad146399d42d6e6cbca7fd2c8ac28"
tx_status: success
tx_type: smart_contract
fee_rate: "3000"
sender_address: STJTXEJPJPPVDNA9B052NSRRBGQCFNKVS178VGH1
sponsored: false
post_condition_mode: allow
is_unanchored: false
microblock_hash: ""
microblock_sequence: 2147483647
microblock_canonical: true
block_hash: "0x105685d3d4f251d73b75865b192cefb111dd49f67b8970a95094dc7ecf826caa"
block_height: 3196
burn_block_time: 1594228322
canonical: true
tx_index: 1
post_conditions: []
smart_contract:
contract_id: STJTXEJPJPPVDNA9B052NSRRBGQCFNKVS178VGH1.hello_world
source_code: >-
(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)))
events:
- event_index: 0
event_type: fungible_token_asset
asset:
asset_event_type: mint
asset_id: STJTXEJPJPPVDNA9B052NSRRBGQCFNKVS178VGH1.hello_world::novel-token-19
sender: ""
recipient: SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR
amount: "12"
- event_index: 1
event_type: non_fungible_token_asset
asset:
asset_event_type: mint
asset_id: STJTXEJPJPPVDNA9B052NSRRBGQCFNKVS178VGH1.hello_world::hello-nft
sender: ""
recipient: SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR
value:
hex: "0x0100000000000000000000000000000001"
repr: "1"
- event_index: 2
event_type: non_fungible_token_asset
asset:
asset_event_type: mint
asset_id: STJTXEJPJPPVDNA9B052NSRRBGQCFNKVS178VGH1.hello_world::hello-nft
sender: ""
recipient: SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR
value:
hex: "0x0100000000000000000000000000000002"
repr: "2"
- event_index: 3
event_type: smart_contract_log
contract_log:
contract_id: STJTXEJPJPPVDNA9B052NSRRBGQCFNKVS178VGH1.hello_world
topic: print
value:
hex: "0x02000000124576656e74212048656c6c6f20776f726c64"
repr: '"Event! Hello world"'
- event_index: 4
event_type: fungible_token_asset
asset:
asset_event_type: transfer
asset_id: STJTXEJPJPPVDNA9B052NSRRBGQCFNKVS178VGH1.hello_world::novel-token-19
sender: SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR
recipient: SM2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQVX8X0G
amount: "2"
- event_index: 5
event_type: non_fungible_token_asset
asset:
asset_event_type: transfer
asset_id: STJTXEJPJPPVDNA9B052NSRRBGQCFNKVS178VGH1.hello_world::hello-nft
sender: SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR
recipient: SM2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQVX8X0G
value:
hex: "0x0100000000000000000000000000000001"
repr: "1"
"404":
description: Cannot find contract of given ID
parameters:
- name: contract_id
in: path
description: Contract identifier formatted as `<contract_address>.<contract_name>`
required: true
schema:
type: string
- name: unanchored
in: query
description: Include transaction data from unanchored (i.e. unconfirmed) microblocks
required: false
schema:
type: boolean
default: false
/extended/v1/contract/by_trait:
get:
summary: Get contracts by trait
description: Retrieves a list of contracts based on the following traits listed
in JSON format - functions, variables, maps, fungible tokens and
non-fungible tokens
tags:
- Smart Contracts
operationId: get_contracts_by_trait
responses:
"200":
description: List of contracts implement given trait
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/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:
$schema: http://json-schema.org/draft-07/schema#
type: object
title: SmartContract
description: A Smart Contract Detail
required:
- tx_id
- canonical
- block_height
- source_code
- abi
properties:
tx_id:
type: string
canonical:
type: boolean
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 <fungible-token>)) (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 <fungible-token>)) (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 <fungible-token>)) (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
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 `<contract_address>.<contract_name>`
required: true
schema:
type: string
- name: limit
in: query
description: max number of contract events to fetch
required: false
schema:
type: integer
- name: offset
in: query
description: index of first contract event to fetch
required: false
schema:
type: integer
- name: unanchored
in: query
description: Include transaction data from unanchored (i.e. unconfirmed)
microblocks
required: false
schema:
type: boolean
default: false
responses:
"200":
description: List of events
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema#
type: object
title: TransactionEvent
anyOf:
- $schema: http://json-schema.org/draft-07/schema#
type: object
title: TransactionEventSmartContractLog
description: Only present in `smart_contract` and `contract_call` tx types.
allOf:
- $schema: http://json-schema.org/draft-07/schema#
type: object
required:
- event_index
properties:
event_index:
type: integer
- type: object
required:
- event_type
- tx_id
- contract_log
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
- $schema: http://json-schema.org/draft-07/schema#
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
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
- $schema: http://json-schema.org/draft-07/schema#
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
properties:
event_type:
type: string
enum:
- stx_asset
tx_id:
type: string
asset:
$schema: http://json-schema.org/draft-07/schema#
type: object
title: TransactionEventAsset
additionalProperties: false
properties:
asset_event_type:
$schema: http://json-schema.org/draft-07/schema#
title: TransactionEventAssetType
type: string
enum:
- transfer
- mint
- burn
asset_id:
type: string
sender:
type: string
recipient:
type: string
amount:
type: string
value:
type: string
- $schema: http://json-schema.org/draft-07/schema#
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
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
- $schema: http://json-schema.org/draft-07/schema#
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
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:
$schema: http://json-schema.org/draft-07/schema#
description: GET request to get contract interface
title: ContractInterfaceResponse
type: object
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
schema:
type: string
- name: contract_name
in: path
required: true
description: Contract name
schema:
type: string
- name: tip
in: query
schema:
type: string
description: The Stacks chain tip to query from
"/v2/map_entry/{contract_address}/{contract_name}/{map_name}":
post:
summary: Get specific data-map inside a contract
tags:
- Smart Contracts
operationId: get_contract_data_map_entry
description: >
Attempt to fetch data from a contract data map. The contract is
identified with Stacks Address `contract_address` and Contract Name
`contract_address` in the URL path. The map is identified with [Map
Name].
The key to lookup in the map is supplied via the POST body. This should be supplied as the hex string serialization of the key (which should be a Clarity value). Note, this is a JSON string atom.
In the response, `data` is the hex serialization of the map response. Note that map responses are Clarity option types, for non-existent values, this is a serialized none, and for all other responses, it is a serialized (some ...) object.
responses:
"200":
description: Success
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema#
description: Response of get data map entry request
title: MapEntryResponse
type: object
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
- name: contract_name
in: path
required: true
description: Contract name
schema:
type: string
- name: map_name
in: path
required: true
description: Map name
schema:
type: string
- name: proof
in: query
description: Returns object without the proof field when set to 0
schema:
type: integer
- name: tip
in: query
schema:
type: string
description: The Stacks chain tip to query from
x-codegen-request-body-name: key
requestBody:
description: Hex string serialization of the lookup key (which should be a
Clarity value)
required: true
content:
application/json:
schema:
type: string
"/v2/contracts/source/{contract_address}/{contract_name}":
get:
summary: Get contract source
tags:
- Smart Contracts
operationId: get_contract_source
description: Retrieves the Clarity source code of a given contract, along with
the block height it was published in, and the MARF proof for the data
responses:
"200":
description: Success
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/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
- name: contract_name
in: path
required: true
description: Contract name
schema:
type: string
- name: proof
in: query
description: Returns object without the proof field if set to 0
schema:
type: integer
- name: tip
in: query
schema:
type: string
description: The Stacks chain tip to query from
required: false
"/v2/contracts/call-read/{contract_address}/{contract_name}/{function_name}":
post:
summary: Call read-only function
tags:
- Smart Contracts
operationId: call_read_only_function
description: >
Call a read-only public function on a given smart contract.
The smart contract and function are specified using the URL path. The arguments and the simulated tx-sender are supplied via the POST body in the following JSON format:
responses:
"200":
description: Success
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/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:
okay: true
result: 0x111...
fail:
okay: false
cause: Unchecked(PublicFunctionNotReadOnly(...
parameters:
- name: contract_address
in: path
required: true
description: Stacks address
schema:
type: string
- name: contract_name
in: path
required: true
description: Contract name
schema:
type: string
- name: function_name
in: path
required: true
description: Function name
schema:
type: string
- name: tip
in: query
schema:
type: string
description: The Stacks chain tip to query from
required: false
requestBody:
description: map of arguments and the simulated tx-sender where sender is either
a Contract identifier or a normal Stacks address, and arguments is an
array of hex serialized Clarity values.
required: true
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/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
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
"/extended/v1/address/{principal}/balances":
get:
summary: Get account balances
description: Retrieves total account balance information for a given Address or
Contract Identifier. This includes the balances of STX Tokens, Fungible
Tokens and Non-Fungible Tokens for the account.
tags:
- Accounts
operationId: get_account_balance
parameters:
- name: principal
in: path
description: Stacks address or a Contract identifier (e.g.
`SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`)
required: true
schema:
type: string
- name: unanchored
in: query
description: Include transaction data from unanchored (i.e. unconfirmed)
microblocks
required: false
schema:
type: boolean
default: false
- name: until_block
in: query
description: returned data representing the state up until that point in time,
rather than the current block.
required: false
schema:
type: string
responses:
"200":
description: Success
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema#
description: GET request that returns address balances
title: AddressBalanceResponse
type: object
required:
- stx
- fungible_tokens
- non_fungible_tokens
properties:
stx:
$schema: http://json-schema.org/draft-07/schema#
description: 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
patternProperties:
"*":
$schema: http://json-schema.org/draft-07/schema#
description: 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
patternProperties:
"*":
$schema: http://json-schema.org/draft-07/schema#
description: 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:
$schema: http://json-schema.org/draft-07/schema#
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:
$schema: http://json-schema.org/draft-07/schema#
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 (e.g.
`SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`)
required: true
schema:
type: string
- name: unanchored
in: query
description: Include transaction data from unanchored (i.e. unconfirmed)
microblocks
required: false
schema:
type: boolean
default: false
- name: until_block
in: query
description: returned data representing the state up until that point in time,
rather than the current block.
required: false
schema:
type: string
responses:
"200":
description: Success
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/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"
- 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).
tags:
- Accounts
operationId: get_account_transactions
parameters:
- name: principal
in: path
description: Stacks address or a Contract identifier (e.g.
`SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`)
required: true
schema:
type: string
- name: limit
in: query
description: max number of account transactions to fetch
required: false
schema:
type: integer
- name: offset
in: query
description: index of first account transaction to fetch
required: false
schema:
type: integer
- name: height
in: query
description: Filter for transactions only at this given block height
required: false
schema:
type: number
- name: unanchored
in: query
description: Include transaction data from unanchored (i.e. unconfirmed)
microblocks
required: false
schema:
type: boolean
default: false
- name: until_block
in: query
description: returned data representing the state up until that point in time,
rather than the current block.
required: false
schema:
type: string
responses:
"200":
description: Success
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/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 Transcation Id `tx_id`,
for a given account or contract Identifier.
tags:
- Accounts
operationId: get_single_transaction_with_transfers
parameters:
- name: principal
in: path
description: Stacks address or a contract identifier
required: true
schema:
type: string
- name: tx_id
in: path
description: Transaction id
required: true
schema:
type: string
responses:
"200":
description: Success
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/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 (e.g.
`SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`)
required: true
schema:
type: string
- name: limit
in: query
description: max number of account transactions to fetch
required: false
schema:
type: integer
- name: offset
in: query
description: index of first account transaction to fetch
required: false
schema:
type: integer
- name: height
in: query
description: Filter for transactions only at this given block height
required: false
schema:
type: number
- name: unanchored
in: query
description: Include transaction data from unanchored (i.e. unconfirmed)
microblocks
required: false
schema:
type: boolean
default: false
- name: until_block
in: query
description: returned data representing the state up until that point in time,
rather than the current block.
required: false
schema:
type: string
responses:
"200":
description: Success
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/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:
$schema: http://json-schema.org/draft-07/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:
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 (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0`)
required: true
schema:
type: string
- name: block_height
in: query
description: Optionally get the nonce at a given block height
required: false
schema:
type: number
- name: block_hash
in: query
description: Optionally get the nonce at a given block hash
required: false
schema:
type: string
responses:
"200":
description: Success
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/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
example:
last_mempool_tx_nonce: 5
last_executed_tx_nonce: 2
possible_next_nonce: 6
detected_missing_nonces:
- 3
- 4
"/extended/v1/address/{principal}/assets":
get:
summary: Get account assets
description: Retrieves a list of all assets events associated with an account or
a Contract Identifier. This includes Transfers, Mints.
tags:
- Accounts
operationId: get_account_assets
parameters:
- name: principal
in: path
description: Stacks address or a Contract identifier (e.g.
`SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`)
required: true
schema:
type: string
- name: limit
in: query
description: max number of account assets to fetch
required: false
schema:
type: integer
- name: offset
in: query
description: index of first account assets to fetch
required: false
schema:
type: integer
- name: unanchored
in: query
description: Include transaction data from unanchored (i.e. unconfirmed)
microblocks
required: false
schema:
type: boolean
default: false
- name: until_block
in: query
description: returned data representing the state at that point in time, rather
than the current block.
required: false
schema:
type: string
responses:
"200":
description: Success
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema#
description: GET request that returns address assets
title: AddressAssetsListResponse
type: object
required:
- results
- limit
- offset
- total
properties:
limit:
type: integer
maximum: 30
offset:
type: integer
total:
type: integer
results:
type: array
items:
$schema: http://json-schema.org/draft-07/schema#
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 (e.g.
`SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`)
required: true
schema:
type: string
- name: limit
in: query
description: number of items to return
required: false
schema:
type: integer
- name: offset
in: query
description: number of items to skip
required: false
schema:
type: integer
- name: height
in: query
description: Filter for transfers only at this given block height
required: false
schema:
type: number
- name: unanchored
in: query
description: Include transaction data from unanchored (i.e. unconfirmed)
microblocks
required: false
schema:
type: boolean
default: false
- name: until_block
in: query
description: returned data representing the state up until that point in time,
rather than the current block.
required: false
schema:
type: string
responses:
"200":
description: Success
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema#
description: GET request that returns a list of inbound STX transfers with a
memo
title: AddressStxInboundListResponse
type: object
required:
- results
- limit
- offset
- total
properties:
limit:
type: integer
maximum: 30
offset:
type: integer
total:
type: integer
results:
type: array
items:
$schema: http://json-schema.org/draft-07/schema#
title: InboundStxTransfer
description: A inbound STX transfer with a memo
type: object
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
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
description: >
Retrieves a list of all nfts owned by an address, contains the clarity
value of the identifier of the nft
tags:
- Accounts
operationId: get_account_nft
parameters:
- name: principal
in: path
description: Stacks address or a Contract identifier (e.g.
`SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`)
required: true
schema:
type: string
- name: limit
in: query
description: number of items to return
required: false
schema:
type: integer
- name: offset
in: query
description: number of items to skip
required: false
schema:
type: integer
- name: unanchored
in: query
description: Include transaction data from unanchored (i.e. unconfirmed)
microblocks
required: false
schema:
type: boolean
default: false
- name: until_block
in: query
description: returned data representing the state up until that point in time,
rather than the current block.
required: false
schema:
type: string
responses:
"200":
description: Success
content:
application/json:
schema:
$schema: http://json-schema.org/draft-04/schema#
type: object
title: AddressNftListResponse
required:
- limit
- offset
- total
- nft_events
properties:
limit:
type: integer
offset:
type: integer
total:
type: integer
nft_events:
type: array
items:
$schema: http://json-schema.org/draft-04/schema#
type: object
title: NftEvent
required:
- sender
- recipient
- asset_identifier
- value
- tx_id
- block_height
properties:
sender:
type: string
recipient:
type: string
asset_identifier:
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
block_height:
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 (e.g.
`SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`)
required: true
schema:
type: string
- name: proof
in: query
description: Returns object without the proof field if set to 0
schema:
type: integer
- name: tip
in: query
schema:
type: string
description: The Stacks chain tip to query from
responses:
"200":
description: Success
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/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:
$schema: http://json-schema.org/draft-07/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:
$schema: http://json-schema.org/draft-07/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: Get Blockchain API status
description: Retrieves the current status of the blockchain API, including the
server version
tags:
- Info
operationId: get_status
responses:
"200":
description: Success
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/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
example:
server_version: stacks-blockchain-api v0.64.1 (master:439d4f46)
status: ready
/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:
$schema: http://json-schema.org/draft-07/schema#
description: GET request that returns network target block times
title: NetworkBlockTimesResponse
type: object
additionalProperties: false
required:
- mainnet
- testnet
properties:
mainnet:
$schema: http://json-schema.org/draft-07/schema#
description: TargetBlockTime
type: object
additionalProperties: false
required:
- target_block_time
- total_sent
- total_received
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
description: Which network to retrieve the target block time of
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).
parameters:
- in: query
name: height
required: false
schema:
type: number
description: The block height at which to query supply details from, if not
provided then the latest block height is used
responses:
"200":
description: Success
content:
application/json:
example:
unlocked_percent: "71.99"
total_stx: "1352464600.000000"
unlocked_stx: "973705260.219817"
block_height: 3210
schema:
$schema: http://json-schema.org/draft-07/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.
responses:
"200":
description: success
content:
text/plain:
example: "123.456789"
schema:
$schema: http://json-schema.org/draft-07/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:
$schema: http://json-schema.org/draft-07/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.
parameters:
- in: query
name: height
required: false
schema:
type: number
description: The block height at which to query supply details from, if not
provided then the latest block height is used
responses:
"200":
description: Success
content:
application/json:
example:
unlockedPercent: "71.99"
totalStacks: "1352464600.000000"
totalStacksFormatted: 1,352,464,600.000000
unlockedSupply: "973705260.219817"
unlockedSupplyFormatted: 973,705,260.219817
blockHeight: "665746"
schema:
$schema: http://json-schema.org/draft-07/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:
$schema: http://json-schema.org/draft-07/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: ST000000000000000000002AMW42H.pox
first_burnchain_block_height: 0
min_amount_ustx: 150000000000
registration_window_length: 250
rejection_fraction: 25
reward_cycle_id: 0
reward_cycle_length: 1000
rejection_votes_left_required: 1000
total_liquid_supply_ustx: 1000000000
"/extended/v1/search/{id}":
get:
summary: Search
description: Search blocks, transactions, contracts, or accounts by hash/ID
tags:
- Search
parameters:
- in: path
name: id
required: true
schema:
type: string
description: The hex hash string for a block or transaction, account address, or
contract address
- in: query
name: include_metadata
schema:
type: boolean
description: This includes the detailed data for purticular hash in the response
operationId: search_by_id
responses:
"200":
description: Success
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema
type: object
title: SearchResult
description: complete search result for terms
additionalProperties: false
anyOf:
- $schema: http://json-schema.org/draft-07/schema
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
- $schema: http://json-schema.org/draft-07/schema
type: object
title: SearchSuccessResult
description: Search success result
additionalProperties: false
anyOf:
- $schema: http://json-schema.org/draft-07/schema
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:
- $schema: http://json-schema.org/draft-07/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"
- 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"
- $schema: http://json-schema.org/draft-07/schema
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:
type: object
anyOf:
- $ref: "#/paths/~1extended~1v1~1block/get/responses/200/content/application~1jso\
n/schema/properties/results/items"
additionalItems: false
- $schema: http://json-schema.org/draft-07/schema
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"
additionalItems: false
- $schema: http://json-schema.org/draft-07/schema
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:
type: object
anyOf:
- $ref: "#/paths/~1extended~1v1~1tx~1mempool/get/responses/200/content/applicatio\
n~1json/schema/properties/results/items"
additionalItems: false
- $schema: http://json-schema.org/draft-07/schema
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:
type: object
anyOf:
- $ref: "#/paths/~1extended~1v1~1tx/get/responses/200/content/application~1json/s\
chema/properties/results/items"
additionalItems: false
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:
$schema: http://json-schema.org/draft-07/schema
$id: rosetta-network-list-response.schema.json
type: object
title: RosettaNetworkListResponse
description: A NetworkListResponse contains all NetworkIdentifiers that the node
can serve information for.
required:
- network_identifiers
properties:
network_identifiers:
type: array
description: The network_identifier specifies which network a particular object
is associated with.
items:
$schema: http://json-schema.org/draft-07/schema
type: object
title: NetworkIdentifier
description: The network_identifier specifies which network a particular object
is associated with.
required:
- blockchain
- network
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
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:
$schema: http://json-schema.org/draft-07/schema
$id: Rosetta-errors
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.
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.
required: []
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:
$schema: http://json-schema.org/draft-07/schema
$id: rosetta-network-options-response
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
properties:
version:
type: object
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
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:
$schema: http://json-schema.org/draft-07/schema
$id: rosetta-operation-statuses.schema.json
type: object
title: RosettaOperationStatus
description: OperationStatus is utilized to indicate which Operation status are
considered successful.
required:
- status
- successful
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:
$schema: http://json-schema.org/draft-07/schema
$id: Rosetta-errors-no-details
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:
$schema: http://json-schema.org/draft-07/schema
$id: Rosetta-options-request
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
/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:
$schema: http://json-schema.org/draft-07/schema
$id: rosetta-network-status-response.schema.json
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:
$id: rosetta-block-identifier.schema.json
title: RosettaBlockIdentifier
description: The block_identifier uniquely identifies a block in a particular
network.
allOf:
- $id: rosetta-block-identifier-hash.schema.json
type: object
title: RosettaBlockIdentifierHash
description: This is also known as the block hash.
properties:
hash:
type: string
description: This is also known as the block hash.
- $id: rosetta-block-identifier-height.schema.json
type: object
title: RosettaBlockIdentifierHeight
description: This is also known as the block height.
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:
$id: rosetta-block-genesis-identifier.schema.json
type: object
title: RosettaGenesisBlockIdentifier
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
oldest_block_identifier:
$id: rosetta-block-oldest-identifier.schema.json
type: object
title: RosettaOldestBlockIdentifier
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
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
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:
$id: rosetta-network-peers.schema.json
type: object
title: RosettaPeers
description: A Peer is a representation of a node's peer.
required:
- peer_id
properties:
peer_id:
type: string
description: peer id
metadata:
type: object
description: meta data
additionalProperties: 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:
$schema: http://json-schema.org/draft-07/schema
$id: Rosetta-status-request
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
description: ""
required: []
/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:
$schema: http://json-schema.org/draft-07/schema
$id: rosetta-account-response
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
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
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
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: ""
required: []
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
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
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:
description: Amount is some Value of a Currency. It is considered invalid to
specify a Value without a Currency.
$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:
$schema: http://json-schema.org/draft-07/schema
$id: rosetta-account-request
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
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
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.
required: []
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.
required: []
block_identifier:
$id: rosetta-partial-block-identifier.schema.json
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"
/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:
$schema: http://json-schema.org/draft-07/schema
$id: rosetta-block-response.schema.json
type: object
title: RosettaBlockResponse
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.
required: []
properties:
block:
$id: rosetta-block.schema.json
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
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
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:
$schema: http://json-schema.org/draft-07/schema
type: object
title: OtherTransactionIdentifier
description: The transaction_identifier uniquely identifies a transaction in a
particular network and block or in the mempool.
required:
- hash
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:
$schema: http://json-schema.org/draft-07/schema
$id: rosetta-block-request
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"
/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:
$schema: http://json-schema.org/draft-07/schema
$id: rosetta-block-transaction-response
type: object
title: RosettaBlockTransactionResponse
description: A BlockTransactionResponse contains information about a block
transaction.
required:
- transaction
properties:
transaction:
$schema: http://json-schema.org/draft-07/schema
type: object
title: RosettaTransaction
description: Transactions contain an array of Operations that are attributable
to the same TransactionIdentifier.
required:
- transaction_identifier
- operations
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.
required: []
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:
$schema: http://json-schema.org/draft-07/schema
$id: rosetta-block-transaction-request.schema.json
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:
$schema: http://json-schema.org/draft-07/schema
type: object
title: TransactionIdentifier
description: The transaction_identifier uniquely identifies a transaction in a
particular network and block or in the mempool.
required:
- hash
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."
/rosetta/v1/mempool:
post:
tags:
- Rosetta
summary: Get All Mempool Transactions
operationId: rosetta_mempool
description: Retrieves a list of transcations currently in the mempool for a
given network.
responses:
"200":
description: Success
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema
type: object
title: RosettaMempoolResponse
description: A MempoolResponse contains all transaction identifiers in the
mempool for a particular network_identifier.
required:
- transaction_identifiers
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:
$schema: http://json-schema.org/draft-07/schema
type: object
title: RosettaMempoolRequest
description: Get all Transaction Identifiers in the mempool
required:
- network_identifier
properties:
network_identifier:
$ref: "#/paths/~1rosetta~1v1~1network~1list/post/responses/200/content/applicat\
ion~1json/schema/properties/network_identifiers/items"
metadata:
type: object
/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:
$schema: http://json-schema.org/draft-07/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
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:
$schema: http://json-schema.org/draft-07/schema
$id: rosetta-mempool-transaction-request
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:
$schema: http://json-schema.org/draft-07/schema
$id: rosetta-construction-derive-response
type: object
title: RosettaConstructionDeriveResponse
description: ConstructionDeriveResponse is returned by the /construction/derive
endpoint.
required: []
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.
required: []
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:
$schema: http://json-schema.org/draft-07/schema
$id: construction-derive-request
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
properties:
network_identifier:
$ref: "#/paths/~1rosetta~1v1~1network~1list/post/responses/200/content/applicat\
ion~1json/schema/properties/network_identifiers/items"
public_key:
$schema: http://json-schema.org/draft-07/schema
$id: rosetta-public-key-schema
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
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
/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:
$schema: http://json-schema.org/draft-07/schema
$id: rosetta-construction-hash-response
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
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:
$schema: http://json-schema.org/draft-07/schema
$id: rosetta-construction-hash-request
type: object
title: RosettaConstructionHashRequest
description: TransactionHash returns the network-specific transaction hash for a
signed transaction.
required:
- network_identifier
- signed_transaction
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
/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:
$schema: http://json-schema.org/draft-07/schema
$id: rosetta-construction-metadata-response
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
properties:
metadata:
type: object
required: []
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:
$schema: http://json-schema.org/draft-07/schema
$id: http://example.com/example.json
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
properties:
network_identifier:
$ref: "#/paths/~1rosetta~1v1~1network~1list/post/responses/200/content/applicat\
ion~1json/schema/properties/network_identifiers/items"
options:
$id: rosetta-construction-options
title: RosettaOptions
type: object
description: The options that will be sent directly to /construction/metadata by
the caller.
required: []
properties:
sender_address:
type: string
description: "sender's address "
type:
type: string
description: Type of operation e.g transfer
status:
type:
- string
- "null"
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"
/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:
$schema: http://json-schema.org/draft-07/schema
$id: rosetta-construction-parse-response
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
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
properties:
operation_identifier:
type: object
title: RosettaOperationIdentifier
description: The operation_identifier uniquely identifies an operation within a
transaction.
required:
- index
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
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
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:
$schema: http://json-schema.org/draft-07/schema
$id: rosetta-construction-parse-request
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
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:
$schema: http://json-schema.org/draft-07/schema
$id: rosetta-construction-preprocess-response
type: object
title: RosettaConstructionPreprocessResponse
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.
required: []
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:
$schema: http://json-schema.org/draft-07/schema
$id: rosett-construction-preprocess-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
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:
$id: rosetta-max-fee
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: ""
required: []
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.
responses:
"200":
description: Success
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema
$id: rosetta-construction-submit-response
type: object
title: RosettaConstructionSubmitResponse
description: TransactionIdentifier contains the transaction_identifier of a
transaction that was submitted to either /construction/submit.
required:
- transaction_identifier
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:
$schema: http://json-schema.org/draft-07/schema
$id: rosetta-construction-submit-request
type: object
title: RosettaConstructionSubmitRequest
description: Submit the transaction in blockchain
required:
- network_identifier
- signed_transaction
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
/rosetta/v1/construction/payloads:
post:
tags:
- Rosetta
summary: Generate an Unsigned Transaction and Signing Payloads
operationId: rosetta_construction_payloads
description: Generate and unsigned transaction from operations and metadata
responses:
"200":
description: Success
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema
$id: http://example.com/example.json
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
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:
$schema: http://json-schema.org/draft-07/schema
$id: rosetta-signing-payload
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
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:
$schema: http://json-schema.org/draft-07/schema
$id: http://example.com/example.json
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
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
required: []
properties:
account_sequence:
type: integer
recent_block_hash:
type: string
/rosetta/v1/construction/combine:
post:
tags:
- Rosetta
summary: Create Network Transaction from Signatures
operationId: rosetta_construction_combine
description: Take unsigned transaction and signature, combine both and return
signed transaction
responses:
"200":
description: Success
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema
$id: rosetta-construction-combine-response
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
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:
$schema: http://json-schema.org/draft-07/schema
$id: http://example.com/example.json
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
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:
$schema: http://json-schema.org/draft-07/schema
$id: rosetta-signature
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
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:
$schema: http://json-schema.org/draft-07/schema
$id: rosetta-signature-type
type: string
description: SignatureType is the type of a cryptographic signature.
enum:
- ecdsa
- ecdsa_recovery
- ed25519
- schnorr_1
- schnorr_poseidon
hex_bytes:
type: 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
example: id
schema:
type: string
responses:
"200":
description: Success
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema
$id: bns-get-namespace-price-response
title: BnsGetNamespacePriceResponse
description: Fetch price for namespace.
required:
- units
- amount
type: object
properties:
units:
type: string
amount:
type: string
pattern: ^[0-9]+$
example:
units: STX
amount: "4000000000"
"/v2/prices/names/{name}":
get:
summary: Get Name Price
description: Retrieves the price of a name. The `amount` given will be in the
smallest possible units of the currency.
tags:
- Names
operationId: get_name_price
parameters:
- name: name
in: path
description: the name to query price information for
required: true
example: muneeb.id
schema:
type: string
responses:
"200":
description: Success
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema
$id: bns-get-name-price-response
title: BnsGetNamePriceResponse
description: Fetch price for name.
required:
- units
- amount
type: object
properties:
units:
type: string
amount:
type: string
pattern: ^[0-9]+$
example:
name_price:
units: STX
amount: "100000"
/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:
$schema: http://json-schema.org/draft-07/schema
$id: bns-get-all-namespaces-response
title: BnsGetAllNamespacesResponse
description: Fetch a list of all namespaces known to the node.
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
example: id
schema:
type: string
- name: page
in: query
description: names are returned in pages of size 100, so specify the page number.
required: true
example: 23
schema:
type: integer
responses:
"200":
description: Success
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema
$id: bns-get-all-namespaces-names-response
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:
$schema: http://json-schema.org/draft-07/schema
$id: bns-error
title: BnsError
description: Error
type: object
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 returned in pages of size 100, so specify the page number.
required: true
example: 23
schema:
type: integer
responses:
"200":
description: Success
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema
$id: bns-get-all-names-response
title: BnsGetAllNamesResponse
description: Fetch a list of all names known to the node.
required: []
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
example: muneeb.id
schema:
type: string
responses:
"200":
description: Success
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema
$id: bns-get-name-info
title: BnsGetNameInfoResponse
description: Get name details
type: object
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}/history":
get:
summary: Get Name History
description: Retrieves a history of all blockchain records of a registered name.
tags:
- Names
operationId: get_name_history
parameters:
- name: name
in: path
description: name to query
required: true
example: muneeb.id
schema:
type: string
- name: page
in: query
description: the page (in 20-entry pages) of the history to fetch
required: true
example: 0
schema:
type: integer
responses:
"200":
description: Success
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema
$id: bns-get-name-history
title: BnsGetNameHistoryResponse
description: Get a history of all blockchain records of a registered name.
type: object
patternProperties:
"^[0-9]+":
type: array
items:
type: object
properties:
address:
type: string
pattern: ^([123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]+)$
base:
type: integer
minimum: 0
maximum: 255
buckets:
anyOf:
- type: array
items:
type: integer
minItems: 16
maxItems: 16
- type: "null"
block_number:
type: integer
minimum: 0
coeff:
anyOf:
- type: integer
minimum: 0
maximum: 255
- type: "null"
consensus_hash:
anyOf:
- type: string
pattern: ^[0-9a-fA-F]{32}
- type: "null"
domain:
type: string
pattern: ^([a-z0-9\-_.+]{3,37})$
fee:
type: integer
minimum: 0
first_registered:
type: integer
minimum: 0
history_snapshot:
type: boolean
importer:
anyOf:
- type: string
pattern: ^76[aA]914[0-9a-fA-F]{40}88[aA][cC]$
- type: "null"
importer_address:
anyOf:
- type: string
pattern: ^([123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]+)$
- type: "null"
last_renewed:
type: integer
minimum: 0
name:
type: string
pattern: ^([a-z0-9\-_.+]{3,37}).([a-z0-9\-_.+]{3,37})$
op:
type: string
pattern: ^([>?+~:!&*:;#]{1}|>>|>~|::)$
op_fee:
type: number
opcode:
type: string
pattern: ^NAME_TRANSFER|NAME_PREORDER|NAME_UPDATE|NAME_REVOKE|NAME_REGISTRATION|NAMESPACE_READY|NAMESPACE_REVEAL|NAMESPACE_PREORDER|NAME_RENEWAL|NAME_IMPORT|ANNOUNCE$
revoked:
type: boolean
sender:
type: string
pattern: ^([0-9a-fA-F]+)$
sender_pubkey:
anyOf:
- type: string
pattern: ^([0-9a-fA-F]+)$
- type: "null"
sequence:
type: integer
minimum: 0
recipient:
anyOf:
- type: string
pattern: ^([0-9a-fA-F]+)$
- type: "null"
recipient_address:
anyOf:
- type: string
pattern: ^([123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]+)$
- type: "null"
recipient_pubkey:
anyOf:
- type: string
pattern: ^([0-9a-fA-F]+)$
- type: "null"
txid:
type: string
pattern: ^([0-9a-fA-F]+)$
value_hash:
anyOf:
- type: string
pattern: ^([0-9a-fA-F]{40})$
- type: "null"
vtxindex:
type: integer
minimum: 0
required:
- txid
- vtxindex
example:
zonefile: >
$ORIGIN muneeb.id
$TTL 3600
_http._tcp IN URI 10 1 "https://blockstack.s3.amazonaws.com/muneeb.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"
"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/get/responses/404/content/application~1j\
son/example"
"/v1/names/{name}/zonefile":
get:
summary: Get Zone File
description: Retrieves a user’s raw zone file. This only works for RFC-compliant
zone files. This method returns an error for names that have
non-standard zone files.
tags:
- Names
operationId: fetch_zone_file
parameters:
- name: name
in: path
description: fully-qualified name
required: true
example: bar.test
schema:
type: string
responses:
"200":
description: Success
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema
$id: bns-fetch-zone-file-response
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.
required: []
anyOf:
- type: object
properties:
zonefile:
type: string
pattern: .+
- type: object
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
example: muneeb.id
schema:
type: string
- name: zoneFileHash
in: path
description: zone file hash
required: true
example: b100a68235244b012854a95f9114695679002af9
schema:
type: string
responses:
"200":
description: Success
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema
$id: bns-fetch-historical-zone-file-response
title: BnsFetchHistoricalZoneFileResponse
description: Fetches the historical zonefile specified by the username and zone
hash.
required: []
anyOf:
- type: object
properties:
zonefile:
type: string
- type: object
properties:
error:
type: string
example:
$schema: http://json-schema.org/draft-07/schema
$id: bns-fetch-historical-zone-file-response
title: BnsFetchHistoricalZoneFileResponse
description: Fetches the historical zonefile specified by the username and zone
hash.
required: []
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
example: bitcoin
schema:
type: string
- name: address
in: path
description: the address to lookup
required: true
example: 1QJQxDas5JhdiXhEbNS14iNjr8auFT96GP
schema:
type: string
responses:
"200":
description: Success
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema
$id: bns-get-names-own-by-address-response
title: BnsNamesOwnByAddressResponse
description: Retrieves a list of names owned by the address provided.
required: []
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
/v1/subdomains:
get:
summary: Get All Subdomains
description: Retrieves a list of all subdomains known to the node.
tags:
- Names
operationId: get_all_subdomains
parameters:
- name: page
in: query
description: names are returned in pages of size 100, so specify the page number.
required: true
example: 3
schema:
type: integer
responses:
"200":
description: Success
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema
$id: bns-get-all-subdomains-response
title: BnsGetAllSubdomainsResponse
description: Fetch a list of all subdomains known to the node.
required: []
type: array
items:
type: string
pattern: ^([a-z0-9\-_.+]{3,37}).([a-z0-9\-_.+]{3,37})$
example:
- collegeinfogeek.verified.podcast
- collider.verified.podcast
- combatandclassics.verified.podcast
- combatjack.verified.podcast
- comedybangbang.verified.podcast
- comedybutton.verified.podcast
- commonsense.verified.podcast
- concilio002.personal.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/subdomains/{txid}":
get:
summary: Get Subdomain at Transaction
description: Retrieves the list of subdomain operations processed by a given
transaction. The returned array includes subdomain operations that have
not yet been accepted as part of any subdomain’s history (checkable via
the accepted field). If the given transaction ID does not correspond to
a Stacks transaction that introduced new subdomain operations, and empty
array will be returned.
tags:
- Names
operationId: get_subdomain_at_transaction
parameters:
- name: txid
in: path
description: transaction id
required: true
example: d04d708472ea3c147f50e43264efdb1535f71974053126dc4db67b3ac19d41fe
schema:
type: string
responses:
"200":
description: Success
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema
$id: bns-get-subdomain-at-tx
title: BnsGetSubdomainAtTx
description: Fetches the list of subdomain operations processed by a given
transaction. The returned array includes subdomain operations
that have not yet been accepted as part of any subdomain’s
history (checkable via the accepted field). If the given
transaction ID does not correspond to a Stacks transaction
that introduced new subdomain operations, and empty array will
be returned.
required:
- accepted
- block_height
- domain
- fully_qualified_subdomain
- missing
- owner
- parent_zonefile_hash
- parent_zonefile_index
- resolver
- sequence
- signature
- txid
- zonefile_hash
- zonefile_offset
type: array
items:
type: object
properties:
accepted:
type: integer
minimum: 0
maximum: 1
block_height:
type: integer
minimum: 0
domain:
type: string
pattern: ^([a-z0-9\-_.+]{3,37})$|^([a-z0-9\-_.+]){3,37}$
fully_qualified_subdomain:
type: string
pattern: ^([a-z0-9\-_.+]{3,37}).([a-z0-9\-_.+]{3,37})$
missing:
type: string
owner:
type: string
pattern: ^([123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]+)$
parent_zonefile_hash:
type: string
pattern: ^[0-9a-fA-F]{40}
parent_zonefile_index:
type: integer
minimum: 0
resolver:
type: string
sequence:
type: integer
minimum: 0
signature:
type: string
txid:
type: string
pattern: ^[0-9a-fA-F]{64}
zonefile_hash:
type: string
pattern: ^[0-9a-fA-F]{40}
zonefile_offset:
type: integer
minimum: 0
example:
- accepted: 1
block_height: 546199
domain: id.blockstack
fully_qualified_subdomain: nturl345.id.blockstack
missing: ""
owner: 17Q8hcsxRLCk3ypJiGeXQv9tFK9GnHr5Ea
parent_zonefile_hash: 58224144791919f6206251a9960a2dd5723b96b6
parent_zonefile_index: 95780
resolver: https://registrar.blockstack.org
sequence: 0
signature: None
txid: d04d708472ea3c147f50e43264efdb1535f71974053126dc4db67b3ac19d41fe
zonefile_hash: d3bdf1cf010aac3f21fac473e41450f5357e0817
zonefile_offset: 0
- accepted: 1
block_height: 546199
domain: id.blockstack
fully_qualified_subdomain: dwerner1.id.blockstack
missing: ""
owner: 17tFeKEBMUAAiHVsCgqKo8ccwYqq7aCn9X
parent_zonefile_hash: 58224144791919f6206251a9960a2dd5723b96b6
parent_zonefile_index: 95780
resolver: https://registrar.blockstack.org
sequence: 0
signature: None
txid: d04d708472ea3c147f50e43264efdb1535f71974053126dc4db67b3ac19d41fe
zonefile_hash: ab79b1774fa7a4c5709b6ad4e5892fb7c0f79765
zonefile_offset: 1
"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 txid
"/extended/v1/tx/block/{block_hash}":
get:
operationId: get_transactions_by_block_hash
summary: Transactions by block hash
description: Retrieves a list of all transactions within a block for a given
block hash.
tags:
- Transactions
parameters:
- name: block_hash
in: path
description: Hash of block
required: true
schema:
type: string
- name: limit
in: query
description: max number of transactions to fetch
required: false
schema:
type: integer
- name: offset
in: query
description: index of first transaction to fetch
required: false
schema:
type: integer
responses:
"200":
description: List of Transactions
content:
application/json:
schema:
$ref: "#/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
- name: limit
in: query
description: max number of transactions to fetch
required: false
schema:
type: integer
- name: offset
in: query
description: index of first transaction to fetch
required: false
schema:
type: integer
- name: unanchored
in: query
description: Include transaction data from unanchored (i.e. unconfirmed)
microblocks
required: false
schema:
type: boolean
default: false
responses:
"200":
description: List of Transactions
content:
application/json:
schema:
$ref: "#/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
- name: limit
in: query
description: max number of transactions to fetch
required: false
schema:
type: integer
- name: offset
in: query
description: index of first transaction to fetch
required: false
schema:
type: integer
- name: unanchored
in: query
description: Include transaction data from unanchored (i.e. unconfirmed)
microblocks
required: false
schema:
type: boolean
default: false
responses:
"200":
description: List of Transactions
content:
application/json:
schema:
$ref: "#/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
description: Retrieves list of fungible tokens with their metadata. More
information on Fungible Tokens on the Stacks blockchain can be found
[here](https://docs.stacks.co/write-smart-contracts/tokens#fungible-tokens).
tags:
- Fungible Tokens
parameters:
- name: limit
in: query
description: max number of tokens to fetch
required: false
schema:
type: integer
- name: offset
in: query
description: index of first tokens to fetch
required: false
schema:
type: integer
responses:
"200":
description: List of fungible tokens metadata
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema#
description: List of fungible tokens metadata
title: FungibleTokensMetadataList
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:
$schema: http://json-schema.org/draft-07/schema
$id: fungible-token-metadata
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/metadata:
get:
operationId: get_nft_metadata_list
summary: Non fungible tokens metadata list
description: Retrieves a list of non fungible tokens with their metadata. More
information on Non-Fungible Tokens on the Stacks blockchain can be found
[here](https://docs.stacks.co/write-smart-contracts/tokens#non-fungible-tokens-nfts).
tags:
- Non-Fungible Tokens
parameters:
- name: limit
in: query
description: max number of tokens to fetch
required: false
schema:
type: integer
- name: offset
in: query
description: index of first tokens to fetch
required: false
schema:
type: integer
responses:
"200":
description: List of non fungible tokens metadata
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema#
description: List of non fungible tokens metadata
title: NonFungibleTokensMetadataList
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:
$schema: http://json-schema.org/draft-07/schema
$id: non-fungible-token-metadata
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
description: Retrieves metadata for non fungible tokens for a given contract id.
More information on Non-Fungible Tokens on the Stacks blockchain can be
found
[here](https://docs.stacks.co/write-smart-contracts/tokens#non-fungible-tokens-nfts).
tags:
- Non-Fungible Tokens
parameters:
- name: contractId
in: path
description: token's contract id
required: true
schema:
type: string
responses:
"200":
description: Non fungible tokens metadata for contract id
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema
$id: non-fungible-token-metadata
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
description: Retrieves the metadata for fungible tokens for a given contract id
tags:
- Fungible Tokens
parameters:
- name: contractId
in: path
description: token's contract id
required: true
schema:
type: string
responses:
"200":
description: Fungible tokens metadata for contract id
content:
application/json:
schema:
$schema: http://json-schema.org/draft-07/schema
$id: fungible-token-metadata
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
description: 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"
Reference in New Issue View Git Blame Copy Permalink