Create a gist now

Instantly share code, notes, and snippets.

Embed
What would you like to do?
basic gatewayd user guide

Simple Gatewayd User's Guide

Gatewayd connects transactions outside the ripple network to transactions on the ripple ledger. When you record a payment that occured external to the ripple ledger that payment sent as a corresponding ripple payment. To match an external payment from one of your users to a ripple payment, first register that user's ripple address in the system, and record the external payment in the external account for that user:

Register User

Command Line
bin/gateway register_user <username> <password> <ripple_address>
REST
POST /v1/registrations
{
  "name": "steven@ripple.com",
  "password": "s0m3supe&$3cretp@s$w0r*",
  "ripple_address": "r4EwBWxrx5HxYRyisfGzMto3AT8FZiYdWk"
}
Javascript
gatewayd.api.registerUser({
  "name": "steven@ripple.com",
  "password": "s0m3supe&$3cretp@s$w0r*",
  "ripple_address": "r4EwBWxrx5HxYRyisfGzMto3AT8FZiYdWk"
}, function(error, user) {
  // includes:
  // user.external_account
  // user.hosted_address
  // user.ripple_address (independent)
};

Once a user is registered their account includes several additional records, including an external account to which they can make deposits, a hosted ripple address, and their independent ripple address. From then on any deposits made to that user's external account will be replicated to the ripple account and sent to their independent wallet. For instance:

Record Deposit

Command Line
bin/gateway record_deposit <amount> <currency> <external_account_id>
REST
POST /v1/deposits
{
  "external_account_id": 307,
  "currency": "BTC"
  "amount": "10.7"
}
Javascript
gatewayd.api.recordDeposit({
  "external_account_id": 307,
  "currency": "BTC"
  "amount": "10.7"
}, function(error, deposit) {
  // do something with deposit
});

Though a gateway should always connect an external transaction to a ripple transaction, there may be a time when the gateway operator wishes to issue currency to a ripple address without a corresponding external transaction. To perform such an action use the enqueue outgoing payment api call:

Enqueue Outgoing Payment

REST
POST /v1/payments/outgoing
{
  "amount": 6.5,
  "currency": "BTC",
  "address": "r4EwBWxrx5HxYRyisfGzMto3AT8FZiYdWk"
}
Javascript
gatewayd.api.enqueueOutgoingPayment({
  "amount": 6.5,
  "currency": "BTC",
  "address": "r4EwBWxrx5HxYRyisfGzMto3AT8FZiYdWk",
}, function(error, payment) {
  // do something with enqueued payment
});
Command Line
not yet implemented

Gatewayd also monitors for payments made to its ripple address, and it will mark payments made to a user's hosted address as a withdrawal request, allowing the administrator to manually or programatically process and clear the withdrawal. In order to make a withdrawal payment on ripple, send to the user's hosted address including the destination tag component of their hosted address. Gatewayd will map the user's destination tag to their external (bank) account and enqueue a pending withdrawl for the administrator to process.

List Queued Withdrawals

Command Line
bin/gateway list_queued_withdrawals
REST
GET /v1/withdrawals
Javascript
gatewayd.api.listQueuedWithdrawals(function(error, withdrawals) {
    // withdrawals is an array of external transaction records 
});

Once the gateway administrator has processed the withdrawal request they can mark the withdrawal as cleared in the system with an api call.

Clear Withdrawal

Command Line
bin/gateway clear_withdrawal <id>
REST
POST /v1/withdrawals/:id/clear
Javascript
gatewayd.api.clearWithdrawal(id, function(error, withdrawal) {
    // withdrawal will be marked as "cleared" 
});
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment