> For the complete documentation index, see [llms.txt](https://docs.ur.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ur.app/api-reference/api/account/managed-custody-mode.md).

# Managed Custody Mode

Server-to-server APIs where UR custodies user funds. Partner Auth (EIP-191) with user identity headers.

## Get BR profile

> Fetch the user's banking profile, including IBAN, fiat limits, contacts, deposit bank details, and card eligibility. Limits are denominated in CHF over a rolling 30-day window. The EUR/CHF IBAN receives EUR and CHF deposits only; a USD IBAN is provisioned separately via POST /v1/apply-usd-payin and then appears under the USD key of depositBank.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"Managed Custody Mode","description":"Server-to-server APIs where UR custodies user funds. Partner Auth (EIP-191) with user identity headers."}],"servers":[{"url":"https://openapi.ur.app","description":"Production (partner API)"},{"url":"https://uropenapi-qa.ur-inc.xyz","description":"Testnet (partner API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"Partner Auth: EIP-191 signature by the partner's registered backend key, with X-Api-Deadline and optional X-Api-PublicKey headers. See the Signature and verify guide."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"McBrResponse":{"allOf":[{"$ref":"#/components/schemas/McBaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/McBrProfile"}}}]},"McBaseResponse":{"type":"object","description":"Standard UR OpenAPI response envelope. code 0 means success; a non-zero code is a business error described by message.","required":["code","message"],"properties":{"code":{"type":"integer","description":"0 on success; non-zero business error code."},"message":{"type":"string","description":"Human-readable explanation. May be empty on success."}}},"McBrProfile":{"type":"object","properties":{"tokenId":{"type":"integer","description":"The user's URID token ID."},"br":{"type":"string","description":"Beneficiary name."},"iban":{"type":"string","description":"The user's default personal Swiss IBAN. Receives EUR and CHF deposits; it does not receive USD."},"email":{"type":"string"},"mobile":{"type":"string"},"debitCard":{"type":"string","description":"Debit card type."},"isCardEligible":{"type":"boolean","description":"Whether the user is eligible for card creation."},"cards":{"type":"array","items":{"type":"string"},"description":"List of existing cards."},"cardActivation":{"$ref":"#/components/schemas/McCardActivation"},"street":{"type":"string"},"postalCode":{"type":"string"},"city":{"type":"string"},"country":{"type":"string","description":"Country code (ISO 3166 alpha-3)."},"limits":{"$ref":"#/components/schemas/McFiatLimits"},"contacts":{"type":"object","description":"Recent payout contacts, keyed by currency.","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/McBrContact"}}},"depositBank":{"type":"object","description":"Deposit bank details, keyed by currency. The USD entry appears only after the USD IBAN is provisioned.","additionalProperties":{"$ref":"#/components/schemas/McDepositBank"}}}},"McCardActivation":{"type":"object","description":"Minimum balance required to activate a card.","properties":{"amount":{"type":"number","description":"Required activation amount."},"currency":{"type":"string","description":"Currency of the activation amount."}}},"McFiatLimits":{"type":"object","description":"Rolling 30-day fiat limits, denominated in CHF. FX, card spending, on-ramp, and payout share this bucket.","properties":{"restartDate":{"type":"string","description":"Date when the rolling window restarts."},"restartDateMs":{"type":"integer","description":"Restart timestamp in milliseconds."},"used":{"type":"number","description":"Used allowance in CHF."},"available":{"type":"number","description":"Remaining allowance in CHF. A single outgoing transaction must not exceed this value."},"max":{"type":"number","description":"Maximum allowance in CHF."}}},"McBrContact":{"type":"object","description":"A recent payout contact.","properties":{"id":{"type":"string","description":"Contact ID. Use it as contactId in the payout submission."},"name":{"type":"string","description":"Contact name."},"account":{"type":"string","description":"Masked account number."},"fullAccount":{"type":"string","description":"Full account number or IBAN."},"bank":{"type":"string","description":"Bank name."},"country":{"type":"string","description":"Country code."},"lastPaymentDate":{"type":"integer","description":"Last payment timestamp in milliseconds."}}},"McDepositBank":{"type":"object","description":"Deposit bank account details for one currency. Show the entry that matches the deposit currency to the user.","properties":{"account":{"type":"string","description":"Deposit account number or IBAN."},"bank":{"type":"string","description":"Bank name."},"BIC":{"type":"string","description":"Bank BIC."},"payee":{"type":"string","description":"Payee name."},"city":{"type":"string"},"street":{"type":"string"},"postalCode":{"type":"string"},"country":{"type":"string"}}}}},"paths":{"/api/fma/v1/br":{"get":{"tags":["Managed Custody Mode"],"operationId":"mcGetBrProfile","summary":"Get BR profile","description":"Fetch the user's banking profile, including IBAN, fiat limits, contacts, deposit bank details, and card eligibility. Limits are denominated in CHF over a rolling 30-day window. The EUR/CHF IBAN receives EUR and CHF deposits only; a USD IBAN is provisioned separately via POST /v1/apply-usd-payin and then appears under the USD key of depositBank.","parameters":[{"name":"X-Api-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed 65-byte hex EIP-191 signature over the Partner Auth message. See the Signature and verify guide."},{"name":"X-Api-Deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds. UR rejects the request when the current time is past the deadline. Keep the validity window at or under 5 minutes."},{"name":"X-Api-PublicKey","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed partner signer address registered with UR."},{"name":"X-Ur-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."},{"name":"X-External-User-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."}],"responses":{"200":{"description":"Standard envelope. Business errors return HTTP 200 with a non-zero code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McBrResponse"}}}}}}}}}
```

## Get user balance

> Fetch the user's tokenized fiat balances held inside the UR-managed account. The endpoint returns fiat only; the UR-managed account never custodies crypto.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"Managed Custody Mode","description":"Server-to-server APIs where UR custodies user funds. Partner Auth (EIP-191) with user identity headers."}],"servers":[{"url":"https://openapi.ur.app","description":"Production (partner API)"},{"url":"https://uropenapi-qa.ur-inc.xyz","description":"Testnet (partner API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"Partner Auth: EIP-191 signature by the partner's registered backend key, with X-Api-Deadline and optional X-Api-PublicKey headers. See the Signature and verify guide."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"McBalanceResponse":{"allOf":[{"$ref":"#/components/schemas/McBaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/McBalanceData"}}}]},"McBaseResponse":{"type":"object","description":"Standard UR OpenAPI response envelope. code 0 means success; a non-zero code is a business error described by message.","required":["code","message"],"properties":{"code":{"type":"integer","description":"0 on success; non-zero business error code."},"message":{"type":"string","description":"Human-readable explanation. May be empty on success."}}},"McBalanceData":{"type":"object","properties":{"fiatItems":{"type":"array","description":"The user's tokenized fiat balances on Mantle (EUR24, CHF24, USD24, etc.).","items":{"$ref":"#/components/schemas/McFiatBalance"}}}},"McFiatBalance":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string","description":"Fiat currency symbol."},"amount":{"type":"string","description":"Balance as a decimal string."}}}}},"paths":{"/api/fma/v1/balance":{"get":{"tags":["Managed Custody Mode"],"operationId":"mcGetBalance","summary":"Get user balance","description":"Fetch the user's tokenized fiat balances held inside the UR-managed account. The endpoint returns fiat only; the UR-managed account never custodies crypto.","parameters":[{"name":"X-Api-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed 65-byte hex EIP-191 signature over the Partner Auth message. See the Signature and verify guide."},{"name":"X-Api-Deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds. UR rejects the request when the current time is past the deadline. Keep the validity window at or under 5 minutes."},{"name":"X-Api-PublicKey","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed partner signer address registered with UR."},{"name":"X-Ur-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."},{"name":"X-External-User-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."}],"responses":{"200":{"description":"Standard envelope. Business errors return HTTP 200 with a non-zero code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McBalanceResponse"}}}}}}}}}
```

## Get account status

> Read the user's UR Account status. Use it as a polling fallback after onboarding submission (1-minute cadence) or as an explicit confirmation before enabling fund-moving features; stop polling when statusStr is Live, Blocked, or Closed. The fma.account.result webhook reports final activation.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"Managed Custody Mode","description":"Server-to-server APIs where UR custodies user funds. Partner Auth (EIP-191) with user identity headers."}],"servers":[{"url":"https://openapi.ur.app","description":"Production (partner API)"},{"url":"https://uropenapi-qa.ur-inc.xyz","description":"Testnet (partner API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"Partner Auth: EIP-191 signature by the partner's registered backend key, with X-Api-Deadline and optional X-Api-PublicKey headers. See the Signature and verify guide."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"McAccountStatusResponse":{"allOf":[{"$ref":"#/components/schemas/McBaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/McAccountStatusData"}}}]},"McBaseResponse":{"type":"object","description":"Standard UR OpenAPI response envelope. code 0 means success; a non-zero code is a business error described by message.","required":["code","message"],"properties":{"code":{"type":"integer","description":"0 on success; non-zero business error code."},"message":{"type":"string","description":"Human-readable explanation. May be empty on success."}}},"McAccountStatusData":{"type":"object","properties":{"status":{"type":"integer","description":"Numeric account status code."},"statusStr":{"type":"string","description":"Account status string, for example Live, Blocked, or Closed."}}}}},"paths":{"/api/fma/v1/account-status":{"get":{"tags":["Managed Custody Mode"],"operationId":"mcGetAccountStatus","summary":"Get account status","description":"Read the user's UR Account status. Use it as a polling fallback after onboarding submission (1-minute cadence) or as an explicit confirmation before enabling fund-moving features; stop polling when statusStr is Live, Blocked, or Closed. The fma.account.result webhook reports final activation.","parameters":[{"name":"X-Api-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed 65-byte hex EIP-191 signature over the Partner Auth message. See the Signature and verify guide."},{"name":"X-Api-Deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds. UR rejects the request when the current time is past the deadline. Keep the validity window at or under 5 minutes."},{"name":"X-Api-PublicKey","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed partner signer address registered with UR."},{"name":"X-Ur-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."},{"name":"X-External-User-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."}],"responses":{"200":{"description":"Standard envelope. Business errors return HTTP 200 with a non-zero code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McAccountStatusResponse"}}}}}}}}}
```

## Apply for a USD IBAN

> Request a USD deposit IBAN for a Live user. The call is synchronous; UR creates the USD IBAN immediately and it then appears under the USD key of depositBank in the BR profile. The user is identified by urId in the request body.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"Managed Custody Mode","description":"Server-to-server APIs where UR custodies user funds. Partner Auth (EIP-191) with user identity headers."}],"servers":[{"url":"https://openapi.ur.app","description":"Production (partner API)"},{"url":"https://uropenapi-qa.ur-inc.xyz","description":"Testnet (partner API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"Partner Auth: EIP-191 signature by the partner's registered backend key, with X-Api-Deadline and optional X-Api-PublicKey headers. See the Signature and verify guide."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"McApplyUsdPayinRequest":{"type":"object","required":["urId","remark"],"properties":{"urId":{"type":"integer","description":"The user's URID (numeric token ID of the URID NFT)."},"remark":{"type":"string","description":"Free-text remark for the USD IBAN application."}}},"McApplyUsdPayinResponse":{"allOf":[{"$ref":"#/components/schemas/McBaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/McApplyUsdPayinData"}}}]},"McBaseResponse":{"type":"object","description":"Standard UR OpenAPI response envelope. code 0 means success; a non-zero code is a business error described by message.","required":["code","message"],"properties":{"code":{"type":"integer","description":"0 on success; non-zero business error code."},"message":{"type":"string","description":"Human-readable explanation. May be empty on success."}}},"McApplyUsdPayinData":{"type":"object","properties":{"applyId":{"type":"integer","description":"Identifier of the USD IBAN application."}}}}},"paths":{"/v1/apply-usd-payin":{"post":{"tags":["Managed Custody Mode"],"operationId":"mcApplyUsdPayin","summary":"Apply for a USD IBAN","description":"Request a USD deposit IBAN for a Live user. The call is synchronous; UR creates the USD IBAN immediately and it then appears under the USD key of depositBank in the BR profile. The user is identified by urId in the request body.","parameters":[{"name":"X-Api-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed 65-byte hex EIP-191 signature over the Partner Auth message. See the Signature and verify guide."},{"name":"X-Api-Deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds. UR rejects the request when the current time is past the deadline. Keep the validity window at or under 5 minutes."},{"name":"X-Api-PublicKey","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed partner signer address registered with UR."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McApplyUsdPayinRequest"}}}},"responses":{"200":{"description":"Standard envelope. Business errors return HTTP 200 with a non-zero code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McApplyUsdPayinResponse"}}}}}}}}}
```

## Get off-ramp quote

> Request an Off-ramp quote for converting crypto on a supported source chain into the user's tokenized fiat. Pass best.to, best.swapCalldata, and best.minUsdcAmount to the Off-ramp contract exactly as returned, and submit before best.deadline. Final settlement is reported asynchronously through the transaction webhook with data.type CRYPTO\_DEPOSIT.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"Managed Custody Mode","description":"Server-to-server APIs where UR custodies user funds. Partner Auth (EIP-191) with user identity headers."}],"servers":[{"url":"https://openapi.ur.app","description":"Production (partner API)"},{"url":"https://uropenapi-qa.ur-inc.xyz","description":"Testnet (partner API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"Partner Auth: EIP-191 signature by the partner's registered backend key, with X-Api-Deadline and optional X-Api-PublicKey headers. See the Signature and verify guide."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"McOfframpQuoteRequest":{"type":"object","required":["chainId","fromToken","toCurrency","amount"],"properties":{"chainId":{"type":"string","description":"Source chain ID in CAIP-2 format. See Supported Chains and Tokens."},"fromToken":{"type":"string","description":"Source crypto token contract address."},"toCurrency":{"type":"string","description":"Target fiat currency symbol (USD, EUR, CHF, SGD, JPY, HKD)."},"amount":{"type":"string","description":"Human-readable decimal string. UR converts it to token smallest units using the source token decimals."}}},"McOfframpQuoteResponse":{"allOf":[{"$ref":"#/components/schemas/McBaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/McOfframpQuoteData"}}}]},"McBaseResponse":{"type":"object","description":"Standard UR OpenAPI response envelope. code 0 means success; a non-zero code is a business error described by message.","required":["code","message"],"properties":{"code":{"type":"integer","description":"0 on success; non-zero business error code."},"message":{"type":"string","description":"Human-readable explanation. May be empty on success."}}},"McOfframpQuoteData":{"type":"object","properties":{"quoteId":{"type":"string","description":"Quote identifier."},"chainId":{"type":"string","description":"Source chain ID in CAIP-2 format."},"targetAccount":{"type":"string","description":"The user's UR Account address. Use as the _targetAccount contract parameter so the resulting fiat is credited to the user."},"best":{"$ref":"#/components/schemas/McOfframpQuoteBest"},"inputAmount":{"type":"string","description":"Input amount echoed from the request."},"outputAmount":{"type":"string","description":"Estimated fiat output amount."},"exchangeRate":{"type":"string","description":"Applied exchange rate."},"crossChainFee":{"type":"string","description":"Cross-chain fee in the source chain's native token, paid by the user in addition to the amount."},"networkFee":{"type":"string","description":"Network fee in the source chain's native token, paid by the user in addition to the amount."},"amountReceived":{"type":"string","description":"Tempo chain only: actual USDC amount received on Arbitrum, in smallest units."},"processingFee":{"type":"string","description":"Processing fee."}}},"McOfframpQuoteBest":{"type":"object","description":"Best aggregator route. Pass to, swapCalldata, and minUsdcAmount to the Off-ramp contract exactly as returned.","properties":{"aggregator":{"type":"string","description":"Aggregator name."},"to":{"type":"string","description":"Aggregator contract address. Use as the _aggregator contract parameter."},"swapCalldata":{"type":"string","description":"Swap calldata. Use as the _swapCalldata contract parameter."},"minUsdcAmount":{"type":"string","description":"Minimum USDC amount in smallest units. Use as the _minUsdcAmount contract parameter."},"expectedUsdcAmount":{"type":"string","description":"Expected USDC amount in smallest units."},"slippageBps":{"type":"integer","description":"Applied slippage in basis points."},"deadline":{"type":"integer","description":"Unix seconds. Submit the contract transaction before this deadline; otherwise it can revert."},"priceImpact":{"type":"string","description":"Estimated price impact."}}}}},"paths":{"/api/fma/v1/quote/deposit":{"post":{"tags":["Managed Custody Mode"],"operationId":"mcGetOfframpQuote","summary":"Get off-ramp quote","description":"Request an Off-ramp quote for converting crypto on a supported source chain into the user's tokenized fiat. Pass best.to, best.swapCalldata, and best.minUsdcAmount to the Off-ramp contract exactly as returned, and submit before best.deadline. Final settlement is reported asynchronously through the transaction webhook with data.type CRYPTO_DEPOSIT.","parameters":[{"name":"X-Api-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed 65-byte hex EIP-191 signature over the Partner Auth message. See the Signature and verify guide."},{"name":"X-Api-Deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds. UR rejects the request when the current time is past the deadline. Keep the validity window at or under 5 minutes."},{"name":"X-Api-PublicKey","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed partner signer address registered with UR."},{"name":"X-Ur-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."},{"name":"X-External-User-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McOfframpQuoteRequest"}}}},"responses":{"200":{"description":"Standard envelope. Business errors return HTTP 200 with a non-zero code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McOfframpQuoteResponse"}}}}}}}}}
```

## Get FX quote

> Quote a conversion between two tokenized fiat balances held inside the user's UR account. Read the minimum and maximum FX amounts from the chain config at request time; do not hardcode them.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"Managed Custody Mode","description":"Server-to-server APIs where UR custodies user funds. Partner Auth (EIP-191) with user identity headers."}],"servers":[{"url":"https://openapi.ur.app","description":"Production (partner API)"},{"url":"https://uropenapi-qa.ur-inc.xyz","description":"Testnet (partner API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"Partner Auth: EIP-191 signature by the partner's registered backend key, with X-Api-Deadline and optional X-Api-PublicKey headers. See the Signature and verify guide."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"McFxQuoteRequest":{"type":"object","required":["fromCurrency","toCurrency","inputAmount"],"properties":{"fromCurrency":{"type":"string","description":"Input fiat currency symbol."},"toCurrency":{"type":"string","description":"Output fiat currency symbol."},"inputAmount":{"type":"string","description":"Input amount as a human-readable decimal string."}}},"McFxQuoteResponse":{"allOf":[{"$ref":"#/components/schemas/McBaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/McFxQuoteData"}}}]},"McBaseResponse":{"type":"object","description":"Standard UR OpenAPI response envelope. code 0 means success; a non-zero code is a business error described by message.","required":["code","message"],"properties":{"code":{"type":"integer","description":"0 on success; non-zero business error code."},"message":{"type":"string","description":"Human-readable explanation. May be empty on success."}}},"McFxQuoteData":{"type":"object","properties":{"inputAmount":{"type":"string","description":"Input amount echoed from the request."},"fromCurrency":{"type":"string"},"toCurrency":{"type":"string"},"outputAmount":{"type":"string","description":"Quoted output amount."},"exchangeRate":{"type":"string","description":"Quoted exchange rate."}}}}},"paths":{"/api/fma/v1/quote/fx":{"post":{"tags":["Managed Custody Mode"],"operationId":"mcGetFxQuote","summary":"Get FX quote","description":"Quote a conversion between two tokenized fiat balances held inside the user's UR account. Read the minimum and maximum FX amounts from the chain config at request time; do not hardcode them.","parameters":[{"name":"X-Api-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed 65-byte hex EIP-191 signature over the Partner Auth message. See the Signature and verify guide."},{"name":"X-Api-Deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds. UR rejects the request when the current time is past the deadline. Keep the validity window at or under 5 minutes."},{"name":"X-Api-PublicKey","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed partner signer address registered with UR."},{"name":"X-Ur-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."},{"name":"X-External-User-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McFxQuoteRequest"}}}},"responses":{"200":{"description":"Standard envelope. Business errors return HTTP 200 with a non-zero code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McFxQuoteResponse"}}}}}}}}}
```

## Execute FX

> Convert one tokenized fiat balance into another inside the user's UR account. Requires a Live UR account; FX counts against the user's rolling 30-day CHF-denominated fiat limit. The response returns only a txHash; the transaction webhook with data.type FRX reports final settlement.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"Managed Custody Mode","description":"Server-to-server APIs where UR custodies user funds. Partner Auth (EIP-191) with user identity headers."}],"servers":[{"url":"https://openapi.ur.app","description":"Production (partner API)"},{"url":"https://uropenapi-qa.ur-inc.xyz","description":"Testnet (partner API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"Partner Auth: EIP-191 signature by the partner's registered backend key, with X-Api-Deadline and optional X-Api-PublicKey headers. See the Signature and verify guide."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"McFxExchangeRequest":{"type":"object","required":["reqId","fromCurrency","toCurrency","amount"],"properties":{"reqId":{"type":"string","description":"Partner-supplied idempotency key. Keep it stable across retries of the same logical operation."},"fromCurrency":{"type":"string","description":"Input fiat currency symbol."},"toCurrency":{"type":"string","description":"Output fiat currency symbol."},"amount":{"type":"string","description":"Amount to convert, as a human-readable decimal string."},"amountOutMinimum":{"type":"string","description":"Slippage protection lower bound. If omitted, UR applies a default 0.5% slippage buffer based on the submitted amount."}}},"McTxHashResponse":{"allOf":[{"$ref":"#/components/schemas/McBaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/McTxHashData"}}}]},"McBaseResponse":{"type":"object","description":"Standard UR OpenAPI response envelope. code 0 means success; a non-zero code is a business error described by message.","required":["code","message"],"properties":{"code":{"type":"integer","description":"0 on success; non-zero business error code."},"message":{"type":"string","description":"Human-readable explanation. May be empty on success."}}},"McTxHashData":{"type":"object","properties":{"txHash":{"type":"string","description":"On-chain transaction hash of the submitted operation. Submission only; final settlement arrives via the transaction webhook."}}}}},"paths":{"/api/fma/v1/fx-exchange":{"post":{"tags":["Managed Custody Mode"],"operationId":"mcExecuteFx","summary":"Execute FX","description":"Convert one tokenized fiat balance into another inside the user's UR account. Requires a Live UR account; FX counts against the user's rolling 30-day CHF-denominated fiat limit. The response returns only a txHash; the transaction webhook with data.type FRX reports final settlement.","parameters":[{"name":"X-Api-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed 65-byte hex EIP-191 signature over the Partner Auth message. See the Signature and verify guide."},{"name":"X-Api-Deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds. UR rejects the request when the current time is past the deadline. Keep the validity window at or under 5 minutes."},{"name":"X-Api-PublicKey","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed partner signer address registered with UR."},{"name":"X-Ur-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."},{"name":"X-External-User-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McFxExchangeRequest"}}}},"responses":{"200":{"description":"Standard envelope. Business errors return HTTP 200 with a non-zero code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McTxHashResponse"}}}}}}}}}
```

## Get payout fees

> Fetch per-currency payout fee configuration, including the minimum payout amount and fiat token address. Public metadata; no authentication required.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"Managed Custody Mode","description":"Server-to-server APIs where UR custodies user funds. Partner Auth (EIP-191) with user identity headers."}],"servers":[{"url":"https://openapi.ur.app","description":"Production (partner API)"},{"url":"https://uropenapi-qa.ur-inc.xyz","description":"Testnet (partner API)"}],"security":[],"paths":{"/api/v1/banks/payout/fees":{"get":{"tags":["Managed Custody Mode"],"operationId":"mcGetPayoutFees","summary":"Get payout fees","description":"Fetch per-currency payout fee configuration, including the minimum payout amount and fiat token address. Public metadata; no authentication required.","responses":{"200":{"description":"Standard envelope keyed by currency.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McPayoutFeesResponse"}}}}}}}},"components":{"schemas":{"McPayoutFeesResponse":{"allOf":[{"$ref":"#/components/schemas/McBaseResponse"},{"type":"object","properties":{"data":{"type":"object","description":"Payout fee configuration, keyed by currency.","additionalProperties":{"$ref":"#/components/schemas/McPayoutFeeItem"}}}}]},"McBaseResponse":{"type":"object","description":"Standard UR OpenAPI response envelope. code 0 means success; a non-zero code is a business error described by message.","required":["code","message"],"properties":{"code":{"type":"integer","description":"0 on success; non-zero business error code."},"message":{"type":"string","description":"Human-readable explanation. May be empty on success."}}},"McPayoutFeeItem":{"type":"object","properties":{"tokenAddress":{"type":"string","description":"Fiat token contract address on Mantle."},"currency":{"type":"string","description":"Fiat currency symbol."},"fee":{"type":"string","description":"Payout fee. Deducted from the payout amount, not charged separately."},"minimalPayoutAmount":{"type":"string","description":"Minimum payout amount for this currency."}}}}}}
```

## List banks

> List recipient banks for payout contact creation, including banks in non-IBAN countries. Public metadata; no authentication required.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"Managed Custody Mode","description":"Server-to-server APIs where UR custodies user funds. Partner Auth (EIP-191) with user identity headers."}],"servers":[{"url":"https://openapi.ur.app","description":"Production (partner API)"},{"url":"https://uropenapi-qa.ur-inc.xyz","description":"Testnet (partner API)"}],"security":[],"paths":{"/api/v1/banks":{"get":{"tags":["Managed Custody Mode"],"operationId":"mcListBanks","summary":"List banks","description":"List recipient banks for payout contact creation, including banks in non-IBAN countries. Public metadata; no authentication required.","responses":{"200":{"description":"Standard envelope. data carries the bank list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McPublicMetadataResponse"}}}}}}}},"components":{"schemas":{"McPublicMetadataResponse":{"allOf":[{"$ref":"#/components/schemas/McBaseResponse"},{"type":"object","properties":{"data":{"description":"Endpoint-specific metadata payload."}}}]},"McBaseResponse":{"type":"object","description":"Standard UR OpenAPI response envelope. code 0 means success; a non-zero code is a business error described by message.","required":["code","message"],"properties":{"code":{"type":"integer","description":"0 on success; non-zero business error code."},"message":{"type":"string","description":"Human-readable explanation. May be empty on success."}}}}}}
```

## Get bank by IBAN

> Resolve the recipient bank from an IBAN when creating a payout contact for a country that supports IBAN. Public metadata; no authentication required.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"Managed Custody Mode","description":"Server-to-server APIs where UR custodies user funds. Partner Auth (EIP-191) with user identity headers."}],"servers":[{"url":"https://openapi.ur.app","description":"Production (partner API)"},{"url":"https://uropenapi-qa.ur-inc.xyz","description":"Testnet (partner API)"}],"security":[],"paths":{"/api/v1/banks/iban/{ibanNo}":{"get":{"tags":["Managed Custody Mode"],"operationId":"mcGetBankByIban","summary":"Get bank by IBAN","description":"Resolve the recipient bank from an IBAN when creating a payout contact for a country that supports IBAN. Public metadata; no authentication required.","parameters":[{"name":"ibanNo","in":"path","required":true,"schema":{"type":"string"},"description":"The recipient IBAN to resolve."}],"responses":{"200":{"description":"Standard envelope. data carries the resolved bank details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McPublicMetadataResponse"}}}}}}}},"components":{"schemas":{"McPublicMetadataResponse":{"allOf":[{"$ref":"#/components/schemas/McBaseResponse"},{"type":"object","properties":{"data":{"description":"Endpoint-specific metadata payload."}}}]},"McBaseResponse":{"type":"object","description":"Standard UR OpenAPI response envelope. code 0 means success; a non-zero code is a business error described by message.","required":["code","message"],"properties":{"code":{"type":"integer","description":"0 on success; non-zero business error code."},"message":{"type":"string","description":"Human-readable explanation. May be empty on success."}}}}}}
```

## List countries and cities

> List countries and cities for collecting the payout recipient's address. Public metadata; no authentication required.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"Managed Custody Mode","description":"Server-to-server APIs where UR custodies user funds. Partner Auth (EIP-191) with user identity headers."}],"servers":[{"url":"https://openapi.ur.app","description":"Production (partner API)"},{"url":"https://uropenapi-qa.ur-inc.xyz","description":"Testnet (partner API)"}],"security":[],"paths":{"/api/v1/country-cities":{"get":{"tags":["Managed Custody Mode"],"operationId":"mcListCountryCities","summary":"List countries and cities","description":"List countries and cities for collecting the payout recipient's address. Public metadata; no authentication required.","responses":{"200":{"description":"Standard envelope. data carries the country and city list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McPublicMetadataResponse"}}}}}}}},"components":{"schemas":{"McPublicMetadataResponse":{"allOf":[{"$ref":"#/components/schemas/McBaseResponse"},{"type":"object","properties":{"data":{"description":"Endpoint-specific metadata payload."}}}]},"McBaseResponse":{"type":"object","description":"Standard UR OpenAPI response envelope. code 0 means success; a non-zero code is a business error described by message.","required":["code","message"],"properties":{"code":{"type":"integer","description":"0 on success; non-zero business error code."},"message":{"type":"string","description":"Human-readable explanation. May be empty on success."}}}}}}
```

## List payment purposes

> List payment purposes to select from when creating or verifying a payout contact. Public metadata; no authentication required.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"Managed Custody Mode","description":"Server-to-server APIs where UR custodies user funds. Partner Auth (EIP-191) with user identity headers."}],"servers":[{"url":"https://openapi.ur.app","description":"Production (partner API)"},{"url":"https://uropenapi-qa.ur-inc.xyz","description":"Testnet (partner API)"}],"security":[],"paths":{"/api/v1/payment-purposes":{"get":{"tags":["Managed Custody Mode"],"operationId":"mcListPaymentPurposes","summary":"List payment purposes","description":"List payment purposes to select from when creating or verifying a payout contact. Public metadata; no authentication required.","responses":{"200":{"description":"Standard envelope. data carries the payment purpose list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McPublicMetadataResponse"}}}}}}}},"components":{"schemas":{"McPublicMetadataResponse":{"allOf":[{"$ref":"#/components/schemas/McBaseResponse"},{"type":"object","properties":{"data":{"description":"Endpoint-specific metadata payload."}}}]},"McBaseResponse":{"type":"object","description":"Standard UR OpenAPI response envelope. code 0 means success; a non-zero code is a business error described by message.","required":["code","message"],"properties":{"code":{"type":"integer","description":"0 on success; non-zero business error code."},"message":{"type":"string","description":"Human-readable explanation. May be empty on success."}}}}}}
```

## Verify reference

> Validate a new payment reference for an existing recent contact and get a fresh refId and purposeId to use in the payout submission.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"Managed Custody Mode","description":"Server-to-server APIs where UR custodies user funds. Partner Auth (EIP-191) with user identity headers."}],"servers":[{"url":"https://openapi.ur.app","description":"Production (partner API)"},{"url":"https://uropenapi-qa.ur-inc.xyz","description":"Testnet (partner API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"Partner Auth: EIP-191 signature by the partner's registered backend key, with X-Api-Deadline and optional X-Api-PublicKey headers. See the Signature and verify guide."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"McVerifyReferenceRequest":{"type":"object","required":["reference"],"properties":{"reference":{"type":"string","description":"The payment reference to validate."}}},"McVerifyReferenceResponse":{"allOf":[{"$ref":"#/components/schemas/McBaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/McPayoutRefParams"}}}]},"McBaseResponse":{"type":"object","description":"Standard UR OpenAPI response envelope. code 0 means success; a non-zero code is a business error described by message.","required":["code","message"],"properties":{"code":{"type":"integer","description":"0 on success; non-zero business error code."},"message":{"type":"string","description":"Human-readable explanation. May be empty on success."}}},"McPayoutRefParams":{"type":"object","properties":{"contactId":{"type":"string","description":"Contact ID to use in the payout submission."},"purposeId":{"type":"integer","description":"Payment purpose ID."},"refId":{"type":"string","description":"Reference ID. Provide together with purposeId in the payout submission."}}}}},"paths":{"/api/fma/v1/verify-reference":{"post":{"tags":["Managed Custody Mode"],"operationId":"mcVerifyReference","summary":"Verify reference","description":"Validate a new payment reference for an existing recent contact and get a fresh refId and purposeId to use in the payout submission.","parameters":[{"name":"X-Api-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed 65-byte hex EIP-191 signature over the Partner Auth message. See the Signature and verify guide."},{"name":"X-Api-Deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds. UR rejects the request when the current time is past the deadline. Keep the validity window at or under 5 minutes."},{"name":"X-Api-PublicKey","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed partner signer address registered with UR."},{"name":"X-Ur-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."},{"name":"X-External-User-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McVerifyReferenceRequest"}}}},"responses":{"200":{"description":"Standard envelope. Business errors return HTTP 200 with a non-zero code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McVerifyReferenceResponse"}}}}}}}}}
```

## Verify contact

> Create and validate a new payout recipient, returning the contactId, purposeId, and refId needed to submit the payout. Creditor name, street, city, and country must use Latin characters.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"Managed Custody Mode","description":"Server-to-server APIs where UR custodies user funds. Partner Auth (EIP-191) with user identity headers."}],"servers":[{"url":"https://openapi.ur.app","description":"Production (partner API)"},{"url":"https://uropenapi-qa.ur-inc.xyz","description":"Testnet (partner API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"Partner Auth: EIP-191 signature by the partner's registered backend key, with X-Api-Deadline and optional X-Api-PublicKey headers. See the Signature and verify guide."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"McVerifyContactRequest":{"type":"object","required":["account","bankName","bic","purpose","reference"],"properties":{"account":{"type":"string","description":"Recipient IBAN or account number."},"bankName":{"type":"string","description":"Recipient bank name."},"bic":{"type":"string","description":"Recipient bank BIC."},"purpose":{"type":"integer","description":"Payment purpose ID from the payment purposes list."},"reference":{"type":"string","description":"Payment reference."},"creditorInfo":{"$ref":"#/components/schemas/McCreditorInfo"}}},"McCreditorInfo":{"type":"object","description":"Recipient details, required when creating a new third-party contact. name, street, city, and country must use Latin characters.","required":["name","street","city","zip","country"],"properties":{"name":{"type":"string"},"street":{"type":"string"},"city":{"type":"string"},"zip":{"type":"string"},"country":{"type":"string"}}},"McVerifyContactResponse":{"allOf":[{"$ref":"#/components/schemas/McBaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/McVerifyContactData"}}}]},"McBaseResponse":{"type":"object","description":"Standard UR OpenAPI response envelope. code 0 means success; a non-zero code is a business error described by message.","required":["code","message"],"properties":{"code":{"type":"integer","description":"0 on success; non-zero business error code."},"message":{"type":"string","description":"Human-readable explanation. May be empty on success."}}},"McVerifyContactData":{"type":"object","properties":{"account":{"type":"string","description":"Recipient IBAN or account number echoed from the request."},"bankName":{"type":"string"},"bic":{"type":"string"},"purpose":{"type":"integer"},"reference":{"type":"string"},"clientPayoutRefParams":{"$ref":"#/components/schemas/McPayoutRefParams"}}},"McPayoutRefParams":{"type":"object","properties":{"contactId":{"type":"string","description":"Contact ID to use in the payout submission."},"purposeId":{"type":"integer","description":"Payment purpose ID."},"refId":{"type":"string","description":"Reference ID. Provide together with purposeId in the payout submission."}}}}},"paths":{"/api/fma/v1/verify-contact":{"post":{"tags":["Managed Custody Mode"],"operationId":"mcVerifyContact","summary":"Verify contact","description":"Create and validate a new payout recipient, returning the contactId, purposeId, and refId needed to submit the payout. Creditor name, street, city, and country must use Latin characters.","parameters":[{"name":"X-Api-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed 65-byte hex EIP-191 signature over the Partner Auth message. See the Signature and verify guide."},{"name":"X-Api-Deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds. UR rejects the request when the current time is past the deadline. Keep the validity window at or under 5 minutes."},{"name":"X-Api-PublicKey","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed partner signer address registered with UR."},{"name":"X-Ur-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."},{"name":"X-External-User-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McVerifyContactRequest"}}}},"responses":{"200":{"description":"Standard envelope. Business errors return HTTP 200 with a non-zero code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McVerifyContactResponse"}}}}}}}}}
```

## Submit payout

> Send tokenized fiat from the user's UR account to an external bank account via SEPA or SWIFT. Requires a Live UR account; fees are deducted from the amount, and the payout counts against the rolling 30-day CHF-denominated fiat limit. The response returns only a txHash; the transaction webhook with data.type FIAT\_WITHDRAW reports final settlement.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"Managed Custody Mode","description":"Server-to-server APIs where UR custodies user funds. Partner Auth (EIP-191) with user identity headers."}],"servers":[{"url":"https://openapi.ur.app","description":"Production (partner API)"},{"url":"https://uropenapi-qa.ur-inc.xyz","description":"Testnet (partner API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"Partner Auth: EIP-191 signature by the partner's registered backend key, with X-Api-Deadline and optional X-Api-PublicKey headers. See the Signature and verify guide."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"McSubmitPayoutRequest":{"type":"object","required":["reqId","amount","contactId","currency","metadata"],"properties":{"reqId":{"type":"string","description":"Partner-supplied idempotency key. Keep it stable across retries of the same logical operation."},"amount":{"type":"string","description":"Payout amount as a string. Minimum is currency-specific; see minimalPayoutAmount from the payout fees endpoint. Network and payout fees are deducted from this amount."},"contactId":{"type":"string","description":"Contact ID from the BR profile contacts or from verify-contact."},"currency":{"type":"string","description":"Payout fiat currency symbol."},"purposeId":{"type":"string","description":"Payment purpose ID as a decimal string. Provide together with refId, or omit both."},"refId":{"type":"string","description":"Reference ID from verify-reference or verify-contact. Provide together with purposeId, or omit both."},"metadata":{"$ref":"#/components/schemas/McPayoutMetadata"}}},"McPayoutMetadata":{"type":"object","description":"Additional bank details. Name, address, and reference values must use Latin characters.","properties":{"bankAccountHolder":{"type":"string","description":"Recipient account holder name."},"bankName":{"type":"string","description":"Recipient bank name."},"bankAccount":{"type":"string","description":"Recipient account number or IBAN."},"bankReference":{"type":"string","description":"Bank reference."}}},"McTxHashResponse":{"allOf":[{"$ref":"#/components/schemas/McBaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/McTxHashData"}}}]},"McBaseResponse":{"type":"object","description":"Standard UR OpenAPI response envelope. code 0 means success; a non-zero code is a business error described by message.","required":["code","message"],"properties":{"code":{"type":"integer","description":"0 on success; non-zero business error code."},"message":{"type":"string","description":"Human-readable explanation. May be empty on success."}}},"McTxHashData":{"type":"object","properties":{"txHash":{"type":"string","description":"On-chain transaction hash of the submitted operation. Submission only; final settlement arrives via the transaction webhook."}}}}},"paths":{"/api/fma/v1/submit-payout":{"post":{"tags":["Managed Custody Mode"],"operationId":"mcSubmitPayout","summary":"Submit payout","description":"Send tokenized fiat from the user's UR account to an external bank account via SEPA or SWIFT. Requires a Live UR account; fees are deducted from the amount, and the payout counts against the rolling 30-day CHF-denominated fiat limit. The response returns only a txHash; the transaction webhook with data.type FIAT_WITHDRAW reports final settlement.","parameters":[{"name":"X-Api-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed 65-byte hex EIP-191 signature over the Partner Auth message. See the Signature and verify guide."},{"name":"X-Api-Deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds. UR rejects the request when the current time is past the deadline. Keep the validity window at or under 5 minutes."},{"name":"X-Api-PublicKey","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed partner signer address registered with UR."},{"name":"X-Ur-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."},{"name":"X-External-User-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McSubmitPayoutRequest"}}}},"responses":{"200":{"description":"Standard envelope. Business errors return HTTP 200 with a non-zero code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McTxHashResponse"}}}}}}}}}
```

## Get on-ramp limit

> Check On-ramp availability and per-currency amount limits before starting the flow. Block the flow when regionLocked, usdcDepegged, or livenessLocked is true, or when the requested amount falls outside the minAmounts to maxAmounts range. On-ramp is not yet available for integration; this reference is a preview.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"Managed Custody Mode","description":"Server-to-server APIs where UR custodies user funds. Partner Auth (EIP-191) with user identity headers."}],"servers":[{"url":"https://openapi.ur.app","description":"Production (partner API)"},{"url":"https://uropenapi-qa.ur-inc.xyz","description":"Testnet (partner API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"Partner Auth: EIP-191 signature by the partner's registered backend key, with X-Api-Deadline and optional X-Api-PublicKey headers. See the Signature and verify guide."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"McOnrampLimitResponse":{"allOf":[{"$ref":"#/components/schemas/McBaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/McOnrampLimitData"}}}]},"McBaseResponse":{"type":"object","description":"Standard UR OpenAPI response envelope. code 0 means success; a non-zero code is a business error described by message.","required":["code","message"],"properties":{"code":{"type":"integer","description":"0 on success; non-zero business error code."},"message":{"type":"string","description":"Human-readable explanation. May be empty on success."}}},"McOnrampLimitData":{"type":"object","properties":{"livenessLocked":{"type":"boolean","description":"True when the user is temporarily locked out of liveness checks. Block the flow when true."},"livenessLockMins":{"type":"integer","description":"Remaining liveness lock duration in minutes."},"maxAmounts":{"type":"object","description":"Maximum amounts keyed by fiat currency. Derived from a USD anchor at the live rate; read at request time, do not hardcode.","additionalProperties":{"type":"string"}},"minAmounts":{"type":"object","description":"Minimum amounts keyed by fiat currency. About 5 USD equivalent; read at request time, do not hardcode.","additionalProperties":{"type":"string"}},"usdcDepegged":{"type":"boolean","description":"True when USDC is depegged. Block the flow when true."},"regionLocked":{"type":"boolean","description":"True when the user's region is restricted. Block the flow when true."}}}}},"paths":{"/api/fma/v1/onramp-limit":{"get":{"tags":["Managed Custody Mode"],"operationId":"mcGetOnrampLimit","summary":"Get on-ramp limit","description":"Check On-ramp availability and per-currency amount limits before starting the flow. Block the flow when regionLocked, usdcDepegged, or livenessLocked is true, or when the requested amount falls outside the minAmounts to maxAmounts range. On-ramp is not yet available for integration; this reference is a preview.","parameters":[{"name":"X-Api-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed 65-byte hex EIP-191 signature over the Partner Auth message. See the Signature and verify guide."},{"name":"X-Api-Deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds. UR rejects the request when the current time is past the deadline. Keep the validity window at or under 5 minutes."},{"name":"X-Api-PublicKey","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed partner signer address registered with UR."},{"name":"X-Ur-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."},{"name":"X-External-User-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."}],"responses":{"200":{"description":"Standard envelope. Business errors return HTTP 200 with a non-zero code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McOnrampLimitResponse"}}}}}}}}}
```

## Check pending on-ramp retry

> Read the user's pending On-ramp retry, an On-ramp whose bridge leg succeeded but whose swap leg failed. An empty originalTxHash means no pending retry. While a pending retry exists, block new On-ramp submissions until the user retries or cancels. On-ramp is not yet available for integration; this reference is a preview.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"Managed Custody Mode","description":"Server-to-server APIs where UR custodies user funds. Partner Auth (EIP-191) with user identity headers."}],"servers":[{"url":"https://openapi.ur.app","description":"Production (partner API)"},{"url":"https://uropenapi-qa.ur-inc.xyz","description":"Testnet (partner API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"Partner Auth: EIP-191 signature by the partner's registered backend key, with X-Api-Deadline and optional X-Api-PublicKey headers. See the Signature and verify guide."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"McOnrampPendingRetryResponse":{"allOf":[{"$ref":"#/components/schemas/McBaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/McOnrampPendingRetryData"}}}]},"McBaseResponse":{"type":"object","description":"Standard UR OpenAPI response envelope. code 0 means success; a non-zero code is a business error described by message.","required":["code","message"],"properties":{"code":{"type":"integer","description":"0 on success; non-zero business error code."},"message":{"type":"string","description":"Human-readable explanation. May be empty on success."}}},"McOnrampPendingRetryData":{"type":"object","properties":{"originalTxHash":{"type":"string","description":"Original On-ramp transaction hash. Empty when there is no pending retry."},"originalChainId":{"type":"string","description":"Source chain ID of the original On-ramp, in CAIP-2 format."},"originalCurrency":{"type":"string","description":"Original source fiat currency symbol."},"chainId":{"type":"string","description":"Destination chain ID in CAIP-2 format. Use as srcChainId and dstChainId in the retry quote."},"fromToken":{"type":"string","description":"Bridge intermediate token (USDC) address on the destination chain."},"toToken":{"type":"string","description":"Destination token address."},"amount":{"type":"string","description":"Stuck USDC amount as a human-readable decimal string. Use as the retry quote amount."},"amountRaw":{"type":"string","description":"Stuck USDC amount in smallest units. Use as usdcAmount in the retry submission."},"failedAt":{"type":"integer","description":"Failure timestamp in Unix seconds."}}}}},"paths":{"/api/fma/v1/onramp/pending-retry":{"get":{"tags":["Managed Custody Mode"],"operationId":"mcGetOnrampPendingRetry","summary":"Check pending on-ramp retry","description":"Read the user's pending On-ramp retry, an On-ramp whose bridge leg succeeded but whose swap leg failed. An empty originalTxHash means no pending retry. While a pending retry exists, block new On-ramp submissions until the user retries or cancels. On-ramp is not yet available for integration; this reference is a preview.","parameters":[{"name":"X-Api-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed 65-byte hex EIP-191 signature over the Partner Auth message. See the Signature and verify guide."},{"name":"X-Api-Deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds. UR rejects the request when the current time is past the deadline. Keep the validity window at or under 5 minutes."},{"name":"X-Api-PublicKey","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed partner signer address registered with UR."},{"name":"X-Ur-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."},{"name":"X-External-User-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."}],"responses":{"200":{"description":"Standard envelope. Business errors return HTTP 200 with a non-zero code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McOnrampPendingRetryResponse"}}}}}}}}}
```

## Get on-ramp quote

> Quote an On-ramp (scene onramp) or a retry swap (scene swap\_retry). When the response has needLiveness true, complete the liveness check before submitting; after liveness passes, request a new quote and submit with the new quoteId. On-ramp is not yet available for integration; this reference is a preview.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"Managed Custody Mode","description":"Server-to-server APIs where UR custodies user funds. Partner Auth (EIP-191) with user identity headers."}],"servers":[{"url":"https://openapi.ur.app","description":"Production (partner API)"},{"url":"https://uropenapi-qa.ur-inc.xyz","description":"Testnet (partner API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"Partner Auth: EIP-191 signature by the partner's registered backend key, with X-Api-Deadline and optional X-Api-PublicKey headers. See the Signature and verify guide."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"McOnrampQuoteRequest":{"type":"object","required":["scene","dstChainId","toToken","amount"],"properties":{"scene":{"type":"string","enum":["onramp","swap_retry"],"description":"onramp for the main flow; swap_retry for retrying a failed swap leg."},"srcChainId":{"type":"string","description":"Source chain ID in CAIP-2 format; the chain where the user's tokenized fiat is held. For swap_retry, use the pending retry's chainId."},"dstChainId":{"type":"string","description":"Destination chain ID in CAIP-2 format. Must match a token with aggregator support in the chain config."},"fromCurrency":{"type":"string","description":"Source fiat currency symbol. Required when scene is onramp."},"fromToken":{"type":"string","description":"USDC token address. Required when scene is swap_retry."},"toToken":{"type":"string","description":"Destination token address."},"amount":{"type":"string","description":"Input amount as a human-readable decimal string; UR converts it to smallest units by the input currency decimals."},"slippageBps":{"type":"integer","description":"Slippage tolerance in basis points. Defaults to 50."}}},"McOnrampQuoteResponse":{"allOf":[{"$ref":"#/components/schemas/McBaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/McOnrampQuoteData"}}}]},"McBaseResponse":{"type":"object","description":"Standard UR OpenAPI response envelope. code 0 means success; a non-zero code is a business error described by message.","required":["code","message"],"properties":{"code":{"type":"integer","description":"0 on success; non-zero business error code."},"message":{"type":"string","description":"Human-readable explanation. May be empty on success."}}},"McOnrampQuoteData":{"type":"object","properties":{"quoteId":{"type":"string","description":"Quote identifier. Echo it in the On-ramp submission before it expires."},"srcChainId":{"type":"string"},"dstChainId":{"type":"string"},"needLiveness":{"type":"boolean","description":"True when the user must pass a liveness check before this quote can be submitted."},"best":{"$ref":"#/components/schemas/McOnrampQuoteBest"},"inputAmount":{"type":"string","description":"Input fiat amount."},"outputAmount":{"type":"string","description":"Estimated output token amount."},"exchangeRate":{"type":"string","description":"Applied exchange rate."},"crossChainFee":{"type":"string","description":"Cross-chain fee component."},"networkFee":{"type":"string","description":"Destination-chain gas plus cross-chain fee, deducted from the user's input fiat."},"processingFee":{"type":"string","description":"Processing fee."},"totalFee":{"type":"string","description":"Total fee."},"warningMessage":{"type":"string","description":"Warning text, when applicable."}}},"McOnrampQuoteBest":{"type":"object","description":"Best aggregator route for the destination-chain swap.","properties":{"aggregator":{"type":"string","description":"Aggregator name. Do not use as the retry aggregator parameter; use to instead."},"to":{"type":"string","description":"Aggregator contract address. Use as dstAggregator (submit) or aggregator (retry)."},"swapCalldata":{"type":"string","description":"Swap calldata. Use as dstSwapCalldata (submit) or swapCalldata (retry)."},"minUsdcAmount":{"type":"string","description":"Minimum USDC amount in smallest units."},"expectedUsdcAmount":{"type":"string","description":"Expected USDC amount in smallest units."},"minAmountOut":{"type":"string","description":"Minimum output amount in smallest units. Use as dstMinAmountOut (submit) or minAmountOut (retry)."},"expectedAmountOut":{"type":"string","description":"Expected output amount in smallest units."},"slippageBps":{"type":"integer","description":"Applied slippage in basis points."},"deadline":{"type":"integer","description":"Quote deadline in Unix seconds."},"priceImpact":{"type":"string","description":"Estimated price impact."}}}}},"paths":{"/api/fma/v1/quote/onramp":{"post":{"tags":["Managed Custody Mode"],"operationId":"mcGetOnrampQuote","summary":"Get on-ramp quote","description":"Quote an On-ramp (scene onramp) or a retry swap (scene swap_retry). When the response has needLiveness true, complete the liveness check before submitting; after liveness passes, request a new quote and submit with the new quoteId. On-ramp is not yet available for integration; this reference is a preview.","parameters":[{"name":"X-Api-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed 65-byte hex EIP-191 signature over the Partner Auth message. See the Signature and verify guide."},{"name":"X-Api-Deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds. UR rejects the request when the current time is past the deadline. Keep the validity window at or under 5 minutes."},{"name":"X-Api-PublicKey","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed partner signer address registered with UR."},{"name":"X-Ur-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."},{"name":"X-External-User-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McOnrampQuoteRequest"}}}},"responses":{"200":{"description":"Standard envelope. Business errors return HTTP 200 with a non-zero code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McOnrampQuoteResponse"}}}}}}}}}
```

## Get on-ramp liveness token

> Issue a vendor access token for the liveness check. Only call this endpoint when an On-ramp quote returns needLiveness true. On-ramp is not yet available for integration; this reference is a preview.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"Managed Custody Mode","description":"Server-to-server APIs where UR custodies user funds. Partner Auth (EIP-191) with user identity headers."}],"servers":[{"url":"https://openapi.ur.app","description":"Production (partner API)"},{"url":"https://uropenapi-qa.ur-inc.xyz","description":"Testnet (partner API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"Partner Auth: EIP-191 signature by the partner's registered backend key, with X-Api-Deadline and optional X-Api-PublicKey headers. See the Signature and verify guide."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"McLivenessTokenResponse":{"allOf":[{"$ref":"#/components/schemas/McBaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/McLivenessTokenData"}}}]},"McBaseResponse":{"type":"object","description":"Standard UR OpenAPI response envelope. code 0 means success; a non-zero code is a business error described by message.","required":["code","message"],"properties":{"code":{"type":"integer","description":"0 on success; non-zero business error code."},"message":{"type":"string","description":"Human-readable explanation. May be empty on success."}}},"McLivenessTokenData":{"type":"object","properties":{"vendor":{"type":"string","description":"Liveness vendor identifier, for example sumsub."},"access_token":{"type":"string","description":"Vendor access token for running the liveness check."},"user_id":{"type":"string","description":"Vendor user identifier."}}}}},"paths":{"/api/fma/v1/onramp-liveness-token":{"get":{"tags":["Managed Custody Mode"],"operationId":"mcGetOnrampLivenessToken","summary":"Get on-ramp liveness token","description":"Issue a vendor access token for the liveness check. Only call this endpoint when an On-ramp quote returns needLiveness true. On-ramp is not yet available for integration; this reference is a preview.","parameters":[{"name":"X-Api-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed 65-byte hex EIP-191 signature over the Partner Auth message. See the Signature and verify guide."},{"name":"X-Api-Deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds. UR rejects the request when the current time is past the deadline. Keep the validity window at or under 5 minutes."},{"name":"X-Api-PublicKey","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed partner signer address registered with UR."},{"name":"X-Ur-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."},{"name":"X-External-User-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."}],"responses":{"200":{"description":"Standard envelope. Business errors return HTTP 200 with a non-zero code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McLivenessTokenResponse"}}}}}}}}}
```

## Get on-ramp liveness result

> Poll the result of the liveness check. After liveness\_result is pass, request a new On-ramp quote and submit using the new quoteId. On-ramp is not yet available for integration; this reference is a preview.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"Managed Custody Mode","description":"Server-to-server APIs where UR custodies user funds. Partner Auth (EIP-191) with user identity headers."}],"servers":[{"url":"https://openapi.ur.app","description":"Production (partner API)"},{"url":"https://uropenapi-qa.ur-inc.xyz","description":"Testnet (partner API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"Partner Auth: EIP-191 signature by the partner's registered backend key, with X-Api-Deadline and optional X-Api-PublicKey headers. See the Signature and verify guide."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"McLivenessResultResponse":{"allOf":[{"$ref":"#/components/schemas/McBaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/McLivenessResultData"}}}]},"McBaseResponse":{"type":"object","description":"Standard UR OpenAPI response envelope. code 0 means success; a non-zero code is a business error described by message.","required":["code","message"],"properties":{"code":{"type":"integer","description":"0 on success; non-zero business error code."},"message":{"type":"string","description":"Human-readable explanation. May be empty on success."}}},"McLivenessResultData":{"type":"object","properties":{"liveness_result":{"type":"string","description":"Liveness check outcome, e.g. pass or pending."},"checked_at":{"type":"integer","description":"Check timestamp in Unix seconds."},"expired_at":{"type":"integer","description":"Result expiry timestamp in Unix seconds."},"liveness_fail_reason":{"type":"string","description":"Failure reason; empty on pass."},"liveness_locked":{"type":"boolean","description":"True when the user is locked out after repeated failures."},"liveness_unlock_at":{"type":"integer","description":"Unlock timestamp in Unix seconds; 0 when not locked."}}}}},"paths":{"/api/fma/v1/onramp-liveness-result":{"get":{"tags":["Managed Custody Mode"],"operationId":"mcGetOnrampLivenessResult","summary":"Get on-ramp liveness result","description":"Poll the result of the liveness check. After liveness_result is pass, request a new On-ramp quote and submit using the new quoteId. On-ramp is not yet available for integration; this reference is a preview.","parameters":[{"name":"X-Api-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed 65-byte hex EIP-191 signature over the Partner Auth message. See the Signature and verify guide."},{"name":"X-Api-Deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds. UR rejects the request when the current time is past the deadline. Keep the validity window at or under 5 minutes."},{"name":"X-Api-PublicKey","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed partner signer address registered with UR."},{"name":"X-Ur-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."},{"name":"X-External-User-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."}],"responses":{"200":{"description":"Standard envelope. Business errors return HTTP 200 with a non-zero code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McLivenessResultResponse"}}}}}}}}}
```

## Submit on-ramp

> Convert the user's tokenized fiat into crypto delivered to an external wallet. Requires a Live UR account, a valid unexpired quoteId, passed liveness when the quote required it, and no pending retry. The response returns only a txHash; the transaction webhook with data.type ONRAMP reports the final result. On-ramp is not yet available for integration; this reference is a preview.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"Managed Custody Mode","description":"Server-to-server APIs where UR custodies user funds. Partner Auth (EIP-191) with user identity headers."}],"servers":[{"url":"https://openapi.ur.app","description":"Production (partner API)"},{"url":"https://uropenapi-qa.ur-inc.xyz","description":"Testnet (partner API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"Partner Auth: EIP-191 signature by the partner's registered backend key, with X-Api-Deadline and optional X-Api-PublicKey headers. See the Signature and verify guide."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"McOnrampRequest":{"type":"object","required":["reqId","quoteId","fromCurrency","amountIn","withdrawAddress"],"properties":{"reqId":{"type":"string","description":"Partner-supplied idempotency key. Keep it stable across retries of the same logical operation."},"quoteId":{"type":"string","description":"quoteId from the On-ramp quote. Must match UR's cached quote and not be expired."},"fromCurrency":{"type":"string","description":"Source fiat currency symbol."},"chainId":{"type":"string","description":"Source chain ID in CAIP-2 format."},"amountIn":{"type":"string","description":"Input amount as a human-readable decimal string. Must match the amount used for the cached quote."},"dstChainId":{"type":"string","description":"Destination chain ID in CAIP-2 format."},"withdrawAddress":{"type":"string","description":"External wallet that receives the crypto. Required for every On-ramp; the UR-managed account holds fiat only and never receives crypto."},"dstAggregator":{"type":"string","description":"best.to from the quote."},"dstTokenOut":{"type":"string","description":"Destination token address."},"dstSwapCalldata":{"type":"string","description":"best.swapCalldata from the quote."},"dstMinAmountOut":{"type":"string","description":"best.minAmountOut from the quote."}}},"McTxHashResponse":{"allOf":[{"$ref":"#/components/schemas/McBaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/McTxHashData"}}}]},"McBaseResponse":{"type":"object","description":"Standard UR OpenAPI response envelope. code 0 means success; a non-zero code is a business error described by message.","required":["code","message"],"properties":{"code":{"type":"integer","description":"0 on success; non-zero business error code."},"message":{"type":"string","description":"Human-readable explanation. May be empty on success."}}},"McTxHashData":{"type":"object","properties":{"txHash":{"type":"string","description":"On-chain transaction hash of the submitted operation. Submission only; final settlement arrives via the transaction webhook."}}}}},"paths":{"/api/fma/v1/onramp":{"post":{"tags":["Managed Custody Mode"],"operationId":"mcSubmitOnramp","summary":"Submit on-ramp","description":"Convert the user's tokenized fiat into crypto delivered to an external wallet. Requires a Live UR account, a valid unexpired quoteId, passed liveness when the quote required it, and no pending retry. The response returns only a txHash; the transaction webhook with data.type ONRAMP reports the final result. On-ramp is not yet available for integration; this reference is a preview.","parameters":[{"name":"X-Api-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed 65-byte hex EIP-191 signature over the Partner Auth message. See the Signature and verify guide."},{"name":"X-Api-Deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds. UR rejects the request when the current time is past the deadline. Keep the validity window at or under 5 minutes."},{"name":"X-Api-PublicKey","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed partner signer address registered with UR."},{"name":"X-Ur-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."},{"name":"X-External-User-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McOnrampRequest"}}}},"responses":{"200":{"description":"Standard envelope. Business errors return HTTP 200 with a non-zero code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McTxHashResponse"}}}}}}}}}
```

## Retry on-ramp swap

> Redo the swap leg of an On-ramp whose bridge succeeded but whose swap failed. Only call this endpoint when the pending-retry endpoint returns a pending item, and use a fresh quote with scene swap\_retry. The transaction webhook reports the final result. On-ramp is not yet available for integration; this reference is a preview.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"Managed Custody Mode","description":"Server-to-server APIs where UR custodies user funds. Partner Auth (EIP-191) with user identity headers."}],"servers":[{"url":"https://openapi.ur.app","description":"Production (partner API)"},{"url":"https://uropenapi-qa.ur-inc.xyz","description":"Testnet (partner API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"Partner Auth: EIP-191 signature by the partner's registered backend key, with X-Api-Deadline and optional X-Api-PublicKey headers. See the Signature and verify guide."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"McOnrampSwapRequest":{"type":"object","required":["reqId","quoteId","chainId","originalTxHash","usdcAmount","tokenOut","minAmountOut","aggregator","swapCalldata"],"properties":{"reqId":{"type":"string","description":"Partner-supplied idempotency key. Keep it stable across retries of the same logical operation."},"quoteId":{"type":"string","description":"quoteId from a fresh quote with scene swap_retry."},"chainId":{"type":"string","description":"Destination chain ID in CAIP-2 format, from the pending retry."},"originalTxHash":{"type":"string","description":"Original On-ramp transaction hash, from the pending retry."},"usdcAmount":{"type":"string","description":"Stuck USDC amount in smallest units (pending retry amountRaw)."},"tokenOut":{"type":"string","description":"Destination token address (pending retry toToken)."},"minAmountOut":{"type":"string","description":"best.minAmountOut from the retry quote."},"aggregator":{"type":"string","description":"best.to from the retry quote (not best.aggregator)."},"swapCalldata":{"type":"string","description":"best.swapCalldata from the retry quote."}}},"McTxHashResponse":{"allOf":[{"$ref":"#/components/schemas/McBaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/McTxHashData"}}}]},"McBaseResponse":{"type":"object","description":"Standard UR OpenAPI response envelope. code 0 means success; a non-zero code is a business error described by message.","required":["code","message"],"properties":{"code":{"type":"integer","description":"0 on success; non-zero business error code."},"message":{"type":"string","description":"Human-readable explanation. May be empty on success."}}},"McTxHashData":{"type":"object","properties":{"txHash":{"type":"string","description":"On-chain transaction hash of the submitted operation. Submission only; final settlement arrives via the transaction webhook."}}}}},"paths":{"/api/fma/v1/onramp-swap":{"post":{"tags":["Managed Custody Mode"],"operationId":"mcRetryOnrampSwap","summary":"Retry on-ramp swap","description":"Redo the swap leg of an On-ramp whose bridge succeeded but whose swap failed. Only call this endpoint when the pending-retry endpoint returns a pending item, and use a fresh quote with scene swap_retry. The transaction webhook reports the final result. On-ramp is not yet available for integration; this reference is a preview.","parameters":[{"name":"X-Api-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed 65-byte hex EIP-191 signature over the Partner Auth message. See the Signature and verify guide."},{"name":"X-Api-Deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds. UR rejects the request when the current time is past the deadline. Keep the validity window at or under 5 minutes."},{"name":"X-Api-PublicKey","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed partner signer address registered with UR."},{"name":"X-Ur-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."},{"name":"X-External-User-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McOnrampSwapRequest"}}}},"responses":{"200":{"description":"Standard envelope. Business errors return HTTP 200 with a non-zero code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McTxHashResponse"}}}}}}}}}
```

## Cancel on-ramp retry

> Clear the user's pending On-ramp retry record. A successful response allows the normal On-ramp entry point to be re-enabled. On-ramp is not yet available for integration; this reference is a preview.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"Managed Custody Mode","description":"Server-to-server APIs where UR custodies user funds. Partner Auth (EIP-191) with user identity headers."}],"servers":[{"url":"https://openapi.ur.app","description":"Production (partner API)"},{"url":"https://uropenapi-qa.ur-inc.xyz","description":"Testnet (partner API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"Partner Auth: EIP-191 signature by the partner's registered backend key, with X-Api-Deadline and optional X-Api-PublicKey headers. See the Signature and verify guide."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"McOnrampRetryCancelRequest":{"type":"object","required":["originalTxHash"],"properties":{"originalTxHash":{"type":"string","description":"Original On-ramp transaction hash of the pending retry to cancel."}}},"McBaseResponse":{"type":"object","description":"Standard UR OpenAPI response envelope. code 0 means success; a non-zero code is a business error described by message.","required":["code","message"],"properties":{"code":{"type":"integer","description":"0 on success; non-zero business error code."},"message":{"type":"string","description":"Human-readable explanation. May be empty on success."}}}}},"paths":{"/api/fma/v1/onramp/retry/cancel":{"post":{"tags":["Managed Custody Mode"],"operationId":"mcCancelOnrampRetry","summary":"Cancel on-ramp retry","description":"Clear the user's pending On-ramp retry record. A successful response allows the normal On-ramp entry point to be re-enabled. On-ramp is not yet available for integration; this reference is a preview.","parameters":[{"name":"X-Api-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed 65-byte hex EIP-191 signature over the Partner Auth message. See the Signature and verify guide."},{"name":"X-Api-Deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds. UR rejects the request when the current time is past the deadline. Keep the validity window at or under 5 minutes."},{"name":"X-Api-PublicKey","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed partner signer address registered with UR."},{"name":"X-Ur-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."},{"name":"X-External-User-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McOnrampRetryCancelRequest"}}}},"responses":{"200":{"description":"Standard envelope. Business errors return HTTP 200 with a non-zero code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McBaseResponse"}}}}}}}}}
```

## Create card

> Create a virtual card for an eligible Live user. Requires isCardEligible true in the BR profile and a balance that satisfies cardActivation.amount in cardActivation.currency.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"Managed Custody Mode","description":"Server-to-server APIs where UR custodies user funds. Partner Auth (EIP-191) with user identity headers."}],"servers":[{"url":"https://openapi.ur.app","description":"Production (partner API)"},{"url":"https://uropenapi-qa.ur-inc.xyz","description":"Testnet (partner API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"Partner Auth: EIP-191 signature by the partner's registered backend key, with X-Api-Deadline and optional X-Api-PublicKey headers. See the Signature and verify guide."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"McBaseResponse":{"type":"object","description":"Standard UR OpenAPI response envelope. code 0 means success; a non-zero code is a business error described by message.","required":["code","message"],"properties":{"code":{"type":"integer","description":"0 on success; non-zero business error code."},"message":{"type":"string","description":"Human-readable explanation. May be empty on success."}}}}},"paths":{"/api/fma/v1/open-card":{"post":{"tags":["Managed Custody Mode"],"operationId":"mcCreateCard","summary":"Create card","description":"Create a virtual card for an eligible Live user. Requires isCardEligible true in the BR profile and a balance that satisfies cardActivation.amount in cardActivation.currency.","parameters":[{"name":"X-Api-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed 65-byte hex EIP-191 signature over the Partner Auth message. See the Signature and verify guide."},{"name":"X-Api-Deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds. UR rejects the request when the current time is past the deadline. Keep the validity window at or under 5 minutes."},{"name":"X-Api-PublicKey","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed partner signer address registered with UR."},{"name":"X-Ur-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."},{"name":"X-External-User-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Empty JSON object."}}}},"responses":{"200":{"description":"Standard envelope. Business errors return HTTP 200 with a non-zero code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McBaseResponse"}}}}}}}}}
```

## Get card info

> Fetch card metadata and a short-lived cardToken for secure card display. The response never exposes real PAN, CVV, or expiry; render them through UR's card display script using cardToken, which expires after 5 minutes.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"Managed Custody Mode","description":"Server-to-server APIs where UR custodies user funds. Partner Auth (EIP-191) with user identity headers."}],"servers":[{"url":"https://openapi.ur.app","description":"Production (partner API)"},{"url":"https://uropenapi-qa.ur-inc.xyz","description":"Testnet (partner API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"Partner Auth: EIP-191 signature by the partner's registered backend key, with X-Api-Deadline and optional X-Api-PublicKey headers. See the Signature and verify guide."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"McCardResponse":{"allOf":[{"$ref":"#/components/schemas/McBaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/McCardData"}}}]},"McBaseResponse":{"type":"object","description":"Standard UR OpenAPI response envelope. code 0 means success; a non-zero code is a business error described by message.","required":["code","message"],"properties":{"code":{"type":"integer","description":"0 on success; non-zero business error code."},"message":{"type":"string","description":"Human-readable explanation. May be empty on success."}}},"McCardData":{"type":"object","properties":{"security":{"$ref":"#/components/schemas/McCardSecurity"},"currencies":{"type":"array","items":{"type":"string"},"description":"Currencies available for card transactions."},"tokenId":{"type":"integer","description":"The user's URID token ID."},"limits":{"$ref":"#/components/schemas/McCardLimits"},"cardDesign":{"type":"string"},"cardHolder":{"type":"string"},"status":{"type":"string","description":"Card status, for example Active."},"currency":{"type":"string","description":"Default card transaction currency."},"masked":{"$ref":"#/components/schemas/McCardMasked"},"cardToken":{"type":"string","description":"Short-lived token for card detail display only. Expires after 5 minutes. Do not store or log it."},"activeTokens":{"type":"array","items":{"$ref":"#/components/schemas/McCardTokenInfo"}},"inactiveTokens":{"type":"array","items":{"$ref":"#/components/schemas/McCardTokenInfo"}},"externalId":{"type":"string","description":"Stable card management ID. Use it for card management APIs."}}},"McCardSecurity":{"type":"object","properties":{"contactlessEnabled":{"type":"boolean"},"withdrawalEnabled":{"type":"boolean"},"internetPurchaseEnabled":{"type":"boolean"},"overallLimitsEnabled":{"type":"boolean"}}},"McCardLimits":{"type":"object","properties":{"account":{"$ref":"#/components/schemas/McCardLimitItem"},"withdrawal":{"$ref":"#/components/schemas/McCardLimitItem"},"internetPurchase":{"$ref":"#/components/schemas/McCardLimitItem"}}},"McCardLimitItem":{"type":"object","properties":{"restartDate":{"type":"string","description":"Date when the limit window restarts."},"restartDateMs":{"type":"integer","description":"Restart timestamp in milliseconds."},"used":{"type":"number","description":"Used allowance."},"available":{"type":"number","description":"Remaining allowance."},"max":{"type":"number","description":"Maximum allowance."}}},"McCardMasked":{"type":"object","description":"Masked card fields. Real PAN, CVV, and expiry are rendered only through UR's card display script.","properties":{"cardNumber":{"type":"string"},"cvv2":{"type":"string"},"expiry":{"type":"string"}}},"McCardTokenInfo":{"type":"object","description":"Device wallet token, such as Apple Pay. Do not use its id for card detail display or currency settings.","properties":{"id":{"type":"string"},"type":{"type":"string"},"createdAt":{"type":"string"}}}}},"paths":{"/api/fma/v1/card":{"get":{"tags":["Managed Custody Mode"],"operationId":"mcGetCardInfo","summary":"Get card info","description":"Fetch card metadata and a short-lived cardToken for secure card display. The response never exposes real PAN, CVV, or expiry; render them through UR's card display script using cardToken, which expires after 5 minutes.","parameters":[{"name":"X-Api-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed 65-byte hex EIP-191 signature over the Partner Auth message. See the Signature and verify guide."},{"name":"X-Api-Deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds. UR rejects the request when the current time is past the deadline. Keep the validity window at or under 5 minutes."},{"name":"X-Api-PublicKey","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed partner signer address registered with UR."},{"name":"X-Ur-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."},{"name":"X-External-User-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."}],"responses":{"200":{"description":"Standard envelope. Business errors return HTTP 200 with a non-zero code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McCardResponse"}}}}}}}}}
```

## Set default card currency

> Set the user's default card transaction currency. UR resolves the card's externalId from the authenticated user; the setting affects the default refund currency display and debit preference.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"Managed Custody Mode","description":"Server-to-server APIs where UR custodies user funds. Partner Auth (EIP-191) with user identity headers."}],"servers":[{"url":"https://openapi.ur.app","description":"Production (partner API)"},{"url":"https://uropenapi-qa.ur-inc.xyz","description":"Testnet (partner API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"Partner Auth: EIP-191 signature by the partner's registered backend key, with X-Api-Deadline and optional X-Api-PublicKey headers. See the Signature and verify guide."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"McSetCardCurrencyRequest":{"type":"object","required":["currency"],"properties":{"currency":{"type":"string","description":"Target default transaction currency, such as USD, EUR, or CHF."}}},"McBaseResponse":{"type":"object","description":"Standard UR OpenAPI response envelope. code 0 means success; a non-zero code is a business error described by message.","required":["code","message"],"properties":{"code":{"type":"integer","description":"0 on success; non-zero business error code."},"message":{"type":"string","description":"Human-readable explanation. May be empty on success."}}}}},"paths":{"/api/fma/v1/card-currency":{"post":{"tags":["Managed Custody Mode"],"operationId":"mcSetCardCurrency","summary":"Set default card currency","description":"Set the user's default card transaction currency. UR resolves the card's externalId from the authenticated user; the setting affects the default refund currency display and debit preference.","parameters":[{"name":"X-Api-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed 65-byte hex EIP-191 signature over the Partner Auth message. See the Signature and verify guide."},{"name":"X-Api-Deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds. UR rejects the request when the current time is past the deadline. Keep the validity window at or under 5 minutes."},{"name":"X-Api-PublicKey","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed partner signer address registered with UR."},{"name":"X-Ur-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."},{"name":"X-External-User-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McSetCardCurrencyRequest"}}}},"responses":{"200":{"description":"Standard envelope. Business errors return HTTP 200 with a non-zero code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McBaseResponse"}}}}}}}}}
```

## Update card status

> Block or unblock the user's card. UR resolves the card's externalId from the authenticated user; a blocked card declines all authorization attempts until unblocked.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"Managed Custody Mode","description":"Server-to-server APIs where UR custodies user funds. Partner Auth (EIP-191) with user identity headers."}],"servers":[{"url":"https://openapi.ur.app","description":"Production (partner API)"},{"url":"https://uropenapi-qa.ur-inc.xyz","description":"Testnet (partner API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"Partner Auth: EIP-191 signature by the partner's registered backend key, with X-Api-Deadline and optional X-Api-PublicKey headers. See the Signature and verify guide."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"McUpdateCardStatusRequest":{"type":"object","required":["statusChange"],"properties":{"statusChange":{"type":"string","enum":["block","unblock"],"description":"The status transition to apply."}}},"McBaseResponse":{"type":"object","description":"Standard UR OpenAPI response envelope. code 0 means success; a non-zero code is a business error described by message.","required":["code","message"],"properties":{"code":{"type":"integer","description":"0 on success; non-zero business error code."},"message":{"type":"string","description":"Human-readable explanation. May be empty on success."}}}}},"paths":{"/api/fma/v1/update-card-status":{"post":{"tags":["Managed Custody Mode"],"operationId":"mcUpdateCardStatus","summary":"Update card status","description":"Block or unblock the user's card. UR resolves the card's externalId from the authenticated user; a blocked card declines all authorization attempts until unblocked.","parameters":[{"name":"X-Api-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed 65-byte hex EIP-191 signature over the Partner Auth message. See the Signature and verify guide."},{"name":"X-Api-Deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds. UR rejects the request when the current time is past the deadline. Keep the validity window at or under 5 minutes."},{"name":"X-Api-PublicKey","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed partner signer address registered with UR."},{"name":"X-Ur-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."},{"name":"X-External-User-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McUpdateCardStatusRequest"}}}},"responses":{"200":{"description":"Standard envelope. Business errors return HTTP 200 with a non-zero code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McBaseResponse"}}}}}}}}}
```

## Fetch transaction history

> Fetch paginated transaction history for reconciliation, or fetch a single transaction by sending exactly one of id, txHash, or reqId (mutually exclusive). The transaction webhook delivers the same transaction structure; parse detailsJson according to the transaction type.

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"tags":[{"name":"Managed Custody Mode","description":"Server-to-server APIs where UR custodies user funds. Partner Auth (EIP-191) with user identity headers."}],"servers":[{"url":"https://openapi.ur.app","description":"Production (partner API)"},{"url":"https://uropenapi-qa.ur-inc.xyz","description":"Testnet (partner API)"}],"security":[{"partnerAuth":[]},{"userWalletAuth":[]}],"components":{"securitySchemes":{"partnerAuth":{"type":"apiKey","in":"header","name":"X-Api-Signature","description":"Partner Auth: EIP-191 signature by the partner's registered backend key, with X-Api-Deadline and optional X-Api-PublicKey headers. See the Signature and verify guide."},"userWalletAuth":{"type":"apiKey","in":"header","name":"sign","description":"User wallet auth (External Wallet Access Mode): EIP-191 signature by the user's wallet key, with tokenId, network, hash, and deadline headers. See the Signature and verify guide."}},"schemas":{"McTransactionsRequest":{"type":"object","properties":{"pageSize":{"type":"integer","description":"Page size. Defaults to 50; maximum is 100."},"type":{"type":"string","description":"Single transaction type filter. Do not send together with txTypes."},"txTypes":{"type":"array","items":{"type":"string"},"description":"Multiple transaction type filter. Do not send together with type."},"currencies":{"type":"array","items":{"type":"string"},"description":"Currency filter. Values are normalized to lowercase by UR."},"direction":{"type":"string","enum":["IN","OUT","ALL"],"description":"Direction filter."},"status":{"type":"string","description":"Transaction status filter."},"chainId":{"type":"string","description":"Chain ID filter, for example eip155:5000."},"tokenSymbol":{"type":"string","description":"Token symbol filter, for example USDC."},"minAmount":{"type":"string","description":"Minimum amount filter."},"maxAmount":{"type":"string","description":"Maximum amount filter."},"fromTimestamp":{"type":"integer","description":"Start timestamp filter."},"toTimestamp":{"type":"integer","description":"End timestamp filter."},"cursorTimestamp":{"type":"integer","description":"Next-page cursor timestamp from data.nextCursor.timestamp. Send only when hasNextPage is true."},"cursorId":{"type":"integer","description":"Next-page cursor ID from data.nextCursor.id. Send only when hasNextPage is true."},"prevCursorTimestamp":{"type":"integer","description":"Previous-page cursor timestamp from data.prevCursor.timestamp. Send only when hasPrevPage is true."},"prevCursorId":{"type":"integer","description":"Previous-page cursor ID from data.prevCursor.id. Send only when hasPrevPage is true."},"id":{"type":"integer","description":"Exact lookup by UR internal transaction ID. Mutually exclusive with txHash and reqId."},"txHash":{"type":"string","description":"Exact lookup by transaction hash. Mutually exclusive with id and reqId."},"reqId":{"type":"string","description":"Exact lookup by the idempotency key used when the transaction was created. Mutually exclusive with id and txHash."}}},"McTransactionsResponse":{"allOf":[{"$ref":"#/components/schemas/McBaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/McTransactionsData"}}}]},"McBaseResponse":{"type":"object","description":"Standard UR OpenAPI response envelope. code 0 means success; a non-zero code is a business error described by message.","required":["code","message"],"properties":{"code":{"type":"integer","description":"0 on success; non-zero business error code."},"message":{"type":"string","description":"Human-readable explanation. May be empty on success."}}},"McTransactionsData":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/McTransactionItem"}},"hasNextPage":{"type":"boolean","description":"True when a next page exists. Only then send nextCursor fields."},"hasPrevPage":{"type":"boolean","description":"True when a previous page exists. Only then send prevCursor fields; a zero cursor means there is no previous page."},"nextCursor":{"$ref":"#/components/schemas/McTransactionCursor"},"prevCursor":{"$ref":"#/components/schemas/McTransactionCursor"},"currentPageSize":{"type":"integer","description":"Number of items in this page."}}},"McTransactionItem":{"type":"object","properties":{"id":{"type":"integer","description":"UR internal transaction ID."},"txHash":{"type":"string","description":"On-chain transaction hash."},"txLogIndex":{"type":"integer","description":"Transaction log index."},"blockNumber":{"type":"integer","description":"Block number."},"createTimeE9":{"type":"integer","description":"Creation time in nanoseconds."},"broadcastTimeE9":{"type":"integer","description":"Broadcast time in nanoseconds."},"finalTimeE9":{"type":"integer","description":"Finalization time in nanoseconds."},"type":{"type":"string","enum":["CRYPTO_DEPOSIT","INTERNAL_TOKEN_TRANSFER","UNKNOWN","FX_EXCHANGE","MARQETA_AUTHORIZE","FIAT_WITHDRAW","FIAT_DEPOSIT","ONRAMP"],"description":"Transaction type. Determines the structure of detailsJson."},"chainId":{"type":"string","description":"Chain ID, for example eip155:5000."},"chainName":{"type":"string","description":"Chain name, for example Mantle."},"urId":{"type":"string","description":"The user's URID as a string."},"direction":{"type":"string","enum":["IN","OUT"],"description":"Transaction direction."},"amount":{"type":"string","description":"Signed amount as a decimal string."},"currency":{"type":"string","description":"Currency in lowercase."},"status":{"type":"string","enum":["UNKNOWN","INIT","PENDING","CONFIRMED","FAILED","PENDING_DROP","DROPPED","REJECTED"],"description":"Transaction status. CONFIRMED means settled on-chain; REJECTED means UR's validation or compliance checks rejected it."},"reqId":{"type":"string","description":"Idempotency key used when the transaction was created."},"detailsJson":{"type":"string","description":"Stringified JSON whose structure depends on type. Parse the string before reading nested fields."},"refundType":{"type":"string","enum":["","BANK_REFUND","CARD_REFUND","CARD_REVERSAL"],"description":"Refund discriminator. Empty string means not a refund."}}},"McTransactionCursor":{"type":"object","properties":{"timestamp":{"type":"integer","description":"Cursor timestamp."},"id":{"type":"integer","description":"Cursor ID."}}}}},"paths":{"/api/fma/v1/transactions":{"post":{"tags":["Managed Custody Mode"],"operationId":"mcFetchTransactions","summary":"Fetch transaction history","description":"Fetch paginated transaction history for reconciliation, or fetch a single transaction by sending exactly one of id, txHash, or reqId (mutually exclusive). The transaction webhook delivers the same transaction structure; parse detailsJson according to the transaction type.","parameters":[{"name":"X-Api-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed 65-byte hex EIP-191 signature over the Partner Auth message. See the Signature and verify guide."},{"name":"X-Api-Deadline","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds. UR rejects the request when the current time is past the deadline. Keep the validity window at or under 5 minutes."},{"name":"X-Api-PublicKey","in":"header","required":true,"schema":{"type":"string"},"description":"0x-prefixed partner signer address registered with UR."},{"name":"X-Ur-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."},{"name":"X-External-User-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Send at least one of X-Ur-Id or X-External-User-Id. When both are present, UR resolves the user by X-Ur-Id first."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McTransactionsRequest"}}}},"responses":{"200":{"description":"Standard envelope. Business errors return HTTP 200 with a non-zero code. For exact lookups, data.items is empty when no transaction matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McTransactionsResponse"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ur.app/api-reference/api/account/managed-custody-mode.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.