Place an order on the decentralized exchange (DEX) to acquire XRP.
XRP is the base asset: amount is the XRP being bought, and price is the counter-asset paid for it.
xrp.buyOffer(
params: XrpOfferParams,
options?: XrpWriteOptions,
): Promise<SubmissionResult<undefined>>| Parameter | Type | Required | Description |
|---|---|---|---|
amount | string | Yes | The amount of XRP to buy, as a decimal string. Must be non-negative, with at most 6 decimal places (1 drop, XRP's smallest unit). |
orderType | IOUOrderType | Yes | The order type: 'limit', 'market', 'fok', or 'passive'. |
price | XrpOfferPrice | Yes | What's offered in payment — an MPT or an IOU (see below). |
domainID | string | No | Restrict the offer to a permissioned domain. Omit for the open DEX. |
hybrid | boolean | No | Whether a domain-scoped offer also works the open DEX. Only meaningful with domainID; defaults to true when domainID is set. |
offerSequence | number | No | A prior offer sequence to replace. |
price (XrpOfferPrice) is one of:
| Shape | Description |
|---|---|
{ ticker: string; issuer: string; amount: string } | Priced in an IOU. Must be non-negative, with at most 15 significant digits — the XRPL issued-currency limit. |
{ mptIssuanceId: string; amount: string } | Priced in an MPT. However, the XRPL DEX doesn't support MPTs yet and will always be rejected. |
options is an optional second argument that sets the source account and overrides the fee.
| Option | Type | Required | Description |
|---|---|---|---|
from | AccountSelector | No | The account to act as — an r-address string, or an object { address } or { signer, account? }. Defaults to the primary signer's primary account. (For IOU operations, this is the issuer.) |
fee | FeeIntent | No | Fee override — a priority tier and/or a maxFeeDrops cap. |
idempotencyKey | string | No | A prior submission's idempotencyKey, to retry to the same intent instead of creating a duplicate. Auto-generated when omitted. |
Resolves to a SubmissionResult<undefined>.
Every simpleXRPL write resolves to a SubmissionResult<T> — a union tagged by source, with the backend's raw response preserved verbatim. Its common fields are:
| Field | Type | Description |
|---|---|---|
intent | T | The operation-specific output — see the operation's own return fields. |
source | 'xrpld' | 'custody' | 'palisade' | Which backend produced the result; discriminates response. |
response | TxResponse | custody record | Palisade record | The backend's raw response, preserved verbatim. |
txHash | string (optional) | The XRPL transaction hash, once the transaction is on-ledger. |
intentId | string (optional) | The custodian intent id, when the path produced one. Hold onto this to resume via client.intent. |
idempotencyKey | string (optional) | The UUIDv7 this submission carried. Pass it back as a later call's idempotencyKey to retry to the same intent rather than creating a duplicate. |
XRP.buyOffer attaches no intent output; intent is undefined.
Builds and submits a single OfferCreate transaction, with the XRP leg as TakerPays and the price as TakerGets. Throws an IntentValidationError if price is MPT-denominated.
// Buy 50 XRP, paying 100 USD for it.
await client.xrp.buyOffer({
amount: '50',
orderType: 'limit',
price: { ticker: 'USD', issuer: 'rIssuer...', amount: '100' },
})