{"templateId":"markdown","versions":[{"version":"v1.39","label":"v1.39 STS","link":"/products/custody/accounts-and-assets/omnibus/manage-omnibus-api","default":true,"active":true,"folderId":"c15a2701"},{"version":"v1.38","label":"v1.38 STS","link":"/products/custody/v1.38/accounts-and-assets/omnibus/manage-omnibus-api","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.34","label":"v1.34 LTS","link":"/products/custody/v1.34/accounts-and-assets/omnibus/manage-omnibus-api","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.26","label":"v1.26 LTS","link":"/products/custody/v1.26/accounts-and-assets/omnibus/manage-omnibus-api","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.19","label":"v1.19 LTS","link":"/products/custody/v1.19/accounts-and-assets/omnibus/manage-omnibus-api","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.15","label":"v1.15 LTS","link":"/products/custody/v1.15/accounts-and-assets/omnibus/manage-omnibus-api","default":false,"active":false,"folderId":"c15a2701"}],"sharedDataIds":{"sidebar":"sidebar-products/custody/@v1.15/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Manage omnibus with the API","description":"User guides, API reference, and support resources.","siteUrl":"https://docs.ripple.com","lang":"en-US","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"manage-omnibus-with-the-api","__idx":0},"children":["Manage omnibus with the API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this page for Omnibus operations with the API. For console procedures, see"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/accounts-and-assets/omnibus/manage-omnibus-ui"},"children":["Manage an omnibus account in the UI"]},". For the"," ","conceptual model, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/accounts-and-assets/omnibus/overview"},"children":["Omnibus"]},". For domain, system-signed"," ","policy, and Gas Station setup, see"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/accounts-and-assets/omnibus/setup-and-governance"},"children":["Setup and governance"]},"."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"API naming"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The API uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tenantId"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/tenants"]}," for Omnibus virtual account resources."," ","In these docs, a virtual account is the Omnibus object that holds an off-chain"," ","position, and a tenant is the person or customer associated with that virtual"," ","account."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"omnibus-actions","__idx":1},"children":["Omnibus actions"]},{"$$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":"Action"},"children":["Action"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"API procedure"},"children":["API procedure"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Create an omnibus structure"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#create-an-omnibus-structure"},"children":["Create an omnibus structure"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["View omnibus details"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#view-omnibus-details"},"children":["View omnibus details"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Update the sponsoring Gas Station account"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#update-the-sponsoring-gas-station-account"},"children":["Update the sponsoring Gas Station account"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Create a virtual account"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#create-a-virtual-account"},"children":["Create a virtual account"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["List or view virtual accounts"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#list-or-view-virtual-accounts"},"children":["List or view virtual accounts"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Update a virtual account"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#update-a-virtual-account"},"children":["Update a virtual account"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Lock or unlock a virtual account"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#lock-or-unlock-a-virtual-account"},"children":["Lock or unlock a virtual account"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Create or view a deposit wallet"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#create-a-deposit-wallet"},"children":["Create a deposit wallet"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["List deposit wallets"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#list-deposit-wallets"},"children":["List deposit wallets"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Initiate a withdrawal"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#initiate-a-withdrawal"},"children":["Initiate a withdrawal"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Create or track internal transfers"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#create-and-track-internal-transfers"},"children":["Create and track internal transfers"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Set sweep thresholds"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#manage-sweep-thresholds"},"children":["Manage sweep thresholds"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Release quarantined deposits"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#release-quarantined-transfers"},"children":["Release quarantined transfers"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Review balances"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/accounts-and-assets/omnibus/balances-and-reconciliation"},"children":["Balances"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"api-reference-and-shared-process","__idx":2},"children":["API reference and shared process"]},{"$$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":"Task"},"children":["Task"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Reference"},"children":["Reference"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check the endpoint schema"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/reference/api/openapi/omnibus"},"children":["Omnibus"]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/reference/api/openapi/tenants"},"children":["tenants"]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/reference/api/openapi/deposits"},"children":["deposits"]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/reference/api/openapi/withdrawals"},"children":["withdrawals"]},", and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/reference/api/openapi/internal-transfers"},"children":["internal transfers"]}," in the API reference"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Submit a returned unsigned intent"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/governance/intents/manage-intents-and-approvals"},"children":["Manage intents and approvals"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Sign an API request payload"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/identity-and-access/authentication/authenticate-api-requests#signing-intents-state-mutation-operations"},"children":["Sign intents"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Configure Gas Station sponsorship"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/accounts-and-assets/gas-station/manage-gas-station-api"},"children":["Manage a gas station with the API"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Omnibus create and withdrawal requests return an unsigned Custody ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Propose"]}," ","intent. Sign the returned intent and submit it to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/intents"]}," in the"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["request"]}," field."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Deposit-wallet creation, deposit sweeps, and ledger propagation use Omnibus"," ","system-signed automation after the required ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SystemSigned"]}," policy is in place."," ","Other Omnibus management calls are direct Omnibus API calls and do not use the"," ","standard intent proposal endpoint."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Omnibus supports one omnibus structure per domain. If"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/domains/{domainId}/omnibus"]}," returns an existing structure, use its"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," field for management calls instead of creating another structure."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"create-an-omnibus-structure","__idx":3},"children":["Create an omnibus structure"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before creating an omnibus structure, complete the planning steps in"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/accounts-and-assets/omnibus/setup-and-governance"},"children":["Setup and governance"]},". Then call"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/domains/{domainId}/omnibus"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"sh","header":{"controls":{"copy":{}}},"source":"curl -X POST \"${CUSTODY_API_URL}/v1/domains/{domainId}/omnibus\" \\\n  -H \"Authorization: Bearer ${JWT_TOKEN}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"alias\": \"primary-omnibus\",\n    \"vaultId\": \"vault-uuid\",\n    \"keyStrategy\": \"Random\",\n    \"lockStatus\": \"Unlocked\",\n    \"ledgerIds\": [\"ledger-id\"],\n    \"description\": \"Primary omnibus structure\",\n    \"customProperties\": {\n      \"externalReference\": \"omnibus-001\"\n    },\n    \"ignoredAccountIds\": [\"gas-station-account-uuid\"],\n    \"sponsoringGasStationId\": \"gas-station-account-uuid\"\n  }'\n","lang":"sh"},"children":[]},{"$$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":"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":["alias"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Alias for the omnibus account."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vaultId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Vault that stores the omnibus account keys."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["keyStrategy"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Key strategy: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VaultHard"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VaultSoft"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Random"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lockStatus"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Initial lock status: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Unlocked"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Locked"]},". To lock or unlock the structure after creation, lock or unlock the omnibus wallet account with the core account operations. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/accounts-and-assets/accounts/manage-accounts-api#lock-or-unlock-an-account"},"children":["Lock or unlock an account"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ledgerIds"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ledgers to activate on the omnibus account. If omitted, Omnibus activates compatible enabled ledgers."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional account description."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customProperties"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Custom key-value properties for the omnibus account."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ignoredAccountIds"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Custody account IDs to ignore during event processing, such as a Gas Station account."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sponsoringGasStationId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Gas Station account used for supported non-native sweep gas funding."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before you set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sponsoringGasStationId"]},", confirm that the account has an active"," ","Gas Station sponsor configuration. A Gas Station configuration with"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type: \"none\""]}," disables sponsorship and does not make the account an active"," ","sponsor."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Successful create requests return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201 Created"]}," with the created ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["omnibus"]}," ","object and an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unsignedIntent"]},". Sign the returned Custody ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Propose"]}," intent and"," ","submit it to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/intents"]}," in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["request"]}," field. If an omnibus structure"," ","already exists for the domain, the API returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409 Conflict"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"view-omnibus-details","__idx":4},"children":["View omnibus details"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/domains/{domainId}/omnibus"]}," to get the omnibus structure for a"," ","domain:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"sh","header":{"controls":{"copy":{}}},"source":"curl -X GET \"${CUSTODY_API_URL}/v1/domains/{domainId}/omnibus\" \\\n  -H \"Authorization: Bearer ${JWT_TOKEN}\"\n","lang":"sh"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/domains/{domainId}/omnibus/{omnibusId}"]}," when you already know the"," ","omnibus ID:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"sh","header":{"controls":{"copy":{}}},"source":"curl -X GET \"${CUSTODY_API_URL}/v1/domains/{domainId}/omnibus/{omnibusId}\" \\\n  -H \"Authorization: Bearer ${JWT_TOKEN}\"\n","lang":"sh"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Omnibus structure status values are ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CREATING"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PENDING_SPONSORSHIP"]},","," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACTIVE"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]},". Responses also include a separate ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lockStatus"]}," field"," ","with values ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UNLOCKED"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LOCKED"]},"."," ","Responses can include host virtual account balances. For balance behavior, see"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/accounts-and-assets/omnibus/balances-and-reconciliation"},"children":["Balances"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"update-the-sponsoring-gas-station-account","__idx":5},"children":["Update the sponsoring Gas Station account"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT /v1/domains/{domainId}/omnibus/{omnibusId}"]}," to update the Gas Station"," ","account used for supported non-native sweep gas funding."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The current update request accepts ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sponsoringGasStationId"]},". It does not accept"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ignoredAccountIds"]},"; set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ignoredAccountIds"]}," when creating the omnibus structure"," ","and verify returned omnibus details after changing the sponsor account."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before updating ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sponsoringGasStationId"]},", confirm that the account has an active"," ","Gas Station sponsor configuration. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/domains/{domainId}/sponsors"]}," to"," ","list sponsor accounts and"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/domains/{domainId}/account/{accountId}/sponsor"]}," to inspect the sponsor"," ","account's configuration. A Gas Station configuration with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type: \"none\""]}," ","disables sponsorship and does not make the account an active sponsor."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"sh","header":{"controls":{"copy":{}}},"source":"curl -X PUT \"${CUSTODY_API_URL}/v1/domains/{domainId}/omnibus/{omnibusId}\" \\\n  -H \"Authorization: Bearer ${JWT_TOKEN}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"sponsoringGasStationId\": \"gas-station-account-uuid\"\n  }'\n","lang":"sh"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"create-a-virtual-account","__idx":6},"children":["Create a virtual account"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/domains/{domainId}/omnibus/{omnibusId}/tenants"]}," to create a"," ","virtual account for a tenant in an omnibus structure."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"sh","header":{"controls":{"copy":{}}},"source":"curl -X POST \"${CUSTODY_API_URL}/v1/domains/{domainId}/omnibus/{omnibusId}/tenants\" \\\n  -H \"Authorization: Bearer ${JWT_TOKEN}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"alias\": \"tenant-a-virtual-account\",\n    \"description\": \"Virtual account for Tenant A\",\n    \"status\": \"UNLOCKED\"\n  }'\n","lang":"sh"},"children":[]},{"$$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":"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":["alias"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Alias for the virtual account."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional description."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Virtual account status: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LOCKED"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UNLOCKED"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customProperties"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional custom key-value properties."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Successful create requests return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201 Created"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"list-or-view-virtual-accounts","__idx":7},"children":["List or view virtual accounts"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/domains/{domainId}/omnibus/{omnibusId}/tenants"]}," to list"," ","virtual accounts:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"sh","header":{"controls":{"copy":{}}},"source":"curl -X GET \"${CUSTODY_API_URL}/v1/domains/{domainId}/omnibus/{omnibusId}/tenants?page=0&size=20&status=UNLOCKED\" \\\n  -H \"Authorization: Bearer ${JWT_TOKEN}\"\n","lang":"sh"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The list endpoint supports ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["size"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["search"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," query"," ","parameters. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," to filter by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LOCKED"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UNLOCKED"]},". The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["search"]}," ","parameter performs a case-insensitive alias substring match. Search terms shorter"," ","than three characters return an empty page."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["List responses contain ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["content"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/domains/{domainId}/omnibus/{omnibusId}/tenants/{tenantId}"]}," to view"," ","one virtual account:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"sh","header":{"controls":{"copy":{}}},"source":"curl -X GET \"${CUSTODY_API_URL}/v1/domains/{domainId}/omnibus/{omnibusId}/tenants/{tenantId}\" \\\n  -H \"Authorization: Bearer ${JWT_TOKEN}\"\n","lang":"sh"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Virtual account responses include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["omnibusId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["alias"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["isHost"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]},","," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["createdAt"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["updatedAt"]},". They can also include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["balances"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]},","," ","and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customProperties"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"update-a-virtual-account","__idx":8},"children":["Update a virtual account"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT /v1/domains/{domainId}/omnibus/{omnibusId}/tenants/{tenantId}"]}," to"," ","replace mutable virtual account metadata."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"sh","header":{"controls":{"copy":{}}},"source":"curl -X PUT \"${CUSTODY_API_URL}/v1/domains/{domainId}/omnibus/{omnibusId}/tenants/{tenantId}\" \\\n  -H \"Authorization: Bearer ${JWT_TOKEN}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"alias\": \"tenant-a-virtual-account-updated\",\n    \"description\": \"Updated virtual account description\",\n    \"status\": \"UNLOCKED\"\n  }'\n","lang":"sh"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The request accepts the same fields as virtual account creation. Successful update"," ","requests return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200 OK"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"lock-or-unlock-a-virtual-account","__idx":9},"children":["Lock or unlock a virtual account"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/domains/{domainId}/omnibus/{omnibusId}/tenants/{tenantId}/lock"]}," to"," ","lock a virtual account."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Lock a virtual account to block new operations for the associated tenant:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"sh","header":{"controls":{"copy":{}}},"source":"curl -X POST \"${CUSTODY_API_URL}/v1/domains/{domainId}/omnibus/{omnibusId}/tenants/{tenantId}/lock\" \\\n  -H \"Authorization: Bearer ${JWT_TOKEN}\"\n","lang":"sh"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/domains/{domainId}/omnibus/{omnibusId}/tenants/{tenantId}/unlock"]}," ","to unlock a virtual account."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Unlock the virtual account when the associated tenant can resume normal operations:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"sh","header":{"controls":{"copy":{}}},"source":"curl -X POST \"${CUSTODY_API_URL}/v1/domains/{domainId}/omnibus/{omnibusId}/tenants/{tenantId}/unlock\" \\\n  -H \"Authorization: Bearer ${JWT_TOKEN}\"\n","lang":"sh"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Virtual account lock and unlock endpoints do not take a request body. Successful"," ","requests return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200 OK"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"list-deposit-wallets","__idx":10},"children":["List deposit wallets"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/domains/{domainId}/omnibus/{omnibusId}/deposit-wallets"]}," to list"," ","deposit wallets for an omnibus structure:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"sh","header":{"controls":{"copy":{}}},"source":"curl -X GET \"${CUSTODY_API_URL}/v1/domains/{domainId}/omnibus/{omnibusId}/deposit-wallets?page=0&size=20&search=tenant-a\" \\\n  -H \"Authorization: Bearer ${JWT_TOKEN}\"\n","lang":"sh"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The list endpoint supports ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["size"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["search"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["custodyAccountIds"]}," ","query parameters. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["custodyAccountIds"]}," to filter by one or more custody"," ","account IDs. List responses contain ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["content"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"create-a-deposit-wallet","__idx":11},"children":["Create a deposit wallet"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/reference/api/openapi/deposits/createdepositwallet"},"children":["POST ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/domains/{domainId}/omnibus/{omnibusId}/tenants/{tenantId}/deposit-wallet"]}]}," to create the deposit wallet for a virtual account on its first deposit request:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"sh","header":{"controls":{"copy":{}}},"source":"curl -X POST \"${CUSTODY_API_URL}/v1/domains/{domainId}/omnibus/{omnibusId}/tenants/{tenantId}/deposit-wallet\" \\\n  -H \"Authorization: Bearer ${JWT_TOKEN}\"\n","lang":"sh"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is a direct Omnibus API call — it does not return an unsigned intent. Behind it, Omnibus submits a system-signed ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v0_CreateAccount"]}," intent, so the required ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SystemSigned"]}," policy must be in place. A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201 Created"]}," response contains the wallet ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["addresses"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]}," on the same path to retrieve the deposit wallet's status and addresses later. Deposit-wallet creation has no console procedure: tenants trigger it through your integration. For the deposit lifecycle, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/accounts-and-assets/omnibus/deposits"},"children":["Deposits"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"initiate-a-withdrawal","__idx":12},"children":["Initiate a withdrawal"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/reference/api/openapi/withdrawals/createwithdrawal"},"children":["POST ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/domains/{domainId}/omnibus/{omnibusId}/tenants/{tenantId}/withdrawals"]}]}," to move funds from a virtual account to an external destination:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"sh","header":{"controls":{"copy":{}}},"source":"curl -X POST \"${CUSTODY_API_URL}/v1/domains/{domainId}/omnibus/{omnibusId}/tenants/{tenantId}/withdrawals\" \\\n  -H \"Authorization: Bearer ${JWT_TOKEN}\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: {client-chosen-key}\" \\\n  -d '{\n    \"amount\": \"1000000\",\n    \"tickerId\": \"ticker-uuid\",\n    \"ledgerId\": \"ledger-id\",\n    \"destAddress\": \"destination-address\"\n  }'\n","lang":"sh"},"children":[]},{"$$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":"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":["amount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Positive integer string in the ticker's smallest unit."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tickerId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ticker to withdraw."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ledgerId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Blockchain ledger to broadcast on."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["destAddress"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Destination address outside this omnibus."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The required ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Idempotency-Key"]}," header carries a client-chosen key that makes the withdrawal idempotent. Reuse the exact same value on every retry of the same withdrawal, and use a new value for each new withdrawal. Requests with a missing or blank key return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]},". Omnibus derives the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operationId"]}," deterministically from the key, so a retried request resolves to the original operation instead of creating a duplicate withdrawal."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Successful requests return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201 Created"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Fresh create"]},": the reservation is taken, and the response contains the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["withdrawal"]}," object and an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unsignedIntent"]},". Sign the returned Custody ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Propose"]}," intent and submit it to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/intents"]}," in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["request"]}," field."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Pending replay"]}," (same key, still in progress): the response contains the original operation and its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unsignedIntent"]},"; no new reservation is taken."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Terminal replay"]}," (the operation already reached ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CANCELLED"]},"): the response contains the operation status only, with no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unsignedIntent"]}," and no reservation."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The withdrawal object contains ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operationId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transferId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tickerId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ledgerId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["destAddress"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["createdAt"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["updatedAt"]},". It can also include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["estimatedFee"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["custodyTransactionOrderId"]},". Withdrawal status values are ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PENDING"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IN_PROGRESS"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CANCELLED"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For the withdrawal lifecycle, balance reservation, fee handling, and failure behavior, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/accounts-and-assets/omnibus/withdrawals"},"children":["Withdrawals"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"create-and-track-internal-transfers","__idx":13},"children":["Create and track internal transfers"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Internal transfers are asynchronous: Omnibus accepts the request, durably persists the operation, and returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["202 Accepted"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status: \"PENDING\""]}," immediately. Poll the operation for the terminal status."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/reference/api/openapi/internal-transfers/createinternaltransfer"},"children":["POST ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/domains/{domainId}/omnibus/{omnibusId}/tenants/{tenantId}/internal-transfers"]}]}," requires an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Idempotency-Key"]}," header and accepts:"]},{"$$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":"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":["destTenantId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Destination virtual account ID."]}]},{"$$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":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Positive integer string in the ticker's smallest unit."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tickerId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ticker to transfer."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ledgerId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ledger for the transfer."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Idempotency-Key"]}," header carries a client-chosen, per-transfer token, unique within the source tenant. Reuse the exact same value on every retry of the same transfer, and use a new value for each new transfer. Requests with a missing or blank key return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]},". Reusing a key with a different payload returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409"]},". Omnibus derives the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operationId"]}," deterministically from the key, so a retried request resolves to the same operation instead of creating a duplicate transfer."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Successful requests return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["202 Accepted"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operationId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transferId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status: \"PENDING\""]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sourceTenantId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["destTenantId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tickerId"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ledgerId"]},". When the workflow completes, the Accounting Service has recorded both sides of the movement in one double-entry operation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/reference/api/openapi/internal-transfers/getinternaltransfer"},"children":["GET ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/domains/{domainId}/omnibus/{omnibusId}/internal-transfers/{operationId}"]}]}," returns the current state of a transfer. Poll it after the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["202"]}," until the status is terminal (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETED"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]},") or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PENDING_VERIFICATION"]},". Reads are eventually consistent."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/reference/api/openapi/internal-transfers/getinternaltransfers"},"children":["GET ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/domains/{domainId}/omnibus/{omnibusId}/internal-transfers"]}]}," lists internal transfers for an omnibus structure. The list endpoint supports:"]},{"$$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":"Query parameter"},"children":["Query parameter"]},{"$$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":["page"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Page number."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["size"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Page size."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tenantId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Filter by source or destination virtual account."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["role"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Use with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tenantId"]}," to restrict the tenant filter to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SOURCE"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DEST"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Filter by one or more transfer statuses: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PENDING"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IN_PROGRESS"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CANCELLED"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PENDING_VERIFICATION"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tickerId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Filter by ticker."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ledgerIds"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Filter by one or more ledgers."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["createdAfter"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Include transfers created after this timestamp."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["createdBefore"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Include transfers created before this timestamp."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sort"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Sort expression."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["List responses contain ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["content"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For validation rules and the settlement model, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/accounts-and-assets/omnibus/internal-transfers"},"children":["Internal transfers"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"manage-sweep-thresholds","__idx":14},"children":["Manage sweep thresholds"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Sweep thresholds are keyed by ticker and ledger pair, expressed in the ticker's smallest unit. Assets without a configured threshold default to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"0\""]},", which sweeps immediately. For the threshold model, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/accounts-and-assets/omnibus/deposits#dust-thresholds"},"children":["Dust thresholds"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/reference/api/openapi/sweep-thresholds/getsweepthresholds"},"children":["GET ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/domains/{domainId}/sweep-thresholds"]}]}," lists the threshold for every asset in the ","Ripple Custody"," catalog, optionally filtered by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ledgerId"]},". Each configured row carries a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["version"]}," value for optimistic locking."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/reference/api/openapi/sweep-thresholds/updatesweepthresholds"},"children":["PUT ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/domains/{domainId}/sweep-thresholds"]}]}," upserts multiple thresholds in one transaction:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"sh","header":{"controls":{"copy":{}}},"source":"curl -X PUT \"${CUSTODY_API_URL}/v1/domains/{domainId}/sweep-thresholds\" \\\n  -H \"Authorization: Bearer ${JWT_TOKEN}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"updates\": [\n      {\n        \"tickerId\": \"ticker-uuid\",\n        \"ledgerId\": \"ledger-id\",\n        \"minSweepAmount\": \"1000000\",\n        \"version\": 3\n      }\n    ]\n  }'\n","lang":"sh"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Updates apply atomically: if any update fails, the API rolls back the entire request. To change an already-configured asset, send the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["version"]}," from the corresponding GET row; omit it when configuring an asset for the first time. If any submitted ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["version"]}," no longer matches the stored row, the whole request returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409"]}," and nothing is written."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"release-quarantined-transfers","__idx":15},"children":["Release quarantined transfers"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Omnibus does not sweep quarantined deposits. Release held transfers with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v0_ReleaseQuarantinedTransfers"]}," intent, or configure an ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/compliance/transaction-screening/automatic-quarantine-release-policy"},"children":["automatic quarantine release policy"]},". See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/transactions/send-and-receive/receive-assets-api"},"children":["Receive assets with the API"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"operational-notes","__idx":16},"children":["Operational notes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Omnibus workflows use stable identifiers for idempotency:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Custody event IDs for event-driven deposit and sweep operations."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Omnibus operation IDs for internal transfers."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Custody transaction order IDs for withdrawals."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The current Omnibus API exposes balances as fields on omnibus and virtual account"," ","responses rather than as standalone balance endpoints."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-topics","__idx":17},"children":["Related topics"]},{"$$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":"Topic"},"children":["Topic"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Documentation"},"children":["Documentation"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["UI procedures"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/accounts-and-assets/omnibus/manage-omnibus-ui"},"children":["Manage an omnibus account in the UI"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Setup and creation"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/accounts-and-assets/omnibus/setup-and-governance"},"children":["Setup and governance"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Deposit processing"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/accounts-and-assets/omnibus/deposits"},"children":["Deposits"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Withdrawal processing"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/accounts-and-assets/omnibus/withdrawals"},"children":["Withdrawals"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Intra-omnibus movement"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/accounts-and-assets/omnibus/internal-transfers"},"children":["Internal transfers"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Balance behavior"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/accounts-and-assets/omnibus/balances-and-reconciliation"},"children":["Balances"]}]}]}]}]}]}]},"headings":[{"value":"Manage omnibus with the API","id":"manage-omnibus-with-the-api","depth":1},{"value":"Omnibus actions","id":"omnibus-actions","depth":2},{"value":"API reference and shared process","id":"api-reference-and-shared-process","depth":2},{"value":"Create an omnibus structure","id":"create-an-omnibus-structure","depth":2},{"value":"View omnibus details","id":"view-omnibus-details","depth":2},{"value":"Update the sponsoring Gas Station account","id":"update-the-sponsoring-gas-station-account","depth":2},{"value":"Create a virtual account","id":"create-a-virtual-account","depth":2},{"value":"List or view virtual accounts","id":"list-or-view-virtual-accounts","depth":2},{"value":"Update a virtual account","id":"update-a-virtual-account","depth":2},{"value":"Lock or unlock a virtual account","id":"lock-or-unlock-a-virtual-account","depth":2},{"value":"List deposit wallets","id":"list-deposit-wallets","depth":2},{"value":"Create a deposit wallet","id":"create-a-deposit-wallet","depth":2},{"value":"Initiate a withdrawal","id":"initiate-a-withdrawal","depth":2},{"value":"Create and track internal transfers","id":"create-and-track-internal-transfers","depth":2},{"value":"Manage sweep thresholds","id":"manage-sweep-thresholds","depth":2},{"value":"Release quarantined transfers","id":"release-quarantined-transfers","depth":2},{"value":"Operational notes","id":"operational-notes","depth":2},{"value":"Related topics","id":"related-topics","depth":2}],"frontmatter":{"seo":{"title":"Manage omnibus with the API"}},"lastModified":"2026-08-04T20:25:11.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/custody/accounts-and-assets/omnibus/manage-omnibus-api","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}