Construction
Construction endpoints are used to create and broadcast transactions.
/construction/combine
Create Network Transaction from Signatures
Combine creates a network-specific transaction from an unsigned transaction and an array of provided signatures. The signed transaction returned from this method will be sent to the /construction/submit endpoint by the caller.
Request
{
"network_identifier": {
"blockchain": "bitcoin",
"network": "mainnet",
"sub_network_identifier": {
"network": "shard 1",
"metadata": {
"producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
}
}
},
"unsigned_transaction": "string",
"signatures": [
{
"signing_payload": {
"address": "string",
"account_identifier": {
"address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
"sub_account": {
"address": "0x6b175474e89094c44da98b954eedeac495271d0f",
"metadata": {}
},
"metadata": {}
},
"hex_bytes": "string",
"signature_type": "ecdsa"
},
"public_key": {
"hex_bytes": "string",
"curve_type": "secp256k1"
},
"signature_type": "ecdsa",
"hex_bytes": "string"
}
]
}
Response
200 - OK
{
"signed_transaction": "string"
}
500 - Error
{
"code": 12,
"message": "Invalid account format",
"description": "This error is returned when the requested AccountIdentifier is improperly formatted.",
"retriable": true,
"details": {
"address": "0x1dcc4de8dec75d7aab85b567b6",
"error": "not base64"
}
}
/construction/derive
Derive an AccountIdentifier from a PublicKey
Derive returns the AccountIdentifier associated with a public key. Blockchains that require an on-chain action to create an account should not implement this method.
Request
{
"network_identifier": {
"blockchain": "bitcoin",
"network": "mainnet",
"sub_network_identifier": {
"network": "shard 1",
"metadata": {
"producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
}
}
},
"public_key": {
"hex_bytes": "string",
"curve_type": "secp256k1"
},
"metadata": {}
}
Response
200 - OK
{
"address": "string",
"account_identifier": {
"address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
"sub_account": {
"address": "0x6b175474e89094c44da98b954eedeac495271d0f",
"metadata": {}
},
"metadata": {}
},
"metadata": {}
}
500 - Error
{
"code": 12,
"message": "Invalid account format",
"description": "This error is returned when the requested AccountIdentifier is improperly formatted.",
"retriable": true,
"details": {
"address": "0x1dcc4de8dec75d7aab85b567b6",
"error": "not base64"
}
}
/construction/hash
Get the Hash of a Signed Transaction
TransactionHash returns the network-specific transaction hash for a signed transaction.
Request
{
"network_identifier": {
"blockchain": "bitcoin",
"network": "mainnet",
"sub_network_identifier": {
"network": "shard 1",
"metadata": {
"producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
}
}
},
"signed_transaction": "string"
}
Response
200 - OK
{
"transaction_identifier": {
"hash": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f"
},
"metadata": {}
}
500 - Error
{
"code": 12,
"message": "Invalid account format",
"description": "This error is returned when the requested AccountIdentifier is improperly formatted.",
"retriable": true,
"details": {
"address": "0x1dcc4de8dec75d7aab85b567b6",
"error": "not base64"
}
}
/construction/metadata
Get Metadata for Transaction Construction
Get any information required to construct a transaction for a specific network. Metadata returned here could be a recent hash to use, an account sequence number, or even arbitrary chain state. The request used when calling this endpoint is created by calling /construction/preprocess in an offline environment. You should NEVER assume that the request sent to this endpoint will be created by the caller or populated with any custom parameters. This must occur in /construction/preprocess. It is important to clarify that this endpoint should not pre-construct any transactions for the client (this should happen in /construction/payloads). This endpoint is left purposely unstructured because of the wide scope of metadata that could be required.
Request
{
"network_identifier": {
"blockchain": "bitcoin",
"network": "mainnet",
"sub_network_identifier": {
"network": "shard 1",
"metadata": {
"producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
}
}
},
"options": {},
"public_keys": [
{
"hex_bytes": "string",
"curve_type": "secp256k1"
}
]
}
Response
200 - OK
{
"metadata": {
"account_sequence": 23,
"recent_block_hash": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
},
"suggested_fee": [
{
"value": "1238089899992",
"currency": {
"symbol": "BTC",
"decimals": 8,
"metadata": {
"Issuer": "Satoshi"
}
},
"metadata": {}
}
]
}
500 - Error
{
"code": 12,
"message": "Invalid account format",
"description": "This error is returned when the requested AccountIdentifier is improperly formatted.",
"retriable": true,
"details": {
"address": "0x1dcc4de8dec75d7aab85b567b6",
"error": "not base64"
}
}
/construction/parse
Parse a Transaction
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).
Request
{
"network_identifier": {
"blockchain": "bitcoin",
"network": "mainnet",
"sub_network_identifier": {
"network": "shard 1",
"metadata": {
"producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
}
}
},
"signed": true,
"transaction": "string"
}
Response
200 - OK
{
"operations": [
{
"operation_identifier": {
"index": 5,
"network_index": 0
},
"related_operations": [
{
"index": 1
},
{
"index": 2
}
],
"type": "Transfer",
"status": "Reverted",
"account": {
"address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
"sub_account": {
"address": "0x6b175474e89094c44da98b954eedeac495271d0f",
"metadata": {}
},
"metadata": {}
},
"amount": {
"value": "1238089899992",
"currency": {
"symbol": "BTC",
"decimals": 8,
"metadata": {
"Issuer": "Satoshi"
}
},
"metadata": {}
},
"coin_change": {
"coin_identifier": {
"identifier": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f:1"
},
"coin_action": "coin_created"
},
"metadata": {
"asm": "304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd01 03301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2",
"hex": "48304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd012103301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2"
}
}
],
"signers": [
"string"
],
"account_identifier_signers": [
{
"address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
"sub_account": {
"address": "0x6b175474e89094c44da98b954eedeac495271d0f",
"metadata": {}
},
"metadata": {}
}
],
"metadata": {}
}
500 - Error
{
"code": 12,
"message": "Invalid account format",
"description": "This error is returned when the requested AccountIdentifier is improperly formatted.",
"retriable": true,
"details": {
"address": "0x1dcc4de8dec75d7aab85b567b6",
"error": "not base64"
}
}
/construction/payloads
Generate an Unsigned Transaction and Signing Payloads
Payloads is called with an array of operations and the response from /construction/metadata. It returns an unsigned transaction blob and a collection of payloads that must be signed by particular AccountIdentifiers using a certain SignatureType. The array of operations provided in transaction construction often times can not specify all "effects" of a transaction (consider invoked transactions in Ethereum). However, they can deterministically specify the "intent" of the transaction, which is sufficient for construction. For this reason, parsing the corresponding transaction in the Data API (when it lands on chain) will contain a superset of whatever operations were provided during construction.
Request
{
"network_identifier": {
"blockchain": "bitcoin",
"network": "mainnet",
"sub_network_identifier": {
"network": "shard 1",
"metadata": {
"producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
}
}
},
"operations": [
{
"operation_identifier": {
"index": 5,
"network_index": 0
},
"related_operations": [
{
"index": 1
},
{
"index": 2
}
],
"type": "Transfer",
"status": "Reverted",
"account": {
"address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
"sub_account": {
"address": "0x6b175474e89094c44da98b954eedeac495271d0f",
"metadata": {}
},
"metadata": {}
},
"amount": {
"value": "1238089899992",
"currency": {
"symbol": "BTC",
"decimals": 8,
"metadata": {
"Issuer": "Satoshi"
}
},
"metadata": {}
},
"coin_change": {
"coin_identifier": {
"identifier": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f:1"
},
"coin_action": "coin_created"
},
"metadata": {
"asm": "304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd01 03301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2",
"hex": "48304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd012103301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2"
}
}
],
"metadata": {},
"public_keys": [
{
"hex_bytes": "string",
"curve_type": "secp256k1"
}
]
}
Response
200 - OK
{
"unsigned_transaction": "string",
"payloads": [
{
"address": "string",
"account_identifier": {
"address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
"sub_account": {
"address": "0x6b175474e89094c44da98b954eedeac495271d0f",
"metadata": {}
},
"metadata": {}
},
"hex_bytes": "string",
"signature_type": "ecdsa"
}
]
}
500 - Error
{
"code": 12,
"message": "Invalid account format",
"description": "This error is returned when the requested AccountIdentifier is improperly formatted.",
"retriable": true,
"details": {
"address": "0x1dcc4de8dec75d7aab85b567b6",
"error": "not base64"
}
}
/construction/preprocess
Create a Request to Fetch Metadata
Preprocess is called prior to /construction/payloads to construct a request for any metadata that is needed for transaction construction given (i.e. account nonce). The options object returned from this endpoint will be sent to the /construction/metadata endpoint UNMODIFIED by the caller (in an offline execution environment). If your Construction API implementation has configuration options, they MUST be specified in the /construction/preprocess request (in the metadata field).
Request
{
"network_identifier": {
"blockchain": "bitcoin",
"network": "mainnet",
"sub_network_identifier": {
"network": "shard 1",
"metadata": {
"producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
}
}
},
"operations": [
{
"operation_identifier": {
"index": 5,
"network_index": 0
},
"related_operations": [
{
"index": 1
},
{
"index": 2
}
],
"type": "Transfer",
"status": "Reverted",
"account": {
"address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
"sub_account": {
"address": "0x6b175474e89094c44da98b954eedeac495271d0f",
"metadata": {}
},
"metadata": {}
},
"amount": {
"value": "1238089899992",
"currency": {
"symbol": "BTC",
"decimals": 8,
"metadata": {
"Issuer": "Satoshi"
}
},
"metadata": {}
},
"coin_change": {
"coin_identifier": {
"identifier": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f:1"
},
"coin_action": "coin_created"
},
"metadata": {
"asm": "304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd01 03301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2",
"hex": "48304502201fd8abb11443f8b1b9a04e0495e0543d05611473a790c8939f089d073f90509a022100f4677825136605d732e2126d09a2d38c20c75946cd9fc239c0497e84c634e3dd012103301a8259a12e35694cc22ebc45fee635f4993064190f6ce96e7fb19a03bb6be2"
}
}
],
"metadata": {},
"max_fee": [
{
"value": "1238089899992",
"currency": {
"symbol": "BTC",
"decimals": 8,
"metadata": {
"Issuer": "Satoshi"
}
},
"metadata": {}
}
],
"suggested_fee_multiplier": 0
}
Response
200 - OK
{
"options": {},
"required_public_keys": [
{
"address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
"sub_account": {
"address": "0x6b175474e89094c44da98b954eedeac495271d0f",
"metadata": {}
},
"metadata": {}
}
]
}
500 - Error
{
"code": 12,
"message": "Invalid account format",
"description": "This error is returned when the requested AccountIdentifier is improperly formatted.",
"retriable": true,
"details": {
"address": "0x1dcc4de8dec75d7aab85b567b6",
"error": "not base64"
}
}
/construction/submit
Submit a Signed Transaction
Submit a pre-signed transaction to the node. This call should not block on the transaction being included in a block. Rather, it should return immediately with an indication of whether or not the transaction was included in the mempool. The transaction submission response should only return a 200 status if the submitted transaction could be included in the mempool. Otherwise, it should return an error.
Request
{
"network_identifier": {
"blockchain": "bitcoin",
"network": "mainnet",
"sub_network_identifier": {
"network": "shard 1",
"metadata": {
"producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
}
}
},
"signed_transaction": "string"
}
Response
200 - OK
{
"transaction_identifier": {
"hash": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f"
},
"metadata": {}
}
500 - Error
{
"code": 12,
"message": "Invalid account format",
"description": "This error is returned when the requested AccountIdentifier is improperly formatted.",
"retriable": true,
"details": {
"address": "0x1dcc4de8dec75d7aab85b567b6",
"error": "not base64"
}
}