Creating Transactions
Using coinazer's API, you can push transactions to blockchains one
of two ways:
Use a third party library to create your transactions and push raw
transactions
Use our two-endpoint process outlined below, wherein we generate a
TXSkeleton based on your input address, output address, and value
to transfer.
In either case, for security reasons, we never take possession of
your private keys.
Always use HTTPS for creating and pushing transactions.
New Transaction Endpoint
pTo use coinazer's two-endpoint transaction creation tool, first you
need to provide the input address(es), output address, and value to
transfer (in satoshis). Provide this in a partially-filled out TX
request object.
| resource |
method |
request object |
return object |
| /txs/new |
POST |
TX |
TXSkeleton |
| flag |
type |
effect |
| includeToSignTx |
bool |
If true, includes tosign_tx array in TXSkeleton, useful for
validating data to sign; false by default.
|
As you can see from the code example, you only need to provide a
single public address within the
addresses
array of both the
input
and
output
of your TX request object. You also need to fill in the
value
with the amount you'd like to transfer from one address to
another.
If you'd like, you can even use a Wallet instead of addresses as
your input. You just need to use two non-standard fields (your
wallet_name
and
wallet_token
) within the
inputs
array in your transaction, instead of
addresses
:
While this particular usage will differ between client libraries,
the result is the same: the addresses within your wallet will be
used as the inputs, as if all of them had been placed within the
addresses array.
As a return object, you'll receive a TXSkeleton containing a
slightly-more complete TX alongside data you need to sign in the
tosign array. You'll need this object for the next steps of the
transaction creation process.
The TXSkeleton returned by this endpoint may contain some data
that's temporary or incomplete, like the hash, size, and the
inputs' script fields. This is by design, as the final TX can only
be computed once signed data has been added. Do not rely on these
fields until they are returned and sent to the network via the
Send Transaction Endpoint outlined below.
Validating the Data to Sign
For the extra cautious, you can protect yourself from a potential
malicious attack on coinazer by validating the data we're asking
you to sign. Unfortunately, it's impossible to do so directly, as
pre-signed signature data is hashed twice using SHA256. To get
around this, set the includeToSignTx URL flag to true. The
optional tosign_tx array will be returned within the TXSkeleton,
which you can use in the following way:
Hashing the hex-encoded string twice using SHA256 should give you
back the corresponding tosign data.
Decoding the hex-encoded string using our /txs/decode endpoint (or
an independent, client-side source) should give you the output
addresses and amounts that match your work-in-progress
transaction.
If you want to automatically empty your input address(es) without
knowing their exact value, your TX request object's value can be
set to -1 to sweep all value from your input address(es) to your
output address. Please be advised that this only works with a
single output address.
If you are using a bech32 address (starting with bc1) be sure to
add 01 (SIGHASH_ALL) at the end of the signature.
Locally Sign Your Transaction
With your TXSkeleton returned from the New Transaction Endpoint,
you now need to use your private key(s) to sign the data provided
in the tosign array.
Digital signing can be a difficult process, and is where the
majority of issues arise when dealing with cryptocurrency
transactions. We are working on integrating client-side signing
solutions into our libraries to make this process easier. You can
read more about signing here. In the mean time, if you want to
experiment with client-side signing, consider using our signer
tool.
One of the most common errors in the signing process is a data
format mismatch. We always return and expect hex-encoded data, but
oftentimes, standard signing libraries require byte arrays.
Remember to convert your data, and always send hex-encoded
signatures to coinazer.
Send Transaction Endpoint
Once you've finished signing the tosign array locally, put that
(hex-encoded) data into the signatures array of the TXSkeleton.
You also need to include the corresponding (hex-encoded) public
key(s) in the pubkeys array, in the order of the addresses/inputs
provided. Signature and public key order matters, so make sure
they are returned in the same order as the inputs you provided.
| resource |
method |
request object |
return object |
| /txs/send |
POST |
TXSkeleton |
TXSkeleton |
If the transaction was successful, you'll receive a TXSkeleton
with the completed TX (which contains its final hash) and an HTTP
Status Code 201
Dealing with errors
Signing and creating transactions can be one of the trickiest
parts of using blockchains in your applications. Consequently,
when an error is encountered when Creating Transactions, we send
back an HTTP Status Code 400 alongside a descriptive array of
errors within the TXSkeleton.
One of the most common errors we see are users who use
uncompressed public keys when compressed public keys were used to
generate the address; remember to be careful to use the right
keys!
