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

Schema

{
    "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

Schema

{
    "signed_transaction": "string"
}

500 - Error

Schema

{
    "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

Schema

{
    "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

Schema

{
    "address": "string",
    "account_identifier": {
        "address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
        "sub_account": {
            "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
            "metadata": {}
        },
        "metadata": {}
    },
    "metadata": {}
}

500 - Error

Schema

{
    "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

Schema

{
    "network_identifier": {
        "blockchain": "bitcoin",
        "network": "mainnet",
        "sub_network_identifier": {
            "network": "shard 1",
            "metadata": {
                "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
            }
        }
    },
    "signed_transaction": "string"
}

Response

200 - OK

Schema

{
    "transaction_identifier": {
        "hash": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f"
    },
    "metadata": {}
}

500 - Error

Schema

{
    "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

Schema

{
    "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

Schema

{
    "metadata": {
        "account_sequence": 23,
        "recent_block_hash": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
    },
    "suggested_fee": [
        {
            "value": "1238089899992",
            "currency": {
                "symbol": "BTC",
                "decimals": 8,
                "metadata": {
                    "Issuer": "Satoshi"
                }
            },
            "metadata": {}
        }
    ]
}

500 - Error

Schema

{
    "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

Schema

{
    "network_identifier": {
        "blockchain": "bitcoin",
        "network": "mainnet",
        "sub_network_identifier": {
            "network": "shard 1",
            "metadata": {
                "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
            }
        }
    },
    "signed": true,
    "transaction": "string"
}

Response

200 - OK

Schema

{
    "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

Schema

{
    "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

Schema

{
    "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

Schema

{
    "unsigned_transaction": "string",
    "payloads": [
        {
            "address": "string",
            "account_identifier": {
                "address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
                "sub_account": {
                    "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
                    "metadata": {}
                },
                "metadata": {}
            },
            "hex_bytes": "string",
            "signature_type": "ecdsa"
        }
    ]
}

500 - Error

Schema

{
    "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

Schema

{
    "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

Schema

{
    "options": {},
    "required_public_keys": [
        {
            "address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
            "sub_account": {
                "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
                "metadata": {}
            },
            "metadata": {}
        }
    ]
}

500 - Error

Schema

{
    "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

Schema

{
    "network_identifier": {
        "blockchain": "bitcoin",
        "network": "mainnet",
        "sub_network_identifier": {
            "network": "shard 1",
            "metadata": {
                "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
            }
        }
    },
    "signed_transaction": "string"
}

Response

200 - OK

Schema

{
    "transaction_identifier": {
        "hash": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f"
    },
    "metadata": {}
}

500 - Error

Schema

{
    "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"
    }
}