Documentation

RTWire provides a REST API designed for enterprises that require high volume, low value Bitcoin transactions. Our platform is ideally suited to providing the infrastructure for banks, exchanges and micropayment systems.

Our service allows you to create and manage multiple accounts which can all send and receive bitcoins. We also support off chain transactions meaning you can send bitcoins between your accounts instantaneously, for free and for any amount, no matter how small.

We also have an API walkthrough you can view to get better acquainted with the RTWire API.

This API uses Basic Authentication always over HTTPS. Ensure you never share your API key and secret otherwise your money is at risk.

Success Responses

Successful responses (HTTP Status Code 2**) are always in JSON and of the format:

{
"type": <seebelow>,
"next": <seebelow>,
"payload" : <seebelow>
}

Error Responses

If possible error responses (where HTTP Status Code is not 2**) are in JSON and of the format:

{
"type": "errors",
"payload" : [{
"message": <errormessage>
}]
}

Accounts

Accounts are similar to bitcoin wallets. They can have an unlimited number of addresses attached to them allowing you to send and receive bitcoins using the Bitcoin network. You can also transfer bitcoins between accounts for free and instantly. It is important to note that once a balance is within an RTWire account it cannot be reversed due to block chain reorgs. This is unlike regular Bitcoin wallets and makes for a simpler development experience.

Funds arriving from the bitcoin network go through our clearing process until we are confident they are legitimate. This process can take seconds to minutes depending on a variety of network factors.

Read Accounts

This endpoint returns a list of all accounts owned by the user.

Request:HTTP GET [api root]/accounts/?limit=[max returned accounts]&next=[use token obtained from response]Accept: "application/json"QueryParams:- limit (optional) - Limits the number of returned accounts (maximum 20).- next (optional) - Allows you to page through your accounts. You will be supplied with the 'next' token in a response.

Read Account Transactions

This endpoint returns a list of transactions ordered by age with the newest first for a specified account.

Request:HTTP GET [api root]/accounts/[account id]/transactions/?limit=[max returned transactions]&next=[use token obtained from response]Accept: "application/json"QueryParams:- status=pending (optional) - This shows all the pending transactions associated with the specified account. A transaction will be in a pending state if RTWire's risk engine has not yet deemed it safe enough to be confirmed.- limit (optional) - Limits the number of returned transactions (maximum 20).- next (optional) - Allows you to page through your transactions. You will be supplied with the 'next' token in a response.

Read Account By Label

Currently only the fee account is labeled. Using the _fee label will return information on this account. Note that the underscore prefix is used to represent labels generated by the system. This is useful because otherwise you would not know which account was being used for fees other than by looking at https://console.rtwire.com.

Addresses

Addresses are associated with accounts. They allow you to receive bitcoins from the Bitcoin network. Once an address is created it is always associated with the specified account. You are encouraged to create a new address for each transaction.

Transactions

Understanding RTWire transactions is vitally important to help you create robust financial systems. Consider the scenario where you send bitcoins to someones account. However, the network goes down and you don't get a response from our servers. How do you know that the transfer succeeded? Have the bitcoins been sent? Should you try and send them again?

You can't just create another transaction because you might send double the amount of bitcoins. This is where RTWire transactions come in. Each transaction is associated with a unique ID that can only be used once. This makes your your request to transfer money idempotent meaning that you can call the endpoint as many times as you like with the same transaction ID and it will only one transfer of money will occur.

Therefore the standard operating procedure to transfer money between RTWire accounts or to a public key hash is as follows:

POST [api root]/transactions/ to create a transaction ID.

PUT [api root]/transactions/ to initiate a transfer of funds with the ID obtained in step one.

An error will be returned if you try and send the same or another transaction with an already used ID.

Create Transaction

This endpoint allows you to transfer bitcoins between accounts or to Bitcoin addresses (public key hashes). Transfers to accounts are done off-chain meaning they are instant and free. Transfers done to Bitcoin public key hashes incur a miners fee and system fee. Fees can be paid using the RTWire console. If you have insufficient fees then the transfer will be put on hold until you have credited your fee account. Note that if a Bitcoin address happens to be one of RTWire's then the funds will be transferred for free using our off chain system.

Hooks

Hooks allow RTWire to notify your system as soon as someone credits one of your accounts. A hook will call your chosen URI endpoint multiple times when bitcoins enter clearing and when your account is fully credited allowing you to create fully real-time applications.

You are allowed at most 3 hooks and your server must return 200 Status OK. If not we will try and call your endpoint at most 5 times before giving up.

Fees

Read Fees

Read fees allows you to get an estimate of the miner fees required to include a transaction into a block within two confirmations. Note that calculation of fees requires a significant amount of computation work. If the latest fee calculation is not precached then this endpoint will return a 202 Accepted response allowing you to retry later.