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.

API Root

https://[user]:[pass]@api.rtwire.com/v1/[network]

[user] Obtained from visiting https://console.rtwire.com/ in a browser.
[pass] Obtained from visiting https://console.rtwire.com/ in a browser.
[network] testnet3 or mainnet.

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": <see below>,
  "next": <see below>,
  "payload" : <see below>
}

Error Responses

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

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

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.

Create Account

Request:
HTTP POST [api root]/accounts/
Accept: "application/json"

Response Body:

HTTP Status Code: 201 Created
Content-Type: "application/json"

{
  "type": "accounts",
  "payload": [{
      "id": 123,     // Unique account ID.
      "balance": 0 // Account balance in Satoshi.
  }]
}

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. 

Body: Blank

Response:
HTTP Status Code: 200 OK
Content-Type: "application/json"

{
  "type": "accounts",
  "next": "ag34gsfsdf", // Token to get next set of results.
  "payload": [{
      "id": 345,     // Unique account ID.
      "balance": 12 // Account balance in Satoshi.
    },
    {
      "id": 4534,    // Unique account ID.
      "balance": 22 // Account balance in Satoshi.
    },
    {...},
    {...}
  ]
}

Read Account

Request:
HTTP GET [api root]/accounts/[account id]
Accept: "application/json"

Response:
HTTP Status Code: 200 OK
Content-Type: "application/json"

{
  "type": "accounts",
  "payload": [{
      "id": 345,     // Unique account ID.
      "balance": 12 // Account balance in Satoshi.
  }]
}

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. 

Body: Blank

Response:
HTTP Status Code: 200 OK
Content-Type: "application/json"

{
  "type": "transactions",
    
  // Token to get next set of results.
  "next": "asege1asdfQqwerAGDf", 
    
  "payload": [{
       // Transaction ID.
      "id": "234",
    
      // Can be transfer, credit or debit type.
      "type": "transfer",
    
      // Account IDs the transaction represents. May be zero if you are not
      // authorized to view the account.
      "fromAccountID": 235235,
      "toAccountID": 346346,
      
      // Account balance of the sender and receiver account in Satoshi prior
      // to this transaction occuring.
      "fromAccountBalance": 2000,
      "toAccountBalance": 5000,      

      // Previous transaction IDs of the sending and receiving accounts.
      "fromAccountTxID": 4634345,
      "toAccountTxID": 3547457,
      
      // Amount transferred in Satoshi.
      "value": 1000,

      // Time string in  RFC 3339 format.
      "created": "2006-01-02T15:04:05Z07:00",      

      // The following is optional for credit and debit transaction types.

      // The transaction hash the credit or debit pertains to. There may be
      // multiple hashes if a transaction malleability attack occured.
      "txHashes": { 
        "bc2885b57aaa0ad762...",
        "htreh4564644gfdgss..."
      }

      // Specific TxOut that the credit or debit occured in.
      "txIndex": 3 
    },
    {...},
    {...}
  ]
}

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.

Request:
HTTP GET [api root]/accounts/labels/[label]/
Accept: "application/json"

Body: Blank

Response:
HTTP Status Code: 200 OK
Content-Type: "application/json"

{
  "type": "accounts",
  "payload": [{
      "id": 345,     // Unique account ID.
      "balance": 12 // Account balance in Satoshi.
  }]
}

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.

Create Address

Request:
HTTP POST [api root]/accounts/[account id]/addresses/
Accept: "application/json"

Response:
HTTP Status Code: 201 Created
Content-Type: "application/json"

{
  "type": "addresses",
  "payload": [{
    "address": "12nggmHL8wHDoqn8HEYNDsTXnZmeDaUxPu", // Bitcoin address.
  }]
}

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:

  1. POST [api root]/transactions/ to create a transaction ID.
  2. 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 IDs

Request:
HTTP POST [api root]/transactions/
Accept: "application/json"
Content-Type: "application/json"

{
  // Number of transaction IDs to create (max 10).
  "n": 2
}

Response:
HTTP Status Code: 201 Created
Content-Type: "application/json"

{
  "type": "transactions",
  "payload": [{
      "id": 345 // First transaction ID of sequence.
    },
    {
      "id": 232
    },
    {...},
    {...}
  ]
}

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.

Request:
HTTP PUT [api root]/transactions/
Content-Type: "application/json"

{
  "id": 345, // Unique transaction ID. See docs below.
  "fromAccountID": 15324,
  
  // Transfer to an RTWire account.
  "toAccountID": 46346,
  // Or to a Bitcoin address.
  "toAddress": "12nggmHL8wHDoqn8HEYNDsTXnZmeDaUxPu",
    
  "value": 123344 // Value to transfer in Satoshi.
}

Response:
HTTP Status Code: 201 Created

Read Transaction

Request:
HTTP GET [api root]/transactions/[transaction id]
Accept: "application/json"

Response:
HTTP Status Code: 200 OK

{
  "type": "transactions",
    
  "payload": [{
       // Transaction ID.
      "id": "234",
    
      // Can be transfer, credit or debit type.
      "type": "transfer",
    
      // Account IDs the transaction represents. May be zero if you are not
      // authorized to view the account.
      "fromAccountID": 235235,
      "toAccountID": 346346,
      
      // Account balance of the sender and receiver account in Satoshi prior
      // to this transaction occuring.
      "fromAccountBalance": 2000,
      "toAccountBalance": 5000,      

      // Previous transaction IDs of the sending and receiving accounts.
      "fromAccountTxID": 4634345,
      "toAccountTxID": 3547457,
      
      // Amount transferred in Satoshi.
      "value": 1000,

      // Time string in  RFC 3339 format.
      "created": "2006-01-02T15:04:05Z07:00",      

      // The following is optional for credit and debit transaction types.

      // The transaction hash the credit or debit pertains to. There may be
      // multiple hashes if a transaction malleability attack occured.
      "txHashes": { 
        "bc2885b57aaa0ad762...",
        "htreh4564644gfdgss..."
      }

      // Specific TxOut that the credit or debit occured in.
      "txIndex": 3 
  }]
}

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.

Create Hook

Request:
HTTP POST [api root]/hooks/
Content-Type: "application/json"

{
  "url": <your hook url>
}

Response:
HTTP Status Code: 201 Created

Read Hooks

Request:
HTTP GET [api root]/hooks/
Accept: "application/json"

Response:
HTTP Status Code: 200 OK
Content-Type: "application/json"

{
  "type": "hooks",
  "payload": [{
      "url": <uri one>
    },
    {
      "url": <uri two>
    },
    {...}
  ]
}

Delete Hook

Request:
HTTP DELETE [api root]/hooks/[encoded hook uri]
Query Params:
- encoded uri - base64 URL encoded URI. See this Go package for encoding examples.

Response:
HTTP Status Code: 200 OK

Hook Event

This is the request that RTWire makes to your system when a hook event occurs. Note that the same event can be sent multiple times so your system must be able to cope with duplicates.

Request:
HTTP POST [your hook uri]
Body: Content-Type: "application/json"

{
  "type": "transactions",
    
  "payload": [{
       // Transaction ID.
      "id": "234",
    
      // Can be transfer, credit or debit type.
      "type": "transfer",
    
      // Account IDs the transaction represents. May be zero if you are not
      // authorized to view the account.
      "fromAccountID": 235235,
      "toAccountID": 346346,
      
      // Account balance of the sender and receiver account in Satoshi prior
      // to this transaction occuring.
      "fromAccountBalance": 2000,
      "toAccountBalance": 5000,      

      // Previous transaction IDs of the sending and receiving accounts.
      "fromAccountTxID": 4634345,
      "toAccountTxID": 3547457,
      
      // Amount transferred in Satoshi.
      "value": 1000,

      // Time string in  RFC 3339 format.
      "created": "2006-01-02T15:04:05Z07:00",      

      // The following is optional for credit and debit transaction types.

      // The transaction hash the credit or debit pertains to. There may be
      // multiple hashes if a transaction malleability attack occured.
      "txHashes": { 
        "bc2885b57aaa0ad762...",
        "htreh4564644gfdgss..."
      }

      // Specific TxOut that the credit or debit occured in.
      "txIndex": 3, 
    
      // The status property will only be present if the transaction 
      // is pending.
      "status": "pending"
    },
    {...},
    {...}
  ]
}

Response:
HTTP Status Code: 200 OK

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.

Request:
HTTP GET [api root]/fees/
Accept: "application/json"

Response:
HTTP Status Code: 200 OK
Content-Type: "application/json"

{
  "type": "fees",
  "payload": [{
      "feePerByte": 5000,  // Estimated value per byte of transaction in Satoshi.
      "blockHeight": 413690 // The block height from which this estimate is valid.
  }]
}