Walkthrough

This walkthrough shows you how to correctly use the basic API endpoints of RTWire. It will show you how to do the following with cURL on testnet3:

  1. Create an account (A).
  2. Create and address for account A.
  3. Credit account A.
  4. Check account A has been credited.
  5. Create another account (B).
  6. Create a new transaction ID (tx A).
  7. Transfer funds from account A to B using tx A.
  8. Debit account B using tx B.
  9. Track debit transaction tx B.

Prerequisites

  • Ensure you have your testnet3 API credentials to hand. New credientials can be created by visiting https://console.rtwire.com/testnet3/creds.
  • Ensure you fund your testnet3 fee account by transferring some bitcoins to its address which can be found by visiting https://console.rtwire.com/. 0.0005 BTC should be sufficient as this is required to pay the miner fee and our fee in step 6 when we debit account B. Free testnet3 bitcoins can be obtained from numerous faucets. Search for "bitcoin testnet faucet" to find some. Note that they should never charge or ask you for any details other than a Bitcoin address for funds to be sent to.

1. Create an account (A)

Use the Create Account endpoint:

Request:

curl --user [user]:[pass] --header "Accept: application/json" --request POST --data "" https://api.rtwire.com/v1/testnet3/accounts/

Response:

{"type":"accounts","payload":[{"id":[account A ID],"balance":0,"pendingBalance":0}]}

Remember [account A ID] so it can be referenced in the subsequent steps.

2. Create an address for account A

Use the Create Address endpoint:

Request:

curl --user [user]:[pass] --header "Accept: application/json" --request POST --data "" https://api.rtwire.com/v1/testnet3/accounts/[account A ID]/addresses/

Response:

{"type":"addresses","payload":[{"address":"[account A address]"}]}

3. Credit account A

Use a bitcoin testnet faucet to credit [account A address]. Note that many of these faucets produce spurious looking transactions which are flagged up on RTWire's risk assessment system. This sometimes means that RTWire will decide to wait until the transaction is in at least one block before it is credited to [account A ID].

4. Check account A has been credited

Use the Read Accounts endpoint:

Request:

curl --user [user]:[pass] --header "Accept: application/json" --request GET https://api.rtwire.com/v1/testnet3/accounts/[account A ID]

Response:

{"type":"accounts","payload":[{"id":[account A ID],"balance":0,"pendingBalance":0}]}

Note that it might take several minutes for account A's balance to be updated due to the spurious looking transactions that most testnet faucets generate. Once account A's balance has been updated then move on to step 5.

5. Create another account (B)

Once account A has been credited use the Create Account endpoint to create another account:

REQUEST:

curl --user [user]:[pass] --header "Accept: application/json" --request POST --data "" https://api.rtwire.com/v1/testnet3/accounts/

RESPONSE:

{"type":"accounts","payload":[{"id":[account B ID],"balance":0,"pendingBalance":0}]}

Remember [account B ID] so it can be referenced in the subsequent steps.

6. Create two new transaction IDs (tx A & tx B)

Create a transaction ID using the Create Transaction IDs endpoint. A transaction ID is required in the next step where we transfer funds from account A to B.

Request:

curl --user [user]:[pass] --header "Accept: application/json" --header "Content-Type: application/json" --request POST --data '{"n":1}' https://api.rtwire.com/v1/testnet3/transactions/

Response:

{"type":"transactions","payload":[{"id":[tx A ID],"created":"2015-10-10T00:00:00.000000000Z"}]} {"type":"transactions","payload":[{"id":[tx A ID],"created":"2015-10-10T00:00:00.000000000Z"},{"id":[tx B ID],"created":"2015-11-16T15:00:02.1177896Z"}]}

Remember [tx A ID]  and [tx B ID] as they will both be needed in subsequent steps.

7. Transfer funds from account A to account B

Transfer some funds from account A to account B using the Create Transaction endpoint. Note that [value] is in Satoshi, not Bitcoin.

Request:

curl --user [user]:[pass] --header "Content-Type: application/json" --request PUT --data '{"id":[tx A ID],"fromAccountID":[account A ID],"toAccountID":[account B ID],"value":[value]}' https://api.rtwire.com/v1/testnet3/transactions/

Response:

No response.

8. Debit account B

Use the same Create Transaction endpoint as in step 7 but this time send to a testnet3 bitcoin address such as mqpNGFKg9hKaEBqwdvzYu1J5SnnDpGEPMf instead of your account id. Note that [value] is in Satoshi, not Bitcoin and the minimum amount you can debit in one API call is 10000 Satoshi.

REQUEST:

curl --user [user]:[pass] --header "Content-Type: application/json" --request PUT --data '{"id":[tx B ID],"fromAccountID":[account B ID],"toAddress":[testnet3 address],"value":[value]}' https://api.rtwire.com/v1/testnet3/transactions/

RESPONSE:

No response.

9. Track debit transaction tx B

Use the Read Transaction endpoint to fetch your newly created transaction in order to track its progress across the bitcoin network.

Request:

curl --user [user]:[pass] --header "Accept: application/json" --request GET https://api.rtwire.com/v1/testnet3/transactions/[tx B ID]

Response:

{"type":"transactions","payload":[{"id":[tx B ID],"type":"debit","fromAccountID":[account B ID],"fromAccountBalance":[previous account B balance],"fromAccountTxID":[tx A ID],"value":[value],"created":"2015-10-01T00:00:01.000000Z","txHashes":[[bitcoin network transaction hash]],"txIndex":[transaction index of debit]}]}

Note that if a malicious entity malleates your transaction txHashes may be populated with more than one hash; the original and malleated hash.