openapi: 3.0.2
info:
title: Stacks 2.0 Blockchain API
version: STACKS_API_VERSION
contact:
name: API developers
url: 'https://github.com/blockstack/stacks-blockchain-api/issues'
email: [email protected]
description: >
This is the documentation for the Stacks 2.0 Blockchain API. It is comprised
of two parts; the Stacks Blockchain API and the Stacks Core API. <a
href="collection.json" download="collection.json">Download Postman
collection</a>
paths:
/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:
$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
required_public_keys:
type: array
items:
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: []
'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
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:
$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
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:
description: >-
The operation_identifier uniquely identifies an
operation within a transaction.
type: object
title: RosettaOperationIdentifier
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:
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: []
amount:
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:
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).
title: RosettaCurrency
type: object
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: []
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
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:
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).
title: RosettaCurrency
type: object
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: []
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).'
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent