> 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/models.md).

# Models

## The McBaseResponse object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"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."}}}}}}
```

## The McTxHashData object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}}
```

## The McTxHashResponse object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}}
```

## The McAccountStatusData object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}}
```

## The McAccountStatusResponse object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"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."}}}}}}
```

## The McApplyUsdPayinRequest object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"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."}}}}}}
```

## The McApplyUsdPayinData object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"McApplyUsdPayinData":{"type":"object","properties":{"applyId":{"type":"integer","description":"Identifier of the USD IBAN application."}}}}}}
```

## The McApplyUsdPayinResponse object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}}
```

## The McFiatLimits object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}}
```

## The McBrContact object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}}
```

## The McDepositBank object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The McCardActivation object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}}
```

## The McBrProfile object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The McBrResponse object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"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"}}}}}}
```

## The McFiatBalance object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"McFiatBalance":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string","description":"Fiat currency symbol."},"amount":{"type":"string","description":"Balance as a decimal string."}}}}}}
```

## The McBalanceData object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}}
```

## The McBalanceResponse object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"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."}}}}}}
```

## The McOfframpQuoteRequest object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"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."}}}}}}
```

## The McOfframpQuoteBest object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}}
```

## The McOfframpQuoteData object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}}
```

## The McOfframpQuoteResponse object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}}
```

## The McFxQuoteRequest object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"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."}}}}}}
```

## The McFxQuoteData object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}}
```

## The McFxQuoteResponse object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}}
```

## The McFxExchangeRequest object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"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."}}}}}}
```

## The McPayoutFeeItem object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}}
```

## The McPayoutFeesResponse object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"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."}}}}}}
```

## The McPayoutRefParams object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}}
```

## The McVerifyReferenceRequest object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"McVerifyReferenceRequest":{"type":"object","required":["reference"],"properties":{"reference":{"type":"string","description":"The payment reference to validate."}}}}}}
```

## The McVerifyReferenceResponse object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}}
```

## The McCreditorInfo object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The McVerifyContactRequest object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"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"}}}}}}
```

## The McVerifyContactData object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}}
```

## The McVerifyContactResponse object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}}
```

## The McPayoutMetadata object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}}
```

## The McSubmitPayoutRequest object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"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."}}}}}}
```

## The McOnrampLimitData object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}}
```

## The McOnrampLimitResponse object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"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."}}}}}}
```

## The McOnrampPendingRetryData object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}}
```

## The McOnrampPendingRetryResponse object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"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."}}}}}}
```

## The McOnrampQuoteRequest object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"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."}}}}}}
```

## The McOnrampQuoteBest object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}}
```

## The McOnrampQuoteData object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}}
```

## The McOnrampQuoteResponse object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}}
```

## The McLivenessTokenData object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}}
```

## The McLivenessTokenResponse object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"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."}}}}}}
```

## The McLivenessResultData object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}}
```

## The McLivenessResultResponse object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"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."}}}}}}
```

## The McOnrampRequest object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"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."}}}}}}
```

## The McOnrampSwapRequest object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"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."}}}}}}
```

## The McOnrampRetryCancelRequest object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"McOnrampRetryCancelRequest":{"type":"object","required":["originalTxHash"],"properties":{"originalTxHash":{"type":"string","description":"Original On-ramp transaction hash of the pending retry to cancel."}}}}}}
```

## The McCardSecurity object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"McCardSecurity":{"type":"object","properties":{"contactlessEnabled":{"type":"boolean"},"withdrawalEnabled":{"type":"boolean"},"internetPurchaseEnabled":{"type":"boolean"},"overallLimitsEnabled":{"type":"boolean"}}}}}}
```

## The McCardLimitItem object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}}
```

## The McCardLimits object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}}
```

## The McCardMasked object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The McCardTokenInfo object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The McCardData object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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"}}}}}}
```

## The McCardResponse object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"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"}}}}}}
```

## The McSetCardCurrencyRequest object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"McSetCardCurrencyRequest":{"type":"object","required":["currency"],"properties":{"currency":{"type":"string","description":"Target default transaction currency, such as USD, EUR, or CHF."}}}}}}
```

## The McUpdateCardStatusRequest object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"McUpdateCardStatusRequest":{"type":"object","required":["statusChange"],"properties":{"statusChange":{"type":"string","enum":["block","unblock"],"description":"The status transition to apply."}}}}}}
```

## The McTransactionsRequest object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"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."}}}}}}
```

## The McTransactionCursor object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"McTransactionCursor":{"type":"object","properties":{"timestamp":{"type":"integer","description":"Cursor timestamp."},"id":{"type":"integer","description":"Cursor ID."}}}}}}
```

## The McTransactionItem object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}}
```

## The McTransactionsData object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}}
```

## The McTransactionsResponse object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"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."}}}}}}
```

## The McPublicMetadataResponse object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"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."}}}}}}
```

## The EwaEnvelope object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"EwaEnvelope":{"type":"object","properties":{"retCode":{"type":"integer","description":"0 on success; non-zero indicates failure.","format":"int64"},"retMsg":{"type":"string","description":"Human-readable message; error details when retCode is non-zero."},"result":{"description":"Business payload. Shape depends on the endpoint; some endpoints return it as a JSON-encoded string."},"timeNow":{"type":"integer","description":"Server timestamp in milliseconds.","format":"int64"}},"required":["retCode","retMsg"],"description":"Standard response envelope for the user API (api.ur.app)."}}}}
```

## The DcEnvelope object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"DcEnvelope":{"type":"object","properties":{"code":{"type":"integer","description":"0 on success; non-zero indicates a business rejection.","format":"int64"},"message":{"type":"string","description":"Human-readable diagnostic; empty on success."},"data":{"description":"Business payload. Shape depends on the endpoint."}},"required":["code","message"],"description":"Standard response envelope for the partner API (openapi.ur.app)."}}}}
```

## The CardPrefundBalanceResponse object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"CardPrefundBalanceResponse":{"type":"object","description":"Standard response envelope for the Prefund balance endpoint. code 0 means success.","required":["code","message","data"],"properties":{"code":{"type":"integer","description":"0 on success; a non-zero value indicates a business rejection."},"message":{"type":"string","description":"Human-readable diagnostic; empty on success."},"data":{"$ref":"#/components/schemas/CardPrefundBalance"}}},"CardPrefundBalance":{"type":"object","description":"Current state of the partner's Prefund Account in its settlement currency.","required":["partnerId","account","currency","balance"],"properties":{"partnerId":{"type":"string","description":"Partner identifier registered with UR."},"account":{"type":"string","description":"On-chain address of the Prefund Account (Mantle)."},"currency":{"type":"string","description":"The settlement currency, agreed with UR (defaults to USD)."},"balance":{"type":"string","description":"Current balance, decimal string."},"minBalance":{"type":"string","description":"Minimum balance threshold. prefund.balance.alert fires when the balance reaches or falls below it."},"level":{"type":"string","enum":["normal","warning"],"description":"Balance level relative to minBalance. This endpoint emits normal (balance above minBalance) or warning (balance at or below minBalance) only."},"allowance":{"type":"string","description":"The card-spend contract allowance for this account, as a human-readable amount."},"updatedAt":{"type":"integer","format":"int64","description":"Unix seconds, last balance update."}}}}}}
```

## The CardPrefundBalance object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"CardPrefundBalance":{"type":"object","description":"Current state of the partner's Prefund Account in its settlement currency.","required":["partnerId","account","currency","balance"],"properties":{"partnerId":{"type":"string","description":"Partner identifier registered with UR."},"account":{"type":"string","description":"On-chain address of the Prefund Account (Mantle)."},"currency":{"type":"string","description":"The settlement currency, agreed with UR (defaults to USD)."},"balance":{"type":"string","description":"Current balance, decimal string."},"minBalance":{"type":"string","description":"Minimum balance threshold. prefund.balance.alert fires when the balance reaches or falls below it."},"level":{"type":"string","enum":["normal","warning"],"description":"Balance level relative to minBalance. This endpoint emits normal (balance above minBalance) or warning (balance at or below minBalance) only."},"allowance":{"type":"string","description":"The card-spend contract allowance for this account, as a human-readable amount."},"updatedAt":{"type":"integer","format":"int64","description":"Unix seconds, last balance update."}}}}}}
```

## The CardAuthorizationRequest object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"CardAuthorizationRequest":{"type":"object","description":"Signed authorization envelope UR sends to the partner-hosted endpoint. UR signs the raw JSON body with EIP-191 (X-Api-Signature, 0x-prefixed 65-byte hex) and sends its signer address in X-Api-PublicKey; the partner must verify the recovered signer equals the UR public key pinned during onboarding before acting. X-Request-Id matches data.requestId for logging.","required":["event","timestamp","data"],"properties":{"event":{"type":"string","const":"card_authorization","description":"Always card_authorization."},"timestamp":{"type":"integer","format":"int64","description":"Unix seconds when the request was built."},"data":{"$ref":"#/components/schemas/CardAuthorizationData"}}},"CardAuthorizationData":{"type":"object","description":"Authorization details for one card swipe.","required":["version","requestId","expiresAt","action","partnerId","userId","authorizationToken","transaction","settlement","merchant"],"properties":{"version":{"type":"string","description":"Protocol version. Currently \"1\"."},"requestId":{"type":"string","description":"UR-generated idempotency key. The partner must echo it back in the response and respond identically to retries with the same requestId."},"expiresAt":{"type":"integer","format":"int64","description":"Unix milliseconds. The partner should reject requests where expiresAt is in the past."},"action":{"type":"string","enum":["AUTHORIZE","INCREMENT"],"description":"AUTHORIZE for initial authorization, INCREMENT for an incremental authorization on the same transaction. For INCREMENT, return the same decision and paidCurrency as the original AUTHORIZE."},"partnerId":{"type":"string","description":"Partner identifier."},"userId":{"type":"string","description":"User's UR ID."},"authorizationToken":{"type":"string","description":"Card network authorization token."},"transaction":{"$ref":"#/components/schemas/CardAuthorizationMoney"},"settlement":{"$ref":"#/components/schemas/CardAuthorizationMoney"},"merchant":{"$ref":"#/components/schemas/CardAuthorizationMerchant"}}},"CardAuthorizationMoney":{"type":"object","description":"A currency and amount pair.","required":["currency","amount"],"properties":{"currency":{"type":"string","description":"ISO 4217 alpha currency code (e.g. SGD, USD, EUR)."},"amount":{"type":"string","description":"Amount as a string."}}},"CardAuthorizationMerchant":{"type":"object","description":"Merchant details from the card network.","properties":{"id":{"type":"string","description":"Merchant identifier."},"name":{"type":"string","description":"Merchant display name."},"mcc":{"type":"string","description":"Merchant category code."},"city":{"type":"string","description":"Merchant city."},"country":{"type":"string","description":"Merchant country code."}}}}}}
```

## The CardAuthorizationData object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"CardAuthorizationData":{"type":"object","description":"Authorization details for one card swipe.","required":["version","requestId","expiresAt","action","partnerId","userId","authorizationToken","transaction","settlement","merchant"],"properties":{"version":{"type":"string","description":"Protocol version. Currently \"1\"."},"requestId":{"type":"string","description":"UR-generated idempotency key. The partner must echo it back in the response and respond identically to retries with the same requestId."},"expiresAt":{"type":"integer","format":"int64","description":"Unix milliseconds. The partner should reject requests where expiresAt is in the past."},"action":{"type":"string","enum":["AUTHORIZE","INCREMENT"],"description":"AUTHORIZE for initial authorization, INCREMENT for an incremental authorization on the same transaction. For INCREMENT, return the same decision and paidCurrency as the original AUTHORIZE."},"partnerId":{"type":"string","description":"Partner identifier."},"userId":{"type":"string","description":"User's UR ID."},"authorizationToken":{"type":"string","description":"Card network authorization token."},"transaction":{"$ref":"#/components/schemas/CardAuthorizationMoney"},"settlement":{"$ref":"#/components/schemas/CardAuthorizationMoney"},"merchant":{"$ref":"#/components/schemas/CardAuthorizationMerchant"}}},"CardAuthorizationMoney":{"type":"object","description":"A currency and amount pair.","required":["currency","amount"],"properties":{"currency":{"type":"string","description":"ISO 4217 alpha currency code (e.g. SGD, USD, EUR)."},"amount":{"type":"string","description":"Amount as a string."}}},"CardAuthorizationMerchant":{"type":"object","description":"Merchant details from the card network.","properties":{"id":{"type":"string","description":"Merchant identifier."},"name":{"type":"string","description":"Merchant display name."},"mcc":{"type":"string","description":"Merchant category code."},"city":{"type":"string","description":"Merchant city."},"country":{"type":"string","description":"Merchant country code."}}}}}}
```

## The CardAuthorizationMoney object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"CardAuthorizationMoney":{"type":"object","description":"A currency and amount pair.","required":["currency","amount"],"properties":{"currency":{"type":"string","description":"ISO 4217 alpha currency code (e.g. SGD, USD, EUR)."},"amount":{"type":"string","description":"Amount as a string."}}}}}}
```

## The CardAuthorizationMerchant object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"CardAuthorizationMerchant":{"type":"object","description":"Merchant details from the card network.","properties":{"id":{"type":"string","description":"Merchant identifier."},"name":{"type":"string","description":"Merchant display name."},"mcc":{"type":"string","description":"Merchant category code."},"city":{"type":"string","description":"Merchant city."},"country":{"type":"string","description":"Merchant country code."}}}}}}
```

## The CardAuthorizationDecision object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"CardAuthorizationDecision":{"type":"object","description":"The partner's signed authorization decision. UR verifies the partner's EIP-191 signature and rejects mismatched requestId, missing decisionId, invalid decision values, or a missing paidCurrency on APPROVE; each failure declines the swipe.","required":["requestId","decisionId","decision"],"properties":{"requestId":{"type":"string","description":"Must match data.requestId from the request. UR rejects mismatches."},"decisionId":{"type":"string","description":"Partner-generated unique ID for this decision. Used for audit trail and reconciliation."},"decision":{"type":"string","enum":["APPROVE","DECLINE","PASS"],"description":"APPROVE settles against the Prefund Account in paidCurrency (UR still performs final balance, limit, compliance, and Prefund checks and may override to decline). DECLINE rejects the authorization. PASS falls back to the user's own UR fiat balance with no Prefund debit. Any other value is treated as an error and UR declines."},"paidCurrency":{"type":"string","description":"Required on APPROVE: a currency in the Prefund Account (in fixed mode it must equal settlement.currency from the request). On PASS: a currency in the user's UR fiat balance, or empty to let UR select the currency. Not used on DECLINE."},"reason":{"type":"string","description":"Optional reconciliation code, e.g. ok, insufficient_user_crypto, insufficient_partner_prefund, user_blocked, merchant_blocked, card_disabled, internal_error."}}}}}}
```

## The CardTransactionWebhook object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"CardTransactionWebhook":{"type":"object","description":"Webhook envelope for post-swipe card payment transactions. UR signs the raw body with EIP-191; verify the recovered signer against UR's public key before acting on the payload.","required":["event","data","timestamp"],"properties":{"event":{"type":"string","const":"transaction_v2","description":"Always transaction_v2."},"data":{"$ref":"#/components/schemas/CardTransactionData"},"timestamp":{"type":"integer","format":"int64","description":"Unix seconds when the event was emitted."}}},"CardTransactionData":{"type":"object","description":"Card payment transaction record. Card payments use type MARQETA_AUTHORIZE; the same event covers successful and failed payments.","required":["id","type","status"],"properties":{"id":{"type":"integer","format":"int64","description":"UR transaction record ID. Use this field as the idempotency key for transaction_v2 delivery."},"txHash":{"type":"string","description":"On-chain transaction hash when available."},"blockNumber":{"type":"integer","format":"int64","description":"Block number of the on-chain transaction."},"createTimeE9":{"type":"integer","format":"int64","description":"Creation time, Unix nanoseconds."},"broadcastTimeE9":{"type":"integer","format":"int64","description":"Broadcast time, Unix nanoseconds."},"finalTimeE9":{"type":"integer","format":"int64","description":"Finalization time, Unix nanoseconds."},"type":{"type":"string","description":"Card payment transactions use MARQETA_AUTHORIZE."},"chainId":{"type":"string","description":"CAIP-2 chain identifier (e.g. eip155:5000)."},"chainName":{"type":"string","description":"Chain short name (e.g. MNT)."},"urId":{"type":"string","description":"User's UR ID."},"direction":{"type":"string","description":"OUT for card spend."},"amount":{"type":"string","description":"Amount recorded on the transaction row."},"currency":{"type":"string","description":"Currency recorded on the transaction row."},"status":{"type":"string","description":"Terminal transaction status, such as CONFIRMED or FAILED."},"detailsJson":{"type":"string","description":"Stringified JSON with card payment details (authorizationId, balance, cardCurrency, cardId, city, country, mcc, merchant, merchantId, settlementAmount, settlementCurrency, transactionAmount, transactionCurrency, and reason on failures). Parse this value before reading nested fields."}}}}}}
```

## The CardTransactionData object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"CardTransactionData":{"type":"object","description":"Card payment transaction record. Card payments use type MARQETA_AUTHORIZE; the same event covers successful and failed payments.","required":["id","type","status"],"properties":{"id":{"type":"integer","format":"int64","description":"UR transaction record ID. Use this field as the idempotency key for transaction_v2 delivery."},"txHash":{"type":"string","description":"On-chain transaction hash when available."},"blockNumber":{"type":"integer","format":"int64","description":"Block number of the on-chain transaction."},"createTimeE9":{"type":"integer","format":"int64","description":"Creation time, Unix nanoseconds."},"broadcastTimeE9":{"type":"integer","format":"int64","description":"Broadcast time, Unix nanoseconds."},"finalTimeE9":{"type":"integer","format":"int64","description":"Finalization time, Unix nanoseconds."},"type":{"type":"string","description":"Card payment transactions use MARQETA_AUTHORIZE."},"chainId":{"type":"string","description":"CAIP-2 chain identifier (e.g. eip155:5000)."},"chainName":{"type":"string","description":"Chain short name (e.g. MNT)."},"urId":{"type":"string","description":"User's UR ID."},"direction":{"type":"string","description":"OUT for card spend."},"amount":{"type":"string","description":"Amount recorded on the transaction row."},"currency":{"type":"string","description":"Currency recorded on the transaction row."},"status":{"type":"string","description":"Terminal transaction status, such as CONFIRMED or FAILED."},"detailsJson":{"type":"string","description":"Stringified JSON with card payment details (authorizationId, balance, cardCurrency, cardId, city, country, mcc, merchant, merchantId, settlementAmount, settlementCurrency, transactionAmount, transactionCurrency, and reason on failures). Parse this value before reading nested fields."}}}}}}
```

## The CardPrefundBalanceAlertWebhook object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"CardPrefundBalanceAlertWebhook":{"type":"object","description":"Webhook envelope for Prefund balance level changes. UR signs the raw body with EIP-191; verify the recovered signer against UR's public key before acting on the payload.","required":["event","data","timestamp"],"properties":{"event":{"type":"string","const":"prefund.balance.alert","description":"Always prefund.balance.alert."},"data":{"$ref":"#/components/schemas/CardPrefundBalanceAlertData"},"timestamp":{"type":"integer","format":"int64","description":"Unix seconds when the event was emitted."}}},"CardPrefundBalanceAlertData":{"type":"object","description":"Balance level change for one settlement currency in the Prefund Account. If two currencies cross a threshold, UR sends two events.","required":["partnerId","account","currency","balance","minBalance","previousLevel","level","updatedAt"],"properties":{"partnerId":{"type":"string","description":"Partner identifier registered with UR."},"account":{"type":"string","description":"On-chain address of the Prefund Account (Mantle)."},"currency":{"type":"string","description":"The settlement currency this alert is about."},"balance":{"type":"string","description":"Balance in that currency at the moment the level changed."},"minBalance":{"type":"string","description":"The threshold configured for that currency."},"previousLevel":{"type":"string","enum":["normal","warning","critical"],"description":"The level before this change."},"level":{"type":"string","enum":["normal","warning","critical"],"description":"The level after this change. critical means the next swipe in that currency is at real risk of declining."},"updatedAt":{"type":"integer","format":"int64","description":"Unix seconds, the balance update that triggered the alert."}}}}}}
```

## The CardPrefundBalanceAlertData object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"CardPrefundBalanceAlertData":{"type":"object","description":"Balance level change for one settlement currency in the Prefund Account. If two currencies cross a threshold, UR sends two events.","required":["partnerId","account","currency","balance","minBalance","previousLevel","level","updatedAt"],"properties":{"partnerId":{"type":"string","description":"Partner identifier registered with UR."},"account":{"type":"string","description":"On-chain address of the Prefund Account (Mantle)."},"currency":{"type":"string","description":"The settlement currency this alert is about."},"balance":{"type":"string","description":"Balance in that currency at the moment the level changed."},"minBalance":{"type":"string","description":"The threshold configured for that currency."},"previousLevel":{"type":"string","enum":["normal","warning","critical"],"description":"The level before this change."},"level":{"type":"string","enum":["normal","warning","critical"],"description":"The level after this change. critical means the next swipe in that currency is at real risk of declining."},"updatedAt":{"type":"integer","format":"int64","description":"Unix seconds, the balance update that triggered the alert."}}}}}}
```

## The KycCreateAccountRequest object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"KycCreateAccountRequest":{"type":"object","description":"Body for create-account. The user's identity travels in the X-External-User-Id header, not the body. Do not send a Sumsub applicantId on either KYC path; the applicant is assigned or handed off later.","required":["email"],"properties":{"email":{"type":"string","description":"The user's email address. Must be unique across UR partners; reusing the same email under a different partner returns L1_CONFLICT (code 30015)."},"nationality":{"type":"string","description":"ISO 3166-1 alpha-3 country code. Sending it lets UR fail country gates before the URID is minted."},"residency":{"type":"string","description":"ISO 3166-1 alpha-3 country code of residence."},"dob":{"type":"string","description":"Date of birth in YYYY-MM-DD format."},"documentExpiry":{"type":"string","description":"Passport or ID expiry date in YYYY-MM-DD format."}}}}}}
```

## The KycCreateAccountResponse object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"KycCreateAccountResponse":{"type":"object","properties":{"code":{"type":"integer","description":"Business result code. 0 means success; business rejections return HTTP 200 with a non-zero code."},"message":{"type":"string","description":"Human-readable diagnostic for non-zero codes."},"data":{"type":"object","properties":{"sessionId":{"type":"string","description":"UUID for this onboarding attempt. Constant for the lifetime of the attempt; use it in every subsequent KYC endpoint."},"urId":{"type":"integer","format":"int64","description":"The user's URID, equal to the on-chain NFT token id. Stable for the user's lifetime across all retries."},"evmAddress":{"type":"string","description":"The user's UR-managed wallet address. Form A is signed by this address."},"state":{"type":"string","description":"Session entry state: ConfirmYourCountryOfResidence on the SDK path, PartnerDataIngestion on the shared-token path."},"idempotentReplay":{"type":"boolean","description":"True when an active onboarding session already exists for (partnerId, X-External-User-Id). The existing session is returned unchanged so repeated calls cannot mint duplicate URIDs."}}}}}}}}
```

## The KycSumsubAccessTokenRequest object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"KycSumsubAccessTokenRequest":{"type":"object","description":"Empty body by design. UR reads urId from the X-Ur-Id header and resolves the active onboarding session server-side.","additionalProperties":false,"properties":{}}}}}
```

## The KycSumsubAccessTokenResponse object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"KycSumsubAccessTokenResponse":{"type":"object","properties":{"code":{"type":"integer","description":"Business result code. 0 means success; business rejections return HTTP 200 with a non-zero code."},"message":{"type":"string","description":"Human-readable diagnostic for non-zero codes."},"data":{"type":"object","properties":{"token":{"type":"string","description":"Sumsub access token with a 20 minute TTL. Pass this string to the Sumsub SDK constructor on the user device."}}}}}}}}
```

## The KycSessionCurrentResponse object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"KycSessionCurrentResponse":{"type":"object","properties":{"code":{"type":"integer","description":"Business result code. 0 means success; business rejections return HTTP 200 with a non-zero code."},"message":{"type":"string","description":"Human-readable diagnostic for non-zero codes."},"data":{"type":"object","properties":{"sessionId":{"type":"string","description":"UUID of the active onboarding session."},"flowId":{"type":"integer","format":"int64","description":"Internal flow id for the session."},"retryLevel":{"type":"integer","format":"int64","description":"Increments each time the user starts a fresh onboarding attempt after a previous one terminated."},"state":{"type":"string","description":"Current session state, in onboarding order: ConfirmYourCountryOfResidence, AddressProof, UnderstandRisk, LiabilityWaiver, IdOrPassportOrOtherIdInformationScan, IdAndLiveness, SignFormA, Register. Treat any unlisted value as an in-progress state. Terminal outcomes are reported by the fma.account.result webhook, after which this endpoint returns NO_ACTIVE_SESSION (code 30031)."},"dataChannel":{"type":"string","description":"Onboarding path of the session; sdk for the Sumsub SDK path. Any other value indicates a partner configuration issue for that path."},"createdAt":{"type":"integer","format":"int64","description":"Session creation time, Unix seconds."},"lastUserActivityAt":{"type":"integer","format":"int64","description":"Last user activity time, Unix seconds."}}}}}}}}
```

## The KycReuseShareTokenRequest object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"KycReuseShareTokenRequest":{"type":"object","required":["shareToken"],"properties":{"shareToken":{"type":"string","description":"Single-use Sumsub share token minted in your tenant with forClientId set to UR's clientId, valid for about 20 minutes. Mint a fresh token for every handoff attempt."}}}}}}
```

## The KycReuseShareTokenResponse object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"KycReuseShareTokenResponse":{"type":"object","properties":{"code":{"type":"integer","description":"Business result code. 0 means success; business rejections return HTTP 200 with a non-zero code."},"message":{"type":"string","description":"Human-readable diagnostic for non-zero codes."},"data":{"type":"object","properties":{"status":{"type":"string","enum":["passed","incomplete","terminal"],"description":"Conclusive verdict for this handoff attempt. The envelope code mirrors it: passed maps to code 0, incomplete to 20004, terminal to a numeric eligibility code (30010, 30011, or 30012)."},"applicantId":{"type":"string","description":"The imported applicant id in UR's Sumsub tenant. Present once the applicant is copied."},"attempt":{"type":"integer","format":"int64","description":"1-indexed handoff attempt within this session."},"missingFields":{"type":"array","items":{"type":"string"},"description":"Present on incomplete; machine paths of the gaps the user must remediate in your workflow."}}}}}}}}
```

## The KycCheckRequest object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"KycCheckRequest":{"type":"object","required":["sessionId"],"properties":{"sessionId":{"type":"string","description":"The onboarding session UUID returned by create-account."}}}}}}
```

## The KycCheckResponse object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"KycCheckResponse":{"type":"object","properties":{"code":{"type":"integer","description":"Business result code. 0 means success; business rejections return HTTP 200 with a non-zero code."},"message":{"type":"string","description":"Human-readable diagnostic for non-zero codes."},"data":{"type":"object","properties":{"state":{"type":"string","description":"Current session state."},"complete":{"type":"boolean","description":"True when the staged KYC data is complete and the session can proceed."},"missingFields":{"type":"array","items":{"type":"string"},"description":"Machine paths of the fields the completeness check found missing. Empty or omitted when the session is complete."}}}}}}}}
```

## The KycFormAInfoResponse object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"KycFormAInfoResponse":{"type":"object","properties":{"code":{"type":"integer","description":"Business result code. 0 means success; business rejections return HTTP 200 with a non-zero code."},"message":{"type":"string","description":"Human-readable diagnostic for non-zero codes."},"data":{"type":"object","properties":{"formAVersion":{"type":"string","description":"Current Form A template version. Pin this in your audit trail."},"text":{"type":"string","description":"The Markdown text the user must consent to. Render exactly as returned."},"textHash":{"type":"string","description":"0x-prefixed Keccak-256 hash of the UTF-8 text bytes. Pass it back unchanged in sign-form so UR can detect tampering between render and sign."}}}}}}}}
```

## The KycSignFormRequest object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"KycSignFormRequest":{"type":"object","required":["sessionId","textHash"],"properties":{"sessionId":{"type":"string","description":"The onboarding session UUID returned by create-account."},"textHash":{"type":"string","description":"The textHash from the latest form-a-info render. Must match the current render or the call fails with FORMA_TEXT_MISMATCH (code 20005)."}}}}}}
```

## The KycSignFormResponse object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"KycSignFormResponse":{"type":"object","properties":{"code":{"type":"integer","description":"Business result code. 0 means success; business rejections return HTTP 200 with a non-zero code."},"message":{"type":"string","description":"Human-readable diagnostic for non-zero codes."},"data":{"type":"object","properties":{"state":{"type":"string","description":"Still SignFormA after a successful sign; only submit advances the session."},"signature":{"type":"string","description":"Hex signature over the Form A text, produced by the UR-managed wallet."},"signerAddress":{"type":"string","description":"The UR-managed TurnKey wallet that signed. Equals the evmAddress from create-account."}}}}}}}}
```

## The KycSubmitRequest object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"KycSubmitRequest":{"type":"object","required":["sessionId"],"properties":{"sessionId":{"type":"string","description":"The onboarding session UUID returned by create-account."}}}}}}
```

## The KycSubmitResponse object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"KycSubmitResponse":{"type":"object","properties":{"code":{"type":"integer","description":"Business result code. 0 means success; business rejections return HTTP 200 with a non-zero code."},"message":{"type":"string","description":"Human-readable diagnostic for non-zero codes."},"data":{"type":"object","properties":{"state":{"type":"string","description":"Submitting on success; UR's background scheduler now owns the session."},"queued":{"type":"boolean","description":"False is the success signal for these KYC paths; UR can proceed with bank activation immediately without further user action."},"awaitingPenny":{"type":"boolean","description":"False on the documented KYC paths."}}}}}}}}
```

## The KycRequiredLevel object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"KycRequiredLevel":{"type":"object","description":"Groups missing fields into a cloned-workflow level the user must rerun on your side. Present only on incomplete verdicts.","properties":{"levelName":{"type":"string","description":"Name of the Sumsub level in your cloned workflow."},"action":{"type":"string","description":"Remediation action; always RERUN_LEVEL in v1."},"fields":{"type":"array","items":{"type":"string"},"description":"Machine paths of the missing fields covered by this level."}}}}}}
```

## The KycEwaReuseShareTokenRequest object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"KycEwaReuseShareTokenRequest":{"type":"object","required":["shareToken","urId"],"properties":{"shareToken":{"type":"string","description":"Single-use Sumsub share token minted in your tenant with forClientId set to UR's clientId. Mint a fresh token for every handoff attempt."},"urId":{"type":"integer","format":"int64","description":"The user's URID (NFT token id). Travels in the body in External Wallet Access Mode."}}}}}}
```

## The KycEwaReuseShareTokenResponse object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"KycEwaReuseShareTokenResponse":{"type":"object","properties":{"code":{"type":"integer","description":"Business result code. 0 means success; business rejections return HTTP 200 with a non-zero code."},"message":{"type":"string","description":"Human-readable diagnostic for non-zero codes."},"data":{"type":"object","properties":{"status":{"type":"string","enum":["passed","incomplete","terminal"],"description":"Conclusive verdict for this handoff attempt. The envelope code mirrors it: passed maps to code 0, incomplete to 20004, terminal to a numeric eligibility code (30010, 30011, or 30012)."},"applicantId":{"type":"string","description":"The imported applicant id in UR's Sumsub tenant."},"sessionId":{"type":"string","description":"Onboarding session UUID, for audit correlation. The first handoff lazily creates the session."},"attempt":{"type":"integer","format":"int64","description":"1-indexed handoff attempt within this session."},"missingFields":{"type":"array","items":{"type":"string"},"description":"Present on incomplete; machine paths of the gaps the user must remediate in your workflow."},"requiredLevels":{"type":"array","items":{"$ref":"#/components/schemas/KycRequiredLevel"},"description":"Present on incomplete; the cloned-workflow levels the user must rerun."}}}}},"KycRequiredLevel":{"type":"object","description":"Groups missing fields into a cloned-workflow level the user must rerun on your side. Present only on incomplete verdicts.","properties":{"levelName":{"type":"string","description":"Name of the Sumsub level in your cloned workflow."},"action":{"type":"string","description":"Remediation action; always RERUN_LEVEL in v1."},"fields":{"type":"array","items":{"type":"string"},"description":"Machine paths of the missing fields covered by this level."}}}}}}
```

## The KycEwaCheckRequest object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"KycEwaCheckRequest":{"type":"object","required":["urId"],"properties":{"urId":{"type":"integer","format":"int64","description":"The user's URID (NFT token id)."}}}}}}
```

## The KycEwaCheckResponse object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"KycEwaCheckResponse":{"type":"object","properties":{"code":{"type":"integer","description":"Business result code. 0 means success; business rejections return HTTP 200 with a non-zero code."},"message":{"type":"string","description":"Human-readable diagnostic for non-zero codes."},"data":{"type":"object","properties":{"state":{"type":"string","description":"Current session state."},"complete":{"type":"boolean","description":"True when the shared KYC data is complete."},"missingFields":{"type":"array","items":{"type":"string"},"description":"Machine paths of the missing fields. Empty or omitted when complete."},"requiredLevels":{"type":"array","items":{"$ref":"#/components/schemas/KycRequiredLevel"},"description":"Present on incomplete; the cloned-workflow levels the user must rerun."},"sessionId":{"type":"string","description":"Onboarding session UUID."}}}}},"KycRequiredLevel":{"type":"object","description":"Groups missing fields into a cloned-workflow level the user must rerun on your side. Present only on incomplete verdicts.","properties":{"levelName":{"type":"string","description":"Name of the Sumsub level in your cloned workflow."},"action":{"type":"string","description":"Remediation action; always RERUN_LEVEL in v1."},"fields":{"type":"array","items":{"type":"string"},"description":"Machine paths of the missing fields covered by this level."}}}}}}
```

## The KycEwaSubmitRequest object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"KycEwaSubmitRequest":{"type":"object","required":["urId"],"properties":{"urId":{"type":"integer","format":"int64","description":"The user's URID (NFT token id)."}}}}}}
```

## The KycEwaSubmitResponse object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"KycEwaSubmitResponse":{"type":"object","properties":{"code":{"type":"integer","description":"Business result code. 0 means success; business rejections return HTTP 200 with a non-zero code."},"message":{"type":"string","description":"Human-readable diagnostic for non-zero codes."},"data":{"type":"object","properties":{"state":{"type":"string","description":"Session state after submit; the register runs asynchronously from here."},"sessionId":{"type":"string","description":"Onboarding session UUID."}}}}}}}}
```

## The KycByNetworkRequest object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"KycByNetworkRequest":{"type":"object","required":["tokenId","network"],"properties":{"tokenId":{"type":"string","description":"URID NFT token id."},"network":{"type":"string","description":"Network or chain identifier, for example 5000 or 11155111."}}}}}}
```

## The KycAccessTokenByNetworkResponse object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"KycAccessTokenByNetworkResponse":{"type":"object","properties":{"code":{"type":"integer","description":"Business result code. 0 means success; business rejections return HTTP 200 with a non-zero code."},"message":{"type":"string","description":"Human-readable diagnostic for non-zero codes."},"data":{"type":"object","properties":{"token":{"type":"string","description":"Sumsub access token, usually starting with act-. Used to initialize the Sumsub SDK. This endpoint returns only the token; it does not return a Sumsub applicant id."}}}}}}}}
```

## The KycSumsubStatusByNetworkResponse object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"KycSumsubStatusByNetworkResponse":{"type":"object","properties":{"code":{"type":"integer","description":"Business result code. 0 means success; business rejections return HTTP 200 with a non-zero code."},"message":{"type":"string","description":"Human-readable diagnostic for non-zero codes."},"data":{"type":"object","description":"Latest Sumsub webhook-derived state. An empty object when UR has not yet received a Sumsub webhook for that tokenId and network.","properties":{"type":{"type":"string","description":"Sumsub webhook type, for example applicantWorkflowCompleted."},"reviewStatus":{"type":"string","description":"Review status, for example init, pending, completed."},"reviewAnswer":{"type":"string","description":"Review answer: GREEN for success, RED for failure."},"reviewRejectType":{"type":"string","description":"Rejection type, for example FINAL or RETRY."},"levelName":{"type":"string","description":"Sumsub level name."},"rejectLabels":{"type":"array","items":{"type":"string"},"description":"Rejection labels when applicable."},"applicantId":{"type":"string","description":"Sumsub applicant id."},"applicantType":{"type":"string","description":"Applicant type, for example individual."},"createdAtMs":{"type":"integer","format":"int64","description":"Event time in milliseconds."}}}}}}}}
```

## The KycAccountResultEvent object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"KycAccountResultEvent":{"type":"object","description":"Envelope for the fma.account.result webhook. Delivery metadata, including the idempotency id, travels in X-Webhook-* headers, not in the body.","required":["event","data","timestamp"],"properties":{"event":{"type":"string","const":"fma.account.result"},"timestamp":{"type":"integer","format":"int64","description":"Delivery timestamp, Unix seconds."},"data":{"type":"object","required":["urId","sessionId","partnerId","status","occurredAt"],"properties":{"urId":{"type":"integer","format":"int64","description":"The user's URID."},"sessionId":{"type":"string","description":"The onboarding session this outcome belongs to."},"partnerId":{"type":"string","description":"Your partner id."},"status":{"type":"string","enum":["activated","rejected"],"description":"Terminal onboarding outcome."},"occurredAt":{"type":"integer","format":"int64","description":"Outcome time, Unix seconds."},"rejectCode":{"type":"string","description":"Present when status is rejected. Common values: SUMSUB_REJECTED, KYC_REJECTED, SESSION_EXPIRED, NATIONALITY_RESTRICTED, RESIDENCY_UNSUPPORTED."},"rejectReason":{"type":"string","description":"Human-readable rejection detail. Present when status is rejected."}}}}}}}}
```

## The KycReuseCheckResultEvent object

```json
{"openapi":"3.1.0","info":{"title":"UR API","version":"1.0.0"},"components":{"schemas":{"KycReuseCheckResultEvent":{"type":"object","description":"Envelope for the fma.kyc.reuse_check.result webhook, the async mirror of a shared-token handoff attempt's verdict. Idempotency business key: {urId}:kyc:reuse_check:{attempt}.","required":["event","data","timestamp"],"properties":{"event":{"type":"string","const":"fma.kyc.reuse_check.result"},"timestamp":{"type":"integer","format":"int64","description":"Delivery timestamp, Unix seconds."},"data":{"type":"object","required":["urId","partnerId","sessionId","attempt","status","occurredAt"],"properties":{"urId":{"type":"integer","format":"int64","description":"The user's URID."},"partnerId":{"type":"string","description":"Your partner id."},"sessionId":{"type":"string","description":"The onboarding session this attempt belongs to."},"attempt":{"type":"integer","format":"int64","description":"1-indexed handoff attempt within the session."},"status":{"type":"string","enum":["passed","incomplete"],"description":"Attempt verdict. Terminal verdicts are not webhooked in v1."},"missingFields":{"type":"array","items":{"type":"string"},"description":"Present on incomplete; omitted on passed."},"requiredLevels":{"type":"array","items":{"$ref":"#/components/schemas/KycRequiredLevel"},"description":"Present on incomplete; omitted on passed."},"occurredAt":{"type":"integer","format":"int64","description":"Verdict time, Unix seconds."},"correlationId":{"type":"string","description":"Correlation id for tracing this attempt."}}}}},"KycRequiredLevel":{"type":"object","description":"Groups missing fields into a cloned-workflow level the user must rerun on your side. Present only on incomplete verdicts.","properties":{"levelName":{"type":"string","description":"Name of the Sumsub level in your cloned workflow."},"action":{"type":"string","description":"Remediation action; always RERUN_LEVEL in v1."},"fields":{"type":"array","items":{"type":"string"},"description":"Machine paths of the missing fields covered by this level."}}}}}}
```


---

# 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/models.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.