{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"iou.issue()","siteUrl":"https://opensource.ripple.com/","meta":[{"name":"google-site-verification","content":"bLwyBi1imklcIuQxZ7JeI_kRF5Mg7yfr6arpEQV2nsE"}],"llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]},"description":"IOU.issue bootstraps a new trust line-based IOU. It enables rippling, extends trust, and optionally distributes an opening amount to the hot wallet."},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"iouissue","__idx":0},"children":["iou.issue()"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://github.com/ripple/simpleXRPL/blob/95b977b15f8950c5bc076b25165217869c0b06d3/src/verticals/iou.ts#L101"},"children":["[Source]"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}," is given, the issuer distributes that amount to the hot wallet."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Omit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}," to set the trust line up only and distribute later with ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/simplexrpl/references/verticals/iou/transfer"},"children":["iou.transfer"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"sourcing-the-issuer-and-hot-wallet","__idx":1},"children":["Sourcing the issuer and hot wallet"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There are two ways to name the two accounts an issuance needs:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Pass ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["holder"]}]}," — a client-owned account, on any connector. The issuer comes from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["options.from"]}," (default: the primary signer). Both resolve through the client's signers, so either can be custody-held on ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/simplexrpl/references/connectors/ripple-custody"},"children":["Ripple Custody"]}," or ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/simplexrpl/references/connectors/palisade"},"children":["Palisade"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Omit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["holder"]}]}," — both accounts are bootstrapped from the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["XRPL_ISSUER_SEED"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["XRPL_HOT_WALLET_SEED"]}," environment seeds. This is the local dev flow."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"signature","__idx":2},"children":["Signature"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ts","header":{"controls":{"copy":{}}},"source":"iou.issue(\n  params: IOUIssueParams,\n  options?: IOUWriteOptions,\n): Promise<SubmissionResult<IOUIssueIntent>>\n","lang":"ts"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"parameters","__idx":3},"children":["Parameters"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ticker"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["holder"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["How much of the new IOU the issuer distributes to the hot wallet as a final step, as a decimal string. Must be ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["strictly positive"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'0'"]}," is rejected) with at most 15 significant digits. Omit to set the trust line up only."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"options","__idx":4},"children":["Options"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["options"]}," is an optional second argument that sets the source account and overrides the fee."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Option"},"children":["Option"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["from"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AccountSelector"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The account to act as — an r-address string, or an object ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ address }"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ signer, account? }"]},". Defaults to the primary signer's primary account. (For IOU operations, this is the issuer.)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fee"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FeeIntent"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fee override — a priority tier and/or a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["maxFeeDrops"]}," cap."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idempotencyKey"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A prior submission's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idempotencyKey"]},", to retry to the same intent instead of creating a duplicate. Auto-generated when omitted."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"returns","__idx":5},"children":["Returns"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Resolves to a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SubmissionResult<IOUIssueIntent>"]}," (from the final step)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every simpleXRPL write resolves to a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SubmissionResult<T>"]}," — a union tagged by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["source"]},", with the backend's raw response preserved verbatim. Its common fields are:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["intent"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["T"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The operation-specific output — see the operation's own return fields."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["source"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'xrpld' | 'custody' | 'palisade'"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Which backend produced the result; discriminates ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TxResponse"]}," | custody record | Palisade record"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The backend's raw response, preserved verbatim."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["txHash"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}," ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["(optional)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The XRPL transaction hash, once the transaction is on-ledger."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["intentId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}," ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["(optional)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The custodian intent id, when the path produced one. Hold onto this to resume via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client.intent"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idempotencyKey"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}," ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["(optional)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The UUIDv7 this submission carried. Pass it back as a later call's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idempotencyKey"]}," to retry to the same intent rather than creating a duplicate."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"return-fields","__idx":6},"children":["Return fields"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IOU.issue"]},", the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["intent"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IOUIssueIntent"]},") carries:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["iouID"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The currency code and issuer of the new IOU, e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USD.rIssuer..."]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}," ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["(optional)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The amount distributed to the hot wallet, or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["undefined"]}," when the issuance only set the trust line up."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"underlying-xrpl-transactors","__idx":7},"children":["Underlying XRPL transactors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Runs as an ordered, multi-step sequence (no rollback on partial failure):"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://xrpl.org/docs/references/protocol/transactions/types/accountset"},"children":["AccountSet"]}," — the issuer enables rippling (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["defaultRipple"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://xrpl.org/docs/references/protocol/transactions/types/trustset"},"children":["TrustSet"]}," — the hot wallet extends trust to the issuer, up to the maximum limit."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://xrpl.org/docs/references/protocol/transactions/types/payment"},"children":["Payment"]}," — ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["only when ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}," is given"]},". The issuer distributes that amount to the hot wallet. The distribution must follow the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TrustSet"]},": without the limit in place, the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Payment"]}," fails with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tecPATH_DRY"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Throws an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IntentValidationError"]}," if the environment-seed flow is used and the required seeds aren't set, or if ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}," is not a positive finite number. Throws a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/simplexrpl/references/verticals/iou/transfer"},"children":["iou.transfer"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"example","__idx":8},"children":["Example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ts","header":{"controls":{"copy":{}}},"source":"// Issue USD and put 1,000 into circulation on a custody-held hot wallet.\nconst { intent } = await client.iou.issue(\n  {\n    ticker: 'USD',\n    holder: 'rHotWallet...',\n    amount: '1000',\n  },\n  { from: 'rIssuer...' },\n)\n\nconsole.log(intent.iouID, intent.amount)\n","lang":"ts"},"children":[]}]},"headings":[{"value":"iou.issue()","id":"iouissue","depth":1},{"value":"Sourcing the issuer and hot wallet","id":"sourcing-the-issuer-and-hot-wallet","depth":2},{"value":"Signature","id":"signature","depth":2},{"value":"Parameters","id":"parameters","depth":2},{"value":"Options","id":"options","depth":2},{"value":"Returns","id":"returns","depth":2},{"value":"Return fields","id":"return-fields","depth":3},{"value":"Underlying XRPL transactors","id":"underlying-xrpl-transactors","depth":2},{"value":"Example","id":"example","depth":2}],"frontmatter":{"seo":{"description":"IOU.issue bootstraps a new trust line-based IOU. It enables rippling, extends trust, and optionally distributes an opening amount to the hot wallet.","title":"iou.issue()"},"labels":["simpleXRPL","SDK"]},"editPage":{"to":"https://github.com/ripple/opensource.ripple.com/tree/main/docs/simpleXRPL/references/verticals/iou/issue.md"},"lastModified":"2026-08-26T19:04:06.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/simplexrpl/references/verticals/iou/issue","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}