Generate a new trust line-based IOU in one call: the issuer enables rippling, the hot wallet extends trust to the maximum limit, and if amount is given, the issuer distributes that amount to the hot wallet.
Omit amount to set the trust line up only and distribute later with iou.transfer.
There are two ways to name the two accounts an issuance needs:
- Pass
holder— a client-owned account, on any connector. The issuer comes fromoptions.from(default: the primary signer). Both resolve through the client's signers, so either can be custody-held on Ripple Custody or Palisade. - Omit
holder— both accounts are bootstrapped from theXRPL_ISSUER_SEEDandXRPL_HOT_WALLET_SEEDenvironment seeds. This is the local dev flow.
iou.issue(
params: IOUIssueParams,
options?: IOUWriteOptions,
): Promise<SubmissionResult<IOUIssueIntent>>| Parameter | Type | Required | Description |
|---|---|---|---|
ticker | string | Yes | The currency code: a 3-character ISO-4217-style code or a 40-character hex code. Any other code (e.g., a 5-character ticker) is auto-encoded to the 40-character hex form. |
holder | string | No | The hot-wallet (holder) r-address that extends trust to the issuer — a client-owned account on any connector. Omit to bootstrap both accounts from the environment seeds. |
amount | string | No | How much of the new IOU the issuer distributes to the hot wallet as a final step, as a decimal string. Must be strictly positive ('0' is rejected) with at most 15 significant digits. Omit to set the trust line up only. |
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<IOUIssueIntent> (from the final step).
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. |
For IOU.issue, the intent (IOUIssueIntent) carries:
| Field | Type | Description |
|---|---|---|
iouID | string | The currency code and issuer of the new IOU, e.g. USD.rIssuer.... |
amount | string (optional) | The amount distributed to the hot wallet, or undefined when the issuance only set the trust line up. |
Runs as an ordered, multi-step sequence (no rollback on partial failure):
- AccountSet — the issuer enables rippling (
defaultRipple). - TrustSet — the hot wallet extends trust to the issuer, up to the maximum limit.
- Payment — only when
amountis given. The issuer distributes that amount to the hot wallet. The distribution must follow theTrustSet: without the limit in place, thePaymentfails withtecPATH_DRY.
Throws an IntentValidationError if the environment-seed flow is used and the required seeds aren't set, or if amount is not a positive finite number. Throws a MultiStepFailureError if any step fails, carrying the steps that already committed — a distribution failure leaves the trust line in place, so it can be retried with iou.transfer.
// Issue USD and put 1,000 into circulation on a custody-held hot wallet.
const { intent } = await client.iou.issue(
{
ticker: 'USD',
holder: 'rHotWallet...',
amount: '1000',
},
{ from: 'rIssuer...' },
)
console.log(intent.iouID, intent.amount)