Trade in the Decentralized Exchange
This tutorial demonstrates how you can buy and sell tokens in the decentralized exchange (DEX).
Prerequisites
- You need a connection to the XRP Ledger network. As shown in this tutorial, you can use public servers for testing.
- You should be familiar with the Getting Started instructions for your preferred client library. This page provides examples for the following:
- JavaScript with the xrpl.js library. See Get Started Using JavaScript for setup steps.
- Python with the
xrpl-py
library. See Get Started using Python for setup steps. - You can also read along and use the interactive steps in your browser without any setup.
Example Code
Complete sample code for all of the steps of this tutorial is available under the MIT license.
- See Code Samples: Trade in the Decentralized Exchange in the source repository for this website.
Steps
This tutorial demonstrates how to buy a fungible token in the decentralized exchange by selling XRP. (Other types of trades are possible, but selling a token, for example, requires you to have it first.) The example token used in this tutorial is as follows:
Currency Code | Issuer | Notes |
---|---|---|
TST | rP9jPyP5kyvFRb6ZiRghAGw5u8SGAmU4bd | A test token pegged to XRP at a rate of approximately 10 XRP per 1 TST. The issuer has existing Offers on the XRP Ledger Testnet to buy and sell these tokens. |
1. Connect to Network
You must be connected to the network to submit transactions to it. Additionally, some languages (including JavaScript) require a high-precision number library for performing calculations on currency amounts you may find in the ledger. The following code shows how to connect to a public XRP Ledger Testnet server a supported client library with the appropriate dependencies.
// In browsers, add the following <script> tags to the HTML to load dependencies // instead of using require(): // <script src="https://unpkg.com/[email protected]/build/xrpl-latest-min.js"></script> // <script src='https://cdn.jsdelivr.net/npm/[email protected]/bignumber.min.js'></script> const xrpl = require('xrpl') const BigNumber = require('bignumber.js') // Wrap code in an async function so we can use await async function main() { // Define the network client const client = new xrpl.Client("wss://s.altnet.rippletest.net:51233") await client.connect() // ... custom code goes here // Disconnect when done (If you omit this, Node.js won't end the process) await client.disconnect() } main()
Note: The JavaScript code samples in this tutorial use the async
/await
pattern. Since await
needs to be used from within an async
function, the remaining code samples are written to continue inside the main()
function started here. You can also use Promise methods .then()
and .catch()
instead of async
/await
if you prefer.
For this tutorial, click the following button to connect:
2. Get Credentials
To transact on the XRP Ledger, you need an address, a secret key, and some XRP. For development purposes, you can get these on the Testnet using the following interface:
注意: RippleはTestnetとDevnetをテストの目的でのみ運用しており、その状態とすべての残高を定期的にリセットしています。予防措置として、Testnet、DevnetとMainnetで同じアドレスを使用しないことをお勧めします。
When you're building production-ready software, you should use an existing account, and manage your keys using a secure signing configuration. The following code shows how to create a Wallet
instance to use your keys:
// Get credentials from the Testnet Faucet ----------------------------------- console.log("Requesting address from the Testnet faucet...") const wallet = (await client.fundWallet()).wallet console.log(`Got address ${wallet.address}.`) // To use existing credentials, you can load them from a seed value, for // example using an environment variable as follows: // const wallet = xrpl.Wallet.fromSeed(process.env['MY_SEED'])
3. Look Up Offers
Before you buy or sell a token, you usually want to look up what others are buying and selling for, to get a sense of how others value it. In the XRP Ledger, you can look up existing offers for any currency pair using the book_offers method.
Tip: Technically, this step is not a requirement for placing an Offer, but it is a good practice to confirm the current situation before trading anything with real value.
The following code shows how to look up existing Offers and compare them to a proposed Offer to estimate how it would execute:
// Define the proposed trade. ------------------------------------------------ // Technically you don't need to specify the amounts (in the "value" field) // to look up order books using book_offers, but for this tutorial we reuse // these variables to construct the actual Offer later. const we_want = { currency: "TST", issuer: "rP9jPyP5kyvFRb6ZiRghAGw5u8SGAmU4bd", value: "25" } const we_spend = { currency: "XRP", // 25 TST * 10 XRP per TST * 15% financial exchange (FX) cost value: xrpl.xrpToDrops(25*10*1.15) } // "Quality" is defined as TakerPays / TakerGets. The lower the "quality" // number, the better the proposed exchange rate is for the taker. // The quality is rounded to a number of significant digits based on the // issuer's TickSize value (or the lesser of the two for token-token trades.) const proposed_quality = BigNumber(we_spend.value) / BigNumber(we_want.value) // Look up Offers. ----------------------------------------------------------- // To buy TST, look up Offers where "TakerGets" is TST: const orderbook_resp = await client.request({ "command": "book_offers", "taker": wallet.address, "ledger_index": "current", "taker_gets": we_want, "taker_pays": we_spend }) console.log(JSON.stringify(orderbook_resp.result, null, 2)) // Estimate whether a proposed Offer would execute immediately, and... // If so, how much of it? (Partial execution is possible) // If not, how much liquidity is above it? (How deep in the order book would // other Offers have to go before ours would get taken?) // Note: These estimates can be thrown off by rounding if the token issuer // uses a TickSize setting other than the default (15). In that case, you // can increase the TakerGets amount of your final Offer to compensate. const offers = orderbook_resp.result.offers const want_amt = BigNumber(we_want.value) let running_total = BigNumber(0) if (!offers) { console.log(`No Offers in the matching book. Offer probably won't execute immediately.`) } else { for (const o of offers) { if (o.quality <= proposed_quality) { console.log(`Matching Offer found, funded with ${o.owner_funds} ${we_want.currency}`) running_total = running_total.plus(BigNumber(o.owner_funds)) if (running_total >= want_amt) { console.log("Full Offer will probably fill") break } } else { // Offers are in ascending quality order, so no others after this // will match, either console.log(`Remaining orders too expensive.`) break } } console.log(`Total matched: ${Math.min(running_total, want_amt)} ${we_want.currency}`) if (running_total > 0 && running_total < want_amt) { console.log(`Remaining ${want_amt - running_total} ${we_want.currency} would probably be placed on top of the order book.`) } } if (running_total == 0) { // If part of the Offer was expected to cross, then the rest would be placed // at the top of the order book. If none did, then there might be other // Offers going the same direction as ours already on the books with an // equal or better rate. This code counts how much liquidity is likely to be // above ours. // Unlike above, this time we check for Offers going the same direction as // ours, so TakerGets and TakerPays are reversed from the previous // book_offers request. const orderbook2_resp = await client.request({ "command": "book_offers", "taker": wallet.address, "ledger_index": "current", "taker_gets": we_spend, "taker_pays": we_want }) console.log(JSON.stringify(orderbook2_resp.result, null, 2)) // Since TakerGets/TakerPays are reversed, the quality is the inverse. // You could also calculate this as 1/proposed_quality. const offered_quality = BigNumber(we_want.value) / BigNumber(we_spend.value) const offers2 = orderbook2_resp.result.offers let tally_currency = we_spend.currency if (tally_currency == "XRP") { tally_currency = "drops of XRP" } let running_total2 = 0 if (!offers2) { console.log(`No similar Offers in the book. Ours would be the first.`) } else { for (const o of offers2) { if (o.quality <= offered_quality) { console.log(`Existing offer found, funded with ${o.owner_funds} ${tally_currency}`) running_total2 = running_total2.plus(BigNumber(o.owner_funds)) } else { console.log(`Remaining orders are below where ours would be placed.`) break } } console.log(`Our Offer would be placed below at least ${running_total2} ${tally_currency}`) if (running_total > 0 && running_total < want_amt) { console.log(`Remaining ${want_amt - running_total} ${tally_currency} will probably be placed on top of the order book.`) } } }
Note: Other users of the XRP Ledger can also make trades at any time, so this is only an estimate of what would happen if nothing else changes. The outcome of a transaction is not guaranteed until it is final.
The following block demonstrates these calculations in action:
4. Send OfferCreate Transaction
To actually make a trade, send an OfferCreate transaction. In this case, you want to buy TST using XRP, so you should set the parameters as follows:
Field | Type | Description |
---|---|---|
TakerPays | Token Amount object | How much of what currency you want to buy, in total. For this tutorial, buy some amount of TST issued by rP9jPyP5kyvFRb6ZiRghAGw5u8SGAmU4bd . |
TakerGets | XRP, in drops | How much of what currency you are offering to pay in total. For this tutorial, you should specify about 11.5 XRP per TST or slightly more. |
The following code shows how to prepare, sign, and submit the transaction:
// Send OfferCreate transaction ---------------------------------------------- // For this tutorial, we already know that TST is pegged to // XRP at a rate of approximately 10:1 plus spread, so we use // hard-coded TakerGets and TakerPays amounts. const offer_1 = { "TransactionType": "OfferCreate", "Account": wallet.address, "TakerPays": we_want, "TakerGets": we_spend.value // since it's XRP } const prepared = await client.autofill(offer_1) console.log("Prepared transaction:", JSON.stringify(prepared, null, 2)) const signed = wallet.sign(prepared) console.log("Sending OfferCreate transaction...") const result = await client.submitAndWait(signed.tx_blob) if (result.result.meta.TransactionResult == "tesSUCCESS") { console.log(`Transaction succeeded: https://testnet.xrpl.org/transactions/${signed.hash}`) } else { throw `Error sending transaction: ${result}` }
You can use this interface to send the transaction specified by the amounts in the previous step:
5. Wait for Validation
Most transactions are accepted into the next ledger version after they're submitted, which means it may take 4-7 seconds for a transaction's outcome to be final. If the XRP Ledger is busy or poor network connectivity delays a transaction from being relayed throughout the network, a transaction may take longer to be confirmed. (For information on how to set an expiration for transactions, see Reliable Transaction Submission.)
トランザクションのID: | (無) |
---|---|
最新の検証レジャーインデックス: | 接続されていません |
送信時のレジャーインデックス: | (まだ送信されません) |
トランザクションのLastLedgerSequence : | (準備されません) |
6. Check Metadata
You can use the validated transaction's metadata to determine exactly what it did. (Don't use metadata from tentative transaction results, because it may be different from the final result, especially when using the decentralized exchange.) In case of an OfferCreate transaction, likely results include:
- Some or all of the Offer may have been filled by matching with existing Offers in the ledger.
- The unmatched remainder, if any, has been placed into the ledger to await new matching Offers.
- Other bookkeeping may have occurred, such as removing expired or unfunded Offers that would have matched.
The following code demonstrates how to check the metadata of the transaction:
// Check metadata ------------------------------------------------------------ // In JavaScript, you can use getBalanceChanges() to help summarize all the // balance changes caused by a transaction. const balance_changes = xrpl.getBalanceChanges(result.result.meta) console.log("Total balance changes:", JSON.stringify(balance_changes, null,2)) // Helper to convert an XRPL amount to a string for display function amt_str(amt) { if (typeof amt == "string") { return `${xrpl.dropsToXrp(amt)} XRP` } else { return `${amt.value} ${amt.currency}.${amt.issuer}` } } let offers_affected = 0 for (const affnode of result.result.meta.AffectedNodes) { if (affnode.hasOwnProperty("ModifiedNode")) { if (affnode.ModifiedNode.LedgerEntryType == "Offer") { // Usually a ModifiedNode of type Offer indicates a previous Offer that // was partially consumed by this one. offers_affected += 1 } } else if (affnode.hasOwnProperty("DeletedNode")) { if (affnode.DeletedNode.LedgerEntryType == "Offer") { // The removed Offer may have been fully consumed, or it may have been // found to be expired or unfunded. offers_affected += 1 } } else if (affnode.hasOwnProperty("CreatedNode")) { if (affnode.CreatedNode.LedgerEntryType == "RippleState") { console.log("Created a trust line.") } else if (affnode.CreatedNode.LedgerEntryType == "Offer") { const offer = affnode.CreatedNode.NewFields console.log(`Created an Offer owned by ${offer.Account} with TakerGets=${amt_str(offer.TakerGets)} and TakerPays=${amt_str(offer.TakerPays)}.`) } } } console.log(`Modified or removed ${offers_affected} matching Offer(s)`)
You can use this interface to test it out:
7. Check Balances and Offers
This is also a good time to look up the balances and outstanding Offers owned by your account as of the latest validated ledger. This shows any changes caused by your transaction as well as any others that executed in the same ledger version.
The following code demonstrates how to look up balances using the account_lines method and look up Offers using the account_offers method.
// Check balances ------------------------------------------------------------ console.log("Getting address balances as of validated ledger...") const balances = await client.request({ command: "account_lines", account: wallet.address, ledger_index: "validated" // You could also use ledger_index: "current" to get pending data }) console.log(JSON.stringify(balances.result, null, 2)) // Check Offers -------------------------------------------------------------- console.log(`Getting outstanding Offers from ${wallet.address} as of validated ledger...`) const acct_offers = await client.request({ command: "account_offers", account: wallet.address, ledger_index: "validated" }) console.log(JSON.stringify(acct_offers.result, null, 2))
You can use this interface to test it out: