Getting Started with XRPL DEX Trading

npm install xrpl

import { Client, Wallet, xrpToDrops, AccountSetAsfFlags } from "xrpl";

const client = new Client("wss://s.altnet.rippletest.net:51233");
await client.connect();

// Two throwaway Testnet wallets: an issuer and a market maker.
const { wallet: issuer } = await client.fundWallet();
const { wallet: maker  } = await client.fundWallet();

const submit = async (w: Wallet, tx: any) =>
  client.submitAndWait((w.sign(await client.autofill(tx))).tx_blob);

// 1. The issuer must allow its token to move between holders.
await submit(issuer, { TransactionType: "AccountSet", Account: issuer.classicAddress,
                       SetFlag: AccountSetAsfFlags.asfDefaultRipple });

// 2. The maker trusts the issuer for TST.
await submit(maker, { TransactionType: "TrustSet", Account: maker.classicAddress,
                      LimitAmount: { currency: "TST", issuer: issuer.classicAddress, value: "1000" } });

// 3. The issuer sends the maker 100 TST.
await submit(issuer, { TransactionType: "Payment", Account: issuer.classicAddress,
                       Destination: maker.classicAddress,
                       Amount: { currency: "TST", issuer: issuer.classicAddress, value: "100" } });

// 4. The maker posts liquidity: sell 20 TST for 4 XRP (0.2 XRP/TST).
await submit(maker, { TransactionType: "OfferCreate", Account: maker.classicAddress,
                      TakerPays: xrpToDrops(4),
                      TakerGets: { currency: "TST", issuer: issuer.classicAddress, value: "20" } });

console.log("Tradeable pair ready. Issuer:", issuer.classicAddress);
await client.disconnect();

import { Client, dropsToXrp } from "xrpl";

// NOTE: rvYAfWj5... is Bitstamp's MAINNET issuer. It has no meaningful book on
// Testnet. Substitute an issuer that is actually active on Testnet, or issue your
// own test token and trade against it.
const USD_ISSUER = process.env.TEST_ISSUER!;   // a Testnet issuer you control
const client    = new Client("wss://s.altnet.rippletest.net:51233");
await client.connect();

const [asks, bids] = await Promise.all([
  client.request({
    command:    "book_offers",
    taker_pays: { currency: "USD", issuer: USD_ISSUER },
    taker_gets: { currency: "XRP" },
    limit: 20,
  }),
  client.request({
    command:    "book_offers",
    taker_pays: { currency: "XRP" },
    taker_gets: { currency: "USD", issuer: USD_ISSUER },
    limit: 20,
  }),
]);

// `quality` is TakerPays/TakerGets in PROTOCOL units — XRP is in drops, so an
// XRP-denominated quality is 1,000,000x off and the two book sides are inverted.
// Always derive the price from the amounts instead.
const amt = (a: any) => typeof a === "string" ? Number(dropsToXrp(a)) : Number(a.value);
const price = (o: any, getsBase: boolean) =>
  getsBase ? amt(o.TakerPays) / amt(o.TakerGets) : amt(o.TakerGets) / amt(o.TakerPays);

// `book_offers` also returns offers their owner cannot currently fund — including
// completely unfunded ones, which carry a real-looking price and size. Tradeable
// size is `taker_gets_funded` when present; drop anything that resolves to 0.
const fundedGets  = (o: any) => o.taker_gets_funded ?? o.TakerGets;
const liveOffers  = (os: any[]) => os.filter(o => amt(fundedGets(o)) > 0);

const askOffers = liveOffers(asks.result.offers);   // taker_gets = XRP -> getsBase = true
const bidOffers = liveOffers(bids.result.offers);   // taker_pays = XRP -> getsBase = false
const bestAsk   = askOffers.length ? price(askOffers[0], true)  : null;
const bestBid   = bidOffers.length ? price(bidOffers[0], false) : null;

// A one-sided book has no mid price and no spread. Report that honestly.
if (bestAsk === null || bestBid === null) {
  console.log("One-sided book — mid price and spread are undefined.");
} else {
  const midPrice  = (bestAsk + bestBid) / 2;
  const spreadPct = ((bestAsk - bestBid) / midPrice) * 100;
  console.log(`Mid price: ${midPrice.toFixed(6)} USD/XRP`);
  console.log(`Spread   : ${spreadPct.toFixed(3)} %`);
}

await client.disconnect();

import { OfferCreate, xrpToDrops } from "xrpl";

const XRPL_EPOCH_OFFSET = 946_684_800;
const expiryXRPL = Math.floor(Date.now() / 1000) + 3600 - XRPL_EPOCH_OFFSET;

const offer: Omit<OfferCreate, "Fee" | "Sequence" | "LastLedgerSequence"> = {
  TransactionType: "OfferCreate",
  Account:    "rYourAddress",
  TakerPays:  { currency: "USD", issuer: "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B", value: "5" },
  TakerGets:  xrpToDrops(10),      // "10000000" drops
  Expiration: expiryXRPL,
  // Fee, Sequence, LastLedgerSequence: set by Wallet skill autofill
  // SourceTag: applied by Wallet skill (20260530) automatically
};
// → hand to XRPL Agent Wallet skill

import { OfferCancel } from "xrpl";

const cancel: Omit<OfferCancel, "Fee" | "Sequence" | "LastLedgerSequence"> = {
  TransactionType: "OfferCancel",
  Account:        "rYourAddress",
  OfferSequence:  48291010,   // Sequence of the original OfferCreate
};
// → hand to XRPL Agent Wallet skill