Submit XRP Ledger transactions via the API

This guide shows you how to submit XRP Ledger (XRPL) transaction types beyond simple payments — trust lines, account settings, clawbacks, DEX offers, signer lists, and automated market maker (AMM) operations — from a Ripple Custody (Wallet) wallet. To create these and other XRP Ledger transaction types in the console instead, see XRP Ledger transactions in the console. To send XRP or an issued token as a payment, see Send assets via the API.

Permissions: In the console, owners, administrators, and proposers can create transactions, and owners, administrators, proposers, and approvers can approve them. See User roles and permissions. The API procedures need an API credential of type TRANSACTIONS. See Prerequisites.

• An API credential of type TRANSACTIONS. It grants access to creating and managing transactions, including XRP Ledger transaction types. Create credentials in the console — see Manage API credentials and Credential types.
• An access token. Exchange your credential's clientId and clientSecret for an access token — see Authenticate.
• A funded XRP Ledger wallet. The endpoints on this page act on a single wallet, so you need the wallet's vaultId and walletId — see Create your first wallet.
• An active policy that permits outgoing transactions — see Unlock outgoing transactions.

For the base URLs, token lifetime, pagination, filtering, and error format that every endpoint shares, see API conventions.

Every endpoint on this page is a POST to /v2/vaults/{vaultId}/wallets/{walletId}/transactions/xrp/<type>. Each accepts these optional fields alongside its own:

• sequence (string) — the account sequence number to use.
• lastLedgerSequence (string) — the highest ledger index this transaction can appear in.
• sourceTag (string) — the source tag for this transaction.

Amounts use a currency amount object with value (string) and asset (the currency code) — both required — and issuer, the issuing address. You can omit issuer when the asset is XRP. Fields that identify an asset without an amount, such as asset and asset2 on AMM deposits and withdrawals, take only asset and issuer.

Each endpoint returns the created transaction object, which then moves through the standard lifecycle. See Track the result.

A request that omits a required field returns HTTP 400 with the reason PAL000.020. Check field names and flag names against this page before you submit.

API reference: Create an XRP Trust Set transaction

Create or modify a trust line, which lets the wallet hold a token issued by another account. limitAmount is required: it defines the currency, its issuer, and the maximum amount to trust.

Optional fields:

• qualityIn and qualityOut (integers) — value incoming and outgoing balances on the trust line at the ratio of this number per 1,000,000,000 units. 0 treats balances at face value.
• flags — an array of any of SETF_AUTH, SET_NORIPPLE, UNSET_NORIPPLE, SET_FREEZE, UNSET_FREEZE, SET_DEEP_FREEZE, and UNSET_DEEP_FREEZE.

curl -X POST "https://api.sandbox.palisade.co/v2/vaults/$VAULT_ID/wallets/$WALLET_ID/transactions/xrp/trust-set" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "limitAmount": {
      "value": "1000000",
      "asset": "USD",
      "issuer": "rGgKM3hTn8MBMGgiiPMbz73VEkSBocqab6"
    },
    "qualityIn": 0,
    "qualityOut": 0,
    "flags": ["SET_NORIPPLE"]
  }'

API reference: Create an XRP Account Set transaction

Change the wallet's XRPL account settings. All fields are optional; set only what you want to change. setFlag turns on one account flag and clearFlag turns one off. Each takes one of ACCOUNT_TXN_ID, ALLOW_TRUSTLINE_CLAWBACK, AUTHZ_NFTOKEN_MINTER, DEFAULT_RIPPLE, DEPOSIT_AUTH, DISABLE_MASTER, DISALLOW_INCOMING_CHECK, DISALLOW_INCOMING_PAY_CHAN, DISALLOW_INCOMING_TRUSTLINE, DISALLOW_XRP, GLOBAL_FREEZE, NO_FREEZE, REQUIRE_AUTH, or REQUIRE_DEST.

Other fields:

• domain — the hex-encoded ASCII domain that owns this account, less than 256 characters. Set it to an empty string to remove it.
• emailHash — the hex-encoded 128-bit hash of the email address for this account. Set it to an empty string to remove it.
• messageKey — a 33-byte public key for sending encrypted messages to this account. The first byte must be 0x02, 0x03, or 0xED. Set it to an empty string to remove it.
• nfTokenMinter — the address of another account that can mint NFTokens for this account.
• transferRate (integer) — the fee to charge when users transfer tokens this account issues, in billionths of a unit: 0, or a value from 1000000000 to 2000000000.
• tickSize (integer) — the tick size for offers involving a currency this account issues: 0, or from 3 through 15.
• walletLocator — an arbitrary 256-bit hash value to associate with this account.
• walletSize (integer) — an unused field you can set on the account.

curl -X POST "https://api.sandbox.palisade.co/v2/vaults/$VAULT_ID/wallets/$WALLET_ID/transactions/xrp/account-set" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "setFlag": "REQUIRE_DEST",
    "domain": "6578616d706c652e636f6d",
    "transferRate": 1005000000,
    "tickSize": 5
  }'

API reference: Create an XRP Clawback transaction

Reclaim tokens that the wallet issued from a holder's account. The wallet must turn on the ALLOW_TRUSTLINE_CLAWBACK account flag before it issues the tokens. amount is required: it sets the amount and currency to claw back, and its issuer field holds the token holder's address, not the wallet's. For MPTokens, set the optional holder field to the holder's address.

curl -X POST "https://api.sandbox.palisade.co/v2/vaults/$VAULT_ID/wallets/$WALLET_ID/transactions/xrp/clawback" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": {
      "value": "250",
      "asset": "USD",
      "issuer": "rLsV52sRDL79HXGGm9yzwKibb6BeruhUzy"
    }
  }'

API reference: Create an XRP Offer Create transaction

Place an order on the XRPL decentralized exchange. takerGets (the amount and currency to sell) and takerPays (the amount and currency to buy) are required.

Optional fields:

• expiration (string) — the Unix timestamp after which the offer is no longer active.
• offerSequence (string) — the sequence number of an existing offer to cancel before placing this one.
• flags — an array of any of PASSIVE, IMMEDIATE_OR_CANCEL, FILL_OR_KILL, and SELL. Don't combine IMMEDIATE_OR_CANCEL and FILL_OR_KILL.

curl -X POST "https://api.sandbox.palisade.co/v2/vaults/$VAULT_ID/wallets/$WALLET_ID/transactions/xrp/offer-create" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "takerGets": {
      "value": "100",
      "asset": "XRP"
    },
    "takerPays": {
      "value": "55.50",
      "asset": "USD",
      "issuer": "rGgKM3hTn8MBMGgiiPMbz73VEkSBocqab6"
    },
    "expiration": "1885634315",
    "flags": ["PASSIVE"]
  }'

API reference: Create an XRP Offer Cancel transaction

Remove an offer that the wallet placed on the decentralized exchange. offerSequence is required: it's the sequence number of the OfferCreate transaction that placed the offer, which is the sequence field of that transaction in Ripple Custody (Wallet).

curl -X POST "https://api.sandbox.palisade.co/v2/vaults/$VAULT_ID/wallets/$WALLET_ID/transactions/xrp/offer-cancel" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "offerSequence": "2"
  }'

API reference: Create an XRP SignerList Set transaction

Configure the list of accounts that can multi-sign for this wallet's XRPL account. signerQuorum (integer) is the minimum sum of signer weights that authorizes a transaction. The weights of all signers must add up to at least this value. List each signer in signerEntries with an account address and a signerWeight (integer); the signer account doesn't need to exist. To remove the signer list, set signerQuorum to 0 and leave signerEntries empty.

curl -X POST "https://api.sandbox.palisade.co/v2/vaults/$VAULT_ID/wallets/$WALLET_ID/transactions/xrp/signer-list-set" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "signerQuorum": 3,
    "signerEntries": [
      { "account": "rGgKM3hTn8MBMGgiiPMbz73VEkSBocqab6", "signerWeight": 2 },
      { "account": "rLsV52sRDL79HXGGm9yzwKibb6BeruhUzy", "signerWeight": 2 }
    ]
  }'

To sign as one of the signers on another account's multi-signed transaction, use raw signing with a multi-signing payload — see Transaction encoding formats: XRP Ledger.

API reference: Create an XRP AMM Create transaction

Create an AMM instance and fund its initial pool. amount (the first asset and amount to deposit), amount2 (the second asset and amount to deposit), and tradingFee are all required. tradingFee (integer) is the fee for trades against the AMM, in units of 1/100,000.

curl -X POST "https://api.sandbox.palisade.co/v2/vaults/$VAULT_ID/wallets/$WALLET_ID/transactions/xrp/amm-create" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": {
      "value": "1000",
      "asset": "XRP"
    },
    "amount2": {
      "value": "500",
      "asset": "USD",
      "issuer": "rGgKM3hTn8MBMGgiiPMbz73VEkSBocqab6"
    },
    "tradingFee": 1000
  }'

API reference: Create an XRP AMM Deposit transaction

Add liquidity to an existing AMM in exchange for its LP tokens. asset and asset2 are required: they identify the AMM's asset pair. You must also set amount, amount2, or both.

Optional fields:

• amount — the amount of the first asset to deposit.
• amount2 — the amount of the second asset to deposit. Not allowed with DEPOSIT_SINGLE_ASSET.
• ePrice — the maximum effective price, in the deposit asset, to pay for each LP token received.
• tradingFee (integer) — a vote for the AMM's trading fee, in units of 1/100,000.
• flags — a single deposit mode: DEPOSIT_SINGLE_ASSET, DEPOSIT_TWO_ASSET, DEPOSIT_LIMIT_LP_TOKEN, or DEPOSIT_TWO_ASSET_IF_EMPTY. Unlike trust-set and offer-create, this field is a string, not an array.

Ripple Custody (Wallet) rejects lpTokenOut and the DEPOSIT_LP_TOKEN and DEPOSIT_ONE_ASSET_LP_TOKEN modes, although they appear in the API reference.

curl -X POST "https://api.sandbox.palisade.co/v2/vaults/$VAULT_ID/wallets/$WALLET_ID/transactions/xrp/amm-deposit" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "asset": { "asset": "XRP" },
    "asset2": {
      "asset": "USD",
      "issuer": "rGgKM3hTn8MBMGgiiPMbz73VEkSBocqab6"
    },
    "amount": { "value": "100", "asset": "XRP" },
    "amount2": {
      "value": "50",
      "asset": "USD",
      "issuer": "rGgKM3hTn8MBMGgiiPMbz73VEkSBocqab6"
    },
    "flags": "DEPOSIT_TWO_ASSET"
  }'

API reference: Create an XRP AMM Withdraw transaction

Remove liquidity from an AMM by redeeming LP tokens. asset, asset2, lpTokenIn, and flags are required. asset and asset2 identify the AMM's asset pair, and lpTokenIn is how many of the AMM's LP tokens to redeem.

Ripple Custody (Wallet) accepts two withdrawal modes in flags (a string, not an array):

• WITHDRAW_LP_TOKEN — redeem lpTokenIn for both assets in proportion to the pool. Don't send amount.
• WITHDRAW_ONE_ASSET_LP_TOKEN — redeem lpTokenIn for a single asset. Set amount to the first asset and the amount to withdraw.

The other values in the flag enum aren't supported, and the request doesn't accept amount2 or ePrice.

curl -X POST "https://api.sandbox.palisade.co/v2/vaults/$VAULT_ID/wallets/$WALLET_ID/transactions/xrp/amm-withdraw" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "asset": { "asset": "XRP" },
    "asset2": {
      "asset": "USD",
      "issuer": "rGgKM3hTn8MBMGgiiPMbz73VEkSBocqab6"
    },
    "lpTokenIn": {
      "value": "25",
      "asset": "039C99CD9AB0B70B32ECDA51EAAE471625608EA2",
      "issuer": "rE54zDvgnghAoPopCgvtiqWNq3dU5y836S"
    },
    "flags": "WITHDRAW_LP_TOKEN"
  }'

API reference: Get a transaction

Each call returns a transaction object with HTTP 200 and a status of REQUESTED. The action field is PALISADE_MANAGED, and the transactionType field holds the XRPL transaction type, for example TrustSet. The response also includes the account sequence, the encodedTransaction signing payload, and the expected fee in proposedAssetChanges. qty is "0" for types that don't move an amount, such as trust-set, account-set, and offer-cancel. For an offer-create that sells XRP, qty is the XRP amount in takerGets, and proposedAssetChanges also lists both sides of the offer. When the offer isn't filled straight away, confirmedAssetChanges holds only the fee. For a trust line, destination is the issuer from limitAmount. Track the transaction to confirmation the same way as a transfer — see Track the transaction lifecycle.

• XRP Ledger transactions in the console — Create XRPL offers, trust lines, account settings, signer lists, and credential, vault, and loan transactions in the console
• Raw signing — Sign any XRPL transaction type, including multi-signing
• Ripple Custody (Wallet) API reference — Full request and response schemas