> 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/integration-methods/delegated-mode.md).

# Delegated Mode

{% hint style="warning" %}
**Will be deprecated soon.** Delegated Mode is no longer available for new integrations. Existing partners on this mode continue to be supported. New partners should use [Managed Custody Mode](/integration-methods/managed-custody-mode.md), which provides the same API-driven experience without the delegation ceremony.
{% endhint %}

In Delegated Mode, your platform interacts with UR through REST APIs. Users authenticate once via the UR Webview to complete KYC and grant delegation permissions. After that, your platform can operate their UR Account via API without requiring further user wallet signatures.

This mode is designed for partners who want a Web2-style integration with minimal blockchain exposure for their users.

## User onboarding

You redirect the user to a secure UR Webview. Within this Webview, the user completes identity verification (KYC), creates their UR Account and URID, and signs an approval to delegate access to your platform. Once complete, UR redirects the user back to your app with an authorization code.

Unlike External Wallet Access Mode, the user does not sign every action with a personal wallet; they perform a one-time delegation setup here.

**Authorization Flow Diagram**

```mermaid

sequenceDiagram
    participant User as User Browser
    participant Partner as Partner Server
    participant UR as UR Authorization Server
    participant MiniDapp as UR Mini Dapp

    Partner->>Partner: 1. Construct authorization URL
    Partner->>User: 2. Display authorization link
    User->>MiniDapp: 3. Click to visit authorization page
    Note over MiniDapp: 4. Parse URL parameters<br/>(client_id, redirect_uri, scope, state)
    User->>MiniDapp: 5. Complete KYC and authorization
    Note over UR: 6. Generate authorization code
    UR->>User: 7. Redirect to redirect_uri
    Note over User: redirect_uri?code=xxx&state=xxx
    User->>Partner: 8. Browser redirects to Partner
    Partner->>UR: 9. Call API to exchange code for user info<br/>(with signature verification)
    UR->>Partner: 10. Return user info and authorization details
    Partner->>User: 11. Complete business flow
```

**Flow Description:**

* **Initialization**: The user initiates the process on the Partner App. The Partner [constructs a standard OAuth-style Authorization URL](https://docs.ur.app/api-reference/account/delegated-contract-mode#authorization-url-construction) and redirects the user to UR.
* **Onboarding** (UR Side): The user lands on the secure UR Webview and authenticates via social login (Google or Email OTP, managed by the UR account system). A UR account is automatically created along with a unique URID. The user completes the KYC process (Liveness/ID scan) directly within the UR Webview. The initial status of the URID is set to "Tourist".
* **Delegation (Critical Step):** Upon submitting KYC data for review, UR prompts the user to grant permissions to the Delegated Contract that is dedicated to the Partner. This authorization enables the Partner to execute future actions (such as offramps) via API without requiring blockchain interaction for every transaction.
* **Account creation**: UR redirects the user back to the Partner's `redirect_uri` with an Authorization Code. The Partner App [to retrieve the user's `URID`, `ETH Address`, and status](https://docs.ur.app/api-reference/account/delegated-contract-mode#partner-to-fetch-user-onboarding-information), completing the binding process.
* **Finalization**: Once KYC has been approved, the URID status will become live. Follow up functions will be then unlocked for the user.
* **KYC retry**: This step is an **exception handling mechanism** and is not part of the standard workflow. Following the initial KYC submission, UR may occasionally flag specific verification steps for retry (e.g., due to document quality issues). This status is updated dynamically via the [profile](https://docs.ur.app/api-reference/account/delegated-contract-mode#fetch-ur-account-information) API. <mark style="color:$primary;">Best Practice: We recommend performing a status check on this field before the user initiates any UR-related features. The user should be redirected to</mark> [<mark style="color:$primary;">get.ur.app</mark>](https://get.ur.app) <mark style="color:$primary;">to complete the retry process if and only if the</mark> <mark style="color:$primary;">`kycRetryVerificationLevel`</mark> <mark style="color:$primary;">field returns a non-zero value.</mark><br>

## Card

Once the user completes onboarding and their URID status becomes **'Live'**, they are eligible for card issuance. Critical operations, such as card activation, revealing card details (PAN/CVV), and managing card settings, are performed by redirecting the user to the **UR Card Webview**. [`Refer to this document`](https://docs.ur.app/api-reference/account/delegated-contract-mode#card) for details of integrating the Card webview integration.

## Profile

Some users may need to view their IBAN information, so we provide an integration for the **Profile Webview**. Partners can integrate this webview into their app as either a webview or a dialog. For detailed integration instructions, please refer to [`this document`](https://docs.ur.app/api-reference/account/delegated-contract-mode#profile).

## Bank transfer

For users who need to move funds between their UR account and external bank accounts, we provide an integration for the **Bank Transfer Webview**. Partners can integrate this webview into their app as either a webview or a dialog. For detailed integration instructions, please refer to [`this document`](https://docs.ur.app/api-reference/account/delegated-contract-mode#bank-transfer).

## Core banking functions

### Crypto-to-fiat (off-ramp)

```mermaid
sequenceDiagram
    autonumber
    actor User
    participant App as Partner App
    participant UR as UR Backend
    participant Delegator as UR Delegator Contract
    participant Chain as UR Chain

    rect rgb(240, 248, 255)
    note right of User: Phase 1: Quotation
    User->>App: Request USDC offramp in my UR account (e.g. 100 USDC)
    App->>UR: POST /quote/deposit (Amount, Chain)
    UR-->>App: Return Quote<br/>(Exchange Rate, Fees, Est. Fiat Output, Error code)
    App-->>User: Display Estimated Fiat Received
    end

    rect rgb(255, 250, 240)
    note right of User: Phase 2: Permit & Execution
    User->>App: Confirm Transaction
    App->> Chain: Transfer USDC to User's UR account
    Chain->> App: Event: Transfer confirmed 

    App->>UR: API: Create Offramp Request

    UR->>Delegator: request offramp for the user's UR account 
    UR->>App: API response: TX hash
    App-->>User: Show "Status: Processing"
    end

    rect rgb(240, 255, 240)
    note right of User: Phase 3: Settlement
    UR->>Delegator: Start Monitoring (Listening for Event)
    alt Event Offramp Done (Within 5 mins)
        Delegator->>Chain: Done the offramp and send fiat to user's UR account
        Delegator-->>UR: Event: DepositSuccess
        UR->>App: Webhook: Offramp final status
        App-->>User: Show "Status: Success"

    else Timeout (No Webhook report > 5 mins)
        Note right of App: Monitoring exceeded time limit
        
            App->>UR: API: Report Timeout
            UR->>Ops: 🚨 Alert: Deposit Stuck (TxHash)
            Ops->>UR: Fix status
            UR->>App: Fix status
    end
    end
```

**Core Mechanism**

* **Quotation & Pricing**: The Partner requests a real-time exchange rate and fee structure via the [Offramp quote API](https://docs.ur.app/api-reference/account/delegated-contract-mode#fetch-offramp-quote). This ensures the user sees the exact estimated fiat output before confirming.
* **API-Driven Execution**: Once the user confirms the trade on the Partner's UI, the Partner triggers the transaction by calling the [Offramp API](https://docs.ur.app/api-reference/account/delegated-contract-mode#create-offramp-request). Critically, this step does not require a user wallet signature. The [Partner signs the API request](https://docs.ur.app/api-reference/signature-and-verify) using their [own key](https://docs.ur.app/api-reference/signature-and-verify#id-1.-generate-key-pair).
* **On-Chain Settlement**: UR's backend validates the request and triggers the Delegated Contract on the Mantle Network. The contract verifies the user's pre-authorized allowance, transfers the authorized crypto assets (e.g., USDC), and credits the user's UR account with the corresponding fiat balance (e.g., USD).
* **Asynchronous Notification**: Upon successful on-chain settlement, UR notifies the Partner via a [webhook](/developer-resources/webhook.md#event-transaction), allowing the Partner to update the user's UI to reflect the completed transaction.

### Fiat-to-crypto (on-ramp)

{% hint style="warning" %}
**Available soon.** On-ramp (fiat-to-crypto) is not yet available for integration and will be enabled in a future release. See [External Wallet Access Mode](/integration-methods/external-wallet-access-mode.md#on-ramp-flow-fiat-to-crypto) for the on-ramp implementation reference.
{% endhint %}

### Fiat-to-fiat (FX)

{% hint style="info" %}
Coming soon. See the [External Wallet Access Mode](/integration-methods/external-wallet-access-mode.md#fiat-to-fiat-fx) for the current FX implementation.
{% endhint %}

### Cash pay-in

{% hint style="info" %}
Coming soon. Users' bank account details can be retrieved via the Profile API. Currently, bank transfers are limited to same-name accounts in EUR and CHF only.
{% endhint %}

### Cash pay-out (bank transfer)

{% hint style="info" %}
Coming soon. See the [External Wallet Access Mode](/integration-methods/external-wallet-access-mode.md#cash-pay-out-bank-transfer) for the current bank transfer implementation.
{% endhint %}


---

# 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/integration-methods/delegated-mode.md?ask=<question>&goal=<endgoal>
```

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

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

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