# xrp.buyOffer()

[[Source]](https://github.com/ripple/simpleXRPL/blob/95b977b15f8950c5bc076b25165217869c0b06d3/src/verticals/xrp.ts#L173)

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.

## Signature


```ts
xrp.buyOffer(
  params: XrpOfferParams,
  options?: XrpWriteOptions,
): Promise<SubmissionResult<undefined>>
```

## Parameters

| 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

`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. |


## Returns

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. |


### Return fields

`XRP.buyOffer` attaches no `intent` output; `intent` is `undefined`.

## Underlying XRPL transactor

Builds and submits a single [OfferCreate](https://xrpl.org/docs/references/protocol/transactions/types/offercreate) transaction, with the XRP leg as `TakerPays` and the price as `TakerGets`. Throws an `IntentValidationError` if `price` is MPT-denominated.

## Example


```ts
// Buy 50 XRP, paying 100 USD for it.
await client.xrp.buyOffer({
  amount: '50',
  orderType: 'limit',
  price: { ticker: 'USD', issuer: 'rIssuer...', amount: '100' },
})
```