# Agent Checkouts Quickstart ⚡
Source: https://docs.crossmint.com/agents/agent-checkouts-quickstart

Start a checkout, answer buyer requests, and read the result

Send the agent a product URL and a task. It navigates the merchant's checkout, asks your application for missing inputs or payment authorization, and returns the purchase result.

<CardGroup>
  <Card title="Try the Live Demo" icon="rocket" href="https://agent-commerce.demos-crossmint.com/">
    Explore the complete experience in a working app
  </Card>

  <Card title="View the Sample App" icon="github" href="https://github.com/Crossmint/agent-commerce-sample-app">
    Use the full integration as a reference for your app
  </Card>
</CardGroup>

## Prerequisites

* **API key**: A production server-side key with `agent-checkouts.create`, `agent-checkouts.read`, `agent-checkouts.update`, and `agent-checkouts.cancel` scopes from the <a href="https://www.crossmint.com/console/projects/apiKeys">Crossmint Console</a>
* **Buyer identity**: A stable identifier for your user, sent as `x-crossmint-user-id` on every request
* **Purchase task**: A product URL, the variant and quantity to buy, and a spending cap
* **Card authorization**: To complete a card purchase, a [saved](/agents/payment-methods/cards/save-card) and [registered](/agents/payment-methods/cards/register-card) card, plus a client-side key and buyer JWT as described in [Authorize Payments](/agents/checkouts/payments)

Use the same user ID as your JWT's configured user ID claim (`sub` by default), so the checkout and its card authorization belong to the same buyer.

Agent Checkouts does not support staging. These examples run on your backend; keep the server key out of browser code. For direct browser calls, see [Authenticate Each Request](/agents/checkouts/follow-run#authenticate-each-request).

<Warning>Agent Checkouts and the live demo can place real orders. Use a task and spending cap that you intend to authorize.</Warning>

## Run a Checkout

<Steps>
  <Step title="Start the checkout">
    Set these variables in your terminal. Reuse them in the following steps:

    ```bash theme={null}
    export CROSSMINT_API_KEY="YOUR_SERVER_API_KEY"
    export CROSSMINT_USER_ID="YOUR_USER_ID"
    export CHECKOUT_API="https://www.crossmint.com/api/unstable/agent-checkouts"
    ```

    Replace the sample URL and task with your intended purchase, then create a run:

    ```bash cURL theme={null}
    curl --fail-with-body --request POST "$CHECKOUT_API" \
        --header "X-API-KEY: $CROSSMINT_API_KEY" \
        --header "x-crossmint-user-id: $CROSSMINT_USER_ID" \
        --header "Content-Type: application/json" \
        --data '{
            "request": {
                "startUrl": "https://merchant.example/products/classic-tee",
                "task": "Buy one black Classic Tee in size medium. Use standard delivery and pay by card."
            },
            "constraints": {
                "maxCost": { "amount": "100.00", "currency": "USD" }
            }
        }'
    ```

    The response contains a `runId`. Save it for subsequent calls:

    ```bash theme={null}
    export RUN_ID="YOUR_RETURNED_RUN_ID"
    ```

    To prefill shipping details or set the browser country, see [Configure a Checkout](/agents/checkouts/configure).
  </Step>

  <Step title="Read the run">
    Read its current status and any request waiting for your application:

    ```bash cURL theme={null}
    curl --fail-with-body "$CHECKOUT_API/$RUN_ID" \
        --header "X-API-KEY: $CROSSMINT_API_KEY" \
        --header "x-crossmint-user-id: $CROSSMINT_USER_ID"
    ```

    While the run is active, repeat this read every 2 seconds. When `status` is `"awaiting_input"`, handle `requiredAction`. Your application chooses how to present the request: in a web page, a native app, or a conversation.

    | `requiredAction.request.interaction.kind` | What your application does |
    | - | - |
    | `form` | Collect the requested fields. Use ordinary controls for `handling: "standard"` and `CrossmintProtectedInput` for `handling: "protected"`. |
    | `payment` | For `method: "card"`, authorize the buyer's saved card with an order intent. For `method: "klarna"`, show the buyer the request's `authorizationUrl` and send no answer. |

    For live updates and conversation history, see [Follow a Run](/agents/checkouts/follow-run). You can optionally display the agent's browser using `run.browser.embedUrl` once `run.browser` is available.
  </Step>

  <Step title="Answer the request">
    Copy `requiredAction.requestId` into your response. For example, if a form requests a standard field whose `key` is `email`, send the buyer's answer:

    ```bash cURL theme={null}
    curl --fail-with-body --request POST "$CHECKOUT_API/$RUN_ID/messages" \
        --header "X-API-KEY: $CROSSMINT_API_KEY" \
        --header "x-crossmint-user-id: $CROSSMINT_USER_ID" \
        --header "Content-Type: application/json" \
        --data '{
            "id": "answer_email_001",
            "parts": [{
                "type": "input_response",
                "requestId": "YOUR_FORM_REQUEST_ID",
                "action": "submit",
                "response": { "kind": "form", "answers": { "email": "buyer@example.com" } }
            }]
        }'
    ```

    Each submission answers the complete request: include all required fields, and omit optional fields left unanswered. [Handle Buyer Inputs](/agents/checkouts/buyer-inputs) shows the field types, ordinary rendering, and protected collection.

    When the agent asks for a card payment, follow [Authorize Payments](/agents/checkouts/payments) to create an order intent for the request's amount and merchant using the same buyer's saved card. Complete any verification, then submit this body to the same messages endpoint:

    ```json theme={null}
    {
        "id": "answer_payment_001",
        "parts": [{
            "type": "input_response",
            "requestId": "YOUR_PAYMENT_REQUEST_ID",
            "action": "submit",
            "response": { "kind": "payment", "orderIntentId": "YOUR_ORDER_INTENT_ID" }
        }]
    }
    ```

    Use a unique message `id` for each answer. If you retry after a lost acknowledgement, resend the same ID and body. A payment answer contains the order intent ID; it never contains card details.
  </Step>

  <Step title="Read the result">
    After each answer, resume reading the run and handle further requests until it finishes. A read can briefly show a request you already answered; handle each `requestId` only once, retrying its original message if needed.

    At a terminal status, read the result:

    | Status | What to read |
    | - | - |
    | `succeeded` | `result.summary` describes the purchase. If `result.purchase.kind` is `"receipt_captured"`, read `result.purchase.receipt`. |
    | `blocked` | `result.code` and `result.summary` explain why the agent stopped. |
    | `failed` | `reason` explains the failure. |
    | `cancelled` | Cancellation has completed. |

    An accepted answer resumes the agent. The final run status tells you whether the purchase succeeded.

    To stop an active run, request cancellation and keep reading until it reaches a terminal status:

    ```bash cURL theme={null}
    curl --fail-with-body --request POST "$CHECKOUT_API/$RUN_ID/cancel" \
        --header "X-API-KEY: $CROSSMINT_API_KEY" \
        --header "x-crossmint-user-id: $CROSSMINT_USER_ID"
    ```

    See [Finish or Cancel](/agents/checkouts/follow-run#finish-or-cancel) for the complete result behavior.
  </Step>
</Steps>

## Launching in Production

Agent Checkouts already uses production credentials. Before serving buyers, add [streaming and recovery](/agents/checkouts/follow-run), [buyer input handling](/agents/checkouts/buyer-inputs), and [payment authorization](/agents/checkouts/payments) for your application's user experience. The sample app above shows how these pieces fit together.

If a create-run acknowledgement is lost, inspect [List Checkouts](/api-reference/agent-checkouts/list-agent-checkouts) before creating another run.

## Learn More

<CardGroup>
  <Card title="Configure a Checkout" icon="sliders" href="/agents/checkouts/configure">
    Prefill buyer details and set merchant guidance
  </Card>

  <Card title="Follow a Run" icon="arrows-rotate" href="/agents/checkouts/follow-run">
    Stream updates, steer the agent, and recover after disconnects
  </Card>
</CardGroup>


# Agent Cards Quickstart ⚡
Source: https://docs.crossmint.com/agents/cards-quickstart

Get your agent paying with agent cards in 15 minutes

Give agents permission to pay with a user's card using Crossmint's Agentic Payments API. This quickstart runs the [agent cards reference app](https://github.com/Crossmint/card-permissions-quickstart).

By the end you will have a running app where a user can sign in, save a card, register its supported rails, authorize an order intent, and mint secure card credentials.

<CardGroup>
  <Card title="Try the live demo" icon="rocket" href="https://card-permissions-quickstart.vercel.app/">
    See the full flow in action without setting anything up locally.
  </Card>

  <Card title="Agent Cards Quickstart" icon="code" href="https://github.com/Crossmint/card-permissions-quickstart">
    Explore the full reference implementation for agents, payment methods, and agent cards.
  </Card>
</CardGroup>

## Prerequisites

* Node.js 20+ and pnpm
* A [Stytch](https://stytch.com) account (used as the auth provider in this example)

<Note>
  **Eligible Cards**

  Agent cards work with any credit or debit card. What varies by card is who issues the agent's credential: a card-network program, or Crossmint's encrypted card fallback.

  Card-network rails — Visa Intelligent Commerce and Mastercard Agent Pay — support a subset of cards, and Visa and Mastercard keep expanding that coverage:

  * **Mastercard Agent Pay:** Mastercard credit and debit cards
  * **Visa Intelligent Commerce:** U.S.-issued Visa credit and debit cards, except business cards, prepaid cards, Chase cards, and Fidelity cards

  Cards that no card-network rail supports yet, such as AMEX, Ramp, or non-US Visa cards, use the [encrypted card rail](/agents/payment-methods/cards/retrieve-agent-card). To enable it in production, <a href="https://www.crossmint.com/contact/sales">contact us</a>.
</Note>

## Setup

<Steps>
  <Step title="Clone the repo and install dependencies">
    You can ask your agent to walk you through the setup to run this quickstart.

    ```bash theme={null}
    git clone https://github.com/Crossmint/card-permissions-quickstart.git
    cd card-permissions-quickstart
    pnpm install
    ```
  </Step>

  <Step title="Configure environment variables">
    Copy the example file and fill in the keys from the previous steps:

    ```bash theme={null}
    cp .env.example .env.local
    ```

    ```bash .env.local theme={null}
    NEXT_PUBLIC_STYTCH_PUBLIC_TOKEN=your-stytch-public-token
    NEXT_PUBLIC_CROSSMINT_CLIENT_API_KEY=your-crossmint-client-api-key
    ```
  </Step>

  <Step title="Get a Crossmint staging API key">
    Sign in to the <a href="https://staging.crossmint.com/signin?callbackUrl=/console">Crossmint Staging Console</a> and create a project.

    Staging keys come with **all scopes enabled by default**, so you don't need to configure anything else for the quickstart. Copy the key and paste it into your `.env.local`.
  </Step>

  <Step title="Set up Stytch">
    In the <a href="https://stytch.com/dashboard">Stytch dashboard</a>, in the **Test** environment of a **B2C** project:

    1. **Configuration → SDK Configuration → OAuth** — enable **Google** (Stytch's shared test client works, no Google Cloud setup needed).
    2. **Configuration → Redirect URLs** — add `http://localhost:3000` as both **Login** and **Signup**. Use exactly that, no trailing slash or `/callback`.
    3. **Project Settings → API Keys** — copy the **Public token** (`public-token-test-...`) into `NEXT_PUBLIC_STYTCH_PUBLIC_TOKEN` in your `.env.local`.
  </Step>

  <Step title="Register Stytch as your auth provider in Crossmint">
    In the <a href="https://staging.crossmint.com/console/projects/apiKeys">Crossmint Staging Console</a>, under **3P Auth providers**:

    1. Select **Stytch** from the provider dropdown.
    2. Paste your Stytch **Project ID** (`project-test-...`, found in Stytch under **Project Settings → Project ID**).
    3. Leave **Verifier Id** as `sub` (default).

    Crossmint will start trusting JWTs minted by your Stytch project on subsequent SDK calls.
  </Step>

  <Step title="Run the dev server">
    ```bash theme={null}
    pnpm dev
    ```

    Open [http://localhost:3000](http://localhost:3000).
  </Step>
</Steps>

## Understanding the user flow

Once running, the app walks the user through six steps:

1. **Authenticate.** Sign in with Google via Stytch. The session JWT is bridged into the Crossmint SDK so every API call is scoped to the user.
2. **Save a card.** The `CrossmintPaymentMethodManagement` component collects the card in a PCI-compliant iframe and returns a `paymentMethodId`.
3. **Register the card.** Registration discovers the card's supported rails, such as Visa Intelligent Commerce or Mastercard Agent Pay. It grants no spending permission and requires no verification.
4. **Create an order intent.** The app creates an allowance with an amount, description, expiration, and—when already known—the merchant. The response can contain multiple rails, each with its own verification status and credential formats. If no card-network rail is usable, the response also includes an `encrypted-card` rail that is active immediately (in production, only for projects with encrypted card access enabled).
5. **Verify the rail you want to use.** If the selected rail has `status: "pending_verification"`, the `OrderIntentVerification` component runs its provider ceremony. Other rails do not need to be verified and can remain pending. A returning Visa user authenticates with the passkey already bound to the device.
6. **Mint credentials.** The app uses the selected rail's `rail` and `provider` and requests a credential for a specific amount. If the merchant was not set on the order intent, the app supplies it now. The response contains the secure one-time card number, expiration, and CVC. For the `encrypted-card` rail, minting takes an RSA public key instead and returns the saved card as a JWE for the agent to decrypt locally.

Treat `rails` as a menu, not a checklist. Only the rail used to mint the credential must be `active`; unrelated rails do not block it.

## Next Steps

<CardGroup>
  <Card title="Customize UI" icon="palette" href="/agents/payment-methods/cards/customize-verification-ui">
    Style the card and passkey verification modals to match your brand.
  </Card>

  <Card title="Agent Checkouts" icon="browser" href="/agents/agent-checkouts-quickstart">
    Let Crossmint drive a real browser and complete checkout on any site.
  </Card>
</CardGroup>


# Agent Cards
Source: https://docs.crossmint.com/agents/cards/overview

Save a user's card once, then issue as many scoped, revocable agent cards from it as your agents need

<Frame type="simple">
  <img alt="Save a real card once, Crossmint tokenizes it, and you create virtual cards with their own limits for your agents" />

  <img alt="Save a real card once, Crossmint tokenizes it, and you create virtual cards with their own limits for your agents" />
</Frame>

Your user saves their real card once. From that card, you create as many **scoped authorizations** as your agents need, each with its own limit, purpose, and expiration. Crossmint calls these order intents. From an order intent, the agent mints a credential on whichever rail the purchase needs, and pays without ever seeing the real card number.

For the problem this solves and how it compares to other approaches, read [How Agents Pay](/agents/how-agents-pay).

<video />

## Key Features

<CardGroup>
  <Card title="Save once, authorize many" icon="layer-group">
    One saved card backs any number of scoped agent cards
  </Card>

  <Card title="Scoped by design" icon="sliders">
    Every agent card has an amount, a purpose, an expiration, and optionally a merchant
  </Card>

  <Card title="Enforced by the network" icon="shield-check">
    Visa Intelligent Commerce and Mastercard Agent Pay hold the limit, not your code
  </Card>

  <Card title="Real card never exposed" icon="eye-slash">
    Agents receive one-time or encrypted credentials from a PCI-compliant vault
  </Card>

  <Card title="Multiple rails" icon="route">
    Network tokens, encrypted card, and protocol credentials such as SPT from the same authorization
  </Card>

  <Card title="Revocable" icon="ban">
    The user cancels an agent card or deletes the saved card at any time
  </Card>
</CardGroup>

## How It Works

<Steps>
  <Step title="The user saves a card once">
    Your app renders a Crossmint-hosted secure iframe. The card goes straight into Crossmint's PCI-compliant vault and never touches your servers.
  </Step>

  <Step title="You create scoped agent cards from it">
    Each agent card is an order intent: an allowance with an amount, description, expiration, and optionally a merchant. Create one per agent, per task, or per purchase. The user approves it with a passkey or a network-hosted step, and can cancel it at any time.
  </Step>

  <Step title="The agent pays on the right rail">
    From an approved agent card, the agent mints the credential the purchase needs: a one-time card number bounded by the allowance, an encrypted card for cards outside the network programs, or a protocol credential. A network-issued credential is bounded to the allowance, expires, and is revoked with the agent card. The encrypted card is the saved card itself, so keep the purchase within the allowance and cancel the agent card when it is no longer needed.
  </Step>
</Steps>

## Rails

One agent card can mint credentials on several rails. Pick the rail the purchase needs; the rest stay unused.

| Rail | What the agent receives | Limit enforced by |
| - | - | - |
| Visa Intelligent Commerce | One-time card number or network token bounded by the allowance | Visa |
| Mastercard Agent Pay | One-time card number or network token bounded by the allowance | Mastercard |
| Encrypted card | The saved card encrypted to a key only the agent holds, when no network rail is available | Your allowance handling |
| SPT | A protocol-specific credential for merchants and services that accept it | The protocol |

Depending on the rail, the credential is delivered as a one-time card number, a network token, or a protocol-specific format such as MPP.

## Get Started

<CardGroup>
  <Card title="Quickstart" icon="bolt" href="/agents/cards-quickstart">
    Run the reference app: sign in, save a card, authorize an agent card, and mint a credential
  </Card>

  <Card title="Try the live demo" icon="rocket" href="https://card-permissions-quickstart.vercel.app/">
    See the full flow without setting anything up locally
  </Card>
</CardGroup>

## Guides

<CardGroup>
  <Card title="Save a Card" icon="credit-card" href="/agents/payment-methods/cards/save-card">
    Collect a user's card in a PCI-compliant iframe
  </Card>

  <Card title="Register a Card" icon="list-check" href="/agents/payment-methods/cards/register-card">
    Discover the rails a saved card supports
  </Card>

  <Card title="Create an Agent Card" icon="file-signature" href="/agents/payment-methods/cards/create-agent-card">
    Create and authorize a scoped order intent
  </Card>

  <Card title="Retrieve Secure Card Numbers" icon="key" href="/agents/payment-methods/cards/retrieve-agent-card">
    Mint a credential from an approved agent card
  </Card>

  <Card title="Customize UI" icon="palette" href="/agents/payment-methods/cards/customize-verification-ui">
    Style the approval modal to match your brand
  </Card>

  <Card title="Cancel Card Access" icon="ban" href="/agents/payment-methods/cards/remove-cards">
    Cancel an agent card or delete a saved card
  </Card>
</CardGroup>

## API Reference

<CardGroup>
  <Card title="Payment Methods" icon="brackets-curly" href="/api-reference/agentic-commerce/payment-methods/create-payment-method">
    Create, list, and delete saved cards
  </Card>

  <Card title="Order Intents" icon="brackets-curly" href="/api-reference/agentic-commerce/order-intents/create-order-intent">
    Create, mint credentials from, and revoke agent cards
  </Card>
</CardGroup>

## FAQs

<AccordionGroup>
  <Accordion title="Does the agent ever see the user's real card number?">
    No. The agent receives a one-time card-network credential minted for a specific amount, or, when no network rail is available, a copy of the saved card encrypted to a key the agent controls. The real card stays in Crossmint's PCI-compliant vault.
  </Accordion>

  <Accordion title="Do your users keep their rewards, refunds, and chargeback rights?">
    Yes. Every purchase runs on the user's own card, so the card's normal protections apply. Nothing is prefunded and no new account is opened.
  </Accordion>

  <Accordion title="What happens when a card supports neither Visa Intelligent Commerce nor Mastercard Agent Pay?">
    The agent card includes an encrypted-card rail. Minting from it returns the saved card encrypted to a public key you supply, so the agent can still pay while the card details stay out of transit logs. In production this rail is available only for projects with encrypted card access enabled.
  </Accordion>

  <Accordion title="Can an Agent Card pay inside an Agent Checkout?">
    Yes. [Agent Checkouts](/agents/checkouts/overview) accepts any method the merchant supports, and a Crossmint Agent Card is the recommended one. See [Authorize Payments](/agents/checkouts/payments).
  </Accordion>
</AccordionGroup>


# Handle Buyer Inputs
Source: https://docs.crossmint.com/agents/checkouts/buyer-inputs

Render ordinary and protected fields and submit one complete form response

An Agent Checkout form can contain ordinary and protected fields. Render ordinary fields with your own controls. Render each field whose `handling` is `"protected"` with `CrossmintProtectedInput`; your application receives a reference instead of its value.

## Prerequisites

* **Checkout integration**: Complete the [Agent Checkouts quickstart](/agents/agent-checkouts-quickstart).
* **React SDK**: Install `@crossmint/client-sdk-react-ui` version 4.9.0 or later.
* **API key**: Use a production key with `agent-checkouts.read` and `agent-checkouts.update`. Add `protected-inputs.create` to the client-side key when collecting protected fields.
* **User authentication**: Pass the buyer's JWT from your [external authentication integration](/wallets/guides/bring-your-own-auth). Use the same project, environment, and user as the checkout run.

## Collect and Submit Answers

<Steps>
  <Step title="Read the requested fields">
    Use an open `input_request` part from the Messages API, or `requiredAction.request` when polling the run. Both expose the same `interaction.fields` descriptors. A protected field belongs to a `"form"` interaction.

    ```json theme={null}
    {
        "type": "input_request",
        "requestId": "req_456",
        "status": "open",
        "question": "Enter your email and password to sign in.",
        "expiresAt": "2026-10-02T15:30:00.000Z",
        "interaction": {
            "kind": "form",
            "fields": [
                {
                    "key": "email",
                    "label": "Email",
                    "required": true,
                    "handling": "standard",
                    "input": { "kind": "text", "autoComplete": "email" }
                },
                {
                    "key": "password",
                    "label": "Password",
                    "required": true,
                    "handling": "protected",
                    "input": {
                        "kind": "text",
                        "display": "masked",
                        "autoComplete": "current-password"
                    }
                }
            ]
        }
    }
    ```

    Pass each protected descriptor unchanged as the component's `field`. It supplies the key, accessible label, requiredness, and supported input hints. `display: "masked"` controls appearance; `handling: "protected"` controls how the value is collected. A standard text field can also be masked.
  </Step>

  <Step title="Render ordinary fields with your controls">
    Keep the request's field order and use each `key` as its answer key. Display its `label`, respect `required`, and pass supported presentation hints to your controls. For a standard single-line text descriptor:

    ```tsx StandardTextField.jsx theme={null}
    export function StandardTextField({ field, value, onChange }) {
        return (
            <label>
                {field.label}
                <input
                    name={field.key}
                    value={value}
                    required={field.required}
                    type={field.input.display === "masked" ? "password" : "text"}
                    placeholder={field.input.placeholder}
                    autoComplete={field.input.autoComplete}
                    inputMode={field.input.inputMode}
                    onChange={(event) => onChange(event.target.value)}
                />
            </label>
        );
    }
    ```

    Your parent component owns the value and `onChange` callback. For other input kinds, choose a control and submit the corresponding typed value:

    | Input | Ordinary Control | Answer |
    | - | - | - |
    | Single-line text | Text input; use a password input for `display: "masked"` | String, preserving leading zeros |
    | Multiline text | Textarea | String |
    | Number / integer | Numeric input; parse before submission | Finite number / safe integer |
    | Boolean | Checkbox or toggle | `true` or `false`; required means an answer must be present, not necessarily `true` |
    | Choice, `selection.kind: "one"` | Select or radio group | One option's `value` |
    | Choice, `selection.kind: "many"` | Multiple select or checkbox group | Array of option values, respecting `selection.min` and optional `max` |

    Use choice labels for display and values for answers. Placeholder options are not answers. Disabled options cannot be newly selected; preserve already-selected disabled options. Browser form serialization omits disabled controls, so include those locked selections explicitly when constructing answers.

    For example, an ordinary response can contain `email: "buyer@example.com"`, `quantity: 2`, `giftWrap: false`, and `colors: ["navy", "black"]`. Submit only keys requested by this form. Omit unanswered optional keys; `null` is not an answer.
  </Step>

  <Step title="Render and collect protected fields">
    This example handles one protected field. Your page owns the visible label, button, and error text. The iframe contains only the input. Call `ref.collect()` when the buyer chooses to continue; an HTML `<form>` is optional.

    <Snippet />

    ```tsx ProtectedField.tsx theme={null}
    import { useRef, useState } from "react";
    import {
        CrossmintProvider,
        CrossmintProtectedInput,
        type CrossmintProtectedInputRef,
        type ProtectedInputField,
    } from "@crossmint/client-sdk-react-ui";

    type Props = {
        apiKey: string;
        jwt: string;
        field: ProtectedInputField;
        onCollected: (answer: { protectedInputId: string }) => Promise<void>;
    };

    export function ProtectedField({ apiKey, jwt, field, onCollected }: Props) {
        const ref = useRef<CrossmintProtectedInputRef>(null);
        const [busy, setBusy] = useState(false);
        const [error, setError] = useState("");

        async function collect() {
            if (busy || ref.current === null) {
                return;
            }
            setBusy(true);
            setError("");
            try {
                const result = await ref.current.collect();
                if (result.status !== "collected") {
                    setError(result.message);
                    return;
                }
                await onCollected(result.input);
            } catch {
                setError("Could not complete collection or submission. Try again.");
            } finally {
                setBusy(false);
            }
        }

        return (
            <CrossmintProvider apiKey={apiKey}>
                <div>{field.label}</div>
                <CrossmintProtectedInput
                    ref={ref}
                    jwt={jwt}
                    field={field}
                    disabled={busy}
                    invalid={error !== ""}
                />
                {error !== "" && <p role="alert">{error}</p>}
                <button type="button" disabled={busy} onClick={collect}>
                    Continue
                </button>
            </CrossmintProvider>
        );
    }
    ```

    Pass your client-side API key as `apiKey`, the buyer's JWT as `jwt`, and the descriptor from `interaction.fields` as `field`. Mount this request's UI with `key={requestId}` so a replacement request resets its state. If your page already has a `CrossmintProvider`, use that provider instead of nesting another one. External authentication does not require `CrossmintAuthProvider`.

    For a form with multiple protected fields, the parent owns one Continue button and one ref per field. Collect them together with `Promise.all`, then submit the combined answers. Check every result before submitting. Each result is independent: correcting one field does not discard an unchanged field's successful reference.

    | Result | Your next action |
    | - | - |
    | `collected` | Use `result.input` as the answer for that field key. |
    | `invalid` | Show `result.message` and let the buyer correct the input. |
    | `unavailable` | Show `result.message` and offer a retry. |
    | `superseded` | Collect again because the field or its authentication changed. |

    `collect()` validates and registers the value before returning a reference. Numeric parsing runs during collection, so invalid numeric text is reported before you submit an answer. Unchanged successful collections reuse their reference until it expires; editing or clearing the field invalidates that reuse.
  </Step>

  <Step title="Submit the complete form answer">
    Combine the collected reference with ordinary answers under the keys from the request. For the email and password example, send this body to `POST /api/unstable/agent-checkouts/{runId}/messages`:

    <Snippet />

    Send all required answers in one `response.answers` object, using the field keys from the request. Ordinary answers are strings, booleans, numbers, or choice values; protected answers are `{ protectedInputId }`. Answers do not repeat `handling`. Omit unanswered optional field keys.

    Follow [response and retry handling](/agents/checkouts/follow-run#respond-or-steer): retain one message ID and body until acknowledged, and use a new ID after correcting a definitive validation rejection. If the request closes or expires, load the current request.

    An accepted answer resumes the run; it does not confirm that the merchant accepted the value. Follow subsequent messages for application results or another request.
  </Step>
</Steps>

## Choose the Input Type and Presentation

| Input | Protected support | Representation |
| - | - | - |
| Single-line text | Yes | Preserves the string, including leading zeros. Use for passwords, verification codes, and identifiers. |
| Number | Yes | A finite numeric value; permits fractions. |
| Integer | Yes | A safe whole-number value. |
| Multiline text, boolean, choice | No | Render ordinary controls for fields with `handling: "standard"`. |

Use `appearance` to supply fonts and supported theme variables for the input. Style labels, buttons, and error messages in your own page. `disabled` and `invalid` update the mounted input dynamically. Numeric fields use numeric keyboard hints; a text code can specify `inputMode: "numeric"` without losing leading zeros.

Protected references last 24 hours by default and at most 7 days. The component's optional `expiresAt` sets the reference lifetime; the request's `expiresAt` is the separate deadline to answer the request.

## Use a Chat or Native Handoff

A messaging agent can collect ordinary answers, then send the buyer to an authenticated page that renders only the protected fields. Your application associates that page with the run and request, merges the references with the ordinary answers, and submits the complete response. A native app can use the same page in a webview.

Collection keeps plaintext out of your application JavaScript and answer messages. After application to a merchant page, page content, screenshots, or recordings can expose values. Do not rely on the collection component to mask browser evidence.

## Next Steps

<CardGroup>
  <Card title="Reuse Merchant Sessions" icon="user-lock" href="/agents/checkouts/merchant-sessions">
    Reuse the buyer's merchant session on later checkouts
  </Card>

  <Card title="Send a Message" icon="message" href="/api-reference/agent-checkouts/send-agent-checkout-message">
    Review form, payment, and steering message formats
  </Card>
</CardGroup>


# Configure a Checkout
Source: https://docs.crossmint.com/agents/checkouts/configure

Set the purchase task, buyer details, browser country, and merchant guidance

Configure a run before it starts so the agent knows what to buy and can reuse information you already have. Missing details can become [buyer input requests](/agents/checkouts/buyer-inputs) during checkout.

## Prerequisites

* A [working checkout integration](/agents/agent-checkouts-quickstart)
* A production API key with `agent-checkouts.create`; add `agent-checkouts.buyer-profiles.create` when creating a buyer profile
* A stable buyer identity shared by the run and any profiles or payment authorization

The examples use a server-side key. For client-side authentication, see [Follow a Run](/agents/checkouts/follow-run#authenticate-each-request).

## Configure the Run

<Steps>
  <Step title="Define the purchase and spending cap">
    A run needs `request.startUrl` and `constraints.maxCost`. Add `request.task` when the URL does not fully describe the purchase.

    ```typescript theme={null}
    const BASE_URL = "https://www.crossmint.com/api/unstable/agent-checkouts";
    const headers = {
        "Content-Type": "application/json",
        "X-API-KEY": process.env.CROSSMINT_API_KEY!,
        "x-crossmint-user-id": "YOUR_USER_ID",
    };

    const checkout = {
        request: {
            startUrl: "https://merchant.example/products/classic-tee",
            task: "Buy one black Classic Tee in size medium. Use standard delivery and pay by card.",
        },
        constraints: {
            maxCost: { amount: "100.00", currency: "USD" },
        },
    };
    ```

    Use a product URL when it identifies the item. A merchant home page, category, search, or cart URL also works when the task describes what to find. Include quantity, variants, delivery preferences, and billing preferences in the task.

    `maxCost` limits what the agent may spend. A checkout that would exceed it ends as `blocked` with `result.code: "policy.max_cost_exceeded"`.

    Name the payment method in the task, then [authorize payment](/agents/checkouts/payments) when requested. Keep raw card details and protected values out of the task.
  </Step>

  <Step title="Supply reusable buyer details">
    A buyer profile stores name, contact, and shipping details. Create it once and attach its ID to later runs for the same buyer. It does not contain payment credentials.

    ```typescript theme={null}
    // Uses BASE_URL and headers from the previous step.
    const profileResponse = await fetch(`${BASE_URL}/buyer-profiles`, {
        method: "POST",
        headers,
        body: JSON.stringify({
            label: "Home",
            name: { first: "Ada", last: "Lovelace" },
            contact: { email: "ada@example.com" },
            shipping: {
                addressLines: ["1 Market St"],
                locality: "San Francisco",
                administrativeAreaCode: "US-CA",
                postalCode: "94105",
                countryCode: "US",
            },
        }),
    });
    if (!profileResponse.ok) {
        throw new Error(`Could not create buyer profile: ${profileResponse.status}`);
    }
    const { id: buyerProfileId } = await profileResponse.json();
    ```

    Use the profile for reusable identity and address data, and the task for this purchase's preferences. The agent can still request details the profile does not supply, such as a gift message or a merchant-specific question.

    Buyer-profile create, list, read, update, and delete operations have separate `agent-checkouts.buyer-profiles.*` scopes. See [Create Buyer Profile](/api-reference/agent-checkouts/create-buyer-profile) for the complete schema.
  </Step>

  <Step title="Choose the browser country">
    Add `browser.location` to request where the managed browser's network traffic appears to originate:

    ```json theme={null}
    {
        "browser": {
            "location": { "type": "country", "countryCode": "CA" }
        }
    }
    ```

    This is an optional fragment of the create body. `countryCode` uses ISO 3166-1 alpha-2 codes, such as `US`, `GB`, and `CA`; Crossmint trims and uppercases it. Managed browsers use US egress when you omit the location.

    Location affects network egress. It does not set or verify residence, shipping address, language, or purchase eligibility.

    Routing is best effort, and there is no fixed public list of supported countries. If the requested location is unavailable, the run ends as `failed` with `reason: "browser_location_unsupported"` instead of knowingly using another country. Retry later, choose another country, or start a new run without `browser.location` to use the US default.
  </Step>

  <Step title="Add merchant guidance when needed">
    `merchantGuidance` supplies short operational notes about a merchant's checkout. Use it for repeatable problems you have observed, rather than ordinary checkout instructions.

    | Observed problem | Useful guidance |
    | - | - |
    | A fit-finder modal derails size selection | Close the fit finder and use the product page's size dropdown. |
    | The agent misses the guest path | Guest checkout is the Continue without an account link below the sign-in form. |
    | The checkout button stays disabled briefly | Wait for the cart drawer to finish loading before pressing Checkout. |

    Guidance applies to the merchant of `startUrl`, for this run only. It cannot expand the task, authorize consent, or raise the spending cap. The agent uses the actual page when it contradicts the guidance.

    Supplying guidance replaces any guidance Crossmint maintains for that merchant. Omit it for standard checkouts; an empty string is rejected. The limit is 20,000 characters, but keep notes short and concrete.
  </Step>

  <Step title="Create the configured run">
    Combine the options you need in one create request:

    ```typescript theme={null}
    // Uses checkout, buyerProfileId, BASE_URL, and headers from the earlier steps.
    const response = await fetch(BASE_URL, {
        method: "POST",
        headers,
        body: JSON.stringify({
            ...checkout,
            buyerProfileId,
            browser: { location: { type: "country", countryCode: "CA" } },
            merchantGuidance: "Close the fit finder and use the product page's size dropdown.",
        }),
    });
    if (!response.ok) {
        throw new Error(`Could not start checkout: ${response.status}`);
    }
    const { runId } = await response.json();
    ```

    To reuse a merchant session, also set `browser.profileId`. It is independent of location; see [Reuse Merchant Sessions](/agents/checkouts/merchant-sessions).

    Compare the run's result and browser behavior with earlier attempts when evaluating guidance. Update or remove notes when the merchant changes its layout.
  </Step>
</Steps>

## Next Steps

<CardGroup>
  <Card title="Follow a Run" icon="arrows-rotate" href="/agents/checkouts/follow-run">
    Observe progress and handle requests after starting the checkout
  </Card>

  <Card title="Create a Checkout" icon="brackets-curly" href="/api-reference/agent-checkouts/create-agent-checkout">
    Review the complete create request schema
  </Card>
</CardGroup>


# Follow a Run
Source: https://docs.crossmint.com/agents/checkouts/follow-run

Observe checkout updates, recover after disconnects, and respond or steer through messages

Follow a checkout from its returned `runId` until it reaches a terminal status. The run exposes current status and `requiredAction`; its messages expose conversation, progress, activity, input requests, and results.

## Prerequisites

* A checkout started through the [quickstart](/agents/agent-checkouts-quickstart)
* A production API key with `agent-checkouts.read` and `agent-checkouts.update`; add `agent-checkouts.cancel` to cancel runs
* The same buyer identity used to create the run

## Authenticate Each Request

For a backend integration, keep the server key outside client bundles and send the buyer's identifier on every call:

```typescript theme={null}
const BASE_URL = "https://www.crossmint.com/api/unstable/agent-checkouts";
const runId = "YOUR_RUN_ID";
const headers = {
    "Content-Type": "application/json",
    "X-API-KEY": process.env.CROSSMINT_API_KEY!,
    "x-crossmint-user-id": "YOUR_USER_ID",
};
```

For browser or native calls, use a production client-side key and `Authorization: Bearer YOUR_USER_JWT` instead of `x-crossmint-user-id`. Register your JWT issuer under **3P Auth providers** in the <a href="https://www.crossmint.com/console/projects/apiKeys">Crossmint Console</a> and allow your app's origins. The request bodies are the same.

## Observe and Recover

<Steps>
  <Step title="Choose the observation strategy">
    | Strategy | Use it when |
    | - | - |
    | Backend SSE stream | Your server can keep a connection open. Relay updates to your website, native app, messaging agent, or voice agent through its existing channel. |
    | Direct client stream | Your browser or native client calls Crossmint with a client key and JWT. Use a fetch-based SSE client; native `EventSource` cannot attach the authentication headers. |
    | Polling | Your runtime cannot keep a stream open. Read the run for status and requests, and list messages for conversation details. |

    Crossmint recommends streaming for live production integrations. The [quickstart](/agents/agent-checkouts-quickstart) uses polling to keep its example small.
  </Step>

  <Step title="Open the message stream">
    The stream is an HTTP response with content type `text/event-stream`. It carries both run snapshots and message changes:

    ```bash theme={null}
    curl --no-buffer \
        --url "https://www.crossmint.com/api/unstable/agent-checkouts/YOUR_RUN_ID/messages/stream" \
        --header "Accept: text/event-stream" \
        --header "X-API-KEY: YOUR_SERVER_API_KEY" \
        --header "x-crossmint-user-id: YOUR_USER_ID"
    ```

    ```text theme={null}
    id: cursor_01
    event: run.updated
    data: {"runId":"...","revision":3,"status":"awaiting_input","requiredAction":{...}}

    id: cursor_02
    event: message.upsert
    data: {"id":"msg_...","revision":2,"role":"assistant","parts":[...]}
    ```

    Store each event's `id` as the resume cursor. Keep the greatest run `revision`, and the greatest message `revision` for each message ID. Replayed or stale snapshots must not replace newer state. Revisions can skip; they order snapshots, while the cursor identifies the stream replay position.

    Handle open requests once by `requestId`, whether they arrive in `requiredAction` or a message part. Dispatch `interaction.kind: "form"` to [Handle Buyer Inputs](/agents/checkouts/buyer-inputs), and `"payment"` to [Authorize Payments](/agents/checkouts/payments).

    Reconnect with the cursor in the `last-event-id` header or `after` query parameter. If the cursor is rejected or recovery needs a fresh snapshot, use the next step.
  </Step>

  <Step title="Bootstrap or resynchronize from history">
    List all message pages before opening a stream for an existing run. The final page's `streamCursor` provides the handoff to live updates. Read the current run after history so you also discover a pending action.

    ```typescript theme={null}
    // Uses BASE_URL, runId, and headers from the authentication section.
    const messages = new Map();
    let cursor: string | null = null;
    let streamCursor: string | null = null;

    do {
        const query = new URLSearchParams({ limit: "100" });
        if (cursor !== null) {
            query.set("cursor", cursor);
        }
        const response = await fetch(`${BASE_URL}/${runId}/messages?${query}`, { headers });
        if (!response.ok) {
            throw new Error(`Could not list messages: ${response.status}`);
        }
        const page = await response.json();
        for (const message of page.data) {
            const existing = messages.get(message.id);
            if (!existing || message.revision > existing.revision) {
                messages.set(message.id, message);
            }
        }
        cursor = page.nextCursor;
        streamCursor = page.streamCursor;
    } while (cursor !== null);

    const response = await fetch(`${BASE_URL}/${runId}`, { headers, cache: "no-store" });
    if (!response.ok) {
        throw new Error(`Could not read checkout: ${response.status}`);
    }
    const run = await response.json();
    const streamUrl = new URL(`${BASE_URL}/${runId}/messages/stream`);
    if (streamCursor !== null) {
        streamUrl.searchParams.set("after", streamCursor);
    }
    ```

    Render the recovered messages and current run. If `run.status` is `"awaiting_input"` and its request has not been answered, handle `run.requiredAction` before connecting to `streamUrl` with the same authentication. Retain your request deduplication state across reconnects. See [List Messages](/api-reference/agent-checkouts/list-agent-checkout-messages) and [Stream Messages](/api-reference/agent-checkouts/stream-agent-checkout-messages) for pagination and replay details.
  </Step>

  <Step title="Poll when streaming is unavailable">
    Read `GET /{runId}` with the same headers and `cache: "no-store"`. Poll every 2 seconds while active, increase the interval while nothing changes, and reset it after a status change or response. Stop at a terminal status.

    Retry transient read failures with bounded backoff. For `429`, respect the response's `retryAfterSeconds`. This read helper illustrates the retry behavior:

    ```typescript theme={null}
    // Uses BASE_URL, runId, and headers from the authentication section.
    async function readRun() {
        const retryable = new Set([408, 429, 500, 502, 503, 504]);
        for (let attempt = 0; attempt < 5; attempt++) {
            let response: Response | undefined;
            try {
                response = await fetch(`${BASE_URL}/${runId}`, { headers, cache: "no-store" });
            } catch (error) {
                if (attempt === 4) {
                    throw error;
                }
            }
            if (response?.ok) {
                return response.json();
            }
            if (response && (!retryable.has(response.status) || attempt === 4)) {
                throw new Error(`Could not read checkout: ${response.status}`);
            }
            const body = response?.status === 429 ? await response.json().catch(() => null) : null;
            const seconds = body?.retryAfterSeconds;
            const serverDelay = typeof seconds === "number" && Number.isFinite(seconds) && seconds > 0
                ? seconds * 1_000 : 0;
            await new Promise((resolve) => setTimeout(resolve, Math.max(1_000 * 2 ** attempt, serverDelay)));
        }
        throw new Error("Could not read checkout after retries");
    }
    ```

    A poll immediately after a successful response can still contain the same action. Track answered request IDs so you do not submit again. For resumed integrations, recover message history rather than relying only on an in-memory set.
  </Step>
</Steps>

## Process Message Parts

A message can contain several parts. Store it by `id`, retain its greatest `revision`, and use `role` to identify the speaker.

| Part | What Your App Does |
| - | - |
| `text` | Show the instruction or reply. A user message's `delivery` distinguishes accepted from consumed. |
| `progress` | Show the agent's current progress. |
| `activity` | Optionally show operations and their running, completed, incomplete, or uncertain status. |
| `input_request` | Handle an `open` request according to `interaction.kind`. |
| `input_response` | Show the projected application outcome, alternative, or decline. Acceptance is separate from application at the merchant. |
| `result` | Show `outcome` and `summary`, with the receipt or blocked code when present. |

Your UI can also display the read-only checkout browser in an iframe using `run.browser.embedUrl`. `browser` is `null` until a session exists; displaying it is optional.

## Respond or Steer

Submit the [form answer](/agents/checkouts/buyer-inputs) or [payment authorization](/agents/checkouts/payments) to `POST /{runId}/messages`. Generate the message `id` once and retain its exact body until acknowledged. If acknowledgement is lost, retry the same ID and body. After a definitive validation rejection, correct the response with a new ID. Do not reuse an ID for changed content.

Respond before the request's `expiresAt`. If it closes or expires, load the current request. After a response, continue observing: the agent may ask several questions during a purchase.

To choose another path, send an alternative instead of the requested answer:

```json theme={null}
{
    "id": "msg_alternative_123",
    "parts": [{
        "type": "input_response",
        "requestId": "req_123",
        "action": "alternative",
        "text": "Check out as a guest instead"
    }]
}
```

Use `action: "decline"` without `text` to refuse a request. To steer without answering a particular request, send a text part:

```json theme={null}
{
    "id": "msg_steering_123",
    "parts": [{ "type": "text", "text": "Use standard shipping. Choose navy if black is sold out." }]
}
```

A `202 Accepted` confirms message acceptance, not that the agent consumed it. Follow its `delivery` and subsequent run updates.

## Finish or Cancel

| Run Status | Result |
| - | - |
| `succeeded` | The merchant confirmed the purchase. `result.purchase` contains a captured receipt or reports confirmation without a receipt. |
| `blocked` | The agent stopped because of a policy, product, fulfillment, or merchant condition. Use `result.code` for logic and `result.summary` for display. |
| `failed` | The run could not continue. Use `reason` for recovery logic. |
| `cancelled` | Cancellation completed. |

For a succeeded run with `result.purchase.kind: "receipt_captured"`, read `result.purchase.receipt` for the total and merchant order ID. The result message supplies the user-facing summary.

Cancel an active run with `POST /{runId}/cancel`, using the same authentication. It returns `202 Accepted`; keep observing until the run reaches a terminal status. The stream closes after terminal updates.

## Connect Your User Channel

| Channel | Integration |
| - | - |
| Web | Render inputs and authorization in your application. |
| Native | Render ordinary controls natively; use an authenticated webview for protected collection or card verification. |
| Messaging or voice | Map messages into the conversation, collect ordinary answers there, and send an authenticated application link when a protected field or verification requires a web surface. |
| Server agent | Consume updates on your backend and involve a buyer surface when input or verification requires it. |

Your application associates each handoff with the buyer, run, and request. See [Handle Buyer Inputs](/agents/checkouts/buyer-inputs#use-a-chat-or-native-handoff) for combining answers collected across channels.

## Next Steps

<CardGroup>
  <Card title="Handle Buyer Inputs" icon="keyboard" href="/agents/checkouts/buyer-inputs">
    Render and submit ordinary and protected answers
  </Card>

  <Card title="Authorize Payments" icon="credit-card" href="/agents/checkouts/payments">
    Answer card requests with order intents and send Klarna links to the buyer
  </Card>
</CardGroup>


# Reuse Merchant Sessions
Source: https://docs.crossmint.com/agents/checkouts/merchant-sessions

Save a merchant session after sign-in and reuse it on later checkouts

Some purchases require a merchant account for saved addresses, member prices, order history, or a cart the user already filled. A browser profile lets Agent Checkouts save the merchant session after the user signs in and load it on later runs.

Complete sign-in through [buyer input requests](/agents/checkouts/buyer-inputs). Password collection is separate from the saved session.

<video />

## Prerequisites

* **Agent Checkout integration**: Complete the [Agent Checkouts quickstart](/agents/agent-checkouts-quickstart) so your application can start a run, observe it, and send messages.
* **Server-side API key**: Use a production key with `agent-checkouts.create`, `agent-checkouts.read`, `agent-checkouts.update`, and `agent-checkouts.browser-profiles.create` scopes.

Browser profiles are scoped to a user. With a server-side key, identify that user with `x-crossmint-user-id` on every request.

<Warning>Always send `x-crossmint-user-id` with a server-side key. Without it, requests use your project's shared service subject, so different users could share the same browser profile.</Warning>

```typescript theme={null}
const BASE_URL = "https://www.crossmint.com/api/unstable/agent-checkouts";

const headers = {
    "Content-Type": "application/json",
    "X-API-KEY": process.env.CROSSMINT_API_KEY!,
    "x-crossmint-user-id": "YOUR_USER_ID",
};
```

## Sign In Once and Reuse the Session

<Steps>
  <Step title="Create a browser profile for the user">
    Create one profile and store its `id` with the user in your system. The optional `label` is only for your own bookkeeping.

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request POST \
          --url https://www.crossmint.com/api/unstable/agent-checkouts/browser-profiles \
          --header 'Content-Type: application/json' \
          --header 'X-API-KEY: YOUR_SERVER_API_KEY' \
          --header 'x-crossmint-user-id: YOUR_USER_ID' \
          --data '{ "label": "Primary shopping profile" }'
      ```

      ```typescript Node.js theme={null}
      // Uses BASE_URL and headers from the prerequisites.
      const res = await fetch(`${BASE_URL}/browser-profiles`, {
          method: "POST",
          headers,
          body: JSON.stringify({ label: "Primary shopping profile" }),
      });

      if (!res.ok) {
          throw new Error(`Could not create browser profile: ${res.status}`);
      }
      const { id: profileId } = await res.json();
      ```
    </CodeGroup>

    The response contains metadata only. It does not return cookies, tokens, or other browser state.

    ```json theme={null}
    {
        "id": "7c3b1f2a-9d54-4e80-b1a6-2f0c8e5d4a31",
        "label": "Primary shopping profile",
        "createdAt": "2026-08-10T11:00:00.000Z",
        "updatedAt": "2026-08-10T11:00:00.000Z"
    }
    ```

    A user can have one browser profile. Reuse that profile rather than creating one for each merchant.
  </Step>

  <Step title="Attach the profile to a checkout run">
    Pass the profile as `browser.profileId` when you start a run. The first run starts without a saved merchant session, so tell the agent to sign in before it buys.

    ```typescript theme={null}
    // Uses BASE_URL, headers, and profileId from the earlier steps.
    const res = await fetch(BASE_URL, {
        method: "POST",
        headers,
        body: JSON.stringify({
            request: {
                startUrl: "https://shop.example.com/products/classic-tee",
                task: "Sign in, then buy the medium in black.",
            },
            browser: { profileId },
            constraints: {
                maxCost: { amount: "100.00", currency: "USD" },
            },
        }),
    });

    if (!res.ok) {
        throw new Error(`Could not start checkout: ${res.status}`);
    }
    const { runId } = await res.json();
    ```

    You can also include `browser.location` in the same object when the checkout should run from a particular country. See [Configure a Checkout](/agents/checkouts/configure#configure-the-run).

    [Follow the run](/agents/checkouts/follow-run) and answer sign-in requests through [Handle Buyer Inputs](/agents/checkouts/buyer-inputs). An accepted form response does not itself confirm successful sign-in.
  </Step>

  <Step title="Complete the first signed-in checkout">
    Answer each request by its `requestId`, then continue observing the run. After the checkout finishes cleanly, the merchant's session is stored in the browser profile.

    The profile itself does not report what happened during a checkout. Read the run and its messages to confirm whether the agent signed in, encountered another verification step, or completed the purchase.
  </Step>

  <Step title="Reuse the profile on later runs">
    Pass the same `browser.profileId` on the next checkout for this user.

    ```typescript theme={null}
    // Uses BASE_URL, headers, and profileId from the earlier steps.
    const nextResponse = await fetch(BASE_URL, {
        method: "POST",
        headers,
        body: JSON.stringify({
            request: {
                startUrl: "https://shop.example.com/products/wool-scarf",
                task: "Buy one in grey using my saved account.",
            },
            browser: { profileId },
            constraints: {
                maxCost: { amount: "100.00", currency: "USD" },
            },
        }),
    });
    if (!nextResponse.ok) {
        throw new Error(`Could not start checkout: ${nextResponse.status}`);
    }
    ```

    The run loads the saved session before it navigates. If the merchant has expired the session or requires the user to sign in again, the agent sends new input requests. Handle them the same way as the first run.
  </Step>
</Steps>

## How Browser Profiles Stay Protected

* **The profile API returns metadata only.** Cookies, tokens, and other saved browser state are not returned.
* **Saved browser state is not added to a model prompt.** It is loaded only into the browser for that user's checkout.
* **Each run has its own browser.** The browser is released when the run finishes.
* **Payment authorization is separate.** Follow [Authorize Payments](/agents/checkouts/payments) when the run asks for a card credential.

## Manage a Browser Profile

Browser profile routes live under `https://www.crossmint.com/api/unstable/agent-checkouts/browser-profiles` and are documented with the Agent Checkouts API reference.

* A user can have one profile. Creating another returns `409`.
* Requesting a profile owned by another user returns `404`, so its existence cannot be probed.
* `label` is the only editable field.
* Deleting a profile irreversibly erases its saved browser state. Runs already using it continue, and erasure finishes after they end.

## Next Steps

<CardGroup>
  <Card title="Authorize Payments" icon="credit-card" href="/agents/checkouts/payments">
    Pay with an Agent Card, a merchant-saved card, or a local method
  </Card>

  <Card title="Configure a Checkout" icon="browser" href="/agents/checkouts/configure">
    Set purchase context before starting the run
  </Card>
</CardGroup>


# Agent Checkouts
Source: https://docs.crossmint.com/agents/checkouts/overview

One API to start from any URL and buy with any payment method the merchant accepts, under a spending cap you set

<video />

Agent Checkouts lets your agent buy from any merchant with a single API. Start a run from any URL, optionally describe what to buy in natural language, and set a spending cap. Crossmint completes the purchase on your user's behalf and returns the receipt.

Behind that API, Crossmint picks the right rail for each merchant: an agentic commerce protocol where the merchant supports one, and an optimized browser session everywhere else. You integrate once and get every merchant. For the problem this solves and how it compares to building it yourself, read [How Agents Buy](/agents/how-agents-buy).

<Note>Agent Checkouts runs in production only. There is no staging environment, so use a production API key and live auth credentials.</Note>

## Key Features

<CardGroup>
  <Card title="Any merchant" icon="store">
    Any starting URL, with or without a purchase API or protocol support
  </Card>

  <Card title="Any payment method" icon="money-bill-transfer">
    Crossmint Agent Cards, other agent cards, cards on file, Apple Pay, Google Pay, PayPal, Shop Pay, and more
  </Card>

  <Card title="Right rail per merchant" icon="route">
    Agentic commerce protocols where supported, an optimized browser everywhere else
  </Card>

  <Card title="Hard spending cap" icon="gauge-high">
    The checkout never spends above the cap you set
  </Card>

  <Card title="Live browser view" icon="eye">
    Embed the session so your user watches the purchase happen
  </Card>

  <Card title="Ask only when needed" icon="comments-question">
    Prefill identity, shipping, and intent; the agent asks the user only for what is missing
  </Card>
</CardGroup>

## How It Works

<Steps>
  <Step title="Start a run">
    Send any starting URL and the maximum the checkout may spend. Add an optional task when the URL alone does not identify the product, variant, quantity, or other purchase preferences.
  </Step>

  <Step title="Follow and steer the agent">
    Follow the run for its next required action, and read or stream its messages for the complete conversation. Your app can answer forms, authorize a secure card credential, answer protected fields, or send a text message to steer the agent at any time.
  </Step>

  <Step title="Read the result">
    The run ends with a receipt, a safe blocked outcome, or a clear failure reason. Cancel at any point before completion.
  </Step>
</Steps>

## Get Started

<CardGroup>
  <Card title="Quickstart" icon="bolt" href="/agents/agent-checkouts-quickstart">
    Start a checkout and handle its requests
  </Card>

  <Card title="Try the live demo" icon="rocket" href="https://agent-commerce.demos-crossmint.com/">
    Explore the full checkout experience in the sample app
  </Card>

  <Card title="View the sample app" icon="github" href="https://github.com/Crossmint/agent-commerce-sample-app">
    See how the API and UI components fit together
  </Card>
</CardGroup>

## Guides

<CardGroup>
  <Card title="Configure a Checkout" icon="sliders" href="/agents/checkouts/configure">
    Set the task, buyer details, browser country, and merchant guidance
  </Card>

  <Card title="Follow a Run" icon="arrows-rotate" href="/agents/checkouts/follow-run">
    Observe updates, recover after disconnects, and steer the agent
  </Card>

  <Card title="Handle Buyer Inputs" icon="keyboard" href="/agents/checkouts/buyer-inputs">
    Render ordinary and protected fields and submit complete answers
  </Card>

  <Card title="Authorize Payments" icon="credit-card" href="/agents/checkouts/payments">
    Answer card requests with order intents and send Klarna links to the buyer
  </Card>

  <Card title="Reuse Merchant Sessions" icon="user-lock" href="/agents/checkouts/merchant-sessions">
    Save a signed-in session and reuse it on later checkouts
  </Card>
</CardGroup>

## API Reference

<CardGroup>
  <Card title="Agent Checkouts" icon="brackets-curly" href="/api-reference/agent-checkouts/create-agent-checkout">
    Create, read, respond to, and cancel checkouts
  </Card>

  <Card title="Buyer Profiles" icon="brackets-curly" href="/api-reference/agent-checkouts/create-buyer-profile">
    Reusable name, contact, and shipping details
  </Card>

  <Card title="Browser Profiles" icon="brackets-curly" href="/api-reference/agent-checkouts/create-browser-profile">
    Saved merchant logins for later checkouts
  </Card>
</CardGroup>

## FAQs

<AccordionGroup>
  <Accordion title="Which payment methods can a checkout use?">
    Any method the merchant accepts: a Crossmint Agent Card, an agent card from another provider such as Ramp or Link, a card already saved in the user's account at the merchant, Apple Pay, Google Pay, PayPal, or a local method such as Shop Pay, bank transfer, or Bizum. See [Authorize Payments](/agents/checkouts/payments).
  </Accordion>

  <Accordion title="How does my app follow the checkout?">
    Follow the run to read its current status and `requiredAction`. Read or stream `/messages` when your UI needs the complete conversation, progress, activity, input requests, or result. See [Follow a Run](/agents/checkouts/follow-run) for both views and recovery.
  </Accordion>

  <Accordion title="Can I pass card details when I create the checkout?">
    No. When the run asks for a card payment, create an order intent for the same buyer and amount, then send only its `orderIntentId` in an input response. Raw card details never belong in the run request or message history. See [Authorize Payments](/agents/checkouts/payments).
  </Accordion>

  <Accordion title="Does the checkout stop to ask the user questions?">
    It moves to `awaiting_input` whenever it needs information or authorization. Form requests list typed fields. Ordinary answers contain values; [protected field answers](/agents/checkouts/buyer-inputs) contain collected references. Card payment requests take an order intent ID. Klarna payment requests link to a page where the buyer pays. You can pre-answer many ordinary questions with a [buyer profile and task](/agents/checkouts/configure).
  </Accordion>

  <Accordion title="Can the user change the request after the run starts?">
    Yes. Send a text part to `/messages` at any time before the run finishes. Use it to change preferences, answer a conversational question, or redirect the agent without starting over.
  </Accordion>

  <Accordion title="Can the agent buy inside the user's account at a merchant?">
    Yes. A [browser profile](/agents/checkouts/merchant-sessions) keeps the browser state from a login so later checkouts start signed in, with access to saved addresses, payment methods, and member pricing.
  </Accordion>

  <Accordion title="Can I call the API from the browser?">
    Yes. Every endpoint accepts a server-side key, or a client-side key plus the signed-in user's JWT from your auth provider. See [Follow a Run](/agents/checkouts/follow-run#authenticate-each-request) for both authentication methods.
  </Accordion>
</AccordionGroup>


# Authorize Payments
Source: https://docs.crossmint.com/agents/checkouts/payments

Answer card payment requests with order intents and send Klarna payment links to the buyer

Agent Checkouts can use any payment method the merchant accepts. Tell the agent which method to use in the run's `task`. If the agent needs a card credential, it pauses and sends a typed payment request for your application to authorize. If the merchant takes Klarna, the payment request links to a page where the buyer pays.

Your agent runtime can run on a server and communicate through any user channel, including a website, native app, messaging app, or voice assistant. The user only needs a secure application surface when they must authorize or verify the card.

## Prerequisites

* **Agent Checkout integration**: Complete the [Agent Checkouts quickstart](/agents/agent-checkouts-quickstart) so your application can start a run, observe it, and send messages.
* **Agent Card setup**: To use an Agent Card, [save the user's card](/agents/payment-methods/cards/save-card), [register it](/agents/payment-methods/cards/register-card), and be ready to [create an order intent](/agents/payment-methods/cards/create-agent-card).
* **Consistent user identity**: Use the same Crossmint project, environment, and user identity for the checkout run and its order intent.

## Choose the Method in the Task

Describe the user's preferred method when you start the run. Be specific enough that the agent does not have to infer which option to select.

| Method | Example task | What else to provide |
| - | - | - |
| Crossmint Agent Card | `Buy one in black and pay by card.` | Authorize the typed payment request with an order intent. |
| Klarna | `Buy one in black and pay with Klarna.` | Show the buyer the payment request's `authorizationUrl`. See [Handle a Klarna Payment Request](#handle-a-klarna-payment-request). |
| Card saved at the merchant | `Buy one in black using my saved Visa ending in 4242.` | Start the run with the user's [`browser.profileId`](/agents/checkouts/merchant-sessions). |
| Local or alternative method | `Buy one in black and pay with Shop Pay.` | Answer any instructions the merchant presents. If the method is unavailable, steer the run to another method. |

<Note>The task selects the method. It does not authorize a charge. Only answer a typed payment request when the agent is ready to pay.</Note>

## Authorize an Agent Card

<Steps>
  <Step title="Detect the payment request">
    The run moves to `awaiting_input` and exposes the request in both places you can observe a run:

    * `requiredAction.request` when you read the run
    * an `input_request` message part when you list or stream messages

    Dispatch on `interaction.kind === "payment"`, then on `interaction.method`. Answer with an order intent only when `method` is `"card"`. For `"klarna"`, see [Handle a Klarna Payment Request](#handle-a-klarna-payment-request). A card request carries charge metadata only. It never contains card details, an iframe URL, or an order intent ID. A Klarna request also carries `authorizationUrl`, a link that opens the buyer's payment page, so keep it as private as a credential.

    An open payment message part looks like this:

    ```json theme={null}
    {
        "type": "input_request",
        "status": "open",
        "requestId": "req_123",
        "question": "Authorize a card payment of 42.50 USD at shop.example.com.",
        "expiresAt": "2026-10-02T15:30:00.000Z",
        "interaction": {
            "kind": "payment",
            "purpose": "checkout_payment",
            "method": "card",
            "amount": { "kind": "exact", "value": "42.50", "currency": "USD" },
            "merchant": {
                "url": "https://shop.example.com",
                "name": "Example Shop",
                "countryCode": "US"
            }
        }
    }
    ```

    * `method: "card"` requests a card credential.
    * Other `method` values, such as `"klarna"`, do not request a card credential. Do not answer them with an order intent.
    * `amount.value` is a decimal string and `amount.currency` is an ISO 4217 code. `kind: "exact"` is the requested payable total; `kind: "maximum"` is the run's cost ceiling.
    * `merchant` identifies where the credential will be used. Copy its `url`, `name`, and `countryCode` unchanged when you create the order intent.
  </Step>

  <Step title="Create the order intent">
    Create the order intent in your authenticated application with a production client-side key that has `order-intents.create` and `order-intents.read` scopes. Send the JWT for the same user who owns the saved card and the checkout run.

    Use the exact amount from the payment request, set a short expiration, and copy `interaction.merchant` into the order intent. This makes the merchant available to payment rails that need it before credential minting. If you omit it, Agent Checkouts supplies the same merchant when it requests the credential.

    ```typescript theme={null}
    // Uses an open payment request from the checkout run.
    const runId = "YOUR_RUN_ID";
    const apiKey = "YOUR_CLIENT_API_KEY";
    const jwt = "YOUR_USER_JWT";
    const checkoutHeaders = { "X-API-KEY": apiKey, Authorization: `Bearer ${jwt}` };
    const runResponse = await fetch(
        `https://www.crossmint.com/api/unstable/agent-checkouts/${runId}`,
        { headers: checkoutHeaders }
    );
    if (!runResponse.ok) {
        throw new Error(`Could not read checkout: ${runResponse.status}`);
    }
    const run = await runResponse.json();
    const interaction = run.status === "awaiting_input" ? run.requiredAction.request.interaction : undefined;
    if (interaction?.kind !== "payment" || interaction.method !== "card") {
        throw new Error("Checkout does not have an open card payment request");
    }
    const action = run.requiredAction;
    const paymentRequest = action.request;
    const expiresAt = new Date(Date.now() + 2 * 60 * 60 * 1_000).toISOString();

    const response = await fetch("https://www.crossmint.com/api/unstable/order-intents", {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            "X-API-KEY": apiKey,
            Authorization: `Bearer ${jwt}`,
        },
        body: JSON.stringify({
            paymentMethodId: "YOUR_PAYMENT_METHOD_ID",
            amount: {
                value: paymentRequest.interaction.amount.value,
                currency: paymentRequest.interaction.amount.currency,
            },
            description: `Agent Checkout at ${paymentRequest.interaction.merchant.name}`,
            merchant: paymentRequest.interaction.merchant,
            expiresAt,
        }),
    });

    if (!response.ok) {
        throw new Error(`Could not create order intent: ${response.status}`);
    }

    let orderIntent = await response.json();
    ```

    `YOUR_PAYMENT_METHOD_ID` is the ID returned when you [save](/agents/payment-methods/cards/save-card) and [register](/agents/payment-methods/cards/register-card) the user's card. For the complete request and response, see [Create an Agent Card](/agents/payment-methods/cards/create-agent-card#create-the-order-intent).
  </Step>

  <Step title="Complete verification when required">
    Read `orderIntent.rails` and look for an `active` rail whose `credentialFormats` includes `"card"`. The top-level order-intent status does not tell you whether a card credential is ready.

    If no card rail is active, follow [Verify the Selected Rail](/agents/payment-methods/cards/create-agent-card#verify-the-selected-rail) for `pending_verification`, or [Recollect the CVC](/agents/payment-methods/cards/recollect-cvc) for `pending_cvc_recollection`. Fetch the order intent again after that step and confirm that a card-capable rail is active. If none can become active, ask the buyer for another card.

    <Note>
      **Encrypted card in production.** Agent Checkouts can pay with the `encrypted-card` rail even when encrypted card access is not enabled for your project. The card never leaves the Crossmint vault: the checkout uses it to pay the merchant, and your application only handles the `orderIntentId`. Without that access, your own reads of the order intent do not list the rail, so this check finds no active card rail when the saved card has no usable card-network rail. Submit the `orderIntentId` anyway. If the checkout answers `rail_unavailable`, [recollect the CVC](/agents/payment-methods/cards/recollect-cvc) and answer the new payment request.
    </Note>

    The [Agent Card guide](/agents/payment-methods/cards/create-agent-card#verify-the-selected-rail) shows the verification component. Card setup and verification are separate from submitting the checkout response.
  </Step>

  <Step title="Submit the order intent ID">
    Send one `input_response` part that references the request's `requestId`. Do not send card numbers, expiration dates, or security codes.

    <Snippet />

    You can instead send `action: "alternative"` with text such as `"Pay with Shop Pay instead"`, or `action: "decline"` to refuse the charge. See [Send Agent Checkout Message](/api-reference/agent-checkouts/send-agent-checkout-message) for the complete schema.

    Answer before the request's `expiresAt`. If it expires, observe the run for a new request and answer its new `requestId`.

    <Warning>Never put card details in the `task`, a buyer profile, form answers, or a text message. Raw card details are not accepted.</Warning>
  </Step>

  <Step title="Continue observing the run">
    The accepted response resumes the run. Continue streaming messages or reading the run until it completes, asks for another input, or stops.

    If the merchant total changes or the authorization cannot be used, the agent sends a new payment request. Answer the new `requestId`; do not reuse a response from an earlier request.
  </Step>
</Steps>

## Handle a Klarna Payment Request

Some merchants take payment through Klarna. Then the payment request has `method: "klarna"` and links to a page where the buyer pays with their own Klarna account:

```json theme={null}
{
    "kind": "payment",
    "purpose": "checkout_payment",
    "method": "klarna",
    "amount": { "kind": "exact", "value": "129.00", "currency": "GBP" },
    "merchant": { "url": "https://shop.example.com" },
    "authorizationUrl": "https://uc.example.com/payments/klarna/run_123/0123456789abcdefghijABCDEFGHIJ_-"
}
```

* Show `authorizationUrl` to the buyer unchanged, for example as a link or in a new tab. Do not rewrite it or join it to another origin.
* Do not create an order intent, and do not send an `input_response`. The run continues after the buyer pays. [Follow the run](/agents/checkouts/follow-run) for the result.
* `amount` is the exact total. `merchant` has only `url`.

<Warning>`authorizationUrl` is a payment capability: anyone who has it can open the payment page. Give it only to the buyer. Do not log it or put it in analytics, traces, or error reports.</Warning>

## Handle Authorization Problems

Submitting the ID acknowledges authorization; it does not confirm that the merchant accepted the card. [Follow the run](/agents/checkouts/follow-run) for application outcomes, another request, or the final result.

| Condition | Your Next Action |
| - | - |
| The order intent is expired or revoked | Create a replacement when answering the current open payment request. |
| No card rail is active | Complete the verification or CVC recollection required by the selected rail; recheck the order intent. |
| The checkout asks for a new amount or authorization | Use that new request's amount and merchant when creating the replacement order intent. |
| The request closed or expired | Read the run again and handle its current action. |
| The merchant declines the card | The run ends as `blocked` with `result.code: "merchant.payment_declined"`. |

Use the same production project and buyer for the run, saved card, and order intent. Your application sends identifiers instead of raw card data. Protected collection does not guarantee that values applied to merchant inputs are absent from later browser observations or recordings.

For web, native, messaging, and server integrations, see [Connect Your User Channel](/agents/checkouts/follow-run#connect-your-user-channel).

## Next Steps

<CardGroup>
  <Card title="Create an Agent Card" icon="credit-card" href="/agents/payment-methods/cards/create-agent-card">
    Create the order intent and verify its selected rail
  </Card>

  <Card title="Reuse Merchant Sessions" icon="user-lock" href="/agents/checkouts/merchant-sessions">
    Reuse a signed-in session on later checkouts
  </Card>
</CardGroup>


# How Agents Buy
Source: https://docs.crossmint.com/agents/how-agents-buy

Why a secure payment method was not enough for an agent to buy anything, and how one API covers every merchant

Once an agent has a secure card, a second problem appears: it still cannot buy much. Almost every merchant built its checkout for a human with a mouse.

## Problems

An agent holding an Agent Card has spending power, but no place to use it programmatically:

* **Most merchants have no purchase API.** There is nothing to call. The only path to a purchase is the same web checkout a human uses.
* **Checkouts are built to keep bots out.** CAPTCHAs, bot detection, and multi-factor prompts are aimed precisely at automated buyers.
* **Every merchant is different.** Carts, guest checkout, account login, shipping forms, coupon fields, and payment pages all vary. A hand-rolled integration works for one store and breaks on the next.
* **Browser automation is slow and expensive even when it works.** A general-purpose browser agent has to look at every page, decide what to click, and recover from every surprise. One checkout can take minutes and cost several dollars in tokens.
* **Generic automation is not a checkout solution.** A browser agent built for any task treats a purchase like any other web page. A checkout needs things it does not provide: a spending cap enforced outside the model, a way to enter card details without exposing them to the model, a structured way to ask the buyer a question mid-run, and a structured result at the end. It also starts from scratch at each merchant instead of reusing what worked there before.

Three approaches to closing that gap emerged, and each covers only part of the market:

| Approach | Where it works | Where it falls short |
| - | - | - |
| **Merchant APIs** | The few merchants that expose one | Nearly every other merchant |
| **Agentic commerce protocols** (UCP, ACP, AP2, ...) | Merchants that have adopted a given protocol | Adoption is early and fragmented across several protocols, and many implementations hand back a checkout link rather than completing the purchase |
| **Browser automation** | Anywhere a human could buy | Slow, brittle, and expensive: with frontier models a single checkout can cost several dollars in tokens, and it needs constant maintenance |

To buy anywhere, an agent developer would have to build and maintain all three, choose between them per merchant, and keep up as protocols change. That is the effort most teams cannot afford, and the reason many "shopping agents" stop at a product link.

## Solutions

### Agent Checkouts

[Agent Checkouts](/agents/checkouts/overview) puts all three approaches behind one API. Hand it a product URL, a natural-language request, and a hard spending cap, and Crossmint completes the purchase on your user's behalf:

* **The right rail for each merchant.** Crossmint uses an agentic commerce protocol where the merchant supports one, and runs an **optimized browser session** as the universal fallback everywhere else. You integrate once and get every rail, including new ones as merchants adopt them.
* **A complete purchase, not a cart.** The checkout runs end to end and returns a receipt with the merchant order id, not a link for the user to finish.
* **Any payment method the merchant accepts.** A Crossmint Agent Card, an agent card from another provider such as Ramp or Link, a card already on file in the user's merchant account, Apple Pay, Google Pay, PayPal, or a local method such as Shop Pay, bank transfer, or Bizum.
* **Bounded and observable.** The checkout never spends above the cap you set. You can embed the live browser session so the user watches the purchase happen, and the agent asks the user only for what you did not provide up front.
* **Crossmint runs the browser side.** The browser infrastructure, the models, the prompts, and the per-merchant behavior live in Crossmint's service rather than in your integration. Improvements to them apply to every checkout without a change on your side.

### x402 and MPP

Not every purchase has a checkout page. When the counterparty is an API or another agent, the payment is a protocol exchange settled in stablecoins:

| Protocol | How it works | Best for |
| - | - | - |
| [x402](/agents/payment-flows/x402) | The agent calls an endpoint, receives `402 Payment Required`, pays in stablecoin, and retries | Pay-per-call APIs and micropayments |
| [MPP](/agents/payment-flows/mpp) | Agent-to-agent and service-to-service payments over the Machine Payment Protocol | Programmatic machine economies |

Both are paid from an [Agent Wallet](/agents/wallets/overview), with the same scoped, revocable permissions described in [How Agents Pay](/agents/how-agents-pay).

<Info>One integration covers both kinds of counterparty: Agent Checkouts for merchants, x402 and MPP for machines. The per-merchant work lives in Crossmint's service, not in your codebase.</Info>

## See Also

<CardGroup>
  <Card title="How Agents Pay" icon="lock" href="/agents/how-agents-pay">
    Scoped cards and wallets the user controls
  </Card>

  <Card title="Agent Checkouts" icon="browser" href="/agents/checkouts/overview">
    The product, its features, and where to start
  </Card>

  <Card title="Checkouts Quickstart" icon="bolt" href="/agents/agent-checkouts-quickstart">
    Create your first checkout from a product URL
  </Card>
</CardGroup>


# How Agents Pay
Source: https://docs.crossmint.com/agents/how-agents-pay

Why giving an agent a payment method used to mean handing over the user's real card, and how scoped cards and wallets fix it

An agent that can only recommend is a search engine. An agent that can act needs to spend money, and the web gave developers no safe way to let it.

## Problems

The only payment credential most of your users have is a card, and nothing about a card was designed to be handed to software that acts on its own:

* **The real card number ends up in the agent's context.** It travels through prompts, logs, tool calls, and model providers. Once leaked, it can be charged again and again. There is no limit the agent cannot exceed, no expiry, and no way to revoke without cancelling the card. It also drags the developer into PCI scope.
* **Keeping a human in the loop defeats the purpose.** Approving every payment is safe, but the user is interrupted at the exact moment the agent was supposed to save them time.
* **Prepaid or virtual cards from a fintech give up the user's card.** The user funds a new balance instead of using the card they already have, loses their rewards, refunds, and chargeback protections, and the developer often becomes the account holder for money that is not theirs.
* **Custodial agent wallets create custody and trust problems.** Someone other than the user controls the funds, which raises licensing questions and still gives the agent unlimited access to whatever is in the wallet.
* **Limits enforced only in application code do not hold.** They stop honest mistakes, not a compromised agent, a manipulated model, or a leaked credential.

Agents amplify every one of these risks. An agent with unlimited access to money is a liability. What is missing is spending power that is **scoped, enforced outside the agent, and revocable by the user**, while the user keeps their own card.

## Solutions

Crossmint gives agents two payment instruments. Both follow the same principle: the user delegates a bounded allowance, the bound is enforced outside the agent, and the user can revoke it at any time.

### Agent Cards

<Frame type="simple">
  <img alt="Verify a card once, set spending rules, and the agent pays with a one-time card number that only works within those rules" />

  <img alt="Verify a card once, set spending rules, and the agent pays with a one-time card number that only works within those rules" />
</Frame>

The user saves their real card once, in a Crossmint-hosted PCI-compliant iframe. From that saved card, your app creates as many **scoped authorizations** as it needs. Crossmint calls these **order intents**: each one is an allowance with an amount, a description, an expiration, and optionally a merchant. The user approves each one, and can cancel it at any time.

From an active order intent, the agent **mints credentials on the rail the purchase needs**:

| Rail | What the agent receives | Enforced by |
| - | - | - |
| Visa Intelligent Commerce | A one-time card number or network token bounded by the allowance | Visa |
| Mastercard Agent Pay | A one-time card number or network token bounded by the allowance | Mastercard |
| Encrypted card | The saved card encrypted to a key only the agent holds, for cards outside the network programs; minted for an amount the order intent consumes | The order intent, for the amount; the card network does not bound the card |
| Protocol credentials (SPT) | A protocol-specific token for merchants and services that accept it | The protocol |

Depending on the rail, the credential is delivered as a one-time card number, a network token, or a protocol-specific format such as MPP.

The real card number never leaves the vault. A leaked network credential is worthless: it is bounded to an amount, expires, and is revoked with the order intent. The encrypted card is the exception: it decrypts to the saved card, so the allowance is yours to enforce and you should cancel the order intent as soon as it is no longer needed. And because the purchase runs on the user's own card, rewards, refunds, and chargebacks keep working. Read the [Agent Cards overview](/agents/cards/overview) for the product.

### Agent Wallets

For machine-to-machine payments, cards do not fit. Paying an API per call or settling with another agent involves amounts too small and too frequent for card fees and chargeback rules. These payments run on stablecoins.

The user owns a non-custodial wallet and adds the agent as a **signer with a scoped permission set**: a spend cap, allowed counterparties, and a time window. The permissions are enforced onchain, so a transaction outside them is rejected at the wallet level, and the user can revoke the signer at any time. Neither you nor Crossmint takes custody. Read the [Agent Wallets overview](/agents/wallets/overview) for the product.

<Info>Every delegation is explicit, scoped, enforced outside the agent, and revocable. The agent gets exactly the spending power the user granted, and nothing that survives a leak.</Info>

## See Also

<CardGroup>
  <Card title="How Agents Buy" icon="cart-shopping" href="/agents/how-agents-buy">
    Why a secure card was not enough, and how one API buys from any merchant
  </Card>

  <Card title="Agent Cards" icon="credit-card" href="/agents/cards/overview">
    Save once, authorize many, pay on the right rail
  </Card>

  <Card title="Agent Wallets" icon="wallet" href="/agents/wallets/overview">
    Scoped, non-custodial stablecoin wallets
  </Card>
</CardGroup>


# Overview
Source: https://docs.crossmint.com/agents/overview

Payment infrastructure for AI agents

<video />

Enable agents to **buy anything**, all under spending rules defined and controlled by your users. Integrate via a white-label SDK that plugs into your agent framework as a tool or skill, without handling sensitive credentials and while staying PCI-compliant.

Three products make it happen. Each one works on its own and they are built to compose.

## Products

<CardGroup>
  <Card title="Agent Cards" icon="credit-card" href="/agents/cards/overview">
    Save a user's card once and issue scoped, revocable agent cards from it
  </Card>

  <Card title="Agent Wallets" icon="wallet" href="/agents/wallets/overview">
    Non-custodial stablecoin wallets with scoped agent access, for x402, MPP, and onchain payments
  </Card>

  <Card title="Agent Checkouts" icon="browser" href="/agents/checkouts/overview">
    One API to buy from any merchant with any payment method it accepts
  </Card>
</CardGroup>

## Key Features

<CardGroup>
  <Card title="User stays in control" icon="sliders">
    Every allowance is scoped, explicit, and revocable
  </Card>

  <Card title="Enforced by the network" icon="shield-check">
    Card limits hold at Visa and Mastercard, wallet limits hold onchain
  </Card>

  <Card title="Real card never exposed" icon="eye-slash">
    Agents pay with one-time or encrypted credentials, never the user's card number
  </Card>

  <Card title="Any merchant" icon="store">
    Agentic commerce protocols where merchants support them, an optimized browser everywhere else
  </Card>

  <Card title="Any payment method" icon="money-bill-transfer">
    Crossmint cards, third-party agent cards, cards on file, Apple Pay, Google Pay, PayPal, and local methods
  </Card>

  <Card title="PCI scope stays with Crossmint" icon="vault">
    Cards live in Crossmint's vault, so your app never touches card data
  </Card>
</CardGroup>

## How They Fit Together

Cards and wallets give the agent **spending power** the user can scope and revoke. Agent Checkouts and the x402 and MPP protocols are the **places that spending power goes**.

| You want the agent to... | Spending power | Where it spends |
| - | - | - |
| Buy from an online store or pay a bill | [Agent Cards](/agents/cards/overview) or any card | [Agent Checkouts](/agents/checkouts/overview) |
| Pay an API per call, or pay another agent | [Agent Wallets](/agents/wallets/overview) | [x402](/agents/payment-flows/x402) and [MPP](/agents/payment-flows/mpp) |
| Send stablecoins, swap, or call a contract | [Agent Wallets](/agents/wallets/overview) | [Onchain actions](/agents/payment-methods/stablecoin-wallets/on-chain-actions) |

<CardGroup>
  <Card title="How Agents Pay" icon="lock" href="/agents/how-agents-pay">
    Why agents could not pay securely, and how scoped cards and wallets fix it
  </Card>

  <Card title="How Agents Buy" icon="cart-shopping" href="/agents/how-agents-buy">
    Why a secure card was not enough to buy anything, and how one API covers every merchant
  </Card>
</CardGroup>

## Get Started

<CardGroup>
  <Card title="Cards Quickstart" icon="credit-card" href="/agents/cards-quickstart">
    Get an agent paying with agent cards
  </Card>

  <Card title="Wallets Quickstart" icon="wallet" href="/agents/stablecoin-wallet-quickstart">
    Get an agent paying with stablecoins
  </Card>

  <Card title="Checkouts Quickstart" icon="browser" href="/agents/agent-checkouts-quickstart">
    Buy from any merchant with a single API
  </Card>
</CardGroup>


# MPP
Source: https://docs.crossmint.com/agents/payment-flows/mpp

Pay MPP endpoints with a Crossmint EVM wallet

This guide shows how to pay MPP (Machine Payment Protocol) endpoints using a Crossmint wallet. The example uses the `mppx/client` library to handle the payment automatically.

## Prerequisites

* A Crossmint EVM wallet with USDC. See the [Wallets quickstart](/agents/stablecoin-wallet-quickstart), then [fund it with USDC](/agents/payment-methods/stablecoin-wallets/onramp-add-funds).
* The agent must be authorized as a signer on the wallet. See [Authorize the Agent](/agents/payment-methods/stablecoin-wallets/authorize-agent).

## Install dependencies

<CodeGroup>
  ```bash npm theme={null}
  npm i @crossmint/client-sdk-react-ui mppx/client viem
  ```

  ```bash yarn theme={null}
  yarn add @crossmint/client-sdk-react-ui mppx/client viem
  ```

  ```bash pnpm theme={null}
  pnpm add @crossmint/client-sdk-react-ui mppx/client viem
  ```

  ```bash bun theme={null}
  bun add @crossmint/client-sdk-react-ui mppx/client viem
  ```
</CodeGroup>

## Pay an MPP endpoint

```tsx mpp-payment.tsx theme={null}
import { EVMWallet, useWallet } from "@crossmint/client-sdk-react-ui";
import {
  createWalletClient,
  custom,
  http,
  MethodNotFoundRpcError,
  type EIP1193RequestFn,
} from "viem";
import { tempoDevnet } from "viem/chains";
import { Mppx, tempo } from "mppx/client";
import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";

const crossmint = createCrossmint({
    apiKey: "<your-server-api-key>",
});

const crossmintWallets = CrossmintWallets.from(crossmint);

const wallet = await crossmintWallets.getWallet(
    "<wallet-address>",
    { chain: "base" }
);

// Use the agent signer
await wallet.useSigner({
    type: "server",
    secret: process.env.CROSSMINT_SIGNER_SECRET,
});

const evmWallet = EVMWallet.from(wallet);
const address = evmWallet.address as `0x${string}`;

const httpTransport = http();

const request: EIP1193RequestFn = async ({ method, params }) => {
  if (method === "wallet_sendCalls") {
    throw new MethodNotFoundRpcError(
      new Error("wallet_sendCalls not implemented; falling back"),
    );
  }
  if (method === "eth_sendTransaction") {
    const [tx] = params as Array<{
      to: `0x${string}`;
      data?: `0x${string}`;
      value?: `0x${string}`;
    }>;
    const sent = await evmWallet.sendTransaction({
      to: tx.to,
      data: tx.data ?? "0x",
      value: tx.value ? BigInt(tx.value) : undefined,
    });
    return sent.hash as `0x${string}`;
  }
  return httpTransport.request({ method, params } as any);
};

const walletClient = createWalletClient({
  account: address,
  chain: tempoDevnet,
  transport: custom({ request }),
});

const mppx = Mppx.create({
  polyfill: false,
  methods: [
    tempo({
      mode: "push",
      getClient: () => walletClient as any,
    }),
  ],
});

const response = await mppx.fetch("https://api.example.com/protected");

const responseText = await response.text();
console.log("MPP response:", response.status, responseText);
```

## How the code works

<Steps>
  <Step title="Create a wallet client from the Crossmint wallet">
    The `EVMWallet.from(wallet)` call wraps the Crossmint wallet into an EVM-compatible interface. A custom EIP-1193 request handler is created that delegates `eth_sendTransaction` calls to the Crossmint wallet, which sends transactions using the agent's delegated permissions.
  </Step>

  <Step title="Build a viem wallet client">
    A viem `walletClient` is created with the custom transport, targeting the Tempo devnet chain. This client bridges the Crossmint wallet to standard EVM tooling.
  </Step>

  <Step title="Initialize the MPPX client with Tempo">
    `Mppx.create` initializes the MPP client with the `tempo` payment method in push mode. The `getClient` callback provides the wallet client for signing and sending the onchain transactions.
  </Step>

  <Step title="Fetch the MPP endpoint">
    `mppx.fetch` works like a standard `fetch` call but automatically handles MPP payment negotiation. If the endpoint requires payment, the client pays via Tempo and retries the request.
  </Step>
</Steps>


# x402
Source: https://docs.crossmint.com/agents/payment-flows/x402

Pay x402-protected endpoints with a Crossmint wallet.

This guide shows how to pay <a href="https://www.x402.org/">x402</a>-protected endpoints using a Crossmint wallet. The example uses the `@x402/core` client library to handle the 402 negotiation and payment automatically.

## Prerequisites

* A funded Crossmint EVM wallet on Base with USDC. See the [Wallets quickstart](/agents/stablecoin-wallet-quickstart), then [fund it with USDC](/agents/payment-methods/stablecoin-wallets/onramp-add-funds).
* The agent must be authorized as a signer on the wallet. See [Authorize the Agent](/agents/payment-methods/stablecoin-wallets/authorize-agent).

## Install dependencies

<CodeGroup>
  ```bash npm theme={null}
  npm i @crossmint/client-sdk-react-ui @crossmint/wallets-sdk @x402/core @x402/evm viem
  ```

  ```bash yarn theme={null}
  yarn add @crossmint/client-sdk-react-ui @crossmint/wallets-sdk @x402/core @x402/evm viem
  ```

  ```bash pnpm theme={null}
  pnpm add @crossmint/client-sdk-react-ui @crossmint/wallets-sdk @x402/core @x402/evm viem
  ```

  ```bash bun theme={null}
  bun add @crossmint/client-sdk-react-ui @crossmint/wallets-sdk @x402/core @x402/evm viem
  ```
</CodeGroup>

## Fund the wallet

Before the wallet can pay an x402 endpoint, it must hold USDC. In production, fund it through the [Crossmint onramp](/agents/payment-methods/stablecoin-wallets/onramp-add-funds) or by transferring USDC directly to `wallet.address`. In staging, `wallet.stagingFund(5)` mints test USDXM into the wallet.

```tsx x402-funding.tsx theme={null}
// Add this after you have a wallet handle and an authorized signer.
// In production, replace wallet.stagingFund(5) with your onramp order or direct transfer.
await wallet.stagingFund(5); // 5 USDXM, staging only
```

## Pay an x402 endpoint

```tsx x402-payment.tsx theme={null}
import { EVMWallet } from "@crossmint/client-sdk-react-ui";
import { x402Client, x402HTTPClient, wrapFetchWithPayment } from "@x402/core/client";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import type { Hex } from "viem";
import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";

const crossmint = createCrossmint({
    apiKey: "<your-server-api-key>",
});

const crossmintWallets = CrossmintWallets.from(crossmint);

const wallet = await crossmintWallets.getWallet(
    "<wallet-address>",
    { chain: "base" }
);

// Use the agent signer
await wallet.useSigner({
    type: "server",
    secret: process.env.CROSSMINT_SIGNER_SECRET,
});

// The wallet must be funded with USDC before it can pay x402 endpoints.
// In production, use the Crossmint onramp or a direct USDC transfer.
// In staging, call wallet.stagingFund(5).

const evmWallet = EVMWallet.from(wallet);

const x402Signer = {
  address: evmWallet.address as `0x${string}`,
  async signTypedData(typedData: any) {
    const { signature } = await evmWallet.signTypedData({
      ...typedData,
      chain: "base",
    });
    return signature as Hex;
  },
};

const client = new x402Client();
client.register("eip155:*", new ExactEvmScheme(x402Signer));

const fetchWithPayment = wrapFetchWithPayment(fetch, client);

const response = await fetchWithPayment("https://api.example.com/protected", {
  method: "GET",
});

const responseText = await response.text();
console.log("Response:", response.status, responseText);

if (response.ok) {
  const httpClient = new x402HTTPClient(client);
  const paymentResponse = httpClient.getPaymentSettleResponse(
    (name) => response.headers.get(name)
  );
  console.log("Payment settled:", paymentResponse);
}
```

## How the code works

<Steps>
  <Step title="Create an EVM signer from the Crossmint wallet">
    The `EVMWallet.from(wallet)` call wraps the Crossmint wallet into an EVM-compatible interface. A custom signer object is created that delegates `signTypedData` calls to the Crossmint wallet, which signs on Base using the agent's delegated permissions.
  </Step>

  <Step title="Register the signer with the x402 client">
    The `x402Client` is initialized and the EVM scheme is registered for all EIP-155 chains (`eip155:*`). This tells the x402 client how to sign payments on any EVM chain.
  </Step>

  <Step title="Wrap fetch with x402 payment handling">
    `wrapFetchWithPayment` returns a modified `fetch` function that automatically handles the 402 flow: if a request returns `402 Payment Required`, it reads the payment terms, signs a stablecoin payment, and retries with the payment proof attached.
  </Step>

  <Step title="Verify the payment receipt">
    After a successful response, `getPaymentSettleResponse` extracts the settlement receipt from the response headers, confirming the payment was processed onchain.
  </Step>
</Steps>

## Learn more

<CardGroup>
  <Card title="Wallets quickstart" icon="wallet" href="/agents/stablecoin-wallet-quickstart">
    Set up a stablecoin wallet for your agent.
  </Card>

  <Card title="Onramps" icon="arrow-down-to-line" href="/agents/payment-methods/stablecoin-wallets/onramp-add-funds">
    Fund the wallet with USDC so the agent can pay.
  </Card>
</CardGroup>


# Create an Agent Card
Source: https://docs.crossmint.com/agents/payment-methods/cards/create-agent-card

Create and authorize an order intent backed by a saved card

An agent card is an order intent that gives an agent a bounded amount to spend before a fixed expiration. An order intent can have multiple rails, each with its own status, credential formats, and verification.

## Prerequisites

* **Registered card** — [register a saved card](/agents/payment-methods/cards/register-card). A card with an `enabled` rail unlocks card-network credentials; a card without one can still use the encrypted card fallback described below.
* **Encrypted card access (production only)** — the `encrypted-card` fallback is enabled for every staging project. In production it must be enabled for your project: <a href="https://www.crossmint.com/contact/sales">contact us</a> for access.
* **Crossmint API key** — a client-side key with `order-intents.create` and `order-intents.read` scopes. In staging, all scopes are included by default.
* **User JWT** — use the JWT for the user who owns the saved card.

## Create the Order Intent

Create an order intent with the saved card, spending limit, description, expiration, and merchant. Include the merchant now when you already know where the agent will spend:

```typescript theme={null}
const CROSSMINT_CLIENT_API_KEY = "YOUR_CROSSMINT_CLIENT_API_KEY";
const jwt = "YOUR_USER_JWT";
const expiresAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString();

const response = await fetch("https://staging.crossmint.com/api/unstable/order-intents", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-KEY": CROSSMINT_CLIENT_API_KEY,
        Authorization: `Bearer ${jwt}`,
    },
    body: JSON.stringify({
        paymentMethodId: "pm_123",
        amount: { value: "150.00", currency: "USD" },
        merchant: {
            name: "Acme Store",
            url: "https://acme.example.com",
            countryCode: "US",
        },
        description: "Weekly grocery purchases",
        expiresAt,
    }),
});

if (!response.ok) {
    throw new Error(`Order intent creation failed (${response.status})`);
}

const orderIntent = await response.json();
```

The response separates the order intent's lifecycle from the status of each rail:

```json theme={null}
{
    "orderIntentId": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
    "paymentMethodId": "pm_123",
    "status": "active",
    "amount": {
        "total": "150.00",
        "spent": "0.00",
        "reserved": "0.00",
        "available": "150.00",
        "currency": "USD"
    },
    "merchant": {
        "name": "Acme Store",
        "url": "https://acme.example.com",
        "countryCode": "US"
    },
    "description": "Weekly grocery purchases",
    "rails": [
        {
            "rail": "agentic-token",
            "provider": "vic",
            "status": "pending_verification",
            "credentialFormats": ["card", "network-token"]
        }
    ],
    "verificationConfig": {
        "environment": "test",
        "publicApiKey": "key_test_123",
        "allowanceId": "alw_123"
    },
    "expiresAt": "2099-01-01T00:00:00.000Z"
}
```

Setting `merchant` when creating the order intent is preferred when you know it. The merchant is fixed for the lifetime of that order intent, and credential requests inherit the restriction.

If the agent will choose a merchant later, omit `merchant`. This creates an open order intent, and every credential request must supply the merchant instead.

The top-level `status` is `active` while the allowance exists. A specific rail can still require verification.

Treat `rails` as a set of independent ways to spend the same allowance:

1. Choose the rail that provides the credential you need.
2. If that rail is `pending_verification`, verify it.
3. Once it is `active`, mint with the same `rail` and `provider` values.

You do not need every rail to be active. Other rails can remain `pending_verification` or `error` without blocking the selected rail. For example, when an allowance contains both VIC and SPT, minting a VIC credential only requires the VIC rail to be verified; you do not need to complete an SPT step. Crossmint currently exposes VIC and Mastercard Agent Pay card-network rails, and the same selection rule applies as more rails are added.

### Encrypted Card Fallback

When no card-network rail can mint credentials, because registration reported none, every rail is in `error`, or none supports a credential format, an active order intent appends an `encrypted-card` rail to `rails`. Card-network rails that failed are kept alongside it so you can still read their `error`, so select the entry whose `rail` is `encrypted-card` rather than assuming a one-element array:

```json theme={null}
{
    "rails": [
        {
            "rail": "agentic-token",
            "provider": "vic",
            "status": "error",
            "credentialFormats": [],
            "error": { "code": "CARD_REJECTED" }
        },
        {
            "rail": "encrypted-card",
            "status": "active",
            "credentialFormats": ["card"]
        }
    ]
}
```

In production, the `encrypted-card` rail appears only when encrypted card access is enabled for your project (<a href="https://www.crossmint.com/contact/sales">contact us</a> for access); without it, an order intent with no usable card-network rail returns `rails` without a fallback, and a direct `encrypted-card` credential request fails with `ADDON_REQUIRED`. This access is granted per project because minting from this rail gives your application the user's real card number. Agent Checkouts is the exception: see [Use with Agent Checkouts](#use-with-agent-checkouts).

The `encrypted-card` rail has no `provider` and is always `active`. It never requires verification, so skip the `OrderIntentVerification` step and mint directly. Instead of a network-issued one-time card, minting returns the user's saved card encrypted to an RSA public key that you supply, so only the holder of the matching private key can read it. See [Retrieve Secure Card Numbers](/agents/payment-methods/cards/retrieve-agent-card#mint-an-encrypted-card) for the request format.

The fallback appears only when no card-network rail is usable. As soon as a card-network rail becomes available, prefer it: it enforces the allowance at the network level and never exposes the real card number.

## Verify the Selected Rail

When the rail you want to use has `status: "pending_verification"`, render `OrderIntentVerification` in your client application. Do not start verification merely because an unrelated rail is pending.

```tsx theme={null}
import {
    OrderIntentVerification,
    type OrderIntentVerificationProps,
} from "@crossmint/client-sdk-react-ui";

function VerifyOrderIntent({
    orderIntent,
}: {
    orderIntent: OrderIntentVerificationProps["orderIntent"];
}) {
    return (
        <OrderIntentVerification
            orderIntent={orderIntent}
            displayName="Acme Shopping Agent"
            onVerificationComplete={() => {
                console.log("Allowance verified");
            }}
            onVerificationError={(error) => {
                console.error("Allowance verification failed", error);
            }}
        />
    );
}
```

After verification completes, fetch the order intent again and wait for the selected rail to report `status: "active"`. You do not need to wait for the other rails.

Card registration never prompts for verification. Verification belongs to an individual order-intent rail. The first Visa verification on a device can create a passkey; later order intents authenticate with the existing passkey when the device remains bound. The component also handles the Mastercard-hosted flow.

For the complete request and response schemas, see the [Create Order Intent API Reference](/api-reference/agentic-commerce/order-intents/create-order-intent).

## Use with Agent Checkouts

For checkout payment requests, follow [Authorize Payments](/agents/checkouts/payments) to create the order intent and submit its ID.

Agent Checkouts can pay with the `encrypted-card` rail without encrypted card access enabled for your project. The access gate keeps the card number from reaching your systems. Inside an Agent Checkout, the card never leaves the Crossmint vault: the checkout uses it to pay the merchant, and your application only handles the `orderIntentId`. Without that access, your own reads of the order intent do not list the rail, but the checkout still uses it when the saved card's CVC is live. If the checkout answers `rail_unavailable`, [recollect the CVC](/agents/payment-methods/cards/recollect-cvc).

## Common Gotchas

<AccordionGroup>
  <Accordion title="An active order intent can still have a pending rail">
    Read `rails[].status` before minting. The top-level `status` describes the order intent's lifetime, not whether every rail is ready.
  </Accordion>

  <Accordion title="Each order intent has its own verification state">
    Register the card once, then verify only the order-intent rail you plan to use when it returns `pending_verification`. Do not repeat card registration to authorize a new allowance.
  </Accordion>

  <Accordion title="The encrypted-card rail does not enforce the allowance">
    Card networks enforce `amount` and `merchant` only for `agentic-token` rails. When your agent spends with an encrypted card, keep the purchase within the order intent's limits yourself and cancel the order intent when it is no longer needed.
  </Accordion>

  <Accordion title="The expiration is required">
    Set `expiresAt` to a future ISO 8601 timestamp that matches the permission you present to the user.
  </Accordion>

  <Accordion title="A scoped merchant cannot be changed later">
    Include `merchant` when creating the order intent if you already know it. Otherwise, omit it and supply a merchant with every credential request.
  </Accordion>

  <Accordion title="Browser verification requires HTTPS">
    Use an HTTPS tunnel when testing the verification ceremony from a local browser.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Retrieve Secure Card Numbers" icon="key" href="/agents/payment-methods/cards/retrieve-agent-card">
    Mint a credential from an active rail
  </Card>

  <Card title="Customize UI" icon="palette" href="/agents/payment-methods/cards/customize-verification-ui">
    Style the allowance verification modal and the CVC recollection form
  </Card>
</CardGroup>


# Customize UI
Source: https://docs.crossmint.com/agents/payment-methods/cards/customize-verification-ui

Style the allowance verification modal and the CVC recollection form to match your brand

The cards flow ships two hosted UIs, both styled through an `appearance` prop:

* `OrderIntentVerification` renders the modal where the user completes the card network's verification, such as a Visa passkey (see [Create an Agent Card](/agents/payment-methods/cards/create-agent-card#verify-the-selected-rail)).
* `CrossmintCvcRecollection` renders the field where the user re-enters a saved card's CVC after it expires (see [Recollect the CVC](/agents/payment-methods/cards/recollect-cvc)).

## Customize the Verification Modal

The `OrderIntentVerification` appearance object has two top-level keys: **`variables`** (global design tokens) and **`rules`** (per-element overrides).

<Tabs>
  <Tab title="Variables">
    Global design tokens that apply across the entire modal.

    | Token | What it controls |
    | - | - |
    | `fontFamily` | Font stack for all text |
    | `fontSizeUnit` | Base body font size (for example, `"14px"`). Title, small, error, input, and passkey sizes scale proportionally |
    | `spacingUnit` | Base section spacing (for example, `"16px"`). Modal, input, button-gap, and option-gap scale proportionally |
    | `borderRadius` | Default border radius for modal, input, button, and option elements |
    | `colors.accent` | Primary/brand color — buttons, focus rings, radio selected state, spinner |
    | `colors.textPrimary` | Main text color and button text |
    | `colors.textSecondary` | Secondary and placeholder text |
    | `colors.backgroundPrimary` | Surface/card background |
    | `colors.backgroundSecondary` | Input background, secondary button background |
    | `colors.border` | Default border for modal, inputs, and radio |
    | `colors.danger` | Error text, error border, error icon |
    | `colors.success` | Success icon, success background |

    <Info>
      The SDK auto-infers missing color tokens from the ones you provide. For example, setting only `backgroundPrimary` will derive `textPrimary`, `textSecondary`, `backgroundSecondary`, and `border` automatically.
    </Info>
  </Tab>

  <Tab title="Rules">
    Per-element overrides that take precedence over variables.

    | Rule | Customizable properties |
    | - | - |
    | `Overlay` | `colors.background` (backdrop behind the modal) |
    | `Modal` | `borderRadius`, `colors.border` |
    | `Input` | `borderRadius`, `colors.background`, `colors.border` |
    | `PrimaryButton` | `borderRadius`, `colors.text`, `colors.background`, `hover.colors.background`, `disabled.colors.background` |
    | `SecondaryButton` | `colors.text`, `colors.background`, `hover.colors.background` |
    | `CloseButton` | `colors.background`, `hover.colors.background` |
    | `Radio` | `colors.border`, `selected.colors.border`, `selected.colors.background`, `selected.colors.dot` |
  </Tab>
</Tabs>

### Apply the Appearance

You do not need to specify everything. The SDK infers missing colors:

```tsx theme={null}
import {
    OrderIntentVerification,
    type OrderIntentVerificationProps,
} from "@crossmint/client-sdk-react-ui";

function VerifyOrderIntent({
    orderIntent,
}: {
    orderIntent: OrderIntentVerificationProps["orderIntent"];
}) {
    return (
        <OrderIntentVerification
            orderIntent={orderIntent}
            appearance={{
                variables: {
                    colors: {
                        accent: "#6366f1",
                        backgroundPrimary: "#1e1e2e",
                    },
                },
            }}
            onVerificationComplete={() => {
                console.log("Allowance verified");
            }}
            onVerificationError={(error) => {
                console.error("Allowance verification failed", error);
            }}
        />
    );
}
```

This alone will auto-derive `textPrimary`, `textSecondary`, `backgroundSecondary`, and `border` from the dark background, and use the accent color for buttons, focus rings, and radio selections.

## Customize the CVC Recollection Form

`CrossmintCvcRecollection` accepts the same `appearance` object as [`CrossmintPaymentMethodManagement`](/agents/payment-methods/cards/save-card#steps). Keep `fontSizeUnit` and `spacingUnit` close to their defaults: they multiply the component's internal sizes rather than set a base size.

| Token | What it controls |
| - | - |
| `fontFamily` | Font stack for the label, input, and button |
| `fontSizeUnit` | Font size multiplier (default `"4px"`) |
| `spacingUnit` | Spacing multiplier (default `"3.33px"`) |
| `borderRadius` | Border radius for the input and button |
| `colors.accent` | Button background and focus ring |
| `colors.textPrimary` | Label and input text |
| `colors.backgroundPrimary` | Input background |
| `colors.borderPrimary` | Input border |
| `colors.danger` | Error text and error border |

```tsx theme={null}
import { CrossmintCvcRecollection } from "@crossmint/client-sdk-react-ui";

function RecollectCvc({ jwt, paymentMethodId }: { jwt: string; paymentMethodId: string }) {
    return (
        <CrossmintCvcRecollection
            jwt={jwt}
            paymentMethodId={paymentMethodId}
            appearance={{
                variables: {
                    fontSizeUnit: "4px",
                    spacingUnit: "3.33px",
                    borderRadius: "8px",
                    colors: {
                        accent: "#05B959",
                        textPrimary: "#00150d",
                        borderPrimary: "rgba(0,0,0,0.1)",
                    },
                },
            }}
            onComplete={() => {
                console.log("CVC updated");
            }}
        />
    );
}
```


# Recollect the CVC
Source: https://docs.crossmint.com/agents/payment-methods/cards/recollect-cvc

Ask the user to re-enter a saved card's CVC when it expires

The `encrypted-card` rail returns the user's saved card, including the CVC encrypted when the card was saved. Crossmint keeps that CVC for a limited time. Once it expires, the rail stops minting until the user types the CVC again. `CrossmintCvcRecollection` from `@crossmint/client-sdk-react-ui` renders Crossmint's hosted CVC field for that step: the digits never reach your application.

## Prerequisites

* **Saved and registered card** — follow [Save a Card](/agents/payment-methods/cards/save-card) and [Register a Card](/agents/payment-methods/cards/register-card).
* **Order intent with an `encrypted-card` rail** — follow [Create an Agent Card](/agents/payment-methods/cards/create-agent-card).
* **Crossmint API key** — a client-side key with the `order-intents.read`, `payment-methods.read`, and `payment-methods.update` scopes. In staging, all scopes are included by default.
* **User JWT** — the JWT for the user who owns the card.
* **React SDK** — `@crossmint/client-sdk-react-ui` 4.7.0 or later, with `CrossmintProvider` configured as in the other card guides.

## When to Render the Component

Two signals tell you that the CVC must be collected again. Handle both.

| Signal | Where it appears | Meaning |
| - | - | - |
| `status: "pending_cvc_recollection"` | The `encrypted-card` entry in `rails` of `GET /api/unstable/order-intents/{orderIntentId}` | The saved CVC expired. The rail cannot mint until the user re-enters it |
| `409` with `code: "ORDER_INTENT_CVC_RECOLLECTION_REQUIRED"` | `POST /api/unstable/order-intents/{orderIntentId}/credentials` with `rail: "encrypted-card"` | The CVC expired between your last read and the mint, or is no longer available |

A rail read as `active` can still answer `409` if the CVC expires before the mint. Read the order intent right before the user starts the mint flow, and treat the `409` as the same condition as the pending status.

```typescript theme={null}
const encryptedCard = orderIntent.rails.find((rail) => rail.rail === "encrypted-card");
const needsCvc = encryptedCard?.status === "pending_cvc_recollection";
```

## Render the Hosted CVC Field

Render `CrossmintCvcRecollection` in your client application with the user's JWT and the `paymentMethodId` of the order intent's card. The component renders a single CVC input and a confirm button, and no explanation of its own, so tell the user why the code is requested again.

```tsx theme={null}
import { CrossmintCvcRecollection } from "@crossmint/client-sdk-react-ui";

function RecollectCvc({ jwt, paymentMethodId }: { jwt: string; paymentMethodId: string }) {
    return (
        <div>
            <p>The security code for this card has expired. Enter it again to continue.</p>
            <CrossmintCvcRecollection
                jwt={jwt}
                paymentMethodId={paymentMethodId}
                onComplete={() => {
                    console.log("CVC updated");
                }}
                onError={(error) => {
                    console.error("CVC recollection failed", error);
                }}
            />
        </div>
    );
}
```

After `onComplete` fires, fetch the order intent again: the `encrypted-card` rail returns to `status: "active"` and you can mint as described in [Retrieve Secure Card Numbers](/agents/payment-methods/cards/retrieve-agent-card#mint-an-encrypted-card).

`onError` receives `{ reason, retriable, message }`. When `retriable` is `true`, the form stays mounted and the user can submit again. When it is `false`, the component renders nothing afterwards, so unmount it and show your own message.

To style the form, pass an `appearance` prop as described in [Customize UI](/agents/payment-methods/cards/customize-verification-ui#customize-the-cvc-recollection-form).

## Test in Staging

A freshly saved card does not reach `pending_cvc_recollection` during a normal test run. In staging, expire the CVC on demand:

```bash cURL theme={null}
curl --request POST \
    --url https://staging.crossmint.com/api/unstable/cvc-recollection/expire \
    --header 'Content-Type: application/json' \
    --header 'X-API-KEY: <YOUR_CROSSMINT_CLIENT_API_KEY>' \
    --header 'Authorization: Bearer <YOUR_USER_JWT>' \
    --data '{ "paymentMethodId": "<PAYMENT_METHOD_ID>" }'
```

The call answers `204`. The rail then reports `pending_cvc_recollection` and mints answer `409` until the user completes the form. The endpoint is staging-only.

## Next Steps

<CardGroup>
  <Card title="Retrieve Secure Card Numbers" icon="key" href="/agents/payment-methods/cards/retrieve-agent-card">
    Mint the encrypted card once the rail is active again
  </Card>

  <Card title="Cancel Card Access" icon="trash" href="/agents/payment-methods/cards/remove-cards">
    Cancel an order intent or delete a saved card
  </Card>
</CardGroup>


# Register a Card
Source: https://docs.crossmint.com/agents/payment-methods/cards/register-card

Register a saved card and discover the order-intent rails it supports

Register a saved card once before creating order intents against it. Registration provisions every supported rail, such as Visa Intelligent Commerce or Mastercard Agent Pay. It does not grant spending permission and does not prompt the user for verification.

## Prerequisites

* **Saved card** — follow [Save a Card](/agents/payment-methods/cards/save-card) and keep its `paymentMethodId`.
* **Crossmint API key** — a client-side key with the `payment-methods.create`, `payment-methods.read`, and `payment-methods.update` scopes. The `update` scope lets the user re-enter the card security code (CVC) later, when a card credential needs it. In staging, all scopes are included by default.
* **User JWT** — use the JWT for the user who owns the saved card.

## Register the Card

Send an idempotent `PUT` request with the consumer information used by card-network rails:

```typescript theme={null}
const CROSSMINT_CLIENT_API_KEY = "YOUR_CROSSMINT_CLIENT_API_KEY";
const jwt = "YOUR_USER_JWT";
const paymentMethodId = "pm_123";

const response = await fetch(
    `https://staging.crossmint.com/api/unstable/payment-methods/${paymentMethodId}/order-intent-registration`,
    {
        method: "PUT",
        headers: {
            "Content-Type": "application/json",
            "X-API-KEY": CROSSMINT_CLIENT_API_KEY,
            Authorization: `Bearer ${jwt}`,
        },
        body: JSON.stringify({
            email: "buyer@example.com",
            countryCode: "US",
            languageCode: "en-US",
        }),
    }
);

if (!response.ok) {
    throw new Error(`Card registration failed (${response.status})`);
}

const registration = await response.json();
```

The response reports one or more supported rails independently:

```json theme={null}
{
    "paymentMethodId": "pm_123",
    "rails": [
        {
            "rail": "agentic-token",
            "provider": "vic",
            "status": "enabled"
        }
    ]
}
```

Read the complete `rails` array instead of branching on the card brand or assuming there is only one result. Visa cards can report `provider: "vic"`, and Mastercard cards can report `provider: "agentpay"`.

| Status | Meaning |
| - | - |
| `enabled` | The rail can back a new order intent |
| `pending` | Rail provisioning has not finished |
| `error` | Provisioning failed; read `error.code` |

More than one rail can be available. Registration provisions those rails, but it does not choose between them or require every rail to succeed. Use `GET /api/unstable/payment-methods/{paymentMethodId}/order-intent-registration` to read the registration again.

A card with no `enabled` rail, including one whose `rails` array is empty, can still back an order intent. In that case the order intent's `rails` array includes an `encrypted-card` rail that returns the saved card encrypted to your public key; in production, encrypted card access must be enabled for your project. See [Encrypted Card Fallback](/agents/payment-methods/cards/create-agent-card#encrypted-card-fallback).

Registration is separate from allowance verification: no email code, passkey, or spending approval occurs in this step. You choose which rail to use after creating an order intent.

## Test the Rails

In staging, the saved card number selects a deterministic registration and verification scenario, such as a rejected rail or a failed verification. See [Test Agent Cards](/agents/payment-methods/cards/test-agent-cards) for the test cards.

## Next Steps

<CardGroup>
  <Card title="Create an Agent Card" icon="credit-card" href="/agents/payment-methods/cards/create-agent-card">
    Create an order intent backed by one of the card's rails
  </Card>

  <Card title="Cards Quickstart" icon="rocket" href="/agents/cards-quickstart">
    Run the complete flow in the reference app
  </Card>
</CardGroup>


# Cancel Card Access
Source: https://docs.crossmint.com/agents/payment-methods/cards/remove-cards

Cancel an order intent or delete a saved card

Cancel an order intent to stop minting credentials from that allowance. Delete a saved card when the user no longer wants it stored in Crossmint.

## Prerequisites

* **Crossmint API key** — a client-side key with `order-intents.revoke` or `payment-methods.delete`, depending on the operation. In staging, all scopes are included by default.
* **User JWT** — use the JWT for the user who owns the resource.

## Cancel an Order Intent

Send a `DELETE` request with the `orderIntentId`:

```typescript theme={null}
const CROSSMINT_CLIENT_API_KEY = "YOUR_CROSSMINT_CLIENT_API_KEY";
const jwt = "YOUR_USER_JWT";
const orderIntentId = "a1b2c3d4-e5f6-4890-abcd-ef1234567890";

const response = await fetch(
    `https://staging.crossmint.com/api/unstable/order-intents/${orderIntentId}`,
    {
        method: "DELETE",
        headers: {
            "X-API-KEY": CROSSMINT_CLIENT_API_KEY,
            Authorization: `Bearer ${jwt}`,
        },
    }
);

if (!response.ok) {
    throw new Error(`Order intent cancellation failed (${response.status})`);
}
```

A successful cancellation returns `204 No Content`. Subsequent reads return `status: "cancelled"`, and no additional credentials can be minted from its rails. Create a new order intent when you need a replacement allowance.

## Delete a Saved Card

Send a `DELETE` request with the `paymentMethodId`:

```typescript theme={null}
const CROSSMINT_CLIENT_API_KEY = "YOUR_CROSSMINT_CLIENT_API_KEY";
const jwt = "YOUR_USER_JWT";
const paymentMethodId = "pm_123";

const response = await fetch(
    `https://staging.crossmint.com/api/unstable/payment-methods/${paymentMethodId}`,
    {
        method: "DELETE",
        headers: {
            "X-API-KEY": CROSSMINT_CLIENT_API_KEY,
            Authorization: `Bearer ${jwt}`,
        },
    }
);

if (!response.ok) {
    throw new Error(`Payment method deletion failed (${response.status})`);
}
```

Deleting the saved card prevents new order intents from being created against it. Existing order intents remain independent resources, so cancel them explicitly when access must end immediately.

## Next Steps

<CardGroup>
  <Card title="Create an Agent Card" icon="credit-card" href="/agents/payment-methods/cards/create-agent-card">
    Create a replacement order intent
  </Card>

  <Card title="Order Intent API" icon="code" href="/api-reference/agentic-commerce/order-intents/get-order-intent">
    Inspect order-intent status and balances
  </Card>
</CardGroup>


# Retrieve Secure Card Numbers
Source: https://docs.crossmint.com/agents/payment-methods/cards/retrieve-agent-card

Mint a one-time card-network credential or an encrypted saved card from an active order-intent rail

Mint a credential for a specific amount and merchant from an order intent. Choose one rail from the order-intent response and use that same rail for verification and credential minting.

The request and response shape depend on the rail:

| Rail | What you receive | When it appears |
| - | - | - |
| `agentic-token` | A one-time card number or network token issued by Visa Intelligent Commerce or Mastercard Agent Pay, bounded by the requested amount and merchant | The saved card supports a card-network rail |
| `encrypted-card` | The user's saved card, encrypted to an RSA public key that you provide. Minting consumes the requested amount from the order intent, like the other rails | No card-network rail is usable for the order intent. In production, only for projects with encrypted card access enabled |

## Prerequisites

* **Verified order intent** — follow [Create an Agent Card](/agents/payment-methods/cards/create-agent-card) and wait for a rail with `status: "active"`.
* **Crossmint API key** — a client-side key with the `order-intents.read` and `order-intents.credentials` scopes. To recover from `ORDER_INTENT_CVC_RECOLLECTION_REQUIRED` with the hosted CVC step, the same key also needs `payment-methods.read` and `payment-methods.update`. In staging, all scopes are included by default.
* **User JWT** — use the JWT for the user who owns the order intent.

## Mint a Card-Network Credential

Find the `agentic-token` rail you want to use and confirm that it is active and supports card credentials. Other rails can remain pending. Send the selected rail's `rail` and `provider` values back in the request.

This example continues from the merchant-scoped order intent created in the previous guide, so the credential request does not repeat the merchant:

```typescript theme={null}
const CROSSMINT_CLIENT_API_KEY = "YOUR_CROSSMINT_CLIENT_API_KEY";
const jwt = "YOUR_USER_JWT";
const orderIntentId = "a1b2c3d4-e5f6-4890-abcd-ef1234567890";

const orderIntentResponse = await fetch(
    `https://staging.crossmint.com/api/unstable/order-intents/${orderIntentId}`,
    {
        headers: {
            "X-API-KEY": CROSSMINT_CLIENT_API_KEY,
            Authorization: `Bearer ${jwt}`,
        },
    }
);

if (!orderIntentResponse.ok) {
    throw new Error(`Order intent retrieval failed (${orderIntentResponse.status})`);
}

const orderIntent = await orderIntentResponse.json();

const selectedRail = orderIntent.rails.find(
    (rail) =>
        rail.rail === "agentic-token" &&
        rail.status === "active" &&
        rail.credentialFormats.includes("card")
);

if (selectedRail == null) {
    throw new Error("No active card-network rail supports card credentials");
}

const response = await fetch(
    `https://staging.crossmint.com/api/unstable/order-intents/${orderIntent.orderIntentId}/credentials`,
    {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            "X-API-KEY": CROSSMINT_CLIENT_API_KEY,
            Authorization: `Bearer ${jwt}`,
        },
        body: JSON.stringify({
            rail: selectedRail.rail,
            provider: selectedRail.provider,
            amount: { value: "25.00", currency: orderIntent.amount.currency },
            credential: { format: "card" },
        }),
    }
);

if (!response.ok) {
    throw new Error(`Credential creation failed (${response.status})`);
}

const result = await response.json();
```

### Open Order Intents

If `orderIntent.merchant` is absent, include a merchant in every credential request:

```typescript theme={null}
merchant: {
    name: "Acme Store",
    url: "https://acme.example.com",
    countryCode: "US",
},
```

The response returns the selected rail and the credential value. An inactive status on another rail does not affect this request:

```json theme={null}
{
    "id": "cred_123",
    "rail": "agentic-token",
    "provider": "vic",
    "amount": { "value": "25.00", "currency": "USD" },
    "credential": {
        "format": "card",
        "value": {
            "number": "4000001000004242",
            "expirationMonth": 12,
            "expirationYear": 2030,
            "cvc": "123"
        }
    },
    "expiresAt": "2099-01-01T00:05:00.000Z"
}
```

Treat the credential as a secret. Use it immediately, never log it, and do not persist it for later reuse. Minting deducts the requested amount from the order intent even if the credential is never used.

For the complete schema, see the [Create Order Intent Credential API Reference](/api-reference/agentic-commerce/order-intents/get-order-intent-credentials).

## Mint an Encrypted Card

When the order intent's `rails` array contains an `encrypted-card` entry, the response cannot contain a network-issued one-time card. Instead, the user's saved card is encrypted inside the PCI-compliant vault to a public key that you control, and Crossmint returns the ciphertext. Only the holder of the matching private key can read the card.

### Generate a Key Pair

Generate an RSA key pair of at least 2048 bits for the `RSA-OAEP-256` algorithm. Keep the private key wherever the agent will decrypt the card; only the public key is sent to Crossmint.

```typescript theme={null}
const { publicKey, privateKey } = await crypto.subtle.generateKey(
    {
        name: "RSA-OAEP",
        modulusLength: 2048,
        publicExponent: new Uint8Array([1, 0, 1]),
        hash: "SHA-256",
    },
    true,
    ["encrypt", "decrypt"]
);

const { kty, n, e } = await crypto.subtle.exportKey("jwk", publicKey);
```

### Request the Encrypted Card

Send the public key as a JWK with only the `kty`, `n`, and `e` members. The request takes the same `amount` and optional `merchant` as the other rails; the `encrypted-card` rail has no `provider`:

```typescript theme={null}
const CROSSMINT_CLIENT_API_KEY = "YOUR_CROSSMINT_CLIENT_API_KEY";
const jwt = "YOUR_USER_JWT";
const orderIntentId = "a1b2c3d4-e5f6-4890-abcd-ef1234567890";

const response = await fetch(
    `https://staging.crossmint.com/api/unstable/order-intents/${orderIntentId}/credentials`,
    {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            "X-API-KEY": CROSSMINT_CLIENT_API_KEY,
            Authorization: `Bearer ${jwt}`,
        },
        body: JSON.stringify({
            rail: "encrypted-card",
            amount: { value: "25.00", currency: "USD" }, // the order intent's currency
            credential: {
                format: "card",
                publicKey: { kty, n, e },
            },
        }),
    }
);

if (!response.ok) {
    throw new Error(`Credential creation failed (${response.status})`);
}

const result = await response.json();
```

The response contains the encrypted card as a compact JWE string, with the same `id`, `amount`, and `expiresAt` fields as a card-network credential. The `id` is issued by Crossmint. `expiresAt` is the earlier of two deadlines: the end of the window in which the vault still holds the card's security code, and the order intent's own `expiresAt`. After it passes, mint again for what you still need; the amount already minted does not come back. If the security-code window is what ended, the rail reads `pending_cvc_recollection` and the user re-enters the CVC first; if the order intent itself expired, create a new one:

```json theme={null}
{
    "id": "6f1c2a8e-3b7d-4c1e-9a2f-0d5e7b9c4a11",
    "rail": "encrypted-card",
    "amount": { "value": "25.00", "currency": "USD" },
    "credential": {
        "format": "card",
        "value": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwidHlwIjoiSldFIn0..."
    },
    "expiresAt": "2026-09-23T16:20:00.000Z"
}
```

### Decrypt the Card

The JWE uses `RSA-OAEP-256` for key encryption and `A256GCM` for content encryption. Decrypt it with your private key using a JOSE library. The plaintext is a JSON object with the same fields as a card-network credential:

```typescript theme={null}
import { compactDecrypt } from "jose";

const { plaintext } = await compactDecrypt(result.credential.value, privateKey);
const card = JSON.parse(new TextDecoder().decode(plaintext));
// { number: "4242424242424242", expirationMonth: 12, expirationYear: 2030, cvc: "123" }
```

The decrypted value is the user's real card, not a one-time number. Treat it with the same care as raw cardholder data: decrypt it only where the payment is made, never log or persist it, and discard the private key when the purchase completes. Minting consumes the requested `amount` from the order intent even if the card is never charged, and the order intent refuses a mint above `amount.available`. The card network does not enforce the allowance, so your agent must keep each purchase within the `amount` it minted and the order intent's `merchant`.

### Encrypted Card Errors

| Error code | Meaning |
| - | - |
| `ORDER_INTENT_INVALID_PUBLIC_KEY` | The vault rejected `publicKey`, for example because `n` and `e` do not form a usable RSA key |
| `ADDON_REQUIRED` | Encrypted card access is not enabled for the project in production; <a href="https://www.crossmint.com/contact/sales">contact us</a> for access |
| `ORDER_INTENT_CVC_RECOLLECTION_REQUIRED` | The card security code (CVC) has expired or is no longer available for this card. The `encrypted-card` rail shows `status: "pending_cvc_recollection"`. Ask the user to re-enter the CVC with [Recollect the CVC](/agents/payment-methods/cards/recollect-cvc), then retry the request |
| `ORDER_INTENT_CREDENTIAL_UNAVAILABLE` | The vault rejected the saved card, or the request does not fit the order intent: a different currency, no merchant on an order intent created without one, or a merchant other than the one the order intent was created with. The `message` says which. A request may name only part of the merchant; every field it names must match |
| `ORDER_INTENT_AMOUNT_EXCEEDED` | The requested `amount` is above `amount.available` |
| `ORDER_INTENT_CREDENTIAL_ALREADY_ISSUED` | `409`. A credential was already issued for this `Idempotency-Key`. Credential payloads are returned once; use a new key for a new mint |
| `ORDER_INTENT_EXPIRED` | The order intent has passed its `expiresAt` |
| `ORDER_INTENT_CANCELLED` | The order intent was cancelled |

To make a retry safe, send an `Idempotency-Key` header (1 to 255 characters) with the request. A second call with the same key never consumes the amount again: while the first is unanswered it is refused, and after a successful mint it returns `ORDER_INTENT_CREDENTIAL_ALREADY_ISSUED`. Without the header every call is a new mint.

A malformed request, such as a `publicKey` whose `kty` is not `RSA` or whose encoded `n` is shorter than 342 base64url characters, fails schema validation before the vault is called and returns a `400` without an order-intent error code. Other unusable RSA keys can reach the vault and return `ORDER_INTENT_INVALID_PUBLIC_KEY`.

## List Order Intents

List every order intent owned by the authenticated user:

```typescript theme={null}
const CROSSMINT_CLIENT_API_KEY = "YOUR_CROSSMINT_CLIENT_API_KEY";
const jwt = "YOUR_USER_JWT";

const response = await fetch("https://staging.crossmint.com/api/unstable/order-intents", {
    headers: {
        "X-API-KEY": CROSSMINT_CLIENT_API_KEY,
        Authorization: `Bearer ${jwt}`,
    },
});

if (!response.ok) {
    throw new Error(`Order intent listing failed (${response.status})`);
}

const orderIntents = await response.json();
```

Each item includes its live balance and rails. Use `GET /api/unstable/order-intents/{orderIntentId}` when you only need to refresh one order intent.

## Common Gotchas

<AccordionGroup>
  <Accordion title="The request amount must fit the available balance">
    Use the same currency as the order intent and keep the requested value at or below `amount.available`.
  </Accordion>

  <Accordion title="Creating a credential spends allowance capacity">
    Do not retry a credential request blindly. Each successful mint is a new credential and consumes the requested amount.
  </Accordion>

  <Accordion title="A pending rail cannot mint credentials">
    Complete allowance verification for the rail you selected and fetch the order intent again before minting. You do not need to verify unrelated rails.
  </Accordion>

  <Accordion title="Open order intents require a merchant">
    If the order intent was created without `merchant`, include one in every credential request. If the merchant was set at creation, omit it when minting, or repeat it exactly: a different merchant is refused. This applies to every rail, `encrypted-card` included.
  </Accordion>

  <Accordion title="Encrypted cards differ only in the credential block">
    With `rail: "encrypted-card"`, send `amount`, an optional `merchant`, and `credential.format` with `credential.publicKey`. Do not send `provider`. Requests with unknown fields are rejected.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Cancel Card Access" icon="trash" href="/agents/payment-methods/cards/remove-cards">
    Cancel an order intent or delete a saved card
  </Card>

  <Card title="Cards Quickstart" icon="credit-card" href="/agents/cards-quickstart">
    Run the complete flow in the reference app
  </Card>
</CardGroup>


# Save a Card
Source: https://docs.crossmint.com/agents/payment-methods/cards/save-card

Save a user's card with Crossmint so you can register it for agentic payment rails

## Introduction

The user enters their card into a Crossmint-hosted UI, and your app receives a `paymentMethodId` for subsequent API calls. Raw card data never reaches your servers.

Saving the card does not grant spending permission. You register the saved card to discover its supported rails, then create and verify a separate order intent before minting credentials.

## Prerequisites

* **Crossmint API key** — a client-side key with the `payment-methods.create`, `payment-methods.read`, and `payment-methods.update` scopes. The `update` scope lets the user re-enter the card security code (CVC) later, when a card credential needs it. In staging, all scopes are included by default.
* **User JWT** — authenticate the user with [Crossmint Auth](/authentication/introduction) or a configured external provider.

<Note>
  **Saved card limit.** In production, each project has a limit on the number of cards it can save, unless the Crossmint team has raised or removed it for the project. The limit counts the saved cards of all the project's users; deleted cards do not count. Staging has no limit. The limit applies to cards only: bank accounts have no limit, but in production saving them must be enabled for your project.

  At the limit, saving another card returns `400` with the code `payments:payment-method.card-limit-reached`, and the project's limit in `parameters.limit`. Cards that are already saved keep working, so agents can still spend with them. To save a new card, [remove a card](/agents/payment-methods/cards/remove-cards) that a user no longer needs. To raise the limit, <a href="https://www.crossmint.com/contact/sales">contact the Crossmint team</a>.
</Note>

## Steps

<Steps>
  <Step title="Install the SDK">
    <CodeGroup>
      ```bash npm theme={null}
      npm install @crossmint/client-sdk-react-ui
      ```

      ```bash yarn theme={null}
      yarn add @crossmint/client-sdk-react-ui
      ```

      ```bash pnpm theme={null}
      pnpm add @crossmint/client-sdk-react-ui
      ```

      ```bash bun theme={null}
      bun add @crossmint/client-sdk-react-ui
      ```
    </CodeGroup>
  </Step>

  <Step title="Wrap your app with the Crossmint provider">
    Set up `CrossmintProvider` at the root of your app. This makes the Crossmint SDK available to all child components.

    ```tsx theme={null}
    "use client";
    import { CrossmintProvider } from "@crossmint/client-sdk-react-ui";

    function App() {
        return (
            <CrossmintProvider apiKey={process.env.NEXT_PUBLIC_CROSSMINT_CLIENT_API_KEY}>
                {/* Your app */}
            </CrossmintProvider>
        );
    }
    ```
  </Step>

  <Step title="Add the card collection component">
    Place this component on a page where the user manages their payment methods, or in an ephemeral UI dedicated to saving cards.

    The `CrossmintPaymentMethodManagement` component handles all PCI compliance concerns. Card data is collected directly by Crossmint and never passes through your servers — this is why the UI must be rendered inside your app rather than called from your backend.

    <Note>
      In staging, use the test card number **4242 4242 4242 4242** with any future expiration date and any three-digit CVC. For additional scenarios, see [Test Agent Cards](/agents/payment-methods/cards/test-agent-cards).
    </Note>

    ```tsx theme={null}
    import { CrossmintPaymentMethodManagement } from "@crossmint/client-sdk-react-ui";

    function PaymentMethodsPage({ jwt }: { jwt: string }) {
        // jwt comes from your own auth provider (for example Stytch, Auth0, Dynamic)

        const handlePaymentMethodSelected = (paymentMethod: { paymentMethodId: string }) => {
            // Persist this ID so you can register the card and create order intents.
            console.log("Card saved:", paymentMethod.paymentMethodId);
        };

        return (
            <div>
                <h2>Payment Methods</h2>
                <p>Save a card so your agent can request payments on your behalf.</p>
                <CrossmintPaymentMethodManagement
                    jwt={jwt}
                    onPaymentMethodSelected={handlePaymentMethodSelected}
                />
            </div>
        );
    }
    ```
  </Step>

  <Step title="Store the payment method ID">
    When the user saves a card, the `onPaymentMethodSelected` callback returns a `paymentMethodId`. Persist this ID in your backend associated with the user, apply strict access controls, and avoid exposing it in client-side storage or logs.

    The ID cannot reveal the original card number, but it can be used to register the card and create order intents.
  </Step>
</Steps>

## Next Steps

Continue to [Register a Card](/agents/payment-methods/cards/register-card) to discover which order-intent rails support the saved card.


# Test Agent Cards
Source: https://docs.crossmint.com/agents/payment-methods/cards/test-agent-cards

Use staging test cards to exercise card registration, verification, and credential minting

In staging, every card-network rail routes to a deterministic mock of Visa Intelligent Commerce and Mastercard Agent Pay. No request reaches a real card network, but the endpoints, response shapes, statuses, and error codes match production. The card number you save selects the scenario, so you can test success and failure paths without a real card.

## Prerequisites

* **Staging API key** — a client-side key from the <a href="https://staging.crossmint.com/console/projects/apiKeys">Crossmint Staging Console</a>. In staging, all scopes are included by default.
* **Card flow** — the integration from [Save a Card](/agents/payment-methods/cards/save-card), [Register a Card](/agents/payment-methods/cards/register-card), [Create an Agent Card](/agents/payment-methods/cards/create-agent-card), and [Retrieve Secure Card Numbers](/agents/payment-methods/cards/retrieve-agent-card), pointed at `https://staging.crossmint.com`.

## Test Cards

Save one of these numbers with any future expiration date and any three-digit CVC. Any Visa or Mastercard number not listed follows its brand's happy path.

| Card | Brand | Outcome |
| - | - | - |
| `4242 4242 4242 4242` | Visa | Succeeds end to end |
| `5555 5555 5555 4444` | Mastercard | Succeeds end to end |
| `5186 1600 0000 0001` | Mastercard | Fails at registration with `CARD_REJECTED` |
| `4929 9803 9556 7582` | Visa | Fails at verification: the one-time code is rejected with `INVALID_OTP` |
| `5186 1600 0000 0003` | Mastercard | Fails at verification: the hosted page appears to succeed, but the rail never becomes `active` |

## What a Successful Card Returns

[Register a Card](/agents/payment-methods/cards/register-card) reports one card-network rail for the card. The `rail` is always `agentic-token`; the `provider` names the network program behind it, `vic` for Visa Intelligent Commerce or `agentpay` for Mastercard Agent Pay:

```json theme={null}
{
    "paymentMethodId": "pm_123",
    "rails": [
        {
            "rail": "agentic-token",
            "provider": "agentpay",
            "status": "enabled"
        }
    ]
}
```

An order intent created for that card ([Create an Agent Card](/agents/payment-methods/cards/create-agent-card)) carries the same rail with `status: "pending_verification"`. After the cardholder approves the allowance in `OrderIntentVerification`, fetch the order intent again: the rail reports `status: "active"` and you can mint.

```json theme={null}
{
    "rail": "agentic-token",
    "provider": "agentpay",
    "status": "active",
    "credentialFormats": ["card", "network-token"]
}
```

## Failure Scenarios

<Note>
  The three cards below are designed to fail. The error each one produces is the expected result of the scenario, not
  a problem with your integration.
</Note>

### Card Rejected at Registration

Save `5186 1600 0000 0001`. The registration request succeeds, but the Mastercard rail is reported in `error`:

```json theme={null}
{
    "paymentMethodId": "pm_123",
    "rails": [
        {
            "rail": "agentic-token",
            "provider": "agentpay",
            "status": "error",
            "error": { "code": "CARD_REJECTED" }
        }
    ]
}
```

The card is saved and the rejection is permanent. Confirm that your UI treats this as a saved card with one failed rail, not as a failed save. Order intents for this card include an `encrypted-card` rail, which is enabled for every staging project, so mint through it instead. See [Mint an Encrypted Card](/agents/payment-methods/cards/retrieve-agent-card#mint-an-encrypted-card).

### One-Time Code Rejected

Save `4929 9803 9556 7582`. Registration succeeds with a `vic` rail `enabled`, and the order intent's rail is `pending_verification`. In `OrderIntentVerification`, the Visa flow asks for a one-time code and rejects every code with `INVALID_OTP`. The user can enter another code, but this card never accepts one, so verification does not complete and the rail stays `pending_verification`:

```json theme={null}
{
    "rail": "agentic-token",
    "provider": "vic",
    "status": "pending_verification",
    "credentialFormats": ["card", "network-token"]
}
```

Confirm that your UI lets the user retry or abandon the verification, and that nothing mints while the rail is `pending_verification`.

### Hosted Page Returns but Verification Fails

Save `5186 1600 0000 0003`. Registration succeeds with an `agentpay` rail `enabled`. During verification, the mock Mastercard-hosted page shows a success message and returns to your application, but when Crossmint confirms the result with the network, the confirmation fails. `OrderIntentVerification` calls `onVerificationError`, and the rail stays `pending_verification`.

Confirm that your integration waits for `onVerificationComplete` and then fetches the order intent until the rail reports `active`, rather than minting as soon as the hosted page closes.

## Test Verification

Verification is the step where the cardholder approves an order intent's allowance through the `OrderIntentVerification` component. The mocks run the same browser flow as production, so popups, message listeners, and origin checks are all exercised.

* **Visa** — the verification asks the user to choose a one-time code method (a masked phone number or email address) and accepts any code, unless the card scenario says otherwise. On a device without a passkey, a mock Visa screen enrolls one. Later order intents on the same device go straight to passkey authentication, as in production.
* **Mastercard** — the component opens a mock Mastercard-hosted page that shows its progress and returns to your application. The rail becomes `active` only after Crossmint confirms the result, so fetch the order intent again before minting.

Use an HTTPS tunnel when you test verification from a local browser. It exercises the same iframe, origin, and popup behavior as your deployed site.

## Check the Minted Credentials

Mock credentials are deterministic, so repeated runs return stable values. Use them in integration tests only; they are not accepted by real merchants.

| Format | Value |
| - | - |
| `card` | A virtual card number: `4000 0010 0000 4242` for the `4242` Visa card and `5100 0010 0000 4446` for the `4444` Mastercard. Other cards return `4000 0010 0000 0000` (Visa) or `5100 0010 0000 0006` (Mastercard). The expiration date matches the saved card, and the CVC is derived deterministically |
| `network-token` | The same virtual number with a deterministic cryptogram. Visa returns ECI `07` and Mastercard returns ECI `06` |

Credential expiry follows each network's rule rather than a uniform test value. The Visa mock returns a short synthetic cryptogram window, so do not calibrate how long a credential stays usable against it. Use every credential immediately.

## Test Common Scenarios

The allowance accounting in staging is real, so these scenarios behave exactly as in production.

* **Spend limits** — create an order intent for `10.00`, mint a credential for `7.00`, then read the order intent: `amount.available` is `3.00`. Minting `4.00` next fails with `ORDER_INTENT_AMOUNT_EXCEEDED`.
* **Encrypted card fallback** — save `5186 1600 0000 0001` and mint through the `encrypted-card` rail, as described in [Card Rejected at Registration](#card-rejected-at-registration).
* **CVC recollection** — expire a saved card's CVC on demand to test the `pending_cvc_recollection` state. See [Test in Staging](/agents/payment-methods/cards/recollect-cvc#test-in-staging).

## Next Steps

<CardGroup>
  <Card title="Create an Agent Card" icon="credit-card" href="/agents/payment-methods/cards/create-agent-card">
    Create an order intent and verify its rail
  </Card>

  <Card title="Cards Quickstart" icon="rocket" href="/agents/cards-quickstart">
    Run the complete flow in the reference app
  </Card>
</CardGroup>


# Authorize the Agent
Source: https://docs.crossmint.com/agents/payment-methods/stablecoin-wallets/authorize-agent

Grant your agent delegated control over the user's wallet.

## Introduction

To let the agent move funds from the user's wallet, you create a **signer** for the agent and add it to the wallet. A signer is just a key that can authorize transactions — the agent gets its own, separate from the user's.

You add the signer in two parts so the user stays in control:

1. **On your server**, you create the signer and register it on the wallet as *pending*. The signer's secret stays in your backend and never reaches the browser or the agent.
2. **On the client**, the user approves the new signer with a one-time email code. Only after this step can the agent sign anything.

Once approved, the agent can transact within the limits you set — and the user can revoke it at any time.

## Prerequisites

* A user wallet. See [Server signer setup](/wallets/guides/signers/server-signer#signer-secret-generator) if you have not done this yet.
* A Crossmint **server-side** API key from the <a href="https://staging.crossmint.com/console/projects/apiKeys">Crossmint Console</a>.
* The user must be authenticated and signed in to your app.

## Steps

<Steps>
  <Step title="Generate and store the signer secret">
    The server signer is backed by a 32-byte secret. Generate one with [the signer secret generator](/agents/stablecoin-wallet-quickstart#setup) and store it only as a backend environment variable.

    ```bash theme={null}
    CROSSMINT_SERVER_SIDE_API_KEY=sk_staging_...
    CROSSMINT_SIGNER_SECRET=your-64-char-hex-secret
    ```

    <Warning>
      Anyone who holds `CROSSMINT_SIGNER_SECRET` can sign on behalf of every wallet it has been authorized on. Never commit it, never expose it to the client, and rotate it if you suspect leakage.
    </Warning>
  </Step>

  <Step title="Register the signer from the server">
    Use a server action (or any server-only handler) to call `addSigner` in `prepareOnly` mode. The secret is read from the environment and never sent over the wire.

    ```typescript theme={null}
    "use server";

    import { createCrossmint, CrossmintWallets } from "@crossmint/wallets-sdk";

    export async function prepareServerSigner({ walletAddress }: { walletAddress: string }) {
        const crossmint = createCrossmint({
            apiKey: process.env.CROSSMINT_SERVER_SIDE_API_KEY,
        });
        const wallets = CrossmintWallets.from(crossmint);
        const wallet = await wallets.getWallet(walletAddress, { chain: "base-sepolia" });

        const { locator, signatureId } = await wallet.addSigner(
            { type: "server", secret: process.env.CROSSMINT_SIGNER_SECRET },
            { prepareOnly: true }
        );

        return { locator, signatureId };
    }
    ```

    `prepareOnly: true` is what makes this safe. Without it, the SDK would auto-approve using whatever signer is active, which on the server is the server signer itself — the user would never see a prompt.
  </Step>

  <Step title="Approve from the client">
    On the client, call the server action and then ask the SDK to approve the pending signature with the user's recovery method. This is the step that triggers the email code.

    ```tsx theme={null}
    "use client";

    import { useWallet, useCrossmintAuth } from "@crossmint/client-sdk-react-ui";
    import { prepareServerSigner } from "@/app/actions/add-server-signer";

    export function AuthorizeAgent() {
        const { wallet } = useWallet();
        const { user } = useCrossmintAuth();

        const handleAuthorize = async () => {
            if (!wallet || !user?.email) return;

            const { signatureId } = await prepareServerSigner({ walletAddress: wallet.address });

            await wallet.useSigner({ type: "email", email: user.email });
            await wallet.approve({ signatureId });
        };

        return <button onClick={handleAuthorize}>Authorize agent</button>;
    }
    ```

    Once the user completes the verification, the server signer becomes an authorized signer on the wallet. Verify by calling `wallet.signers()` — you should see an entry with `type: "server"`.
  </Step>
</Steps>

## Revoking the Agent

Once authorized, the agent can be revoked at any time. See [Remove Agent Access](/agents/payment-methods/stablecoin-wallets/remove-agent-access).

## Common Gotchas

<AccordionGroup>
  <Accordion title="Always pass `prepareOnly: true` from the server">
    If you omit it, the server signer signs its own authorization and the user never approves. The pending signature step is what gives the user veto power.
  </Accordion>

  <Accordion title="The signer secret must stay server-side">
    Anyone holding the secret can sign for every wallet it has been authorized on. Treat it like a database password — environment variables only, never the client bundle.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Onramp Funds" icon="arrow-down-to-line" href="/agents/payment-methods/stablecoin-wallets/onramp-add-funds">
    Add stablecoin balance to the user's wallet so the authorized agent can start spending.
  </Card>

  <Card title="Server Signer Deep Dive" icon="server" href="/wallets/guides/signers/server-signer">
    Full reference for the server signer, secret rotation, and multi-tenant patterns.
  </Card>
</CardGroup>


# Create a User Wallet
Source: https://docs.crossmint.com/agents/payment-methods/stablecoin-wallets/create-user-wallet

Create a non-custodial wallet owned by your end user, with email or passkey recovery.

## Introduction

The user wallet is the root of every agent stablecoin flow. It is **non-custodial** and owned by the end user, with an **email** (or passkey) recovery method that stays in the user's control. Your agent is later authorized to use the wallet as a [signer](/agents/payment-methods/stablecoin-wallets/authorize-agent) with explicit spending limits, and that access can be revoked at any time.

Subsequent logins from the same user return the same wallet — creation is idempotent.

## Prerequisites

* A staging Crossmint client API key from the <a href="https://staging.crossmint.com/console/projects/apiKeys">Crossmint Console</a>. In staging, all scopes are enabled by default.
* The user must be authenticated. If you have not set up authentication, see the [Agents overview](/agents/overview) first.

## Steps

<Steps>
  <Step title="Install the SDK">
    <CodeGroup>
      ```bash npm theme={null}
      npm install @crossmint/client-sdk-react-ui
      ```

      ```bash yarn theme={null}
      yarn add @crossmint/client-sdk-react-ui
      ```

      ```bash pnpm theme={null}
      pnpm add @crossmint/client-sdk-react-ui
      ```

      ```bash bun theme={null}
      bun add @crossmint/client-sdk-react-ui
      ```
    </CodeGroup>
  </Step>

  <Step title="Wrap your app with the Crossmint providers">
    Set up `CrossmintProvider`, `CrossmintAuthProvider`, and `CrossmintWalletProvider` at the root of your app. Pass `createOnLogin` to `CrossmintWalletProvider` so the SDK creates the user's wallet automatically as soon as they sign in, with an email-recovery.

    ```tsx theme={null}
    "use client";

    import {
        CrossmintAuthProvider,
        CrossmintProvider,
        CrossmintWalletProvider,
    } from "@crossmint/client-sdk-react-ui";

    export default function RootLayout({ children }: { children: React.ReactNode }) {
        return (
            <CrossmintProvider apiKey={process.env.NEXT_PUBLIC_CROSSMINT_CLIENT_API_KEY}>
                <CrossmintAuthProvider loginMethods={["email", "google"]}>
                    <CrossmintWalletProvider
                        createOnLogin={{
                            chain: "base-sepolia",
                            recoveryMethods: [{ type: "email" }],
                        }}
                    >
                        {children}
                    </CrossmintWalletProvider>
                </CrossmintAuthProvider>
            </CrossmintProvider>
        );
    }
    ```
  </Step>

  <Step title="Read the wallet from any component">
    Use `useWallet()` anywhere below the provider to access the wallet. The hook exposes a `status` field you can use to render a loading state during creation.

    ```tsx theme={null}
    "use client";

    import { useWallet } from "@crossmint/client-sdk-react-ui";

    export function WalletSection() {
        const { wallet, status } = useWallet();

        if (status === "in-progress" || status === "not-loaded") {
            return <p>Creating wallet…</p>;
        }

        return <code>{wallet?.address}</code>;
    }
    ```

    When `status` is `loaded`, `wallet.address` is the user's wallet address and the wallet is ready for delegation.
  </Step>
</Steps>

## Manual Creation (Non-React or Server-Side)

If you are not using the React SDK — for example, creating the wallet server-side from a custom auth backend — use the wallets SDK directly:

```typescript theme={null}
import { createCrossmint, CrossmintWallets } from "@crossmint/wallets-sdk";

const crossmint = createCrossmint({
    apiKey: process.env.CROSSMINT_SERVER_SIDE_API_KEY,
});
const wallets = CrossmintWallets.from(crossmint);

const wallet = await wallets.createWallet({
    chain: "base-sepolia",
    owner: `userId:${userId}`,
    signer: { type: "email", email: userEmail },
});
```

`owner` scopes the wallet to your authenticated user. Pass the same identifier on subsequent `getWallet` calls to resolve it.

## Common Gotchas

<AccordionGroup>
  <Accordion title="Calling createOnLogin twice for the same user is safe">
    Wallet creation is idempotent — repeated calls return the same wallet. You do not need to guard against double-creation in your UI.
  </Accordion>

  <Accordion title="Recovery is configured during wallet creation">
    The current API accepts one recovery method when the wallet is created. Add the agent as a scoped signer so you can revoke its access without changing the wallet address.
  </Accordion>

  <Accordion title="`owner` is required for server-side creation">
    On the React SDK, the user is identified by the auth provider's session. On the server, you must explicitly scope ownership with `owner: userId:<id>` so the wallet resolves correctly on later `getWallet` calls.
  </Accordion>
</AccordionGroup>

## What Is Next

With the user's wallet created, the next step is to add your agent as a signer so it can sign on the user's behalf.

Continue to [Authorize the Agent](/agents/payment-methods/stablecoin-wallets/authorize-agent).

For a full app you can clone and test end-to-end, see the [Stablecoin Wallet Quickstart](/agents/stablecoin-wallet-quickstart).


# Using the Wallet
Source: https://docs.crossmint.com/agents/payment-methods/stablecoin-wallets/on-chain-actions

Use the wallet to send stablecoins, swap, bridge, and call any contract from your agent.

## Introduction

Once a signer is authorized, your agent can drive the wallet like any EOA: **send stablecoins, swap, bridge, or call an arbitrary contract**. All operations go through the same `wallet` handle — the only thing that changes is which signer is active.

Policies attached to the server signer (spend caps, allowed contracts) are enforced on every transaction, so the agent can only sign what the user delegated.

## Prerequisites

* A user wallet with an authorized server signer. See [Authorize the Agent](/agents/payment-methods/stablecoin-wallets/authorize-agent) if you have not done this yet.
* The `walletAddress` of the user's wallet.
* A Crossmint **server-side** API key and the `CROSSMINT_SIGNER_SECRET` for the authorized signer.

## Activate the Server Signer

Before any server-side signing, activate the authorized server signer. Every subsequent call on that `wallet` handle is signed in-process with no user prompt.

```typescript theme={null}
import { createCrossmint, CrossmintWallets } from "@crossmint/wallets-sdk";

const crossmint = createCrossmint({
    apiKey: process.env.CROSSMINT_SERVER_SIDE_API_KEY,
});
const wallets = CrossmintWallets.from(crossmint);

const wallet = await wallets.getWallet(walletAddress, { chain: "base-sepolia" });

await wallet.useSigner({
    type: "server",
    secret: process.env.CROSSMINT_SIGNER_SECRET,
});
```

## Send Stablecoins

The canonical agent action: transfer stablecoins to a recipient. Wrap it in a server action so the secret stays on the backend.

```typescript theme={null}
"use server";

import { createCrossmint, CrossmintWallets } from "@crossmint/wallets-sdk";

export async function sendUsdxmFromServer({
    walletAddress,
    recipient,
    amount,
}: {
    walletAddress: string;
    recipient: string;
    amount: string;
}) {
    const crossmint = createCrossmint({
        apiKey: process.env.CROSSMINT_SERVER_SIDE_API_KEY,
    });
    const wallets = CrossmintWallets.from(crossmint);
    const wallet = await wallets.getWallet(walletAddress, { chain: "base-sepolia" });

    await wallet.useSigner({
        type: "server",
        secret: process.env.CROSSMINT_SIGNER_SECRET,
    });

    const tx = await wallet.send(recipient, "usdxm", amount);
    return { hash: tx.hash, explorerLink: tx.explorerLink };
}
```

`wallet.send(recipient, symbol, amount)` accepts any token symbol the chain supports (`usdc`, `usdt`, `usdxm` on staging, native gas tokens). The transaction is sponsored by default — the user does not need to hold ETH for gas.

See [Transfer Tokens](/wallets/guides/transfer-tokens) for the full symbol list and per-chain behavior.

## Read Balances

```typescript theme={null}
const balances = await wallet.balances(["usdxm", "eth"]);
const usdxm = balances.tokens.find((t) => t.symbol === "usdxm");
```

`balances()` returns native balance and token balances in one call. Pass an explicit array to include non-default symbols. For richer patterns (historical, multi-chain aggregation), see [Check Balances](/wallets/guides/check-balances).

## Fund a Staging Wallet

On supported staging chains, you can mint test stablecoins directly into the wallet — no faucet round-trip.

```typescript theme={null}
await wallet.stagingFund(5); // 5 USDXM
```

<Note>
  This is staging-only and exists to unblock local development. For production funding flows, see [Onramp & Add Funds](/agents/payment-methods/stablecoin-wallets/onramp-add-funds). For EVM-native testnet tokens, see [Fund a Staging Wallet](/wallets/guides/fund-staging-wallet).
</Note>

## Call Any Contract

The wallet exposes a generic transaction path for anything that is not a first-class helper — swaps, bridges, DeFi, NFT mints, custom protocols. The exact call shape differs per chain; follow the reference for the chain you are targeting:

| Chain | Reference |
| - | - |
| EVM | [Custom EVM Transactions](/wallets/guides/send-transaction-evm) |
| Solana | [Custom Solana Transactions](/wallets/guides/send-transaction-solana) |
| Stellar | [Custom Stellar Transactions](/wallets/guides/send-transaction-stellar) |

## Common Gotchas

<AccordionGroup>
  <Accordion title="Calling `useSigner` is a per-handle setting">
    Activating a signer applies only to the `wallet` handle you call it on. If you load a fresh wallet via `getWallet`, you must call `useSigner` again before signing.
  </Accordion>

  <Accordion title="Sponsored gas does not extend to all chains">
    Gas sponsorship is enabled by default on supported chains, but check the chain matrix in [Transfer Tokens](/wallets/guides/transfer-tokens) before assuming the user does not need a gas balance.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Pay with x402" icon="bolt" href="/agents/payment-flows/x402">
    Pay HTTP-402-gated endpoints automatically using the authorized wallet.
  </Card>

  <Card title="Wallet Guides" icon="book" href="/wallets/guides/create-wallet">
    Full reference for signers, transactions, webhooks, and error handling.
  </Card>
</CardGroup>


# Onramp & Add Funds
Source: https://docs.crossmint.com/agents/payment-methods/stablecoin-wallets/onramp-add-funds

Fund an agent wallet for x402, MPP, and onchain transactions.

## Introduction

Once a user wallet is created and the agent is authorized, the next step is to fund it with stablecoins. The agent needs USDC in the wallet to pay x402 endpoints, settle MPP requests, and submit onchain transactions. The onramp flow lets users buy USDC with a credit card and deliver it directly to their Crossmint wallet.

Onramp is a **UI flow, not a headless API**. Card authorization, 3DS challenges, and KYC checks all require the user to interact with a Crossmint-hosted component, the same way Apple Pay or Stripe Elements work. Raw card data and PII never reach your servers.

In this guide, you will learn how to:

* Create a Crossmint order using a server action
* Use Crossmint's embedded checkout component to handle KYC, payment, and delivery automatically

<Snippet />

## Prerequisites

<Steps>
  <Step title="Install the SDK">
    Install the Crossmint client SDK:

    <CodeGroup>
      ```bash npm theme={null}
      npm install @crossmint/client-sdk-react-ui
      ```

      ```bash yarn theme={null}
      yarn add @crossmint/client-sdk-react-ui
      ```

      ```bash pnpm theme={null}
      pnpm add @crossmint/client-sdk-react-ui
      ```

      ```bash bun theme={null}
      bun add @crossmint/client-sdk-react-ui
      ```
    </CodeGroup>
  </Step>

  <Step title="Create API keys">
    Create a [server-side API key](/introduction/platform/api-keys/server-side) with the `orders.create` and `orders.read` scopes enabled.

    Create a [client-side API key](/introduction/platform/api-keys/client-side) for the embedded checkout component.

    In staging, all scopes are enabled by default.
  </Step>

  <Step title="Create a user wallet">
    Make sure the user has a Crossmint wallet. See [Create a User Wallet](/agents/payment-methods/stablecoin-wallets/create-user-wallet) if you have not done this yet.
  </Step>

  <Step title="Add environment variables">
    Add environment variables to your `.env.local`:

    ```bash .env.local theme={null}
    NEXT_PUBLIC_CROSSMINT_CLIENT_SIDE_API_KEY="_YOUR_CLIENT_API_KEY_"
    CROSSMINT_SERVER_SIDE_API_KEY="_YOUR_SERVER_API_KEY_"
    ```
  </Step>
</Steps>

## Steps

<Steps>
  <Step title="Create the server action">
    Create a server action that creates onramp orders via the Crossmint API. The recipient is the user's wallet address — funds are delivered straight to the wallet your agent is authorized on.

    ```typescript app/actions/createOrder.ts theme={null}
    "use server";

    const USDC_TOKEN_LOCATORS = {
        solanaDevnet: "solana:4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
        baseSepolia: "base-sepolia:0x036CbD53842c5426634e7929541eC2318f3dCF7e",
        stellarTestnet: "stellar:CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA",
    };

    interface CreateOrderParams {
        walletAddress: string;
        receiptEmail: string;
        amount: string;
        chain: "solanaDevnet" | "baseSepolia" | "stellarTestnet";
    }

    export async function createOrder({ walletAddress, receiptEmail, amount, chain }: CreateOrderParams) {
        const serverApiKey = process.env.CROSSMINT_SERVER_SIDE_API_KEY;
        if (serverApiKey == null) {
            throw new Error("CROSSMINT_SERVER_SIDE_API_KEY is not set");
        }

        const response = await fetch("https://staging.crossmint.com/api/2022-06-09/orders", {
            method: "POST",
            headers: {
                "Content-Type": "application/json",
                "x-api-key": serverApiKey,
            },
            body: JSON.stringify({
                lineItems: [
                    {
                        tokenLocator: USDC_TOKEN_LOCATORS[chain],
                        executionParameters: {
                            mode: "exact-in",
                            amount,
                        },
                    },
                ],
                payment: {
                    method: "card",
                    receiptEmail,
                },
                recipient: {
                    walletAddress,
                },
            }),
        });

        if (!response.ok) {
            const error = await response.json();
            throw new Error(error.message || "Failed to create order");
        }

        return response.json();
    }
    ```
  </Step>

  <Step title="Build the onramp component">
    Create a client component that pulls the user's wallet from `useWallet()`, creates an order, and renders the embedded checkout. Because the agent is already authorized on the wallet, any USDC delivered here is immediately spendable by the agent on x402 endpoints, MPP requests, and onchain transactions.

    ```tsx app/components/OnrampCheckout.tsx theme={null}
    "use client";

    import { useState } from "react";
    import {
        CrossmintEmbeddedCheckout,
        useCrossmintAuth,
        useWallet,
    } from "@crossmint/client-sdk-react-ui";
    import { createOrder } from "../actions/createOrder";

    export default function OnrampCheckout() {
        const { wallet } = useWallet();
        const { user } = useCrossmintAuth();
        const [order, setOrder] = useState<{ orderId: string; clientSecret: string } | null>(null);
        const [amount, setAmount] = useState("5");
        const [isLoading, setIsLoading] = useState(false);

        async function handleSubmit() {
            if (!wallet || !user?.email) return;
            setIsLoading(true);
            try {
                const result = await createOrder({
                    walletAddress: wallet.address,
                    receiptEmail: user.email,
                    amount,
                    chain: "baseSepolia",
                });
                setOrder({ orderId: result.order.orderId, clientSecret: result.clientSecret });
            } catch (error) {
                console.error("Failed to create order:", error);
            } finally {
                setIsLoading(false);
            }
        }

        if (order != null) {
            return (
                <div className="max-w-[450px] w-full mx-auto p-6 rounded-xl bg-white">
                    <CrossmintEmbeddedCheckout
                        orderId={order.orderId}
                        clientSecret={order.clientSecret}
                        payment={{
                            receiptEmail: user?.email,
                            crypto: { enabled: false },
                            fiat: { enabled: true },
                            defaultMethod: "fiat",
                        }}
                    />
                </div>
            );
        }

        return (
            <div className="max-w-md mx-auto p-8 rounded-xl border border-gray-300 bg-white shadow-sm space-y-6">
                <h2 className="text-2xl font-semibold text-gray-900">Add funds to your wallet</h2>

                <div className="space-y-2">
                    <label className="text-sm font-medium text-gray-900">Recipient Wallet</label>
                    <div className="w-full px-3 py-2 rounded-lg border border-gray-300 bg-gray-50 text-gray-900 text-sm font-mono break-all">
                        {wallet?.address ?? "Connect a wallet…"}
                    </div>
                </div>

                <div className="space-y-2">
                    <label className="text-sm font-medium text-gray-900">Amount (USD)</label>
                    <input
                        type="number"
                        value={amount}
                        onChange={(e) => setAmount(e.target.value)}
                        className="w-full px-3 py-2 rounded-lg border border-gray-300 bg-white text-gray-900 text-sm"
                    />
                </div>

                <button
                    onClick={handleSubmit}
                    disabled={isLoading || !wallet || !user?.email}
                    className="w-full py-3 rounded-lg bg-black text-white font-medium hover:bg-gray-800 disabled:opacity-50 transition-colors"
                >
                    {isLoading ? "Creating Order…" : "Continue to Checkout"}
                </button>
            </div>
        );
    }
    ```

    The embedded checkout already runs inside the `CrossmintProvider` you set up to create the user's wallet, so no extra provider is needed here.
  </Step>

  <Step title="Add the component to your page">
    Drop `OnrampCheckout` into the page where the user funds their wallet — for example, right after authorizing the agent.

    ```tsx app/page.tsx theme={null}
    import OnrampCheckout from "./components/OnrampCheckout";

    export default function FundPage() {
        return (
            <main className="min-h-screen flex items-center justify-center">
                <OnrampCheckout />
            </main>
        );
    }
    ```

    When the user clicks **Continue to Checkout**, the server action creates an order and the embedded checkout component handles KYC, payment, and delivery automatically. As soon as USDC lands in the wallet, the agent can spend it on x402 endpoints, MPP requests, and onchain transactions.
  </Step>
</Steps>

<Tip>
  **Testing:** Use the test credit card number `4242 4242 4242 4242` with any future expiration date and any 3-digit CVC.
</Tip>

## Common Gotchas

<AccordionGroup>
  <Accordion title="Onramp delivers to the user wallet, not the agent">
    The recipient of the order is always the user's wallet address. The agent does not have its own balance — it spends from the user's wallet using its delegated server signer to pay x402 endpoints, MPP requests, and onchain transactions.
  </Accordion>

  <Accordion title="Use staging chains while testing">
    The token locators above target Base Sepolia, Solana Devnet, and Stellar Testnet. Switch to mainnet locators only after end-to-end staging tests pass.
  </Accordion>

  <Accordion title="The user is the payer, even if the agent triggers the flow">
    Card collection, 3DS, and KYC must be completed by the user in the embedded checkout. An agent cannot complete onramp on behalf of the user.
  </Accordion>
</AccordionGroup>

## What Is Next

<CardGroup>
  <Card title="Using the Wallet" icon="paper-plane" href="/agents/payment-methods/stablecoin-wallets/on-chain-actions">
    Once funded, send stablecoins, call contracts, and handle x402 or MPP payments from your agent.
  </Card>

  <Card title="Save a Card" icon="credit-card" href="/agents/payment-methods/cards/save-card">
    Set up the card that will fund the wallet.
  </Card>
</CardGroup>


# Remove Agent Access
Source: https://docs.crossmint.com/agents/payment-methods/stablecoin-wallets/remove-agent-access

Revoke an agent signer from a user's wallet.

## Introduction

This page covers how to remove an agent's access to a user's wallet by revoking its server signer. The user authorizes the removal with their recovery method, and the signer is immediately removed from the wallet's signer set.

## Prerequisites

* A user wallet with at least one server signer authorized. See [Authorize the Agent](/agents/payment-methods/stablecoin-wallets/authorize-agent) if you have not done this yet.
* The `locator` returned by `wallet.addSigner(...)` (or the signer address — both work as locators).
* The user's recovery method (for example, their email signer) — revocation must be authorized by the user, not by the agent itself.

## Revoke an agent signer

Use this when the user wants to cut off a specific agent from a specific wallet. The user authorizes removal with their recovery method (one-time email code), and the server signer is immediately removed from the wallet's signer set. Any in-flight signature requests against that signer fail.

```typescript theme={null}
"use client";

import { useWallet, useCrossmintAuth } from "@crossmint/client-sdk-react-ui";

export function RevokeAgent({ locator }: { locator: string }) {
    const { wallet } = useWallet();
    const { user } = useCrossmintAuth();

    const handleRevoke = async () => {
        if (!wallet || !user?.email) return;

        await wallet.useSigner({ type: "email", email: user.email });
        await wallet.removeSigner({ locator });
    };

    return <button onClick={handleRevoke}>Revoke agent</button>;
}
```

<Note>
  Revocation is per-wallet. If the same server secret has been authorized on multiple wallets — for example because you use a single backend signer for many users — removing it from one wallet does **not** affect the others.
</Note>

## Common Gotchas

<AccordionGroup>
  <Accordion title="Only the recovery method can remove an agent">
    Calls to `wallet.removeSigner` must be made with the user's recovery method active (e.g. `wallet.useSigner({ type: "email", email: user.email })`). If the server signer is active when you call remove, the request fails — by design, an agent cannot revoke itself.
  </Accordion>

  <Accordion title="Per-wallet `locator`s, not per-secret">
    The same secret produces a different `locator` on each wallet it is authorized on. Persist the `locator` returned by `addSigner` against the wallet address so revocation can target the right entry.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Authorize the Agent" icon="user-check" href="/agents/payment-methods/stablecoin-wallets/authorize-agent">
    Re-authorize an agent on the wallet after revocation.
  </Card>

  <Card title="Server Signer Deep Dive" icon="server" href="/wallets/guides/signers/server-signer">
    Full reference for the server signer.
  </Card>
</CardGroup>


# Server Agent Wallets
Source: https://docs.crossmint.com/agents/payment-methods/stablecoin-wallets/server-agent-wallets

Backend-only wallets for autonomous agents with no end user.

## Introduction

A **server agent wallet** is a wallet whose root signer is your backend, not an end user. Use it when there is no human in the loop — autonomous market makers, scheduled task runners, treasury bots, or any agent that operates entirely on its own keys.

This is the opposite end of the trust spectrum from the user-authorized flow. The server signer is the wallet's recovery method, so there is no user-controlled recovery method to delegate to and no user OTP step. Your backend creates the wallet, signs every transaction, and is fully responsible for the secret.

## Prerequisites

* A Crossmint **server-side** API key from the <a href="https://staging.crossmint.com/console/projects/apiKeys">Crossmint Console</a>.
* A secure secret store for the signer key (environment variable, KMS, or hardware-backed vault). The user-authorized flow has the user as a fallback if the server is compromised — this flow does not.

<Note>This page is under construction. Full content — including signer key management patterns, multi-tenant isolation, and the canonical [server signer reference](/wallets/guides/signers/server-signer) — is coming soon.</Note>

## What Is Next

<CardGroup>
  <Card title="Server Signer Deep Dive" icon="server" href="/wallets/guides/signers/server-signer">
    Full reference for the server signer, secret rotation, and key management.
  </Card>

  <Card title="On-Chain Actions" icon="paper-plane" href="/agents/payment-methods/stablecoin-wallets/on-chain-actions">
    Once the wallet is set up, drive it the same way as a user-authorized wallet.
  </Card>
</CardGroup>


# Agent Wallets Quickstart ⚡
Source: https://docs.crossmint.com/agents/stablecoin-wallet-quickstart

Get your agent paying with stablecoins in 10 minutes.

Create a user-owned smart wallet, authorize an agent as a delegated signer, and send USDXM on Base Sepolia. This quickstart runs the [stablecoin wallet reference app](https://github.com/Crossmint/stablecoin-wallet-quickstart).

By the end you'll have a running app where a user can sign in, get a non-custodial wallet, authorize an agent with a one-time email code, and watch the agent send a stablecoin transfer signed entirely on your backend — no user prompt per transaction.

<CardGroup>
  <Card title="Try the live demo" icon="rocket" href="https://stablecoin-wallet-quickstart.vercel.app/">
    See the full flow in action without setting anything up locally.
  </Card>

  <Card title="Stablecoin Wallet Quickstart" icon="code" href="https://github.com/Crossmint/stablecoin-wallet-quickstart">
    Explore the full reference implementation for user wallets, server signers, and USDXM transfers.
  </Card>
</CardGroup>

## Prerequisites

* Node.js 20+ and pnpm

## Setup

<Steps>
  <Step title="Clone the repo and install dependencies">
    You can ask your agent to walk you through the setup to run this quickstart.

    ```bash theme={null}
    git clone https://github.com/Crossmint/stablecoin-wallet-quickstart.git
    cd stablecoin-wallet-quickstart
    pnpm install
    ```
  </Step>

  <Step title="Configure environment variables">
    Copy the example file. You'll fill in the values in the next steps.

    ```bash theme={null}
    cp .env.example .env.local
    ```

    ```bash .env.local theme={null}
    NEXT_PUBLIC_CROSSMINT_CLIENT_API_KEY=your-crossmint-client-api-key
    CROSSMINT_SERVER_SIDE_API_KEY=your-crossmint-server-api-key
    CROSSMINT_SIGNER_SECRET=your-64-char-hex-secret
    ```
  </Step>

  <Step title="Get Crossmint staging API keys">
    Sign in to the <a href="https://staging.crossmint.com/signin?callbackUrl=/console">Crossmint Staging Console</a> and create a project. Then in **Project Settings → API keys**, create:

    1. A **client-side** key → paste into `NEXT_PUBLIC_CROSSMINT_CLIENT_API_KEY`.
    2. A **server-side** key → paste into `CROSSMINT_SERVER_SIDE_API_KEY`.

    Staging keys come with **all scopes enabled by default**, so you don't need to configure anything else for the quickstart.
  </Step>

  <Step title="Generate a signer secret">
    The agent's server signer uses a 32-byte secret that never leaves your backend. Generate one and paste it into `CROSSMINT_SIGNER_SECRET`. Both raw 64-char hex and the prefixed `xmsk1_<64-hex>` format are accepted.

    <SignerSecretGenerator />

    <Warning>
      Anyone who holds this secret can sign on behalf of the wallets it has been authorized on. Store it only as a server-side environment variable; never commit it or ship it to the browser.
    </Warning>
  </Step>

  <Step title="Run the dev server">
    ```bash theme={null}
    pnpm dev
    ```

    Open [http://localhost:3000](http://localhost:3000).
  </Step>
</Steps>

## Understanding the user flow

Once running, the app walks the user through four steps on Base Sepolia:

1. **Authenticate.** Sign in with email OTP or Google via `CrossmintAuthProvider`. Crossmint issues a user JWT that scopes every subsequent SDK call to the signed-in user.
2. **Get a wallet.** `CrossmintWalletProvider` is configured with `createOnLogin={{ chain: "base-sepolia", recoveryMethods: [{ type: "email" }] }}`, so a non-custodial smart wallet is created on first login with the user's email as the recovery method. The address appears as soon as `useWallet()` resolves.
3. **Authorize the agent.** Clicking **Authorize your agent** calls `wallet.addSigner({ type: "server", secret }, { prepareOnly: true })` from your backend, then the user approves the pending registration with a one-time email code. From here on, the server signer can sign for the wallet without any user prompt.
4. **Fund and send.** `wallet.stagingFund(5)` mints 5 USDXM into the wallet (staging-only). A server action then activates the server signer with `wallet.useSigner({ type: "server", secret })` and calls `wallet.send(recipient, "usdxm", amount)` — signed entirely on your backend. This is how an agent spends from a user's wallet in production. To fund a production wallet with USDC, use [Onramp & Add Funds](/agents/payment-methods/stablecoin-wallets/onramp-add-funds) or a direct transfer.

Toggle **Show code** in the header to view the relevant SDK snippet alongside each step.

## Next Steps

<CardGroup>
  <Card title="Using the Wallet" icon="paper-plane" href="/agents/payment-methods/stablecoin-wallets/on-chain-actions">
    Send stablecoins, swap, bridge, and call any contract from your agent.
  </Card>

  <Card title="x402" icon="bolt" href="/agents/payment-flows/x402">
    HTTP-native micropayments — pay-per-call APIs and machine-to-machine settlement.
  </Card>

  <Card title="Remove Agent Access" icon="user-xmark" href="/agents/payment-methods/stablecoin-wallets/remove-agent-access">
    Revoke an agent's signer from a user's wallet.
  </Card>
</CardGroup>


# Agent Wallets
Source: https://docs.crossmint.com/agents/wallets/overview

Give an agent scoped access to a non-custodial stablecoin wallet for x402, MPP, and onchain actions

<video />

An Agent Wallet is a non-custodial smart wallet that an agent can spend from within limits the owner sets. For consumer agents, the user owns the wallet and adds the agent as a signer with a spend cap, allowed counterparties, and a time window. For autonomous agents with no end user, your backend owns the wallet directly.

Permissions are enforced onchain and the owner can revoke them at any time. Neither you nor Crossmint takes custody of funds. Agent Wallets are how agents pay other machines: APIs behind x402 and MPP, other agents, and any contract onchain. For the problem this solves, read [How Agents Pay](/agents/how-agents-pay#agent-wallets).

## Key Features

<CardGroup>
  <Card title="Non-custodial" icon="user-shield">
    The user, or your backend, holds the root key; nobody else can move funds
  </Card>

  <Card title="Scoped agent access" icon="sliders">
    Spend cap, allowed counterparties, and time window per agent
  </Card>

  <Card title="Enforced onchain" icon="shield-check">
    A transaction outside the delegation is rejected at the wallet level
  </Card>

  <Card title="Machine-to-machine ready" icon="bolt">
    Pay x402 and MPP endpoints per call, in stablecoins
  </Card>

  <Card title="Fund with a card" icon="circle-dollar">
    Users top up with the Crossmint onramp or a direct USDC transfer
  </Card>

  <Card title="Revocable" icon="user-xmark">
    Remove the agent signer at any time; the user keeps the wallet and funds
  </Card>
</CardGroup>

## When Are Agent Wallets the Best Fit?

* **The agent pays machines, not stores.** APIs behind x402 or MPP and other agents settle in stablecoins, per call, with no merchant account.
* **Payments are small or frequent.** Card fees and chargebacks make micropayments impractical; stablecoins do not have that problem.
* **The agent acts onchain.** Sending stablecoins, swapping, bridging, and calling contracts all run from the same wallet.

## How It Works

<Steps>
  <Step title="The user creates and funds a wallet">
    The Crossmint SDK creates a non-custodial wallet with email or passkey recovery. The user funds it through the Crossmint onramp or a direct USDC transfer.
  </Step>

  <Step title="The user authorizes the agent">
    The agent's key is added as a signer, bound to a permission set the user approves: spend cap, allowed counterparties, and time window.
  </Step>

  <Step title="The agent transacts within scope">
    The agent signs and submits transactions with its own key, with no user prompt per action. Anything outside the delegated scope is rejected at the wallet level.
  </Step>

  <Step title="The user revokes access when done">
    Removing the agent signer ends its access immediately. The user keeps the wallet and its funds.
  </Step>
</Steps>

## Two Wallet Models

| Model | Who owns the wallet | Use it when |
| - | - | - |
| [User wallet](/agents/payment-methods/stablecoin-wallets/create-user-wallet) | Your end user | An agent spends on behalf of a person who stays in control |
| [Server agent wallet](/agents/payment-methods/stablecoin-wallets/server-agent-wallets) | Your backend | An autonomous agent operates entirely on its own keys with no human in the loop |

## Get Started

<CardGroup>
  <Card title="Quickstart" icon="bolt" href="/agents/stablecoin-wallet-quickstart">
    Run the reference app: create a user wallet, authorize an agent, and send a stablecoin transfer from your backend
  </Card>

  <Card title="Try the live demo" icon="rocket" href="https://stablecoin-wallet-quickstart.vercel.app/">
    See the full flow without setting anything up locally
  </Card>
</CardGroup>

## Guides

<CardGroup>
  <Card title="Create a User Wallet" icon="wallet" href="/agents/payment-methods/stablecoin-wallets/create-user-wallet">
    A non-custodial wallet owned by your end user
  </Card>

  <Card title="Authorize the Agent" icon="user-check" href="/agents/payment-methods/stablecoin-wallets/authorize-agent">
    Grant your agent delegated, scoped control
  </Card>

  <Card title="Onramp & Add Funds" icon="circle-dollar" href="/agents/payment-methods/stablecoin-wallets/onramp-add-funds">
    Fund the wallet with a card or a direct transfer
  </Card>

  <Card title="Server Agent Wallets" icon="server" href="/agents/payment-methods/stablecoin-wallets/server-agent-wallets">
    Backend-only wallets for autonomous agents
  </Card>

  <Card title="Using the Wallet" icon="paper-plane" href="/agents/payment-methods/stablecoin-wallets/on-chain-actions">
    Send, swap, bridge, and call any contract
  </Card>

  <Card title="x402" icon="bolt" href="/agents/payment-flows/x402">
    Pay x402-protected endpoints per call, in stablecoins
  </Card>

  <Card title="MPP" icon="arrows-left-right" href="/agents/payment-flows/mpp">
    Pay Machine Payment Protocol endpoints from an EVM wallet
  </Card>

  <Card title="Remove Agent Access" icon="user-xmark" href="/agents/payment-methods/stablecoin-wallets/remove-agent-access">
    Revoke the agent signer from a user's wallet
  </Card>
</CardGroup>

## FAQs

<AccordionGroup>
  <Accordion title="Does Crossmint or my app take custody of the funds?">
    No. The wallet is non-custodial. The user (or, for server agent wallets, your backend) holds the root signer, and the agent only holds a delegated key bound to the permissions the owner approved.
  </Accordion>

  <Accordion title="What can the user limit?">
    The spend cap, the addresses or protocols the agent can interact with, and the time window in which the delegation is valid. The limits are enforced onchain, so a transaction outside them is rejected at the wallet level.
  </Accordion>

  <Accordion title="Can the user revoke the agent?">
    Yes, at any time. See [Remove Agent Access](/agents/payment-methods/stablecoin-wallets/remove-agent-access).
  </Accordion>

  <Accordion title="Where can I learn more about the underlying wallets?">
    Agent Wallets are Crossmint smart wallets. The [Wallets documentation](/wallets/overview) covers chains, signers, recovery, and the full SDK.
  </Accordion>
</AccordionGroup>


# Get Usage
Source: https://docs.crossmint.com/api-reference/admin/get-usage

api-reference/_open-api/AdminAPIs.json GET /v1-alpha1/projects/{projectId}/usage
Get usage data for a project.

**API scope required** `projects:usage.read`


<Snippet />


# Cancel Agent Checkout
Source: https://docs.crossmint.com/api-reference/agent-checkouts/cancel-agent-checkout

api-reference/_open-api/Agents.json POST /unstable/agent-checkouts/{id}/cancel
Requests cancellation of a checkout run. The response is an acknowledgement; the run reaches `cancelled` once the agent stops, which Get Agent Checkout reflects. Returns `409` when the run can no longer be cancelled.

**API scope required**: `agent-checkouts.cancel`



# Create Agent Checkout
Source: https://docs.crossmint.com/api-reference/agent-checkouts/create-agent-checkout

api-reference/_open-api/Agents.json POST /unstable/agent-checkouts
Starts a checkout run: the agent opens `startUrl`, works toward `task` within `constraints`, and reports back through the run's messages. A `buyerProfileId` supplies identity and shipping details; a `browserProfileId` reuses a saved merchant login. The response is the run in `queued` status. Poll Get Agent Checkout or stream its messages to follow it.

**API scope required**: `agent-checkouts.create`



# Create Browser Profile
Source: https://docs.crossmint.com/api-reference/agent-checkouts/create-browser-profile

api-reference/_open-api/Agents.json POST /unstable/agent-checkouts/browser-profiles
Create a subject-scoped browser profile: a durable browser identity that lets a user's merchant login be reused across checkout runs instead of signing in on every run.

A user has at most one browser profile, and it accumulates saved state across merchants.

**API scope required**: `agent-checkouts.browser-profiles.create`



# Create Buyer Profile
Source: https://docs.crossmint.com/api-reference/agent-checkouts/create-buyer-profile

api-reference/_open-api/Agents.json POST /unstable/agent-checkouts/buyer-profiles
Create a subject-scoped buyer profile (buyer identity + global shipping address) that Universal Checkout can prefill during a checkout run. Payment data is never stored.

**API scope required**: `agent-checkouts.buyer-profiles.create`



# Delete Browser Profile
Source: https://docs.crossmint.com/api-reference/agent-checkouts/delete-browser-profile

api-reference/_open-api/Agents.json DELETE /unstable/agent-checkouts/browser-profiles/{id}
Log the user out and erase their saved browser state. This is irreversible.

It does not cancel checkouts already running with the profile: those runs continue, and erasure completes once they finish. A `503` means erasure could not be scheduled and the profile is intact — retry.

**API scope required**: `agent-checkouts.browser-profiles.delete`



# Delete Buyer Profile
Source: https://docs.crossmint.com/api-reference/agent-checkouts/delete-buyer-profile

api-reference/_open-api/Agents.json DELETE /unstable/agent-checkouts/buyer-profiles/{id}
Delete a buyer profile owned by the authenticated user.

**API scope required**: `agent-checkouts.buyer-profiles.delete`



# Get Agent Checkout
Source: https://docs.crossmint.com/api-reference/agent-checkouts/get-agent-checkout

api-reference/_open-api/Agents.json GET /unstable/agent-checkouts/{id}
Returns one checkout run by ID. Read `status` to see where it is: `queued`, `running`, `awaiting_input` when the agent needs an answer from the user, then `succeeded`, `failed`, `cancelled`, or `blocked`. `requiredAction` describes what an `awaiting_input` run is waiting for.

**API scope required**: `agent-checkouts.read`



# Get Browser Profile
Source: https://docs.crossmint.com/api-reference/agent-checkouts/get-browser-profile

api-reference/_open-api/Agents.json GET /unstable/agent-checkouts/browser-profiles/{id}
Retrieve a browser profile owned by the authenticated user. The response carries metadata only: what a checkout run did with the profile is reported on that run, not here.

A profile owned by another user returns `404`, not `403`.

**API scope required**: `agent-checkouts.browser-profiles.read`



# Get Buyer Profile
Source: https://docs.crossmint.com/api-reference/agent-checkouts/get-buyer-profile

api-reference/_open-api/Agents.json GET /unstable/agent-checkouts/buyer-profiles/{id}
Retrieve a buyer profile owned by the authenticated user.

**API scope required**: `agent-checkouts.buyer-profiles.read`



# List Agent Checkout Messages
Source: https://docs.crossmint.com/api-reference/agent-checkouts/list-agent-checkout-messages

api-reference/_open-api/Agents.json GET /unstable/agent-checkouts/{id}/messages
Returns the run's conversation, one page at a time: the agent's progress reports (`assistant`) and the user's answers (`user`). Each message carries the run `revision` it was recorded at. For a live view, use Stream Agent Checkout Messages.

**API scope required**: `agent-checkouts.read`



# List Agent Checkouts
Source: https://docs.crossmint.com/api-reference/agent-checkouts/list-agent-checkouts

api-reference/_open-api/Agents.json GET /unstable/agent-checkouts
Returns the authenticated user's checkout runs, newest first, one page at a time. Each run carries its `status`, the task and start URL it was created with, and `knownSpentUsdMicros` so far.

**API scope required**: `agent-checkouts.read`



# List Browser Profiles
Source: https://docs.crossmint.com/api-reference/agent-checkouts/list-browser-profiles

api-reference/_open-api/Agents.json GET /unstable/agent-checkouts/browser-profiles
List the authenticated user's browser profiles, newest first.

**API scope required**: `agent-checkouts.browser-profiles.read`



# List Buyer Profiles
Source: https://docs.crossmint.com/api-reference/agent-checkouts/list-buyer-profiles

api-reference/_open-api/Agents.json GET /unstable/agent-checkouts/buyer-profiles
List the authenticated user's buyer profiles, newest first. Paginate with the opaque `cursor` from `nextCursor`.

**API scope required**: `agent-checkouts.buyer-profiles.read`



# Send Agent Checkout Message
Source: https://docs.crossmint.com/api-reference/agent-checkouts/send-agent-checkout-message

api-reference/_open-api/Agents.json POST /unstable/agent-checkouts/{id}/messages
Sends a message into a checkout run: free text, or an `input_response` that answers an `awaiting_input` run by submitting form values, choosing an alternative, or declining. The response acknowledges receipt with a `messageId`; the agent's reply arrives as a later message.

**API scope required**: `agent-checkouts.update`



# Stream Agent Checkout Messages
Source: https://docs.crossmint.com/api-reference/agent-checkouts/stream-agent-checkout-messages

api-reference/_open-api/Agents.json GET /unstable/agent-checkouts/{id}/messages/stream
Server-sent events for one checkout: `message.upsert` carries a message, `run.updated` a run update, and each event's `id` is the cursor to resume from. Resume with `last-event-id` or `after`; omit both to stream from the start.

The checkout is read before the stream opens, so an unknown or inaccessible one returns a normal error status. A stale resume cursor, or one from another checkout, closes the stream instead: re-read the message history and reconnect from the cursor it reports.

**API scope required**: `agent-checkouts.read`



# Update Browser Profile
Source: https://docs.crossmint.com/api-reference/agent-checkouts/update-browser-profile

api-reference/_open-api/Agents.json PATCH /unstable/agent-checkouts/browser-profiles/{id}
Rename a browser profile. `label` is the only editable field.

**API scope required**: `agent-checkouts.browser-profiles.update`



# Update Buyer Profile
Source: https://docs.crossmint.com/api-reference/agent-checkouts/update-buyer-profile

api-reference/_open-api/Agents.json PATCH /unstable/agent-checkouts/buyer-profiles/{id}
Update a buyer profile's writable fields (any non-empty subset).

**API scope required**: `agent-checkouts.buyer-profiles.update`



# Create Agent Card
Source: https://docs.crossmint.com/api-reference/agentic-commerce/order-intents/create-order-intent

api-reference/_open-api/Agents.json POST /unstable/order-intents
Create a new order intent.

**API scope required**: `order-intents.create`



# Get Agent Card
Source: https://docs.crossmint.com/api-reference/agentic-commerce/order-intents/get-order-intent

api-reference/_open-api/Agents.json GET /unstable/order-intents/{orderIntentId}
Get a specific order intent by ID.

**API scope required**: `order-intents.read`



# Get Agent Card Credentials
Source: https://docs.crossmint.com/api-reference/agentic-commerce/order-intents/get-order-intent-credentials

api-reference/_open-api/Agents.json POST /unstable/order-intents/{orderIntentId}/credentials
Create a payment credential from an order intent.

**API scope required**: `order-intents.credentials`



# List Agent Cards
Source: https://docs.crossmint.com/api-reference/agentic-commerce/order-intents/list-order-intents

api-reference/_open-api/Agents.json GET /unstable/order-intents
List all order intents for the authenticated user.

**API scope required**: `order-intents.read`



# Revoke Agent Card
Source: https://docs.crossmint.com/api-reference/agentic-commerce/order-intents/revoke-order-intent

api-reference/_open-api/Agents.json DELETE /unstable/order-intents/{orderIntentId}
Cancel an active order intent.

**API scope required**: `order-intents.revoke`



# Create Payment Method
Source: https://docs.crossmint.com/api-reference/agentic-commerce/payment-methods/create-payment-method

api-reference/_open-api/PaymentMethods.json POST /unstable/payment-methods
Saves a payment method for a user so it can be reused across Checkout, Onramp, and Offramp orders. Sensitive fields (PAN, CVC, account numbers, IBANs, Bre-B keys) must be submitted through `vault.crossmint.com`, which tokenizes them before forwarding to Crossmint servers. Duplicate detection prevents saving the same card or account twice for the same user.

Supported types are `card`, the bank-account variants (`bank-account-us`, `bank-account-mx-clabe`, `bank-account-co`, `bank-account-sepa-iban`, `bank-account-ph`) and `bre-b`. For bank accounts the currency must match the account geography.

**API scope required**: `payment-methods.create`

<Warning>
  **This endpoint is gated behind Payment Card Industry Data Security Standard (PCI DSS) compliance.** Because it accepts raw card numbers, Card Verification Codes (CVCs), and bank account details, you may only use it if your organization is PCI DSS compliant and has been explicitly enabled by Crossmint. You must provide evidence of your compliance (e.g. your Attestation of Compliance) and <a href="https://www.crossmint.com/contact/sales">reach out to Crossmint</a> to have it turned on — it is disabled by default.

  **If you are not PCI compliant, do not use this endpoint.** Instead, use the client-side [Save a Card](/agents/payment-methods/cards/save-card) flow, which renders Crossmint's `CrossmintPaymentMethodManagement` component. Card data is collected directly by Crossmint in the browser and never touches your servers, so **you do not need to be PCI compliant** to use it.
</Warning>

<Warning>
  This endpoint requires a JWT from an **external auth provider** (Auth0, Firebase, Stytch, etc.) or a **custom JWT** backed by a JWKS endpoint. Crossmint Auth is not supported.
</Warning>

<Note>
  This endpoint accepts raw card data and bank account details. Requests must be sent to the **vault host** (`vault.staging.crossmint.com` or `vault.crossmint.com`), which tokenizes sensitive fields before forwarding to the API. Raw card numbers, CVCs, and bank account numbers never reach `api.crossmint.com` directly.
</Note>


# Delete Payment Method
Source: https://docs.crossmint.com/api-reference/agentic-commerce/payment-methods/delete-payment-method

api-reference/_open-api/PaymentMethods.json DELETE /unstable/payment-methods/{paymentMethodId}
Soft-deletes a payment method and returns it. It can no longer be used for payments. A deleted bank account stays readable through retrieve, and through list with `status=deleted`, and carries the terminal status `deleted`. A deleted card is excluded and carries no status. Deleting a bank account that is already deleted returns it again.

**API scope required**: `payment-methods.delete`

<Warning>
  This endpoint requires a JWT from an **external auth provider** (Auth0, Firebase, Stytch, etc.) or a **custom JWT** backed by a JWKS endpoint. Crossmint Auth is not supported.
</Warning>


# List Payment Methods
Source: https://docs.crossmint.com/api-reference/agentic-commerce/payment-methods/list-payment-methods

api-reference/_open-api/PaymentMethods.json GET /unstable/payment-methods
Returns a paginated list of payment methods for a user, newest first by default. A deleted payment method is omitted; pass `status=deleted` to list the deleted bank accounts.

**API scope required**: `payment-methods.read`

<Warning>
  This endpoint requires a JWT from an **external auth provider** (Auth0, Firebase, Stytch, etc.) or a **custom JWT** backed by a JWKS endpoint. Crossmint Auth is not supported.
</Warning>


# Get Action Status
Source: https://docs.crossmint.com/api-reference/common/get-action-status

api-reference/_open-api/MintingAPIs.json GET /2022-06-09/actions/{actionId}
Use this API to poll for the status of asynchonous actions such as NFT mints, transfers, etc.

**API scope required**: `nfts.create`


<Note>
  The shape of the data property in the `200` response for this API depends on the type of action initially performed.
  For example, minting/burning an NFT, creating/updating a collection or template, or NFT transfers.
</Note>

The `action` property will indicate the type of action originally performed and will be one of:

* `nfts.create`
* `nfts.delete`
* `nfts.update`
* `collections.create`
* `collections.update`
* `wallets:nfts.transfer`


# Check Token Support
Source: https://docs.crossmint.com/api-reference/headless/check-token-support

api-reference/_open-api/HeadlessAPIs.json GET /v1-alpha2/tokens/{tokenLocator}
Get a token and its available features by its locator. This endpoint allows you to check if a specific token is supported by Crossmint and what features are available for it.

**API scope required**: `orders.create`




# Create Order
Source: https://docs.crossmint.com/api-reference/headless/create-order

api-reference/_open-api/HeadlessAPIs.json POST /2022-06-09/orders
Creates a new order that can be used to complete a headless checkout.



# Edit Order
Source: https://docs.crossmint.com/api-reference/headless/edit-order

api-reference/_open-api/HeadlessAPIs.json PATCH /2022-06-09/orders/{orderId}
Edit an existing order. You can update the recipient, the payment method, and/or the locale.

**API scope required**: `orders.update`




# Get All Tokens
Source: https://docs.crossmint.com/api-reference/headless/get-all-tokens

api-reference/_open-api/Orders.json GET /2024-09-26/tokens
Returns a paginated list of the tokens that Crossmint supports for checkout, newest first: the tokens your users can buy through Crossmint. Access to this endpoint is enabled per project; contact support to enable it.

**API scope required**: `tokens.read`



# Get Order
Source: https://docs.crossmint.com/api-reference/headless/get-order

api-reference/_open-api/HeadlessAPIs.json GET /2022-06-09/orders/{orderId}
Get specific order by ID.

**Authentication**: Use either a server-side API key with `orders.read` scope, or the `clientSecret` from order creation as an authorization header.




# List Orders
Source: https://docs.crossmint.com/api-reference/headless/list-orders

api-reference/_open-api/HeadlessAPIs.json GET /2022-06-09/orders
Returns a paginated list of orders for your project, sorted by creation date (newest first by default). Use the `nextCursor` or `previousCursor` returned in the response to navigate between pages.

Optional filters accept comma-separated values and repeated query parameters (maximum 20 terms per filter). Keep the same filter params when following cursors.

**API scope required**: `orders.read`




# Create Payment Method
Source: https://docs.crossmint.com/api-reference/headless/payment-methods/create-payment-method

api-reference/_open-api/PaymentMethods.json POST /unstable/payment-methods
Save a payment method for a user so it can be used with Checkout, Onramp, and Offramp orders

Saves a payment method for a user so it can be reused across Checkout, Onramp, and Offramp orders.

<Info>
  **Card payments** require PCI-DSS certification for production access. <a href="https://www.crossmint.com/contact/sales">Contact your Crossmint customer success engineer</a> to get started. Bank account and SEPA payment methods do not have this requirement.
</Info>

## Returns

Returns a [PaymentMethod](/api-reference/headless/payment-methods/payment-method-object) object.


# Delete a Payment Method
Source: https://docs.crossmint.com/api-reference/headless/payment-methods/delete-payment-method

api-reference/_open-api/PaymentMethods.json DELETE /unstable/payment-methods/{paymentMethodId}
Soft-delete a payment method. The record is retained for compliance but can no longer be used.

Deletes a payment method. The record is retained internally but can no longer be used for payments.

## Returns

Returns the [PaymentMethod](/api-reference/headless/payment-methods/payment-method-object) object.


# Retrieve a Payment Method
Source: https://docs.crossmint.com/api-reference/headless/payment-methods/get-payment-method

api-reference/_open-api/PaymentMethods.json GET /unstable/payment-methods/{paymentMethodId}
Fetch a single payment method by its ID

Retrieves a payment method by its ID.

## Returns

Returns a [PaymentMethod](/api-reference/headless/payment-methods/payment-method-object) object.


# List Payment Methods by User
Source: https://docs.crossmint.com/api-reference/headless/payment-methods/list-payment-methods

api-reference/_open-api/PaymentMethods.json GET /unstable/payment-methods
Retrieve all payment methods saved for a given user

Returns a paginated list of payment methods for a given user.

## Returns

An object with a `data` array containing [PaymentMethod](/api-reference/headless/payment-methods/payment-method-object) objects. Use the `cursor` parameter to paginate through results. When `nextCursor` is present, additional pages are available in that direction.


# The Payment Method Object
Source: https://docs.crossmint.com/api-reference/headless/payment-methods/payment-method-object

Attributes and structure of a saved payment method

PaymentMethod objects represent your user's payment instruments. You can use them with any of the Crossmint products like Checkout, Onramp, and Offramp.

## Type Values

`type` names the **account identifier** (the capture schema Crossmint collects and validates) — never the payment rail, scheme, or clearing house. The same saved account can be paid over multiple rails; rail selection happens at payment execution time.

| Value | Description |
| - | - |
| `card` | Credit or debit card. |
| `bank-account-us` | US bank account (routing number + account number). |
| `bank-account-sepa-iban` | Bank account identified by an IBAN within the supported SEPA scope. |
| `bank-account-co` | Colombian bank account (institution ID + account number + national document). |
| `bre-b` | Colombian Bre-B key: an `@handle`, a mobile number, an e-mail, an identity document, or a commerce code. |
| `bank-account-id` | Indonesian bank account (institution ID + account number), paid out over BI-FAST. |
| `bank-account-mx-clabe` | Mexican bank account, identified by an 18-digit CLABE (Clave Bancaria Estandarizada). |
| `bank-account-ng` | Nigerian bank account (institution ID + 10-digit NUBAN, the Nigeria Uniform Bank Account Number), paid out over NIP. |
| `bank-account-ph` | Philippine bank account (institution ID + account number), paid out over InstaPay or PESONet. |
| `bank-account-th` | Thai bank account (institution ID + account number), paid out over PromptPay. |
| `bank-account-vn` | Vietnamese bank account (institution ID + account number), paid out over Napas 247 or CITAD. |

<Note>
  `bank-account-sepa-iban` is the payment-method type; `sepa` and `sepa-instant` are rail values within it. A SEPA IBAN account can support both rails.
</Note>

## Attributes

<ResponseField name="paymentMethodId" type="string">
  Unique identifier for the payment method.
</ResponseField>

<ResponseField name="default" type="boolean">
  Whether this is the user's default payment method. Returned for `card` and `bank-account-sepa-iban` only.
</ResponseField>

<ResponseField name="displayName" type="string">
  Server-derived label, returned for `card` and `bank-account-sepa-iban` only (e.g. `"Visa ••1111"`, `"Deutsche Bank ••6789"`). Absent on every other bank-account type; read `label` there.
</ResponseField>

<ResponseField name="type" type="string">
  Payment method type. One of `card`, `bank-account-us`, `bank-account-sepa-iban`, `bank-account-co`, `bre-b`, `bank-account-id`, `bank-account-mx-clabe`, `bank-account-ng`, `bank-account-ph`, `bank-account-th`, or `bank-account-vn`.
</ResponseField>

<ResponseField name="status" type="string">
  Bank accounts and Bre-B keys only. Readiness of the destination, not user approval, ownership, or a guaranteed payout. One of:

  * `pending`: initial readiness checks are running.
  * `active`: required readiness checks passed. Orders still run their own eligibility checks.
  * `rejected`: the destination cannot receive a supported payout. The initial checks ended without a usable record, a provider refused the account, or the bank returned a payout to it. Retrying requires a new payment method.
  * `deleted`: removed by the client. Never reactivates.

  `pending` moves to `active`, `rejected`, or `deleted`; `active` moves to `rejected` or `deleted`; `rejected` moves only to `deleted`. Creation starts the readiness checks once; reads, label edits, and orders never restart them. Treat an unrecognized status as not ready for orders. See [Manage Payment Methods](/offramp/guides/collect-bank-accounts#statuses).
</ResponseField>

<ResponseField name="statusReason" type="string | null">
  Always `null` except on a `rejected` method, where it may be `destination-not-found`, `destination-closed`, `destination-cannot-receive`, or `no-rail-available`. `null` when no safe destination condition was established. Never carries provider errors or compliance detail. Codes are extensible, so tolerate unknown values.
</ResponseField>

<ResponseField name="card" type="object">
  Card details. Present when `type` is `card`.

  <Expandable title="properties">
    <ResponseField name="brand" type="string">
      Card brand. Can be `visa`, `mastercard`, `amex`, `discover`, `jcb`, `unionpay`, or `diners-club`.
    </ResponseField>

    <ResponseField name="last4" type="string">
      Last four digits of the card number.
    </ResponseField>

    <ResponseField name="expiration" type="object">
      <Expandable title="properties">
        <ResponseField name="month" type="string">
          Two-digit expiration month.
        </ResponseField>

        <ResponseField name="year" type="string">
          Four-digit expiration year.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="billing" type="object">
      Billing details for the cardholder.

      <Expandable title="properties">
        <ResponseField name="name" type="string">
          Full name.
        </ResponseField>

        <ResponseField name="phone" type="string">
          Phone number (E.164 format).
        </ResponseField>

        <ResponseField name="address" type="object">
          Billing address.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="fundingType" type="string">
      Card funding type. Can be `credit`, `debit`, `prepaid`, or `unknown`.
    </ResponseField>

    <ResponseField name="bin" type="string">
      Bank Identification Number (first 6-8 digits of the card number).
    </ResponseField>

    <ResponseField name="country" type="string">
      Two-letter country code of the card issuer.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="bankAccount" type="object">
  Bank account details. Present when `type` is `bank-account-us`, `bank-account-sepa-iban`, `bank-account-co`, `bank-account-id`, `bank-account-mx-clabe`, `bank-account-ng`, `bank-account-ph`, `bank-account-th`, or `bank-account-vn`. A `bre-b` method returns `breB` instead.

  <Expandable title="common properties">
    <ResponseField name="accountHolder" type="object">
      The person or company that owns the account. Always the value the client sent, never the bank's record of the holder. Derived from `billing` when the record predates this field.

      <Expandable title="properties">
        <ResponseField name="name" type="string">
          Full legal name.
        </ResponseField>

        <ResponseField name="email" type="string">
          E-mail address.
        </ResponseField>

        <ResponseField name="phoneNumber" type="string">
          Phone number (E.164 format).
        </ResponseField>

        <ResponseField name="address" type="object">
          Holder address, without a country: the account's own `country` is the bank's jurisdiction. Present only on types that collect one. Never on `bank-account-mx-clabe`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="bankName" type="string | null">
      Name of the bank. `null` if not resolvable. Absent for `bank-account-co`, `bank-account-id`, `bank-account-mx-clabe`, `bank-account-ng`, `bank-account-ph`, `bank-account-th`, and `bank-account-vn`.
    </ResponseField>

    <ResponseField name="accountSuffix" type="string">
      Last four digits of the account number, CLABE, or IBAN.
    </ResponseField>

    <ResponseField name="currency" type="string">
      ISO 4217 currency code (e.g. `usd`, `mxn`, `eur`, `cop`).
    </ResponseField>

    <ResponseField name="country" type="string">
      ISO 3166-1 alpha-2 country code.
    </ResponseField>

    <ResponseField name="entityType" type="string">
      Account holder type. `individual` or `business`. Required on creation. May be absent on records created before the field was enforced.
    </ResponseField>

    <ResponseField name="rails" type="object">
      Read-only. The payout rails a currently-available provider has confirmed for this account. Absent when no payout provider currently serves the account.

      <Expandable title="properties">
        <ResponseField name="status" type="string">
          `pending` while asynchronous rail resolution is still running for optional rails (baseline rails appear immediately); `complete` once resolved.
        </ResponseField>

        <ResponseField name="supported" type="string[]">
          Rail values this account supports. See [Payment Schemes](/offramp/payment-methods) for the current rail catalog and indicative delivery times.
        </ResponseField>

        <ResponseField name="pending" type="string[]">
          Rails still being resolved. Non-empty only while `status` is `pending`; `[]` once `status` is `complete`.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>

  <Expandable title="US-specific properties (bank-account-us)">
    <ResponseField name="bankAddress" type="object">
      Bank branch address.
    </ResponseField>

    <ResponseField name="routingNumber" type="string">
      Nine-digit ABA routing number.
    </ResponseField>

    <ResponseField name="accountType" type="string">
      `checking` or `savings`.
    </ResponseField>
  </Expandable>

  <Expandable title="SEPA-specific properties (bank-account-sepa-iban)">
    <ResponseField name="bic" type="string">
      BIC/SWIFT code (8 or 11 characters).
    </ResponseField>
  </Expandable>

  <Expandable title="CO-specific properties (bank-account-co)">
    <ResponseField name="institutionId" type="string">
      Identifier of the bank that holds the account, for example `co-bancolombia`. See [Bank Institution IDs](/offramp/guides/bank-institution-ids).
    </ResponseField>

    <ResponseField name="accountType" type="string">
      `checking`, `savings`, or `electronic-deposit`.
    </ResponseField>

    <ResponseField name="accountHolder.document" type="object">
      The holder's national document. The full number is never returned.

      <Expandable title="properties">
        <ResponseField name="type" type="string">
          One of `cc`, `nit`, `ce`, `pa`, `ppt`, `ti`, `rc`, `te`, or `die`.
        </ResponseField>

        <ResponseField name="suffix" type="string">
          Last four digits of the document number.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>

  <Expandable title="Local bank properties (bank-account-id, bank-account-ng, bank-account-ph, bank-account-th, bank-account-vn)">
    <ResponseField name="institutionId" type="string">
      Identifier of the bank that holds the account, for example `id-bca`. See [Bank Institution IDs](/offramp/guides/bank-institution-ids).
    </ResponseField>

    <ResponseField name="accountType" type="string">
      `checking` or `savings`. Present when sent on creation.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="breB" type="object">
  Bre-B key details. Present when `type` is `bre-b`, in place of `bankAccount`. The key itself is never returned.

  <Expandable title="properties">
    <ResponseField name="accountHolder" type="object">
      The person or company that owns the key. Always the value the client sent.

      <Expandable title="properties">
        <ResponseField name="name" type="string">
          Full legal name.
        </ResponseField>

        <ResponseField name="email" type="string">
          E-mail address.
        </ResponseField>

        <ResponseField name="phoneNumber" type="string">
          Phone number (E.164 format).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="accountSuffix" type="string">
      Masked form of the key. An e-mail key is masked in place. Every other key shows its last four characters.
    </ResponseField>

    <ResponseField name="currency" type="string">
      Always `cop`. Bre-B only settles in Colombian pesos.
    </ResponseField>

    <ResponseField name="country" type="string">
      Always `CO`.
    </ResponseField>

    <ResponseField name="entityType" type="string">
      Key holder type. `individual` or `business`.
    </ResponseField>

    <ResponseField name="keyType" type="string">
      Category of the key, derived from its format. One of `alphanumeric`, `phone`, `email`, `identification`, or `commerce`. A client-supplied value is refused.
    </ResponseField>

    <ResponseField name="institutionName" type="string">
      Display name of the institution that holds the key. Absent until a name source answers.
    </ResponseField>

    <ResponseField name="rails" type="object">
      Read-only. The payout rails a currently-available provider advertises for this key. Absent when no provider serves the key.

      <Expandable title="properties">
        <ResponseField name="supported" type="string[]">
          Rail values this key supports. Bre-B carries `supported` alone, without the `status` and `pending` fields an ordinary bank account returns.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="label" type="string">
  Bank accounts only. The client's own name for this payment method, when one was sent on creation. At most 255 characters. A card request does not accept it.
</ResponseField>

<ResponseField name="lastPayoutAt" type="string">
  Read-only. Bank accounts only. ISO 8601 timestamp of the most recent successful offramp payout funded by this account. Absent until the first payout.
</ResponseField>

<ResponseExample>
  ```json Card theme={null}
  {
    "paymentMethodId": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
    "default": true,
    "displayName": "Visa ••1111",
    "type": "card",
    "card": {
      "brand": "visa",
      "last4": "1111",
      "expiration": {
        "month": "12",
        "year": "2028"
      },
      "billing": {
        "name": "Alice Smith",
        "phone": "+12125551234",
        "address": {
          "line1": "123 Main St",
          "city": "Springfield",
          "stateOrRegion": "IL",
          "postalCode": "62701",
          "country": "US"
        }
      },
      "fundingType": "debit",
      "bin": "411111",
      "country": "US"
    }
  }
  ```

  ```json US Bank Account theme={null}
  {
    "paymentMethodId": "f2ecef7e-91af-4fa7-93f9-12db856c227f",
    "type": "bank-account-us",
    "bankAccount": {
      "bankName": "Chime",
      "accountSuffix": "6259",
      "currency": "usd",
      "country": "US",
      "entityType": "individual",
      "bankAddress": {
        "line1": "123 Main St",
        "city": "New York",
        "stateOrRegion": "NY",
        "postalCode": "10001",
        "country": "US"
      },
      "routingNumber": "091300010",
      "accountType": "checking",
      "rails": { "status": "complete", "supported": ["rtp", "ach-same-day", "ach-us"], "pending": [] }
    }
  }
  ```

  ```json SEPA theme={null}
  {
    "paymentMethodId": "3323460b-d9d2-4ec6-b380-8a3e01e3f226",
    "default": false,
    "displayName": "Deutsche Bank ••6789",
    "type": "bank-account-sepa-iban",
    "bankAccount": {
      "bankName": "Deutsche Bank",
      "accountSuffix": "6789",
      "currency": "eur",
      "country": "DE",
      "entityType": "individual",
      "bic": "COBADEFFXXX"
    }
  }
  ```

  ```json CO Bank Account theme={null}
  {
    "paymentMethodId": "1cad2281-bd3d-4219-8787-7dfea94c60b1",
    "type": "bank-account-co",
    "bankAccount": {
      "accountSuffix": "7320",
      "institutionId": "co-bancolombia",
      "accountType": "checking",
      "currency": "cop",
      "country": "CO",
      "entityType": "individual",
      "accountHolder": { "name": "Camila Restrepo", "document": { "type": "cc", "suffix": "4050" } },
      "rails": { "status": "pending", "supported": [], "pending": ["ach-credit"] }
    }
  }
  ```

  ```json CO Bre-B key theme={null}
  {
    "paymentMethodId": "9f1a6b2c-3d4e-4f50-9a61-2b3c4d5e6f70",
    "type": "bre-b",
    "status": "active",
    "statusReason": null,
    "breB": {
      "accountHolder": {
        "name": "Carlos Gómez",
        "phoneNumber": "+573001234567"
      },
      "accountSuffix": "CDKS",
      "currency": "cop",
      "country": "CO",
      "entityType": "individual",
      "keyType": "alphanumeric"
    }
  }
  ```

  ```json ID Bank Account theme={null}
  {
    "paymentMethodId": "7a3e5c91-2b4d-4f86-a1c0-9d8e7f6a5b42",
    "type": "bank-account-id",
    "bankAccount": {
      "accountSuffix": "7890",
      "institutionId": "id-bca",
      "currency": "idr",
      "country": "ID",
      "entityType": "individual",
      "accountHolder": { "name": "Budi Santoso" },
      "rails": { "status": "complete", "supported": ["bi-fast"], "pending": [] }
    }
  }
  ```

  ```json MX Bank Account theme={null}
  {
    "paymentMethodId": "27bacbe1-d0ff-4bc3-b37a-ca91cc64fa39",
    "type": "bank-account-mx-clabe",
    "bankAccount": {
      "accountHolder": {
        "name": "Luis Gomez Rios",
        "phoneNumber": "+525512345678"
      },
      "accountSuffix": "7899",
      "currency": "mxn",
      "country": "MX",
      "entityType": "individual"
    }
  }
  ```

  ```json NG Bank Account theme={null}
  {
    "paymentMethodId": "2e9b4d17-6a3c-4f85-b1d0-8c7e5a2f9b63",
    "type": "bank-account-ng",
    "bankAccount": {
      "accountSuffix": "7897",
      "institutionId": "ng-gt-bank",
      "currency": "ngn",
      "country": "NG",
      "entityType": "individual",
      "accountHolder": { "name": "Chinedu Okafor" },
      "rails": { "status": "complete", "supported": ["nip"], "pending": [] }
    }
  }
  ```

  ```json PH Bank Account theme={null}
  {
    "paymentMethodId": "5e2b7c41-9d0a-4f3b-8c6d-2a1b3c4d5e6f",
    "type": "bank-account-ph",
    "bankAccount": {
      "accountSuffix": "7890",
      "institutionId": "ph-bdo",
      "currency": "php",
      "country": "PH",
      "entityType": "individual",
      "accountHolder": { "name": "Maria Santos" },
      "rails": { "status": "complete", "supported": ["instapay", "pesonet"], "pending": [] }
    }
  }
  ```

  ```json TH Bank Account theme={null}
  {
    "paymentMethodId": "8a4c7e39-2f1b-4d96-b3e5-7c0d2a9f6b41",
    "type": "bank-account-th",
    "bankAccount": {
      "accountSuffix": "7890",
      "institutionId": "th-kasikorn-bank",
      "currency": "thb",
      "country": "TH",
      "entityType": "individual",
      "accountHolder": { "name": "Somchai Jaidee" },
      "rails": { "status": "complete", "supported": ["promptpay"], "pending": [] }
    }
  }
  ```

  ```json VN Bank Account theme={null}
  {
    "paymentMethodId": "3f7d1b86-9e2a-4c50-8d34-1a6e9b7c5f02",
    "type": "bank-account-vn",
    "bankAccount": {
      "accountSuffix": "4567",
      "institutionId": "vn-acb",
      "currency": "vnd",
      "country": "VN",
      "entityType": "individual",
      "accountHolder": { "name": "Nguyễn Văn An" },
      "rails": { "status": "complete", "supported": ["napas-247", "citad"], "pending": [] }
    }
  }
  ```
</ResponseExample>


# Update a Payment Method
Source: https://docs.crossmint.com/api-reference/headless/payment-methods/update-payment-method

api-reference/_open-api/PaymentMethods.json PATCH /unstable/payment-methods/{paymentMethodId}
Update the default status of an existing payment method

Updates a payment method's default status. Only `default` can be changed.

## Returns

Returns the updated [PaymentMethod](/api-reference/headless/payment-methods/payment-method-object) object.


# Process Payment
Source: https://docs.crossmint.com/api-reference/headless/process-payment

api-reference/_open-api/HeadlessAPIs.json POST /2022-06-09/orders/{orderId}/payment
Process payment for an order using a crypto transaction ID.

**Authentication**: Use either a server-side API key with `orders.update` scope, the `clientSecret` from order creation as an authorization header, or a JWT token with `orders.create` scope.




# Introduction
Source: https://docs.crossmint.com/api-reference/introduction

Explore the APIs and test them live from the browser

This section provides a detailed guide for each of the APIs, with sample code and responses.

## Testing the APIs from the browser

The reference pages allow you to call the APIs directly from the browser. To get started:

1. Create a developer account on the <a href="https://staging.crossmint.com/console">Staging</a> or <a href="https://www.crossmint.com/console">Production</a> consoles. Read more about the environments [here](/introduction/platform/staging-vs-production).
2. Create an [API key](/introduction/platform/api-keys) from the `API keys` tab on the console, with the permissions required for the APIs you want to use.
3. From the page of your API of choice, insert the right API key in the authorization slot, introduce the different parameters, and call "Send".
4. (Optional) To call APIs in the production environment, find the API endpoint selector (`⌄`) next to the endpoint URL, and change it to `www.crossmint.com/api`.

The following guide will show you how to create a wallet and mint an NFT into it within 5 minutes. For this, make sure your API key has the scopes `wallets.create`, and `nfts.create`.

<AccordionGroup>
  <Accordion title="1. Creating Wallets from the API Reference">
    Follow the next steps to create a wallet within 5 minutes:

    <Steps>
      <Step title="Navigate to the Create Wallet page">
        <Frame type="simple">
          <img alt="Navigate to create wallet endpoint screenshot with light theme" />

          <img alt="Navigate to create wallet endpoint screenshot with dark theme" />
        </Frame>
      </Step>

      <Step title="Select the correct environment for the API key you created">
        <Frame type="simple">
          <img alt="Set environment URL screenshot" />

          <img alt="Set environment URL screenshot" />
        </Frame>
      </Step>

      <Step title="Input your API key into the Authorization section">
        <Frame type="simple">
          <img alt="Set x-api-key screenshot" />

          <img alt="Set x-api-key screenshot" />
        </Frame>
      </Step>

      <Step title="Input the `body` parameters">
        You may add any additional properties. Each API reference page includes the full list of properties and admissible values.

        <Frame type="simple">
          <img alt="Set body params screenshot with light theme" />

          <img alt="Set body params screenshot with dark theme" />
        </Frame>
      </Step>

      <Step title="Send the request">
        Scroll back to the top of the page and click the blue `Send` button to trigger
        the API call.

        <Frame type="simple">
          <img alt="Send request screenshot with light theme" />

          <img alt="Send request screenshot with dark theme" />
        </Frame>

        Here is an example response object:

        <Frame type="simple">
          <img alt="create user wallet response screenshot with light theme" />

          <img alt="create user wallet response screenshot with dark theme" />
        </Frame>
      </Step>
    </Steps>

    **Success!** The next guide will show you how to mint an NFT into this wallet and view the content.
  </Accordion>

  <Accordion title="2. Mint NFTs from the API Reference">
    In the previous guide, you created a wallet. Now you will deliver an NFT into it and read the wallet's content.

    <Steps>
      <Step title="Navigate to the Mint NFT page">
        <p>Open in a new tab here: <a href="/api-reference/minting/nfts/mint-nft">/api-reference/minting/nfts/mint-nft</a></p>

        <Frame type="simple">
          <img alt="Mint NFT in api playground screenshot with light theme" />

          <img alt="Mint NFT in api playground screenshot with light theme" />
        </Frame>
      </Step>

      <Step title="Enter the `default-polygon` collectionId">
        This is a default collection associated to your account. You can create new ones using the [Create Collections](/minting/nfts/integrate/create-collections) API.

        <Frame type="simple">
          <img alt="Enter collectionId screenshot with light theme" />

          <img alt="Enter collectionId screenshot with dark theme" />
        </Frame>
      </Step>

      <Step title="Select the [EVM] Metadata URL metadata option">
        <Note>The selector to choose between the different metadata option can be hard to spot. Look closely at the screenshots below to see where it is.</Note>

        <Frame type="simple">
          <img alt="Select EVM metadata URL option screenshot with light theme" />

          <img alt="Select EVM metadata URL option screenshot with dark theme" />
        </Frame>

        <br />

        <Frame type="simple">
          <img alt="Enter metadata URL screenshot with light theme" />

          <img alt="Enter metadata URL screenshot with dark theme" />
        </Frame>
      </Step>

      <Step title="Enter metadata URL">
        You can provide your own or use this example URL:

        <CodeGroup>
          ```bash metadata URL theme={null}
          https://bafkreidbf4jpxpecwezjbagwmua5qv62ifhhtzsspoml7zls6iq6ms4byi.ipfs.nftstorage.link/
          ```

          ```json example JSON theme={null}
          {
            "name": "Crossmint Test NFT",
            "description": "Created with the Crossmint minting API",
            "image": "https://bafkreiexjl6kw4khdxkrt6dojgacscnzvrys47t472l2t7d6r2ss65kifq.ipfs.nftstorage.link/",
            "external_url": "https://docs.crossmint.com",
            "attributes":  [
              {
                "trait_type": "contract",
                "value": "ERC-721"
              },
              {
                "trait_type": "background",
                "value": "black"
              }
            ]
          }
          ```
        </CodeGroup>

        <br />

        <Note>This URL must point to a valid JSON file that adheres to [EVM metadata standards](/minting/nfts/integrate/define-metadata).</Note>

        <Frame type="simple">
          <img alt="Enter metadata url screenshot with light theme" />

          <img alt="Enter metadata url screenshot with dark theme" />
        </Frame>
      </Step>

      <Step title="Enter the `recipient`">
        There are two options for the `recipient` parameter. The first enables minting to an email address. The second enables minting directly to a wallet address.

        <CodeGroup>
          ```javascript email recipient theme={null}
            // format
            email:<email_address>:<chain>

            // example
            email:testy@crossmint.xyz:polygon
          ```

          ```javascript wallet recipient theme={null}
            // format
            <chain>:<address>

            // example
            polygon:0x0359Cd99FD20e853a85489DFC93EaDFeF7461590
          ```
        </CodeGroup>

        <br />

        <Tip>Enter your own email address on this step and you can log in to see your NFT in the Crossmint wallet later, which can be accessed from <a href="https://crossmint.com">crossmint.com</a> or <a href="https://staging.crossmint.com">staging.crossmint.com</a> if you are in staging.</Tip>

        <Frame type="simple">
          <img alt="Set recipient screenshot with light theme" />

          <img alt="Set recipient screenshot with dark theme" />
        </Frame>
      </Step>

      <Step title="Set `reuploadLinkedFiles` to false">
        This will prevent unnecessary uploading of files that are already pinned to IPFS.

        <Check><p>Crossmint has a 10MB re-upload size limit. For larger files, upload your media to IPFS, create a metadata.json as shown above, submit the metadata file's URL, and ensure `reuploadLinkedFiles` is set to `false`.</p>
        <p>The default option is `true`.</p></Check>

        <Frame type="simple">
          <img alt="Set reuploadLinkedFiles to false screenshot with light theme" />

          <img alt="Set reuploadLinkedFiles to false screenshot with dark theme" />
        </Frame>
      </Step>

      <Step title="Send the request">
        Scroll back to the top of the page and click the blue `Send` button to trigger
        the API call.

        <Frame type="simple">
          <img alt="Click send screenshot with light theme" />

          <img alt="Click send screenshot with dark theme" />
        </Frame>

        Here is an example response object:

        <Frame type="simple">
          <img alt="mint nft example response screenshot with light theme" />

          <img alt="mint nft example response screenshot with dark theme" />
        </Frame>
      </Step>

      <Step title="View the NFT in your wallet">
        If you followed this guide closely you can view the NFT in the staging wallet at <a href="https://staging.crossmint.com/user/collection">[https://staging.crossmint.com/user/collection](https://staging.crossmint.com/user/collection)</a>.

        If you minted directly to a wallet address you can view the NFT in that application. Ensure you are accessing it from a testnet if you used staging.
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>


# Create IP Asset
Source: https://docs.crossmint.com/api-reference/ip/create-ip-asset

api-reference/_open-api/Story.json POST /v1/ip/collections/{collectionId}/ipassets
Create a new IP Asset

**API scope required**: `nfts.create`

<Warning>This API is still under development. Contact support for early access.</Warning>


# Create IP Asset (Idempotent)
Source: https://docs.crossmint.com/api-reference/ip/create-ip-asset-idempotent

api-reference/_open-api/Story.json PUT /v1/ip/collections/{collectionId}/ipassets/{customerFacingId}
Create a new IP Asset with a pre-computed id, or get an existing one if the id already exists

**API scope required**: `nfts.create`

<Warning>This API is still under development. Contact support for early access.</Warning>


# Create IP Collection
Source: https://docs.crossmint.com/api-reference/ip/create-ip-collection

api-reference/_open-api/Story.json POST /v1/ip/collections
Create a new collection with a pre-computed id, or get an existing one if the id already exists

**API scope required**: `collections.create`

<Warning>This API is still under development. Contact support for early access.</Warning>


# Create IP Collection (Idempotent)
Source: https://docs.crossmint.com/api-reference/ip/create-ip-collection-idempotent

api-reference/_open-api/Story.json PUT /v1/ip/collections/{collectionId}
Create a new collection with a pre-computed id, or get an existing one if the id already exists

**API scope required**: `collections.create`

<Warning>This API is still under development. Contact support for early access.</Warning>


# Get All IP Collections
Source: https://docs.crossmint.com/api-reference/ip/get-all-ip-collections

api-reference/_open-api/Story.json GET /v1/ip/collections
Get all collections associated with the Developer Project

**API scope required**: `collections.read`

<Warning>This API is still under development. Contact support for early access.</Warning>


# Get IP Action
Source: https://docs.crossmint.com/api-reference/ip/get-ip-action

api-reference/_open-api/Story.json GET /v1/ip/actions/{actionId}
Get an action by its id

**API scope required**: `nfts.create`

<Warning>This API is still under development. Contact support for early access.</Warning>


# Get IP Asset
Source: https://docs.crossmint.com/api-reference/ip/get-ip-asset

api-reference/_open-api/Story.json GET /v1/ip/collections/{collectionId}/ipassets/{customerFacingId}
Get a single IP Asset

**API scope required**: `nfts.read`

<Warning>This API is still under development. Contact support for early access.</Warning>


# Get IP Assets in Collection
Source: https://docs.crossmint.com/api-reference/ip/get-ip-assets

api-reference/_open-api/Story.json GET /v1/ip/collections/{collectionId}/ipassets
Get all IP Assets in a collection

**API scope required**: `nfts.read`

<Warning>This API is still under development. Contact support for early access.</Warning>


# Get IP Collection
Source: https://docs.crossmint.com/api-reference/ip/get-ip-collection

api-reference/_open-api/Story.json GET /v1/ip/collections/{collectionId}
Get a collection by its id deployed on the Story chain

**API scope required**: `collections.read`

<Warning>This API is still under development. Contact support for early access.</Warning>


# Get IP Asset Graph
Source: https://docs.crossmint.com/api-reference/ip/get-ip-graph

api-reference/_open-api/Story.json GET /v1/ip/graph/{ipAssetId}
Get the graph of an IP Asset, by default it will fetch the first level of parents and children (depth = 1). You can customize the depth using the query parameter 'depth' to a maximum of 3. Maximum 100 parents or children will be returned for each level.

The ipAssetId parameter should be the Story Protocol asset ID (not the Crossmint ID). Must start with '0x' followed by hexadecimal characters.

**API scope required**: `nfts.read`

<Warning>This API is still under development. Contact support for early access.</Warning>


# Get IP Asset License
Source: https://docs.crossmint.com/api-reference/ip/get-ip-license

api-reference/_open-api/Story.json GET /v1/ip/licenses/{ipassetId}
Get the licenses of an IP Asset

The ipassetId parameter should be the Story Protocol asset ID (not the Crossmint ID). Must start with '0x' followed by hexadecimal characters.

**API scope required**: `nfts.read`

<Warning>This API is still under development. Contact support for early access.</Warning>


# Update IP Asset
Source: https://docs.crossmint.com/api-reference/ip/update-ip-asset

api-reference/_open-api/Story.json PATCH /v1/ip/collections/{collectionId}/ipassets/{customerFacingId}
Update an existing IP Asset

**API scope required**: `nfts.update`

<Warning>This API is still under development. Contact support for early access.</Warning>


# Create Collection
Source: https://docs.crossmint.com/api-reference/minting/collection/create-collection

api-reference/_open-api/MintingAPIs.json POST /2022-06-09/collections/
Create a collection that you can mint NFTs/SFTs from

**API scope required**: `collections.create`




# Create Collection (Idempotent)
Source: https://docs.crossmint.com/api-reference/minting/collection/create-collection-idempotent

api-reference/_open-api/MintingAPIs.json PUT /2022-06-09/collections/{collectionId}
Create a collection that you can mint NFTs/SFTs from. This API is idempotent, 
if you call it multiple times with the same ID, only one will be created.

**API scope required**: `collections.create`




# Get All Collections
Source: https://docs.crossmint.com/api-reference/minting/collection/get-all-collections

api-reference/_open-api/MintingAPIs.json GET /2022-06-09/collections/
List all collections created under the current Crossmint project

**API scope required**: `collections.read`


<Note>For Solana collections the `onChain.contractAddress` property will be named `onChain.mintAddress`</Note>

<ResponseExample>
  ```json 200 theme={null}
  {
    "results": [
      {
        "id": "bb691876-edb3-404c-af3e-c019b8e2ed2c",
        "metadata": {
          "name": "Test Collection",
          "description": "Test",
          "imageUrl": "ipfs://QmVocoiYXZLAtheEHV3VF8w4pa68bkPutT8cQZdMrrpzxh",
          "symbol": "XMINT"
        },
        "fungibility": "non-fungible",
        "onChain": {
          "chain": "polygon",
          "type": "erc-721",
          "contractAddress": "0x9564bD85f3D5677D86244dDb06F06bbD22D9d0DB"
        },
        "supplyLimit": 95,
        "payments": {
          "price": "0.001",
          "recipientAddress": "0x6C3b3225759Cbda68F96378A9F0277B4374f9F06"
        }
      }
    ]
  }
  ```

  <Snippet />
</ResponseExample>


# Get Base URI
Source: https://docs.crossmint.com/api-reference/minting/collection/get-base-uri

api-reference/_open-api/MintingAPIs.json GET /v1-alpha1/minting/collections/{collectionId}/base-uri
Get the Base URI of a collection as it appears onchain.

**API scope required**: `collections.read`


<Snippet />


# Get Collection Info
Source: https://docs.crossmint.com/api-reference/minting/collection/get-collection

api-reference/_open-api/MintingAPIs.json GET /2022-06-09/collections/{collectionId}
Get information about a specific collection.

**API scope required**: `collections.read`


<Note>For Solana collections the `onChain.contractAddress` property will be named `onChain.mintAddress`</Note>


# Get Royalties Configuration
Source: https://docs.crossmint.com/api-reference/minting/collection/get-royalties-configuration

api-reference/_open-api/MintingAPIs.json GET /v1-alpha1/minting/collections/{collectionId}/royalties
Fetch the royalty configuration for a collection, from its current state
in the blockchain. 

This API is only supported on EVM chains.

If you call GET too soon after PUT/DELETE,
you may not yet see your latest changes, as they can take a few seconds to
record on the blockchain.

**API scope required**: `collections.read`


<Snippet />


# Get Transferability
Source: https://docs.crossmint.com/api-reference/minting/collection/get-transferability

api-reference/_open-api/MintingAPIs.json GET /v1-alpha1/minting/collections/{collectionId}/transferable
Get the transferable status of a collection. 

This API is supported on EVM and Aptos chains. 

You must contact sales to gain access to this API. 

**API scope required**: `collections.read`


<Snippet />


# Remove Royalties
Source: https://docs.crossmint.com/api-reference/minting/collection/remove-royalties

api-reference/_open-api/MintingAPIs.json DELETE /v1-alpha1/minting/collections/{collectionId}/royalties
Remove all royalties from a given collection. No new NFT sales will yield royalties to the creator. 

This API is only supported on EVM Chains.

**API scope required**: `collections.update`


<Snippet />


# Set Base URI
Source: https://docs.crossmint.com/api-reference/minting/collection/set-base-uri

api-reference/_open-api/MintingAPIs.json PUT /v1-alpha1/minting/collections/{collectionId}/base-uri
Update the Base URI of a collection. Setting the baseURI enables
excluding the metadata param when minting. Tokens minted without the metadata
param will have a tokenURI of: 

`{BASE_URI}/{TOKEN_ID}`

This API is currently only supported on EVM Chains.

**API scope required**: `collections.update`


<Snippet />


# Set Royalties
Source: https://docs.crossmint.com/api-reference/minting/collection/set-royalties

api-reference/_open-api/MintingAPIs.json PUT /v1-alpha1/minting/collections/{collectionId}/royalties
Configure royalties for all NFTs in a collection.

This API is only supported for EVM chains and implements the EIP-2981 standard.

**API scope required**: `collections.update`


<Snippet />


# Set Transferability
Source: https://docs.crossmint.com/api-reference/minting/collection/set-transferability

api-reference/_open-api/MintingAPIs.json PUT /v1-alpha1/minting/collections/{collectionId}/transferable
Update the transferable status of a collection. 

This API is supported on EVM and Aptos chains. 
You must contact sales to gain access to this API. 

**API scope required**: `collections.update`


<Snippet />


# Update Collection
Source: https://docs.crossmint.com/api-reference/minting/collection/update-collection

api-reference/_open-api/MintingAPIs.json PATCH /2022-06-09/collections/{collectionId}
Update the sales details of a collection

**API scope required**: `collections.update`




# Burn NFT
Source: https://docs.crossmint.com/api-reference/minting/nfts/burn-nft

api-reference/_open-api/MintingAPIs.json DELETE /2022-06-09/collections/{collectionId}/nfts/{id}
Burn a minted NFT.

**API scope required**: `nfts.delete`


<Snippet />


# Edit NFT
Source: https://docs.crossmint.com/api-reference/minting/nfts/edit-nft

api-reference/_open-api/MintingAPIs.json PATCH /2022-06-09/collections/{collectionId}/nfts/{id}
Edit a minted NFT's metadata on IPFS. 

If you are using a custom baseURI, invoking this will overwrite the specific tokenURI for the edited token.

**API scope required**: `nfts.update`




# Get All NFTs
Source: https://docs.crossmint.com/api-reference/minting/nfts/get-nfts

api-reference/_open-api/MintingAPIs.json GET /2022-06-09/collections/{collectionId}/nfts
Get a list of all the NFTs in a given collection.

**API scope required**: `nfts.read`




# Mint NFT
Source: https://docs.crossmint.com/api-reference/minting/nfts/mint-nft

api-reference/_open-api/MintingAPIs.json POST /2022-06-09/collections/{collectionId}/nfts
Mint your NFTs and deliver them to a web3 wallet or an email address

**API scope required**: `nfts.create`


<Note>For uncompressed Solana NFTs, [contact sales](https://www.crossmint.com/contact/sales) for access.</Note>

<ResponseExample>
  <Snippet />

  <Snippet />
</ResponseExample>


# Mint NFT with ID
Source: https://docs.crossmint.com/api-reference/minting/nfts/mint-nft-idempotent

api-reference/_open-api/MintingAPIs.json PUT /2022-06-09/collections/{collectionId}/nfts/{id}
This pathway allows you to mint NFTs and guarantee idempotency
to ensure you never double mint for the same NFT. 

**API scope required**: `nfts.create`


Subsequent requests to this endpoint with the same `id` in the path will ***not*** mint additional NFTs.

Furthermore, the success responses (with status code 200) will be different once the initial request has completed and includes the metadata for the minted NFT.

<Accordion title="200 response examples for subsequent requests">
  <CodeGroup>
    ```json EVM theme={null}
    {
      "id": "<string>",
      "metadata": {
        "name": "<string>",
        "image": "<string>",
        "description": "<string>"
      },
      "onChain": {
        "status": "<string>",
        "tokenId": "<string>",
        "owner": "<string>",
        "txId": "<string>",
        "contractAddress": "<string>",
        "chain": "<string>"
      },
      "actionId": "<string>"
    }
    ```

    ```json Solana theme={null}
    {
        "id": "<string>",
        "metadata": {
            "name": "<string>",
            "symbol": "<string>",
            "description": "<string>",
            "seller_fee_basis_points": 0,
            "image": "<string>",
            "attributes": [],
            "properties": {}
        },
        "onChain": {
            "status": "success",
            "mintHash": "<string>",
            "txId": "<string>",
            "owner": "<string>",
            "chain": "solana"
        },
        "actionId": "<string>"
    }
    ```
  </CodeGroup>
</Accordion>

<ResponseExample>
  <Snippet />

  <Snippet />
</ResponseExample>


# Mint SFT
Source: https://docs.crossmint.com/api-reference/minting/nfts/mint-sft

api-reference/_open-api/MintingAPIs.json POST /2022-06-09/collections/{collectionId}/sfts
Mint your SFTs and deliver them to a web3 wallet or an email address

**API scope required**: `nfts.create`




# Mint Status
Source: https://docs.crossmint.com/api-reference/minting/nfts/mint-status

api-reference/_open-api/MintingAPIs.json GET /2022-06-09/collections/{collectionId}/nfts/{id}
Get the status and associated information for a mint operation.

**API scope required**: `nfts.read`


<ResponseExample>
  ```json 200 EVM  theme={null}
    {
      "id": "<string>",
      "metadata": {
        "name": "<string>",
        "image": "<string>",
        "description": "<string>"
      },
      "onChain": {
        "status": "success",
        "tokenId": "<string>",
        "owner": "<string>",
        "txId": "<string>",
        "contractAddress": "<string>",
        "chain": "polygon"
      },
      "action": "https://staging.crossmint.com/api/2022-06-09/actions/<actionId>"
    }
  ```

  ```json 200 Solana theme={null}
  {
      "id": "<string>",
      "metadata": {
          "name": "<string>",
          "symbol": "<string>",
          "seller_fee_basis_points": 0,
          "properties": {},
          "description": "<string>",
          "image": "<string>",
          "attributes": []
      },
      "onChain": {
          "status": "success",
          "mintHash": "<string>",
          "txId": "<string>",
          "owner": "<string>",
          "chain": "solana"
      },
      "action": "https://staging.crossmint.com/api/2022-06-09/actions/<actionId>"
  }
  ```

  <Snippet />
</ResponseExample>


# Create Template
Source: https://docs.crossmint.com/api-reference/minting/template/create-template

api-reference/_open-api/MintingAPIs.json POST /2022-06-09/collections/{collectionId}/templates
Create a token template, that NFTs or SFTs may be minted from

**API scope required**: `nfts.create`




# Create Template with ID
Source: https://docs.crossmint.com/api-reference/minting/template/create-template-idempotent

api-reference/_open-api/MintingAPIs.json PUT /2022-06-09/collections/{collectionId}/templates/{templateId}
Create a token template with preconfigured metadata

**API scope required**: `nfts.create`




# Delete Template
Source: https://docs.crossmint.com/api-reference/minting/template/delete-template

api-reference/_open-api/MintingAPIs.json DELETE /2022-06-09/collections/{collectionId}/templates/{templateId}
Delete a Token template.

**API scope required**: `nfts.delete`




# Edit Template
Source: https://docs.crossmint.com/api-reference/minting/template/edit-template

api-reference/_open-api/MintingAPIs.json PATCH /2022-06-09/collections/{collectionId}/templates/{templateId}
Edit a Token template.

**API scope required**: `nfts.update`




# Get All Templates
Source: https://docs.crossmint.com/api-reference/minting/template/get-all-templates

api-reference/_open-api/MintingAPIs.json GET /2022-06-09/collections/{collectionId}/templates
Get all of the templates for a collection

**API scope required**: `nfts.read`




# Get Template
Source: https://docs.crossmint.com/api-reference/minting/template/get-template

api-reference/_open-api/MintingAPIs.json GET /2022-06-09/collections/{collectionId}/templates/{templateId}
Fetch the contents of a token template.

**API scope required**: `nfts.read`




# Accept Legal Document
Source: https://docs.crossmint.com/api-reference/users/accept-legal-document

api-reference/_open-api/Users.json PUT /2025-06-09/users/{userLocator}/legal-documents
Record user acceptance of a legal document. Supported types are `crossmint-privacy-policy` and `crossmint-terms-of-service`. The latest version of the document is always recorded. When accepting `crossmint-terms-of-service`, the `region` field is required so the correct regional agreement is resolved.

**API scope required**: `users.create`



# Get a User Document by ID
Source: https://docs.crossmint.com/api-reference/users/get-document

api-reference/_open-api/Users.json GET /2025-06-09/documents/{documentId}
Get a specific document by its ID.

**API scope required**: `users.read`



# Get Identity Verification Status
Source: https://docs.crossmint.com/api-reference/users/get-identity-verification

api-reference/_open-api/Users.json GET /2025-06-09/users/{userLocator}/identity-verification
Get identity verification status for a user.

**API scope required**: `users.read`



# Get Linked External Wallet
Source: https://docs.crossmint.com/api-reference/users/get-linked-wallet

api-reference/_open-api/Users.json GET /2025-06-09/users/{userLocator}/linked-wallets/{address}
Get a linked external wallet for a user by address.

**API scope required**: `users.read`



# Get a User
Source: https://docs.crossmint.com/api-reference/users/get-user

api-reference/_open-api/Users.json GET /2025-06-09/users/{userLocator}
Get a user by its id

**API scope required**: `users.read`



# Link External Wallet to User
Source: https://docs.crossmint.com/api-reference/users/link-wallet

api-reference/_open-api/Users.json PUT /2025-06-09/users/{userLocator}/linked-wallets/{address}
Link an external wallet address to a user. Optionally provide a proof to verify ownership.

**API scope required**: `users.create`



# Trigger Identity Verification
Source: https://docs.crossmint.com/api-reference/users/trigger-identity-verification

api-reference/_open-api/Users.json PUT /2025-06-09/users/{userLocator}/identity-verification
Trigger identity verification for a user.

**API scope required**: `users.create`



# Unlink External Wallet from User
Source: https://docs.crossmint.com/api-reference/users/unlink-wallet

api-reference/_open-api/Users.json DELETE /2025-06-09/users/{userLocator}/linked-wallets/{address}
Unlink an external wallet address from a user.

**API scope required**: `users.create`



# Upload a User Document
Source: https://docs.crossmint.com/api-reference/users/upload-document

api-reference/_open-api/Users.json POST /2025-06-09/documents
Upload a document for a user. 

**API scope required**: `users.create`



# Create or Update User
Source: https://docs.crossmint.com/api-reference/users/upsert-user

api-reference/_open-api/Users.json PUT /2025-06-09/users/{userLocator}
Create or update a user and their personal data by user locator. If the user doesn't exist, they will be created.

**API scope required**: `users.create`



# Issue Credential
Source: https://docs.crossmint.com/api-reference/verifiable-credentials/credentials/issue-credential

api-reference/_open-api/VerifiableCredentialsAPIs.json POST /v1-alpha1/credentials/templates/{templateId}/vcs
Issue a credential and deliver it to a wallet or email address.

**API scope required** `credentials.create`


<Snippet />


# Get Credential by Credential ID
Source: https://docs.crossmint.com/api-reference/verifiable-credentials/credentials/retrieve-credential-by-id

api-reference/_open-api/VerifiableCredentialsAPIs.json GET /v1-alpha1/credentials/{id}
Get a verifiable credential by the ID associated with it. 

This ID will have the format: `urn:uuid:<UUID>`. For example: `urn:uuid:64f9877d-a19a-4205-8d61-f8c2abed5766`

**API scope required** `credentials.read`. This enpoint will work also with a client side API key.


<Snippet />


# Get Credential by NFT ID
Source: https://docs.crossmint.com/api-reference/verifiable-credentials/credentials/retrieve-credential-by-nft

api-reference/_open-api/VerifiableCredentialsAPIs.json GET /v1-alpha1/credentials/templates/{collectionId}/nfts/{id}/credentials
Get a verifiable credential by the ID associated with the minted NFT.

This ID will have the format: `<UUID>`. For example: `d7eb777b-e9b4-4f34-ab5f-ce199111166a`

**API scope required** `credentials.read`. This endpoint will not work with a client side API key.


<Snippet />


# Get Credential by NFT Locator
Source: https://docs.crossmint.com/api-reference/verifiable-credentials/credentials/retrieve-credential-by-nft-locator

api-reference/_open-api/VerifiableCredentialsAPIs.json GET /v1-alpha1/nfts/{nftLocator}/credentials
Get a verifiable credential by the NFT locator. 

This locator will have the format: `<chain>:<contract_address>:<tokenId>`. 
For example: `polygon:0x1234abcde...:1`

**API scope required** `credentials.read`. This enpoint will work also with a client side API key.


<Snippet />


# Get Credential NFTs
Source: https://docs.crossmint.com/api-reference/verifiable-credentials/credentials/retrieve-credential-nfts

api-reference/_open-api/VerifiableCredentialsAPIs.json GET /v1-alpha1/wallets/{walletLocator}/credential_nfts
Get only the NFTs in a wallet associated with credentials.

This walletLocator will have the format: `<chain>:<wallet_address>`.
For example: `polygon:0x1234abcde...`

**API scope required** `credentials.read`.


<Snippet />


# Revoke Credential
Source: https://docs.crossmint.com/api-reference/verifiable-credentials/credentials/revoke-credential

api-reference/_open-api/VerifiableCredentialsAPIs.json DELETE /v1-alpha1/credentials/{id}
Revoke a verifiable credential by the credential ID. 
This involves burning the associated nft.

This ID will have the format: `urn:uuid:<UUID>`. For example: `urn:uuid:64f9877d-a19a-4205-8d61-f8c2abed5766`

**API scope required** `credentials.create`.


<Snippet />


# Verify Credential
Source: https://docs.crossmint.com/api-reference/verifiable-credentials/credentials/verify-credential

api-reference/_open-api/VerifiableCredentialsAPIs.json POST /v1-alpha1/credentials/verification/verify
Verify that a verifiable credential is valid.

**API scope required** `credentials.read`


<Snippet />

<Warning>
  It is impractical to use the API Playground to verify a credential. Instead you can copy the sample code for your
  preferred language in the righthand sidebar and fill in the JSON of the credential you intend to verify.
</Warning>

Here is an example of how to verify a credential using javascript:

```javascript verifyVC.js theme={null}
const options = {
    method: "POST",
    headers: {
        "X-API-KEY": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    body: '{"credential": {"id":"urn:uuid:e31316b6-3be1-49af-a95f-c7f4c3f52aa1","credentialSubject":{"course":"Blockchain 101","passed":true,"id":"did:polygon:0x6C3b3225759Cbda68F96378A9F0277B4374f9F06"},"expirationDate":"2034-02-03","nft":{"tokenId":"1","chain":"polygon","contractAddress":"0xdC444A3F4768185497Dae6250E2F348b99bE89F3"},"issuer":{"id":"did:polygon:0xa22CaDEdE67c11dc1444E507fDdd9b831a67aBd1"},"type":["VerifiableCredential","65c15243e9bee8deac219d57"],"issuanceDate":"2024-02-05T23:21:32.641Z","@context":["https://www.w3.org/2018/credentials/v1","https://github.com/haardikk21/ethereum-eip712-signature-2021-spec/blob/main/index.html","DUMMY_CROSSMINT/65c15243e9bee8deac219d57"],"proof":{"verificationMethod":"did:polygon:0xa22CaDEdE67c11dc1444E507fDdd9b831a67aBd1#ethereumAddress","ethereumAddress":null,"created":"2024-02-05T23:22:24.058Z","proofPurpose":"assertionMethod","type":"EthereumEip712Signature2021","proofValue":"0x748a55d9770cbc6ef16689f0d9547355e288bcce03a8949a32d2aac59244cb9e08cbf54c960bc00d133fc51e6651a4ac1366aeda320dd121777118a4e74980631b","eip712":{"domain":{"name":"Krebit","version":"0.1","chainId":4,"verifyingContract":"0xD8393a735e8b7B6E199db9A537cf27C61Aa74954"},"types":{"VerifiableCredential":[{"name":"@context","type":"string[]"},{"name":"type","type":"string[]"},{"name":"id","type":"string"},{"name":"issuer","type":"Issuer"},{"name":"credentialSubject","type":"CredentialSubject"},{"name":"issuanceDate","type":"string"},{"name":"expirationDate","type":"string"},{"name":"nft","type":"Nft"}],"CredentialSubject":[{"name":"id","type":"string"},{"name":"course","type":"string"},{"name":"passed","type":"bool"}],"Issuer":[{"name":"id","type":"string"}],"Nft":[{"name":"tokenId","type":"string"},{"name":"contractAddress","type":"string"},{"name":"chain","type":"string"}]},"primaryType":"VerifiableCredential"}}}}',
};

// note the gigantic VC JSON string in the body property

fetch("https://staging.crossmint.com/api/v1-alpha1/credentials/verification/verify", options)
    .then((response) => response.json())
    .then((response) => console.log(response))
    .catch((err) => console.error(err));
```

<ResponseExample>
  ```json 200 valid theme={null}
  {
      "isValid": true,
      "error": null
  }
  ```

  ```json 200 revoked theme={null}
  {
      "isValid": false,
      "error": "Credential Revoked"
  }
  ```

  ```json 200 expired theme={null}
  {
      "isValid": false,
      "error": "Credential expired at <date>"
  }
  ```

  ```json 200 invalid_proof theme={null}
  {
      "isValid": false,
      "error": "Invalid proof"
  }
  ```
</ResponseExample>


# Create Credential template
Source: https://docs.crossmint.com/api-reference/verifiable-credentials/templates/create-template

api-reference/_open-api/VerifiableCredentialsAPIs.json POST /v1-alpha1/credentials/templates/
Create a template, similar to an NFT collection, for issuing verifiable credentials.

**API scope required** `credentials:template.create`


<Snippet />


# Create Credential Type with Name
Source: https://docs.crossmint.com/api-reference/verifiable-credentials/types/create-named-type

api-reference/_open-api/VerifiableCredentialsAPIs.json PUT /v1-alpha1/credentials/types/{typeName}
Create or import a type with a given name. This is how you define a custom credential schema.

**API scope required** `credentials.create`


<Snippet />


# Create Credential Type
Source: https://docs.crossmint.com/api-reference/verifiable-credentials/types/create-type

api-reference/_open-api/VerifiableCredentialsAPIs.json POST /v1-alpha1/credentials/types
Create or import a credential type with a random UUID. This is how you define a custom credential schema.

**API scope required** `credentials.create`


<Snippet />


# Get a Credential Type
Source: https://docs.crossmint.com/api-reference/verifiable-credentials/types/get-type

api-reference/_open-api/VerifiableCredentialsAPIs.json GET /v1-alpha1/credentials/types/{typeName}
Get the schema of a given type by name (or id)
        
**API scope required** `credentials.read`


<Snippet />


# Add Recovery Method
Source: https://docs.crossmint.com/api-reference/wallets/add-recovery-method

api-reference/_open-api/WalletsV1Alpha2.json POST /2025-06-09/wallets/{walletLocator}/recovery-methods
Add a recovery method to a wallet.



# Approve Signature
Source: https://docs.crossmint.com/api-reference/wallets/approve-signature

api-reference/_open-api/WalletsV1Alpha2.json POST /2025-06-09/wallets/{walletLocator}/signatures/{signatureId}/approvals
Submit approval for a signature to sign a message or typed data.

**API scope required**: `wallets:signatures.create`



# Approve Transaction
Source: https://docs.crossmint.com/api-reference/wallets/approve-transaction

api-reference/_open-api/WalletsV1Alpha2.json POST /2025-06-09/wallets/{walletLocator}/transactions/{transactionId}/approvals
Submit approval signature for a pending transaction. Required for transactions using external signers.

**API scope required**: `wallets:transactions.sign`



# Create Signature
Source: https://docs.crossmint.com/api-reference/wallets/create-signature

api-reference/_open-api/WalletsV1Alpha2.json POST /2025-06-09/wallets/{walletLocator}/signatures
Creates a new signature for signing messages or typed data.

**API scope required**: `wallets:signatures.create`



# Create Transaction
Source: https://docs.crossmint.com/api-reference/wallets/create-transaction

api-reference/_open-api/WalletsV1Alpha2.json POST /2025-06-09/wallets/{walletLocator}/transactions
Creates a new transaction for the specified wallet. Transaction will be automatically broadcast once it has all necessary approvals.

**API scope required**: `wallets:transactions.create`



# Create Wallet
Source: https://docs.crossmint.com/api-reference/wallets/create-wallet

api-reference/_open-api/WalletsV1Alpha2.json POST /2025-06-09/wallets
Creates a new wallet of specified type. If called with an idempotency key or for a user who already has a wallet, returns existing wallet. When owner is provided, subsequent calls with the same owner will return the existing wallet. Supports both custodial and non-custodial wallet types.

**API scope required**: `wallets.create`



# Fund Wallet
Source: https://docs.crossmint.com/api-reference/wallets/fund-wallet

api-reference/_open-api/WalletsV1Alpha2.json POST /v1-alpha2/wallets/{walletLocator}/balances
Send funds to a wallet.

**API scope required**: `wallets.fund`

<Snippet />

<Note>This endpoint is only available in **staging** and only supports **USDXM**.</Note>


# Get NFTs from Wallet
Source: https://docs.crossmint.com/api-reference/wallets/get-nfts-from-wallet

api-reference/_open-api/WalletsAPIs.json GET /2022-06-09/wallets/{identifier}/nfts
Fetch the NFTs in a provided wallet

**API scope required**: `wallets:nfts.read`


This API enables fetching the NFTs for a provided wallet address and chain.

The response will be slightly different between EVM, Solana, and other wallets. See the example responses to the right.

<ResponseExample>
  ```json 200 EVM theme={null}
  [
    {
      "chain": "<string>",
      "contractAddress": "<string>",
      "tokenId": "<string>",
      "metadata": {
        "attributes": [],
        "collection": {},
        "description": "<string>",
        "image": "<string>",
        "animation_url": "<string>",
        "name": "<string>"
      },
      "locator": "<string>",
      "tokenStandard": "<string>"
    }
  ]
  ```

  ```json 200 EVM (with subscription) theme={null}
  [
      {
          "chain": "<string>",
          "contractAddress": "<string>",
          "tokenId": "<string>",
          "metadata": {
              "attributes": [],
              "collection": {},
              "description": "<string>",
              "image": "<string>",
              "animation_url": "<string>",
              "name": "<string>"
          },
          "locator": "<string>",
          "tokenStandard": "<string>",
          "subscription": {
              "expiresAt": "<ISO_string>"
          }
      }
  ]
  ```

  ```json 200 Solana theme={null}
  [
      {
          "chain": "<string>",
          "mintHash": "<string>",
          "metadata": {
              "name": "<string>",
              "description": "<string>",
              "image": "<string>",
              "attributes": []
          },
          "locator": "<string>"
      }
  ]
  ```

  ```json 400 theme={null}
  {
      "error": "<string>"
  }
  ```
</ResponseExample>


# Get Signature
Source: https://docs.crossmint.com/api-reference/wallets/get-signature

api-reference/_open-api/WalletsV1Alpha2.json GET /2025-06-09/wallets/{walletLocator}/signatures/{signatureId}
Retrieves details about a specific signature by its ID.

**API scope required**: `wallets:signatures.read`



# Get All Signatures
Source: https://docs.crossmint.com/api-reference/wallets/get-signatures

api-reference/_open-api/WalletsV1Alpha2.json GET /2025-06-09/wallets/{walletLocator}/signatures
Retrieves all signatures associated with the specified wallet.

**API scope required**: `wallets:signatures.read`



# Get Delegated Signer
Source: https://docs.crossmint.com/api-reference/wallets/get-signer

api-reference/_open-api/WalletsV1Alpha2.json GET /2025-06-09/wallets/{walletLocator}/signers/{signer}
Retrieve details about a specific delegated signer by its locator.

**API scope required**: `wallets.read`



# Get Transaction
Source: https://docs.crossmint.com/api-reference/wallets/get-transaction

api-reference/_open-api/WalletsV1Alpha2.json GET /2025-06-09/wallets/{walletLocator}/transactions/{transactionId}
Retrieves the current status and details of a specific transaction.

**API scope required**: `wallets:transactions.read`



# Get Wallet Transactions
Source: https://docs.crossmint.com/api-reference/wallets/get-transactions

api-reference/_open-api/WalletsV1Alpha2.json GET /2025-06-09/wallets/{walletLocator}/transactions
Retrieves all transactions associated with the specified wallet. Optionally filter by date range using ISO 8601 format (e.g., 2025-10-27T00:00:00Z).

**API scope required**: `wallets:transactions.read`



# Get Transfer Transaction
Source: https://docs.crossmint.com/api-reference/wallets/get-transfer-token

api-reference/_open-api/WalletsV1Alpha2.json GET /2025-06-09/wallets/{walletLocator}/tokens/{tokenLocator}/transfers/{transactionId}
Retrieves the current status and details of a specific transfer transaction.

**API scope required**: `wallets:transactions.read`



# Get Wallet Balance
Source: https://docs.crossmint.com/api-reference/wallets/get-wallet-balance

api-reference/_open-api/WalletsV1Alpha2.json GET /2025-06-09/wallets/{walletLocator}/balances
Get the balance of a wallet for a given chain and currency

**API scope required**: `wallets:balance.read`

<Snippet />

## Example Request

This example uses placeholder values. Modify the call with the wallet locator, tokens, and chains you would like to use.

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/balances?tokens=usdc,eth,pol&chains=base-sepolia,polygon-amoy' \
    --header 'X-API-KEY: <x-api-key>'
  ```

  ```js Node.js theme={null}
  const url =
      "https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/balances?tokens=usdc,eth,pol&chains=base-sepolia,polygon-amoy";
  const options = { method: "GET", headers: { "X-API-KEY": "<x-api-key>" }, body: undefined };

  try {
      const response = await fetch(url, options);
      const data = await response.json();

      // Process each token's balance across chains
      data.forEach((token) => {
          console.log(`${token.symbol}${token.name ? ` (${token.name})` : ""}:`);
          console.log(`  Total amount: ${token.amount} (${token.rawAmount} raw)`);
          console.log(`  Decimals: ${token.decimals}`);

          // Access balance data for each chain
          Object.entries(token.chains).forEach(([chainName, chainBalance]) => {
              console.log(`  ${chainName}: ${chainBalance.amount}`);
              console.log(`    Locator: ${chainBalance.locator}`);
              if (chainBalance.contractAddress) {
                  console.log(`    Contract: ${chainBalance.contractAddress}`);
              } else if (chainBalance.mintHash) {
                  console.log(`    Mint Hash: ${chainBalance.mintHash}`);
              } else if (chainBalance.contractId) {
                  console.log(`    Contract ID: ${chainBalance.contractId}`);
              }
          });
          console.log();
      });
  } catch (error) {
      console.error(error);
  }
  ```

  ```python Python theme={null}
  import requests

  url = "https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/balances"

  querystring = { "tokens": "usdc,eth,pol", "chains": "base-sepolia,polygon-amoy" }

  headers = { "X-API-KEY": "<x-api-key>" }

  response = requests.get(url, params=querystring, headers=headers)
  data = response.json()

  # Process each token's balance across chains
  for token in data:
      name_part = f" ({token['name']})" if token.get('name') else ""
      print(f"{token['symbol']}{name_part}:")
      print(f"  Total amount: {token['amount']} ({token['rawAmount']} raw)")
      print(f"  Decimals: {token['decimals']}")

      # Access balance data for each chain
      for chain_name, chain_balance in token['chains'].items():
          print(f"  {chain_name}: {chain_balance['amount']}")
          print(f"    Locator: {chain_balance['locator']}")
          if 'contractAddress' in chain_balance:
              print(f"    Contract: {chain_balance['contractAddress']}")
          elif 'mintHash' in chain_balance:
              print(f"    Mint Hash: {chain_balance['mintHash']}")
          elif 'contractId' in chain_balance:
              print(f"    Contract ID: {chain_balance['contractId']}")
      print()
  ```
</CodeGroup>

## Example Response

The response returns an array of token objects, each containing balance information across the specified chains:

```json theme={null}
[
    {
        "symbol": "ETH",
        "name": "Ethereum",
        "decimals": 18,
        "amount": "1.5",
        "rawAmount": "1500000000000000000",
        "chains": {
            "base-sepolia": {
                "locator": "base-sepolia:eth",
                "amount": "1.0",
                "rawAmount": "1000000000000000000"
            },
            "polygon-amoy": {
                "locator": "polygon-amoy:eth",
                "amount": "0.5",
                "rawAmount": "500000000000000000"
            }
        }
    },
    {
        "symbol": "USDC",
        "name": "USD Coin",
        "decimals": 6,
        "amount": "100.0",
        "rawAmount": "100000000",
        "chains": {
            "base-sepolia": {
                "locator": "base-sepolia:0x036CbD53842c5426634e7929541eC2318f3dCF7e",
                "amount": "50.0",
                "rawAmount": "50000000",
                "contractAddress": "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
            },
            "polygon-amoy": {
                "locator": "polygon-amoy:0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582",
                "amount": "50.0",
                "rawAmount": "50000000",
                "contractAddress": "0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582"
            }
        }
    },
    {
        "symbol": "SOL",
        "decimals": 9,
        "amount": "2.5",
        "rawAmount": "2500000000",
        "chains": {
            "solana": {
                "locator": "solana:sol",
                "amount": "2.5",
                "rawAmount": "2500000000"
            }
        }
    },
    {
        "symbol": "USDC",
        "name": "USD Coin",
        "decimals": 6,
        "amount": "75.0",
        "rawAmount": "75000000",
        "chains": {
            "solana": {
                "locator": "solana:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
                "amount": "75.0",
                "rawAmount": "75000000",
                "mintHash": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
            }
        }
    }
]
```


# Get Wallet By Locator
Source: https://docs.crossmint.com/api-reference/wallets/get-wallet-by-locator

api-reference/_open-api/WalletsV1Alpha2.json GET /2025-06-09/wallets/{walletLocator}
Retrieves a wallet by its locator (address or user identifier and wallet type)

**API scope required**: `wallets.read`



# List Wallet Transfers
Source: https://docs.crossmint.com/api-reference/wallets/list-transfers

api-reference/_open-api/WalletsV1Alpha2.json GET /unstable/wallets/{walletLocator}/transfers
Retrieves activity history for the specified wallet including transactions and other relevant events. This is an unstable API that may change without notice.

**API scope required**: `wallets.read`

<Warning>
  This is an **unstable API** that may change without notice. The `unstable` prefix indicates that breaking changes may occur in future releases.
</Warning>


# Create Delegated Signer
Source: https://docs.crossmint.com/api-reference/wallets/register-delegated-key

api-reference/_open-api/WalletsV1Alpha2.json POST /2025-06-09/wallets/{walletLocator}/signers
Create a delegated signer for a smart wallet with optional restrictions around permissions and expiry date.

**API scope required**: `wallets.create`



# Remove Delegated Signer
Source: https://docs.crossmint.com/api-reference/wallets/remove-delegated-key

api-reference/_open-api/WalletsV1Alpha2.json DELETE /2025-06-09/wallets/{walletLocator}/signers/{signer}
Remove an operational signer from a smart wallet.

**API scope required**: `wallets.create`



# Remove Recovery Method
Source: https://docs.crossmint.com/api-reference/wallets/remove-recovery-method

api-reference/_open-api/WalletsV1Alpha2.json DELETE /2025-06-09/wallets/{walletLocator}/recovery-methods/{signer}
Remove one recovery method from a wallet.



# Transfer Token
Source: https://docs.crossmint.com/api-reference/wallets/transfer-token

api-reference/_open-api/WalletsV1Alpha2.json POST /2025-06-09/wallets/{walletLocator}/tokens/{tokenLocator}/transfers
Sends a token of any type from this wallet to a recipient



# Customization
Source: https://docs.crossmint.com/authentication/customization

Customize the authentication flow and email templates

<Snippet />

With Crossmint Auth, you can customize the authentication flow and email templates with your brand's identity.

## Modal Customization

The `CrossmintAuthProvider` component allows you to customize the authentication modal appearance and content.

```tsx theme={null}
import { CrossmintAuthProvider } from "@crossmint/client-sdk-react-ui";

<CrossmintAuthProvider
    authModalTitle="Sign in to My App"
    termsOfServiceText={
        <p>
            By continuing, you agree to our <a href="/terms">Terms of Service</a> and{" "}
            <a href="/privacy">Privacy Policy</a>
        </p>
    }
    appearance={{
        spacingUnit: "8px",
        borderRadius: "12px",
        colors: {
            inputBackground: "#fffdf9",
            buttonBackground: "#fffaf2",
            border: "#835911",
            background: "#FAF5EC",
            textPrimary: "#5f2c1b",
            textSecondary: "#835911",
            textLink: "#1400cb",
            danger: "#ff3333",
            accent: "#602C1B",
        },
    }}
>
    {children}
</CrossmintAuthProvider>
```

### Modal props

| Prop | Type | Description |
| - | - | - |
| `authModalTitle` | `string` | Custom title displayed at the top of the authentication modal |
| `termsOfServiceText` | `string \| ReactNode` | Custom terms of service text displayed below the authentication form |
| `appearance` | `UIConfig` | Styling configuration for the modal (see example above) |

The modal will also use your display name configured in the Crossmint Console. To learn more, see the "Email Customization" section below.

## Embedded Login

For a more integrated experience, you can use the embedded login component, which offers flexibility to display the login form in your own modal or as part of a split login screen.

```tsx theme={null}
import { EmbeddedAuthForm, useAuth } from "@crossmint/client-sdk-react-ui";

export default function Home() {
    const { user, status } = useAuth(); // "in-progress" | "logged-in" | "logged-out"

    return <div className="max-w-[150px]">{status === "logged-in" ? user?.email : <EmbeddedAuthForm />}</div>;
}
```

## Email Customization

Email OTP is a login method that allows users to sign in to your app using their email address. They receive a one-time code via email that they can use to log in.

You can customize the email template to align with your brand's identity. Crossmint strongly recommends doing so, as it increases user trust and security.

To modify the email template:

1. In the Crossmint Console, click on Settings, and navigate to the **Branding** tab.
2. Here, you can customize:
   * The **logo** displayed in the email with your logo.
   * The **display name** textbox to include your brand's name.

<Warning>
  When customizing email text, avoid using terms like "airdrop", "token", or "crypto" as these can trigger spam
  filters and hurt email deliverability.
</Warning>

<img alt="Customize email template" />


# Introduction
Source: https://docs.crossmint.com/authentication/introduction

Authenticate users and register customer identities for regulated activities

Crossmint provides two complementary capabilities for managing your users:

* **Identity** — Link a `userLocator` to additional customer information (KYC data, documents) required for regulated activities such as onramp, offramp, and payouts.
* **Auth** — Link a `userLocator` to an authentication system (Crossmint's built-in auth or your own). This lets users sign in, authorize API calls, and access Crossmint products.

Choose the path that matches your needs, or use both together.

<CardGroup>
  <Card title="Get Started with Identity" icon="id-card" href="/identity/overview" />

  <Card title="Get Started with Auth" icon="user" href="/authentication/overview" />
</CardGroup>


# Login Methods
Source: https://docs.crossmint.com/authentication/login-methods

Customize how users can log in to your app

<Snippet />

Crossmint Auth supports the following login methods:

* **Email OTP**: passwordless sign-in using a one time code delivered to the user's email.
* **Social Accounts**: Sign in with Google, X, Farcaster, and more.
* **External wallets**: connect with crypto wallets for Web3 authentication. Use `"web3"` for all wallets, `"web3:evm-only"` for Ethereum-compatible wallets only, or `"web3:solana-only"` for Solana wallets only.

To customize which login methods are shown to your users, use the `loginMethods` prop when initializing Crossmint Auth.

By default, only email and Google are enabled.

```tsx app/providers/Providers.tsx theme={null}
"use client";

import { CrossmintProvider, CrossmintAuthProvider } from "@crossmint/client-sdk-react-ui";

export default function Providers({ children }: { children: React.ReactNode }) {
    return (
        <CrossmintProvider apiKey={process.env.NEXT_PUBLIC_CROSSMINT_API_KEY ?? ""}>
            <CrossmintAuthProvider
                loginMethods={["email", "google", "farcaster", "twitter", "web3"]} // Show email, Google, Farcaster, X (Twitter), and external wallets as login methods
            >
                {children}
            </CrossmintAuthProvider>
        </CrossmintProvider>
    );
}
```


# Overview
Source: https://docs.crossmint.com/authentication/overview

Authenticate users into your app with Crossmint Auth or your own provider

<Snippet />

Crossmint Auth is a quick-to-integrate authentication solution, ideal for staging environments, demos, and prototyping. It lets you authenticate users using web3 or traditional sign-in methods:

* **Email OTP**: passwordless sign-in using a one time code delivered to the user's email.
* **Social Accounts**: Sign in with Google, Apple, X, and more.
* **Farcaster**: using the [Sign In With Farcaster (SIWF) standard](https://github.com/farcasterxyz/protocol/discussions/110).
* **External wallets**: connect with crypto wallets for Web3 authentication.

### When to Use Crossmint Auth

| Scenario | Recommendation |
| - | - |
| **Staging / prototyping** | Use Crossmint Auth. Get up and running in minutes |
| **Demos and quickstarts** | Use Crossmint Auth. Minimal setup, great for testing |
| **Production applications** | [Bring your own auth provider](/wallets/guides/bring-your-own-auth) for full control over user management |

### Key Characteristics

<CardGroup>
  <Card title="Securely authorize your users" icon="table-list">
    Authorize calls to your backend services and any Crossmint product.
  </Card>

  <Card title="Link wallets and user accounts" icon="wallet">
    Unified identities across your backend and the blockchain.
  </Card>

  <Card title="Drag and drop integration" icon="bolt">
    Launch your app in under 5 minutes.
  </Card>
</CardGroup>

### Get Started with Auth

<CardGroup>
  <Card title="React Quickstart" icon="bolt" href="/authentication/quickstarts/react">
    Get started with Crossmint Auth in a React web app in under 5 minutes.
  </Card>

  <Card title="React Native Quickstart" icon="mobile" href="/authentication/quickstarts/react-native">
    Get started with Crossmint Auth in an Expo app in under 5 minutes.
  </Card>

  <Card title="Bring Your Own Auth" icon="key" href="/wallets/guides/bring-your-own-auth">
    Recommended for production. Use Auth0, Firebase, Supabase, or any JWT-based provider with Crossmint.
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Create wallets" icon="wallet" href="/wallets/quickstarts/react">
    Detailed wallet creation guide.
  </Card>

  <Card title="User Profile" icon="user" href="/authentication/user-profile">
    Get and update user information.
  </Card>

  <Card title="Talk to an expert" icon="message" href="https://www.crossmint.com/contact/sales">
    Contact our sales team for advanced support.
  </Card>
</CardGroup>


# Flutter
Source: https://docs.crossmint.com/authentication/quickstarts/flutter

Authenticate users in your Flutter app in under 5 minutes

<Snippet />

<Note>
  Crossmint Auth on Flutter is **headless** — there is no pre-built login modal.
  You build your own UI and call the SDK directly. This guide walks through both
  **email OTP** and **OAuth** login flows. Optional pre-built widgets are available
  via `crossmint_flutter_ui.dart`.
</Note>

<CardGroup>
  <Snippet />

  <Card title="Flutter Wallets Example" icon="github" href="https://github.com/Paella-Labs/crossmint-flutter-sdk">
    See a full working example with auth and wallets.
  </Card>
</CardGroup>

<Steps>
  <Step title="Install the SDK">
    Install the Crossmint Flutter SDK:

    <Snippet />

    The SDK bundles the following dependencies:

    | Package | Purpose |
    | - | - |
    | `flutter_secure_storage` | Encrypted token storage (Keychain on iOS, Keystore on Android) |
    | `url_launcher` | Opens the OAuth consent screen in a system browser |
    | `app_links` | Listens for OAuth deep-link redirects back to your app |
  </Step>

  <Step title="Configure your deep link scheme">
    OAuth redirects require a **deep link scheme** so the browser can return to your app after login.

    **Android** — add to your `AndroidManifest.xml`:

    ```xml android/app/src/main/AndroidManifest.xml theme={null}
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="myapp" />
    </intent-filter>
    ```

    **iOS** — add to your `Info.plist`:

    ```xml ios/Runner/Info.plist theme={null}
    <key>CFBundleURLTypes</key>
    <array>
        <dict>
            <key>CFBundleURLSchemes</key>
            <array>
                <string>myapp</string>
            </array>
        </dict>
    </array>
    ```

    Pass the same scheme to `CrossmintClientConfig.appScheme`.
  </Step>

  <Step title="Initialize the client">
    Initialize `CrossmintClient` and restore any persisted session on app launch.

    ```dart lib/crossmint.dart theme={null}
    import 'package:crossmint_flutter/crossmint_client.dart';
    import 'package:crossmint_flutter/crossmint_flutter_auth.dart';

    /// Shared Crossmint client instance — import this file from your screens.
    final client = CrossmintClient(
      config: CrossmintClientConfig(
        apiKey: const String.fromEnvironment('CROSSMINT_API_KEY'),
        appScheme: 'myapp',
      ),
    );
    ```

    ```dart main.dart theme={null}
    import 'package:flutter/material.dart';
    import 'package:crossmint_flutter/crossmint_flutter_auth.dart';
    import 'crossmint.dart'; // shared client instance

    Future<void> main() async {
      WidgetsFlutterBinding.ensureInitialized();
      await client.initialize();
      await client.auth.restoreSession();

      // Start the OAuth callback router
      final authRouter = CrossmintAuthCallbackRouter(auth: client.auth);
      await authRouter.start();

      runApp(const MyApp());
    }
    ```

    Pass the API key via `--dart-define` when running the app:

    ```bash theme={null}
    flutter run --dart-define=CROSSMINT_API_KEY=YOUR_CLIENT_API_KEY
    ```
  </Step>

  <Step title="Build the login screen">
    Use the `CrossmintAuthClient` to implement email OTP and OAuth login flows.

    ### Email OTP Login

    ```dart login_screen.dart theme={null}
    import 'package:flutter/material.dart';
    import 'package:crossmint_flutter/crossmint_flutter_auth.dart';
    import 'crossmint.dart'; // shared client instance

    class LoginScreen extends StatefulWidget {
      const LoginScreen({super.key});

      @override
      State<LoginScreen> createState() => _LoginScreenState();
    }

    class _LoginScreenState extends State<LoginScreen> {
      final _emailController = TextEditingController();
      final _otpController = TextEditingController();
      String? _emailId;
      bool _otpSent = false;
      bool _isPending = false;

      Future<void> _sendOtp() async {
        final email = _emailController.text.trim();
        if (email.isEmpty) {
          ScaffoldMessenger.of(context).showSnackBar(
            const SnackBar(content: Text('Enter a valid email address')),
          );
          return;
        }

        setState(() => _isPending = true);
        try {
          final challenge = await client.auth.sendEmailOtp(email);
          setState(() {
            _emailId = challenge.id;
            _otpSent = true;
          });
        } catch (e) {
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(content: Text('Failed to send OTP: $e')),
          );
        } finally {
          setState(() => _isPending = false);
        }
      }

      Future<void> _verifyOtp() async {
        final otp = _otpController.text.trim();
        if (otp.isEmpty) {
          ScaffoldMessenger.of(context).showSnackBar(
            const SnackBar(content: Text('Enter the OTP code')),
          );
          return;
        }

        setState(() => _isPending = true);
        try {
          await client.auth.confirmEmailOtp(
            email: _emailController.text.trim(),
            emailId: _emailId!,
            token: otp,
          );
        } catch (e) {
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(content: Text('Invalid OTP: $e')),
          );
        } finally {
          setState(() => _isPending = false);
        }
      }

      @override
      Widget build(BuildContext context) {
        return Scaffold(
          body: Padding(
            padding: const EdgeInsets.all(20),
            child: Column(
              mainAxisAlignment: MainAxisAlignment.center,
              children: [
                TextField(
                  controller: _emailController,
                  decoration: const InputDecoration(
                    hintText: 'Enter your email',
                    border: OutlineInputBorder(),
                  ),
                  enabled: !_otpSent,
                ),
                const SizedBox(height: 10),
                if (!_otpSent)
                  SizedBox(
                    width: double.infinity,
                    child: ElevatedButton(
                      onPressed: _isPending ? null : _sendOtp,
                      style: ElevatedButton.styleFrom(
                        backgroundColor: const Color(0xFF05B959),
                      ),
                      child: _isPending
                          ? const SizedBox(
                              height: 20, width: 20,
                              child: CircularProgressIndicator(
                                color: Colors.white, strokeWidth: 2,
                              ),
                            )
                          : const Text('Send OTP',
                              style: TextStyle(color: Colors.white)),
                    ),
                  )
                else ...[
                  TextField(
                    controller: _otpController,
                    decoration: const InputDecoration(
                      hintText: 'Enter OTP code',
                      border: OutlineInputBorder(),
                    ),
                  ),
                  const SizedBox(height: 10),
                  SizedBox(
                    width: double.infinity,
                    child: ElevatedButton(
                      onPressed: _isPending ? null : _verifyOtp,
                      style: ElevatedButton.styleFrom(
                        backgroundColor: const Color(0xFF05B959),
                      ),
                      child: _isPending
                          ? const SizedBox(
                              height: 20, width: 20,
                              child: CircularProgressIndicator(
                                color: Colors.white, strokeWidth: 2,
                              ),
                            )
                          : const Text('Verify OTP',
                              style: TextStyle(color: Colors.white)),
                    ),
                  ),
                ],
              ],
            ),
          ),
        );
      }

      @override
      void dispose() {
        _emailController.dispose();
        _otpController.dispose();
        super.dispose();
      }
    }
    ```

    ### OAuth Login (Google, Twitter)

    ```dart oauth_button.dart theme={null}
    import 'package:flutter/material.dart';
    import 'package:crossmint_flutter/crossmint_flutter_auth.dart';
    import 'crossmint.dart'; // shared client instance

    class GoogleSignInButton extends StatelessWidget {
      const GoogleSignInButton({super.key});

      @override
      Widget build(BuildContext context) {
        return SizedBox(
          width: double.infinity,
          child: ElevatedButton(
            onPressed: () => client.auth.loginWithOAuth(
              CrossmintOAuthProvider.google,
            ),
            style: ElevatedButton.styleFrom(
              backgroundColor: const Color(0xFF4285F4),
            ),
            child: const Text(
              'Sign in with Google',
              style: TextStyle(color: Colors.white),
            ),
          ),
        );
      }
    }
    ```

    <Accordion title="How OAuth Works on Android vs iOS">
      The SDK handles platform differences automatically via `CrossmintAuthCallbackRouter`:

      * **iOS**: Uses `url_launcher` to open an in-app authentication session. The redirect URL is
        captured by the auth callback router via `app_links`.
      * **Android**: Opens the system browser. The OAuth provider redirects back to your app via the
        deep link scheme configured in `AndroidManifest.xml`.

      The `CrossmintAuthCallbackRouter` listens for incoming deep links on both platforms and automatically
      completes the OAuth flow — no manual URL handling required.
    </Accordion>
  </Step>

  <Step title="Implement logout and display user info">
    ```dart home_screen.dart theme={null}
    import 'package:flutter/material.dart';
    import 'package:crossmint_flutter/crossmint_flutter_auth.dart';
    import 'crossmint.dart'; // shared client instance

    class HomeScreen extends StatelessWidget {
      const HomeScreen({super.key});

      @override
      Widget build(BuildContext context) {
        return Scaffold(
          body: ValueListenableBuilder<CrossmintAuthState>(
            valueListenable: client.auth.stateListenable,
            builder: (context, state, _) {
              final user = state.user;
              if (user == null) return const LoginScreen();

              return Padding(
                padding: const EdgeInsets.all(20),
                child: Column(
                  crossAxisAlignment: CrossAxisAlignment.start,
                  children: [
                    Row(
                      mainAxisAlignment: MainAxisAlignment.spaceBetween,
                      children: [
                        const Text('Welcome!',
                            style: TextStyle(fontSize: 20)),
                        TextButton(
                          onPressed: () => client.auth.logout(),
                          child: const Text('Logout',
                              style: TextStyle(color: Colors.red)),
                        ),
                      ],
                    ),
                    const SizedBox(height: 20),
                    Text('Email: ${user.email}'),
                    Text('User ID: ${user.id}'),
                  ],
                ),
              );
            },
          ),
        );
      }
    }
    ```
  </Step>
</Steps>

## Auth State Values

The `CrossmintAuthState` provides the following status information:

| Status | Description |
| - | - |
| `initializing` | The SDK is loading stored tokens and checking session validity |
| `loggedOut` | No active session. Show your login screen |
| `inProgress` | An OAuth or OTP flow is currently in progress |
| `loggedIn` | The user is authenticated. `user` and `jwt` are available |

## Token Storage

By default, the SDK stores authentication tokens using `flutter_secure_storage`, which encrypts data
at rest using the platform keychain (iOS) or keystore (Android). Tokens persist across app restarts
and are protected by the device's hardware-backed security.

You can provide a custom storage implementation via `CrossmintClientConfig.authStorage` if you need
a different storage backend. The SDK also provides `InMemoryCrossmintAuthStorage` for testing.

## Differences from the React Native SDK

| Feature | React Native | Flutter |
| - | - | - |
| **Login UI** | Headless — build your own UI | Headless — build your own UI (optional pre-built widgets available) |
| **State management** | React hooks (`useCrossmintAuth`) | `ChangeNotifier` / `ValueListenable` |
| **OAuth flow** | System browser via `expo-web-browser` | System browser via `url_launcher` |
| **OAuth callback** | `Linking.useURL()` + `createAuthSession()` | `CrossmintAuthCallbackRouter` (automatic) |
| **Token storage** | `expo-secure-store` (encrypted) | `flutter_secure_storage` (encrypted) |
| **Package** | `@crossmint/client-sdk-react-native-ui` | `crossmint_flutter` |
| **Deep link setup** | `scheme` in `app.json` | `AndroidManifest.xml` + `Info.plist` |
| **OTP prompts** | Manual via `useWalletOtpSigner` hook | Automatic via `CrossmintOtpSignerListener` widget |

## Moving to Production

<Warning>
  **Crossmint Auth is designed for staging and getting started quickly.** For production applications,
  Crossmint strongly recommends migrating to your own authentication provider for full control
  over user management.
</Warning>

When you are ready to go to production, Crossmint recommends:

1. **Set up your own auth provider** (Auth0, Firebase, Supabase, Stytch, etc.) and follow the [Bring Your Own Auth guide](/wallets/guides/bring-your-own-auth) to integrate it with Crossmint via JWT.
2. Create a developer account on the <a href="https://www.crossmint.com/console">production console</a>.
3. Create a production client API key on the <a href="https://www.crossmint.com/console/projects/apiKeys">API Keys</a> page with the API scopes `users.create`, `users.read`, `wallets.read`.
4. [Configure JWT authentication](/introduction/platform/api-keys/jwt-authentication) for your auth provider in the Crossmint Console.

## Next Steps

<CardGroup>
  <Card title="Flutter SDK Reference" icon="book" href="/sdk-reference/wallets/flutter/get-started">
    Install and configure the Flutter SDK, then explore the full API reference
  </Card>

  <Card title="Bring Your Own Auth" icon="key" href="/wallets/guides/bring-your-own-auth">
    Recommended for production — integrate your own auth provider via JWT
  </Card>

  <Card title="Webhooks" icon="bell" href="/authentication/webhooks">
    Get notified when a user signs up or updates their profile
  </Card>

  <Card title="Create Smart Wallets" icon="wallet" href="/wallets/quickstarts/flutter">
    Provision wallets automatically when users sign up
  </Card>
</CardGroup>


# React
Source: https://docs.crossmint.com/authentication/quickstarts/react

Sign up your first user in 5 minutes with React

<Snippet />

<CardGroup>
  <Snippet />

  <Card title="Auth with Wallets Quickstart" icon="github" href="https://github.com/Crossmint/wallets-quickstart">
    See a full working example with auth and wallets.
  </Card>
</CardGroup>

<Steps>
  <Step title="Install the SDK">
    Run the following command to install the SDK:

    <Snippet />
  </Step>

  <Step title="Add the Crossmint providers to your app">
    Add the necessary Crossmint providers to your app.

    <CodeGroup>
      ```tsx next.js theme={null}
      "use client";

      import {
          CrossmintProvider,
          CrossmintAuthProvider,
      } from "@crossmint/client-sdk-react-ui";

      export function Providers({ children }: { children: React.ReactNode }) {
          return (
              <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
                  <CrossmintAuthProvider>
                      {children}
                  </CrossmintAuthProvider>
              </CrossmintProvider>
          );
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Implement login and logout">
    <CodeGroup>
      ```tsx next.js theme={null}
      "use client";

      import { useAuth } from "@crossmint/client-sdk-react-ui";

      export function AuthButton() {
        const { login, logout, user, jwt } = useAuth();

        return (
          <div className="flex gap-4">
            {user == null ? (
              <button
                type="button"
                onClick={login}
                className="bg-blue-500 text-white font-bold py-2 px-4 rounded"
              >
                Login
              </button>
            ) : (
              <button
                type="button"
                onClick={logout}
                className="bg-black text-white font-bold py-2 px-4 rounded border-2 border-blue-500"
              >
                Logout
              </button>
            )}
            <p>User: {user?.id}</p>
            <p>Email: {user?.email ?? "None"}</p>
            <p>Phone Number: {user?.phoneNumber ?? "None"}</p>
            <p>Farcaster username: {user?.farcaster?.username ?? "None"}</p>
            <p>Twitter username: {user?.twitter?.username ?? "None"}</p>
            <p>JWT: {jwt}</p>
          </div>
        );
      }
      ```
    </CodeGroup>
  </Step>
</Steps>

## Moving to Production

<Warning>
  **Crossmint Auth is designed for staging and getting started quickly.** For production applications, Crossmint strongly recommends migrating to your own authentication provider for full control over user management.
</Warning>

When you are ready to go to production, Crossmint recommends:

1. **Set up your own auth provider** (Auth0, Firebase, Supabase, Stytch, etc.) and follow the [Bring Your Own Auth guide](/wallets/guides/bring-your-own-auth) to integrate it with Crossmint via JWT.
2. Create a developer account on the <a href="https://www.crossmint.com/console">production console</a>.
3. Create a production client API key on the <a href="https://www.crossmint.com/console/projects/apiKeys">API Keys</a> page with the API scopes `users.create`, `users.read`, `wallets.read`.
4. [Configure JWT authentication](/introduction/platform/api-keys/jwt-authentication) for your auth provider in the Crossmint Console.

## Next Steps

<CardGroup>
  <Card title="Bring Your Own Auth" icon="key" href="/wallets/guides/bring-your-own-auth">
    Recommended for production — integrate your own auth provider via JWT
  </Card>

  <Card title="Webhooks" icon="bell" href="/authentication/webhooks">
    Get notified when a user signs up or updates their profile
  </Card>

  <Card title="Create Smart Wallets" icon="wallet" href="/wallets/quickstarts/react">
    Provision wallets automatically when users sign up
  </Card>
</CardGroup>


# React Native
Source: https://docs.crossmint.com/authentication/quickstarts/react-native

Authenticate users in your Expo app in under 5 minutes

<Snippet />

<Note>
  Crossmint Auth on React Native is **headless** — there is no pre-built login modal.
  You build your own UI and call the SDK hooks directly. This guide walks through both
  **email OTP** and **OAuth** login flows.
</Note>

<CardGroup>
  <Snippet />

  <Card title="Expo Wallets Quickstart" icon="github" href="https://github.com/Crossmint/wallets-expo-quickstart">
    See a full working example with auth and wallets.
  </Card>
</CardGroup>

<Steps>
  <Step title="Install the SDK">
    Install the Crossmint React Native SDK and its required Expo peer dependencies:

    <Snippet />

    The SDK requires the following Expo packages:

    | Package | Purpose |
    | - | - |
    | `expo-secure-store` | Encrypted token storage (Keychain on iOS, Keystore on Android) |
    | `expo-web-browser` | Opens the OAuth consent screen in a system browser |
    | `expo-device` | Detects device capabilities for secure storage availability |
    | `expo-linking` | Listens for OAuth deep-link redirects back to your app |
  </Step>

  <Step title="Configure your app scheme">
    OAuth redirects require a **deep link scheme** so the browser can return to your app after login.

    Add a `scheme` to your `app.json` (or `app.config.ts`):

    ```json app.json theme={null}
    {
        "expo": {
            "scheme": "myapp"
        }
    }
    ```

    <Warning>
      **Expo Go** uses a different scheme at runtime (`exp://127.0.0.1:8081`). The SDK
      detects Expo Go automatically and adjusts the redirect URI, so OAuth works during
      development without extra configuration. For production builds, the `scheme` value
      above is used.
    </Warning>
  </Step>

  <Step title="Add the Crossmint providers to your app">
    Wrap your application with `CrossmintProvider` and `CrossmintAuthProvider`.

    ```tsx providers.tsx theme={null}
    import {
        CrossmintProvider,
        CrossmintAuthProvider,
    } from "@crossmint/client-sdk-react-native-ui";

    type ProvidersProps = {
        children: React.ReactNode;
    };

    export default function Providers({ children }: ProvidersProps) {
        return (
            <CrossmintProvider
                apiKey={process.env.EXPO_PUBLIC_CROSSMINT_API_KEY!}
            >
                <CrossmintAuthProvider>
                    {children}
                </CrossmintAuthProvider>
            </CrossmintProvider>
        );
    }
    ```

    <Accordion title="CrossmintAuthProvider Props">
      | Prop | Type | Description |
      | - | - | - |
      | `appSchema` | `string \| string[]` | Override the deep link scheme. Defaults to the `scheme` in your Expo config. |
      | `storageProvider` | `StorageProvider` | Custom token storage implementation. Defaults to `expo-secure-store`. |
      | `onLoginSuccess` | `(user) => void` | Callback fired after a successful login. |
    </Accordion>
  </Step>

  <Step title="Build the login screen">
    Use the `useCrossmintAuth` hook to access auth functions. Unlike the React web SDK, there is no
    pre-built modal — you call `loginWithOAuth` and `crossmintAuth.sendEmailOtp` / `crossmintAuth.confirmEmailOtp` directly.

    ### Email OTP Login

    ```tsx LoginScreen.tsx theme={null}
    import React, { useState } from "react";
    import {
        View,
        Text,
        TextInput,
        TouchableOpacity,
        ActivityIndicator,
        Alert,
    } from "react-native";
    import { useCrossmintAuth } from "@crossmint/client-sdk-react-native-ui";

    export default function LoginScreen() {
        const { crossmintAuth, createAuthSession, status } =
            useCrossmintAuth();

        const [email, setEmail] = useState("");
        const [emailId, setEmailId] = useState("");
        const [otp, setOtp] = useState("");
        const [otpSent, setOtpSent] = useState(false);
        const [isPending, setIsPending] = useState(false);

        const sendOtp = async () => {
            if (!email.trim()) {
                Alert.alert("Error", "Enter a valid email address");
                return;
            }
            setIsPending(true);
            try {
                const res =
                    await crossmintAuth?.sendEmailOtp(email);
                if (res == null) {
                    throw new Error("Auth client not ready");
                }
                setEmailId(res.emailId);
                setOtpSent(true);
            } catch (error) {
                const message =
                    error instanceof Error
                        ? error.message
                        : "Failed to send OTP.";
                Alert.alert("Error", message);
            } finally {
                setIsPending(false);
            }
        };

        const verifyOtp = async () => {
            if (!otp.trim()) {
                Alert.alert("Error", "Enter the OTP code");
                return;
            }
            setIsPending(true);
            try {
                const oneTimeSecret =
                    await crossmintAuth?.confirmEmailOtp(
                        email,
                        emailId,
                        otp
                    );
                if (oneTimeSecret == null) {
                    throw new Error("Auth client not ready");
                }
                await createAuthSession(oneTimeSecret);
            } catch (error) {
                const message =
                    error instanceof Error
                        ? error.message
                        : "Invalid OTP. Try again.";
                Alert.alert("Error", message);
            } finally {
                setIsPending(false);
            }
        };

        if (status === "initializing") {
            return (
                <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
                    <ActivityIndicator size="large" />
                </View>
            );
        }

        return (
            <View style={{ flex: 1, padding: 20, justifyContent: "center" }}>
                <TextInput
                    style={{ borderWidth: 1, padding: 10, marginBottom: 10 }}
                    placeholder="Enter your email"
                    value={email}
                    onChangeText={setEmail}
                    editable={!otpSent}
                />

                {!otpSent ? (
                    <TouchableOpacity
                        style={{ backgroundColor: "#05b959", padding: 15, alignItems: "center" }}
                        onPress={sendOtp}
                        disabled={isPending}
                    >
                        {isPending ? (
                            <ActivityIndicator color="#fff" size="small" />
                        ) : (
                            <Text style={{ color: "#fff" }}>Send OTP</Text>
                        )}
                    </TouchableOpacity>
                ) : (
                    <>
                        <TextInput
                            style={{ borderWidth: 1, padding: 10, marginBottom: 10 }}
                            placeholder="Enter OTP code"
                            value={otp}
                            onChangeText={setOtp}
                        />
                        <TouchableOpacity
                            style={{ backgroundColor: "#05b959", padding: 15, alignItems: "center" }}
                            onPress={verifyOtp}
                            disabled={isPending}
                        >
                            {isPending ? (
                                <ActivityIndicator color="#fff" size="small" />
                            ) : (
                                <Text style={{ color: "#fff" }}>Verify OTP</Text>
                            )}
                        </TouchableOpacity>
                    </>
                )}
            </View>
        );
    }
    ```

    ### OAuth Login (Google, Twitter)

    ```tsx OAuthButton.tsx theme={null}
    import React, { useEffect } from "react";
    import { TouchableOpacity, Text } from "react-native";
    import { useCrossmintAuth } from "@crossmint/client-sdk-react-native-ui";
    import * as Linking from "expo-linking";

    export default function OAuthButton() {
        const { loginWithOAuth, createAuthSession } =
            useCrossmintAuth();

        const url = Linking.useURL();

        useEffect(() => {
            if (url != null) {
                createAuthSession(url);
            }
        }, [url, createAuthSession]);

        return (
            <TouchableOpacity
                style={{ backgroundColor: "#4285f4", padding: 15, alignItems: "center" }}
                onPress={() => loginWithOAuth("google")}
            >
                <Text style={{ color: "#fff" }}>
                    Sign in with Google
                </Text>
            </TouchableOpacity>
        );
    }
    ```

    <Accordion title="How OAuth Works on Android vs iOS">
      The SDK handles platform differences automatically:

      * **iOS**: Uses `WebBrowser.openAuthSessionAsync`, which opens an in-app authentication
        session (ASWebAuthenticationSession). The redirect URL is intercepted by the authentication
        session before it reaches your app's URL routing, so `Linking.useURL()` remains `null` after
        the OAuth flow. There is no double invocation — `createAuthSession` is called only once by
        the SDK internally.
      * **Android**: Uses `WebBrowser.openBrowserAsync`, which opens the system browser. The OAuth
        provider redirects back to your app via the deep link scheme. You must listen for the
        incoming URL with `Linking.useURL()` and pass it to `createAuthSession` yourself, as shown
        in the example above.

      The `Linking.useURL()` + `createAuthSession` pattern works on both platforms, so a single
      code path is sufficient.
    </Accordion>
  </Step>

  <Step title="Implement logout and display user info">
    ```tsx HomeScreen.tsx theme={null}
    import React from "react";
    import { View, Text, TouchableOpacity } from "react-native";
    import { useCrossmintAuth } from "@crossmint/client-sdk-react-native-ui";

    export default function HomeScreen() {
        const { user, jwt, logout, status } = useCrossmintAuth();

        return (
            <View style={{ flex: 1, padding: 20 }}>
                <View
                    style={{
                        flexDirection: "row",
                        justifyContent: "space-between",
                        marginBottom: 20,
                    }}
                >
                    <Text style={{ fontSize: 20 }}>Welcome!</Text>
                    <TouchableOpacity onPress={logout}>
                        <Text style={{ color: "red" }}>Logout</Text>
                    </TouchableOpacity>
                </View>

                <Text>Email: {user?.email}</Text>
                <Text>User ID: {user?.id}</Text>
                <Text>Status: {status}</Text>
                <Text>JWT: {jwt ? "Present" : "None"}</Text>
            </View>
        );
    }
    ```
  </Step>
</Steps>

## Auth Status Values

The `status` field returned by `useCrossmintAuth` can be one of the following:

| Status | Description |
| - | - |
| `"initializing"` | The SDK is loading stored tokens and checking session validity |
| `"logged-out"` | No active session. Show your login screen |
| `"in-progress"` | An OAuth or OTP flow is currently in progress |
| `"logged-in"` | The user is authenticated. `user` and `jwt` are available |

## Token Storage

By default, the SDK stores authentication tokens using `expo-secure-store`, which encrypts data
at rest using the platform keychain (iOS) or keystore (Android). This means tokens persist
across app restarts and are protected by the device's hardware-backed security.

You can provide a custom storage implementation via the `storageProvider` prop on
`CrossmintAuthProvider` if you need a different storage backend.

## Differences from the React Web SDK

| Feature | React (Web) | React Native |
| - | - | - |
| **Login UI** | Pre-built modal via `login()` | Headless — build your own UI |
| **Auth hook** | `useAuth()` | `useCrossmintAuth()` |
| **OAuth flow** | Popup / redirect in browser | System browser via `expo-web-browser` |
| **OAuth callback** | Handled automatically | Listen with `Linking.useURL()` + `createAuthSession()` |
| **Token storage** | Browser `localStorage` / cookies | `expo-secure-store` (encrypted) |
| **Package** | `@crossmint/client-sdk-react-ui` | `@crossmint/client-sdk-react-native-ui` |
| **Deep link scheme** | Not required | Required in `app.json` for OAuth |
| **Email OTP** | Handled by modal | Call `sendEmailOtp` / `confirmEmailOtp` manually |

## Moving to Production

<Warning>
  **Crossmint Auth is designed for staging and getting started quickly.** For production applications,
  Crossmint strongly recommends migrating to your own authentication provider for full control
  over user management.
</Warning>

When you are ready to go to production, Crossmint recommends:

1. **Set up your own auth provider** (Auth0, Firebase, Supabase, Stytch, etc.) and follow the [Bring Your Own Auth guide](/wallets/guides/bring-your-own-auth) to integrate it with Crossmint via JWT.
2. Create a developer account on the <a href="https://www.crossmint.com/console">production console</a>.
3. Create a production client API key on the <a href="https://www.crossmint.com/console/projects/apiKeys">API Keys</a> page with the API scopes `users.create`, `users.read`, `wallets.read`.
4. [Configure JWT authentication](/introduction/platform/api-keys/jwt-authentication) for your auth provider in the Crossmint Console.

## Next Steps

* [Create Smart Wallets on sign up](/wallets/quickstarts/react-native) using the wallets React Native quickstart
* [Bring Your Own Auth](/wallets/guides/bring-your-own-auth), recommended for production
* Read and update [user information](/authentication/user-profile)
* Use [webhooks](/authentication/webhooks) to get notified when a user signs up
* [React Native SDK Reference](/sdk-reference/wallets/react-native/get-started) for the full API documentation


# Secure Cookies
Source: https://docs.crossmint.com/authentication/security

Learn how to securely store Crossmint Auth cookies in your application

<Snippet />

Authentication tokens are accessible to client-side JavaScript by default through non-HttpOnly cookies. For stronger security, you can store tokens in HttpOnly cookies, which are accessible only on the server side. This setup requires custom routes for refreshing tokens and logging out, using utilities from `@crossmint/server-sdk`.

<Steps>
  <Step title="Configure the cookie options">
    When initializing the server SDK, configure secure cookie options:

    ```typescript theme={null}
    import { createCrossmint, CrossmintAuth } from "@crossmint/server-sdk";

    const crossmint = createCrossmint({ apiKey: process.env.SERVER_CROSSMINT_API_KEY });
    const crossmintAuth = CrossmintAuth.from(crossmint, {
        cookieOptions: {
            httpOnly: true,
            secure: true, // Only send cookies over HTTPS
            domain: ".yourdomain.com", // Optional: specify cookie domain
        },
    });
    ```

    **Note:** The `httpOnly` flag only applies to the refresh token. The session JWT remains accessible to client-side JavaScript since it's needed for API calls.
  </Step>

  <Step title="Add the token refresh route">
    <Tabs>
      <Tab title="Next.js (App Router)">
        ```typescript theme={null}
        import { createCrossmint, CrossmintAuth } from "@crossmint/server-sdk";
        import { NextRequest } from "next/server";

        const crossmint = createCrossmint({ apiKey: process.env.SERVER_CROSSMINT_API_KEY! });
        const crossmintAuth = CrossmintAuth.from(crossmint);

        export async function POST(request: NextRequest) {
            return await crossmintAuth.handleCustomRefresh(request);
        }
        ```
      </Tab>

      <Tab title="Express.js">
        ```typescript theme={null}
        import express from "express";
        import { createCrossmint, CrossmintAuth } from "@crossmint/server-sdk";

        const app = express()
        const crossmint = createCrossmint({ apiKey: process.env.SERVER_CROSSMINT_API_KEY! });
        const crossmintAuth = CrossmintAuth.from(crossmint);

        app.post("/api/auth/refresh", async (req, res) => {
            await crossmintAuth.handleCustomRefresh(req, res);
            res.end();
        });
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Add the logout route">
    <Tabs>
      <Tab title="Next.js (App Router)">
        ```typescript theme={null}
        import { createCrossmint, CrossmintAuth } from "@crossmint/server-sdk";
        import { NextRequest } from "next/server";

        const crossmint = createCrossmint({ apiKey: process.env.SERVER_CROSSMINT_API_KEY! });
        const crossmintAuth = CrossmintAuth.from(crossmint);

        export async function POST(request: NextRequest) {
            return await crossmintAuth.logout(request);
        }
        ```
      </Tab>

      <Tab title="Express.js">
        ```typescript theme={null}
        import express from "express";
        import { createCrossmint, CrossmintAuth } from "@crossmint/server-sdk";

        const app = express()
        const crossmint = createCrossmint({ apiKey: process.env.SERVER_CROSSMINT_API_KEY! });
        const crossmintAuth = CrossmintAuth.from(crossmint);

        app.post("/api/auth/logout", async (req, res) => {
            await crossmintAuth.logout(req, res);
            res.end();
        });
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Configure the client SDK">
    Configure the client SDK to use your custom routes:

    <Tabs>
      <Tab title="TypeScript">
        ```typescript theme={null}
        import { createCrossmint, CrossmintAuth } from "@crossmint/client-sdk-auth";

        const crossmint = createCrossmint({ apiKey: process.env.NEXT_PUBLIC_CLIENT_CROSSMINT_API_KEY! });
        const crossmintAuth = CrossmintAuth.from(crossmint, {
            refreshRoute: "/api/auth/refresh",
            logoutRoute: "/api/auth/logout"
        });
        ```
      </Tab>

      <Tab title="React">
        ```tsx theme={null}
        import { CrossmintProvider, CrossmintAuthProvider } from "@crossmint/client-sdk-react-ui";

        <CrossmintProvider apiKey={process.env.NEXT_PUBLIC_CLIENT_CROSSMINT_API_KEY ?? ""}>
            <CrossmintAuthProvider
                refreshRoute="/api/auth/refresh"
                logoutRoute="/api/auth/logout"
            >
                {children}
            </CrossmintAuthProvider>
        </CrossmintProvider>
        ```
      </Tab>
    </Tabs>

    **Note:** Depending on the framework you're using, you might need to set the whole URL in the `refreshRoute` and `logoutRoute` options.
  </Step>
</Steps>


# Server-Side Rendering (SSR)
Source: https://docs.crossmint.com/authentication/ssr

Integrate Crossmint Auth on the server-side for user authentication and management

<Snippet />

Crossmint Auth provides a flexible and simple authentication solution for your crypto server-side applications. This guide covers how to integrate and use Crossmint Auth across various server-side frameworks.

## Overview

The Crossmint server SDK allows you to:

* Manage user sessions
* Retrieve user profiles
* Verify JSON Web Tokens (JWTs)

## Installation

First, install the Crossmint Server SDK:

<CodeGroup>
  ```bash npm theme={null}
  npm i @crossmint/server-sdk
  ```

  ```bash yarn theme={null}
  yarn add @crossmint/server-sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @crossmint/server-sdk
  ```

  ```bash bun theme={null}
  bun add @crossmint/server-sdk
  ```
</CodeGroup>

## Initialization

To use Crossmint Auth, you need to initialize it with your Server API key. This API requires the `users.read` scope.

```typescript theme={null}
import { createCrossmint, CrossmintAuth } from "@crossmint/server-sdk";

const crossmint = createCrossmint({ apiKey: process.env.SERVER_CROSSMINT_API_KEY });
const crossmintAuth = CrossmintAuth.from(crossmint);
```

## Core Functionality

### Session Management

The `getSession` method validates or refreshes a user's session based on their JWT and refresh token.

```typescript theme={null}
const { jwt, refreshToken, userId } = await crossmintAuth.getSession(req, res);
```

This method:

1. Fetches the current JWT and refresh token from the cookies with keys `crossmint-jwt` and `crossmint-refresh-token`.
2. Checks if the current JWT is valid
3. Refreshes the session if needed
4. Stores the new JWT and refresh token in cookies
5. Returns new auth materials and the user ID

<Tabs>
  <Tab title="Next.js (App Router)">
    For other frameworks that do not expose standard request and response objects, such as Next.js using the App Router, you can pass in an object with `jwt` and `refreshToken` properties instead:

    <CodeGroup>
      ```typescript middleware.ts theme={null}
      import { NextResponse } from "next/server";
      import type { NextRequest } from "next/server";
      import { createCrossmint, CrossmintAuth } from "@crossmint/server-sdk";

      export async function middleware(request: NextRequest) {
          // Skip middleware for API routes and static files
          if (request.nextUrl.pathname.startsWith("/api") || request.nextUrl.pathname.startsWith("/_next")) {
              return NextResponse.next();
          }

          const response = NextResponse.next();

          const jwt = request.cookies.get("crossmint-jwt")?.value;
          const refreshToken = request.cookies.get("crossmint-refresh-token")?.value;

          if (refreshToken == null) {
              return response;
          }

          try {
              const crossmint = createCrossmint({
                  apiKey: process.env.SERVER_CROSSMINT_API_KEY || "",
              });
              const crossmintAuth = CrossmintAuth.from(crossmint);

              const { jwt: newJwt, refreshToken: newRefreshToken } = await crossmintAuth.getSession({
                  jwt,
                  refreshToken,
              });

              // Only update response cookies if tokens have changed
              if (newJwt !== jwt || newRefreshToken.secret !== refreshToken) {
                  response.cookies.set("crossmint-jwt", newJwt);
                  response.cookies.set("crossmint-refresh-token", newRefreshToken.secret);
              }
          } catch (_) {
              // If auth fails, clear cookies and redirect to home
              response.cookies.delete("crossmint-jwt");
              response.cookies.delete("crossmint-refresh-token");
          }

          return response;
      }
      ```

      ```typescript getAuthSession.ts theme={null}
      import { cookies } from "next/headers";
      import { createCrossmint, CrossmintAuth } from "@crossmint/server-sdk";

      export async function getAuthSession() {
          const cookieStore = await cookies();
          const jwt = cookieStore.get("crossmint-jwt")?.value;
          const refreshToken = cookieStore.get("crossmint-refresh-token")?.value;

          if (refreshToken == null) {
              return;
          }

          try {
              const crossmint = createCrossmint({
                  apiKey: process.env.SERVER_CROSSMINT_API_KEY || "",
              });
              const crossmintAuth = CrossmintAuth.from(crossmint);

              const session = await crossmintAuth.getSession({
                  jwt,
                  refreshToken,
              });
              return session;
          } catch (_) {
              return;
          }
      }
      ```

      ```typescript page.tsx theme={null}
      import { getAuthSession } from "@/hooks/auth";
      import { createCrossmint, CrossmintAuth } from "@crossmint/server-sdk";

      export default async function ProtectedRoute() {
        const session = await getAuthSession();
        const userId = session?.userId;

        if (userId != null) {
          // Fetch user data or perform authorized actions
          const crossmint = createCrossmint({
              apiKey: process.env.SERVER_CROSSMINT_API_KEY || "",
          });
          const crossmintAuth = CrossmintAuth.from(crossmint);
          const userData = await crossmintAuth.getUser(userId);

          return <div>Welcome, {userData.email}!</div>;
        }

        // Handle unauthenticated state
        return <div>Please log in to access this page.</div>;
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Express.js">
    For Express.js applications, you can create middleware to handle authentication:

    ```typescript theme={null}
    import express from "express";
    import { createCrossmint, CrossmintAuth } from "@crossmint/server-sdk";

    const app = express();

    const crossmint = createCrossmint({
        apiKey: process.env.SERVER_CROSSMINT_API_KEY || "",
    });
    const crossmintAuth = CrossmintAuth.from(crossmint);

    const authMiddleware = async (req, res, next) => {
      try {
        const { jwt, refreshToken, userId } = await crossmintAuth.getSession(req, res);
        req.user = { userId };
        next();
      } catch (error) {
        res.status(401).json({ error: "Authentication failed" });
      }
    };

    app.use(authMiddleware);

    app.get("/protected", (req, res) => {
      res.json({ message: "Protected route", userId: req.user.userId });
    });
    ```
  </Tab>

  <Tab title="Vanilla Node.js">
    For a basic Node.js server:

    ```typescript theme={null}
    import http from "http";
    import { createCrossmint, CrossmintAuth } from "@crossmint/server-sdk";

    const crossmint = createCrossmint({
        apiKey: process.env.SERVER_CROSSMINT_API_KEY || "",
    });
    const crossmintAuth = CrossmintAuth.from(crossmint);

    const server = http.createServer(async (req, res) => {
      if (req.url === "/protected") {
        try {
          const { userId } = await crossmintAuth.getSession(req, res);
          const userData = await crossmintAuth.getUser(userId);

          res.writeHead(200, { "Content-Type": "application/json" });
          res.end(JSON.stringify({ message: "Authenticated", user: userData }));
        } catch (error) {
          res.writeHead(401, { "Content-Type": "application/json" });
          res.end(JSON.stringify({ error: "Authentication failed" }));
        }
      } else {
        res.writeHead(404);
        res.end();
      }
    });

    server.listen(3000);
    ```
  </Tab>
</Tabs>

### User Profile Retrieval

Fetch user details using the `getUser` method:

```typescript theme={null}
const user = await crossmintAuth.getUser(userId);
```

This provides access to user information such as email, phone number, and connected accounts (e.g., Twitter, Farcaster).

### JWT Verification

Verify JWTs independently using the `verifyCrossmintJwt` method:

```typescript theme={null}
const decodedJwt = crossmintAuth.verifyCrossmintJwt(token);
```

This is useful for validating tokens in middleware or specific endpoints. We expose our public keys for this purpose at [https://www.crossmint.com/.well-known/jwks.json](https://www.crossmint.com/.well-known/jwks.json).


# User Profile
Source: https://docs.crossmint.com/authentication/user-profile

Retrieve user profile data such as email or social login metadata

<Snippet />

Crossmint Auth provides a way to retrieve and update user profile data, such as email, social login metadata, and more.

<AccordionGroup>
  <Accordion title="Fields in the User Object">
    The user object contains the following information:

    * `id`: User's unique identifier.
    * `email`: User's email address.
    * `phoneNumber`: User's phone number.
    * `farcaster`: User's Farcaster account data.
    * `twitter`: User's Twitter (X) account data.

    Farcaster Account data contains:

    * `fid`: User's Farcaster ID.
    * `username`: User's Farcaster username.
    * `bio`: User's Farcaster bio.
    * `displayName`: User's Farcaster display name.
    * `pfpUrl`: User's Farcaster profile image URL.
    * `custody`: User's FID custody address.
    * `verifications`: List of the user's verified addresses.

    Twitter Account data contains:

    * `id`: User's Twitter ID.
    * `username`: User's Twitter username.
  </Accordion>
</AccordionGroup>

## Reading User Data

This API requires the `users.read` scope.

* **Server side**: Requires a server-side API key.
* **Client side**: Requires a client-side API key, and a logged in user.

### Server-side

For server-side operations, use the `@crossmint/server-sdk` that provides a `getUser` function to fetch user information.

```typescript theme={null}
import { createCrossmint, CrossmintAuth } from "@crossmint/server-sdk";

const crossmint = createCrossmint({ apiKey: "<YOUR_SERVER_API_KEY>" });
const crossmintAuth = CrossmintAuth.from(crossmint);

async function getUser(userId: string) {
    try {
        const user = await crossmintAuth.getUser(userId);
        console.log("User data:", user);
    } catch (error) {
        console.error("Error fetching user data:", error);
    }
}
```

### Response Format

```json theme={null}
{
    "id": "123",
    "email": "test@test.com", // Optional (if user was created with email)
    "phoneNumber": "123456789", // Optional (if user was created with phone number)
    "farcaster": {
        "fid": "123",
        "username": "johndoe",
        "bio": "Hello, I'm John Doe",
        "displayName": "John Doe",
        "pfpUrl": "https://example.com/pfp.jpg",
        "custody": "0x1234567890123456789012345678901234567890",
        "verifications": ["0x1234567890123456789012345678901234567890"]
    },
    "twitter": {
        "id": "456",
        "username": "johndoe"
    }
}
```

### Client-side

Use the `useAuth` react hook from `@crossmint/client-sdk-react-ui` to access the user object.

<Note>
  If you would like to use a different framework, [contact support](https://help.crossmint.com/hc/en-us/requests/new)
</Note>

```tsx React theme={null}
import { useAuth } from "@crossmint/client-sdk-react-ui";

function User() {
    const { user } = useAuth();

    if (!user) {
        return <div>Loading user...</div>;
    }

    return (
        <div>
            <h1>User</h1>
            <p>User ID: {user.id}</p>
            <p>Email: {user.email}</p>
            <p>Phone Number: {user.phoneNumber}</p>
            <p>Farcaster FID: {user.farcaster?.fid}</p>
            <p>Farcaster Username: {user.farcaster?.username}</p>
            <p>Farcaster Bio: {user.farcaster?.bio}</p>
            <p>Farcaster Display Name: {user.farcaster?.displayName}</p>
            <p>Farcaster PFP URL: {user.farcaster?.pfpUrl}</p>
            <p>Farcaster Custody: {user.farcaster?.custody}</p>
            <p>Farcaster Verifications: {user.farcaster?.verifications}</p>
            <p>Twitter ID: {user.twitter?.id}</p>
            <p>Twitter Username: {user.twitter?.username}</p>
        </div>
    );
}
```


# User Webhooks
Source: https://docs.crossmint.com/authentication/webhooks

Crossmint provides webhooks to notify your application about important user-related events. Below are the details of the available webhooks

<Snippet />

### Webhook Events

#### `users.created`

This webhook is triggered when a new user is created.

##### Payload

```json theme={null}
{
    "type": "users.created",
    "status": "success",
    "data": {
        "id": "123", // User's identifier
        "email": "test@test.com", // Optional (if user was created with email)
        "phoneNumber": "123456789" // Optional (if user was created with phone number)
    }
}
```

#### `users.updated`

This webhook is triggered when a user's email or phone number is successfully updated.

##### Payload

```json theme={null}
{
    "type": "users.updated",
    "status": "success",
    "data": {
        "actionId": "1234", // Update action identifier
        "userId": "123", // User identifier
        "oldEmail": "test@test.com", // Optional (if user was created with email)
        "newEmail": "test2@test2.com", // Optional (if user was created with email)
        "oldPhoneNumber": "123456789", // Optional (if user was created with phone number)
        "newPhoneNumber": "987654321" // Optional (if user was created with phone number)
    }
}
```

### Handling Webhooks

To handle webhooks, you need to set up an endpoint in your application that can receive HTTP POST requests from Crossmint. Here is an example of how you might handle a webhook in a Node.js application:

```javascript theme={null}
import express from "express";

const app = express();
app.use(express.json());

function handleUserCreated(data) {
    console.log("User created:", data.id);
}

function handleUserUpdated(data) {
    console.log("User updated:", data.userId);
}

app.post("/webhooks", (req, res) => {
    const event = req.body;

    switch (event.type) {
        case "users.created":
            handleUserCreated(event.data);
            break;
        case "users.updated":
            handleUserUpdated(event.data);
            break;
        default:
            console.log(`Unhandled event type: ${event.type}`);
    }

    res.sendStatus(200);
});

app.listen(3000, () => {
    console.log("Webhook server listening on port 3000");
});
```


# Crossmint help
Source: https://docs.crossmint.com/cli/help

List all commands and provides the help documentation for a given command

Run the following command from your terminal to list all commands

````
crossmint help
```

## Options

```
$ crossmint --help <command>      # Display help for command, including the supported flags
$ crossmint -h <command>             # Display help for command, including the supported flags
```

## Example


```
Usage: crossmint [options] [command]

Crossmint CLI Tool

Options:
  -V, --version   output the version number
  -h, --help      display help for command

Commands:
  keys            API Keys management commands
  login [options] Login to Crossmint
  logout          Logout from Crossmint
  projects        Project management commands
  whoami          Show current user and environment
  help [command]  display help for command
```
````


# Get started with the Crossmint CLI
Source: https://docs.crossmint.com/cli/install

Manage and configure your Crossmint projects directly from the command line

### Latest CLI version - <a href="https://www.npmjs.com/package/@crossmint/cli"><img alt="npm" /></a>

The Crossmint CLI is a command-line tool that allows you to interact with Crossmint directly from your terminal. It can be installed via Homebrew or any javascript package managers and works on macOS, Linux, and Windows.

### Installation

To download and install Crossmint CLI, run the following command from your terminal:

<CodeGroup>
  ```bash pnpm theme={null}
  pnpm add -g @crossmint/cli
  ```

  ```bash yarn theme={null}
  yarn global add @crossmint/cli
  ```

  ```bash npm theme={null}
  npm install -g @crossmint/cli
  ```

  ```bash brew theme={null}
  brew tap crossmint/tap
  brew install crossmint
  ```
</CodeGroup>

### Verify installation

After installing, verify the CLI is available and check the installed version:

```bash theme={null}
crossmint --version
```

### Update

To update to the latest version, re-run the install command for your package manager, or use the following:

<CodeGroup>
  ```bash pnpm theme={null}
  pnpm add -g @crossmint/cli@latest
  ```

  ```bash yarn theme={null}
  yarn global add @crossmint/cli@latest
  ```

  ```bash npm theme={null}
  npm install -g @crossmint/cli@latest
  ```

  ```bash brew theme={null}
  brew upgrade crossmint
  ```
</CodeGroup>

## Command Reference

The Crossmint CLI provides the following commands:

| Command | Description |
| - | - |
| `crossmint login [options]` <ExternalLink href="/cli/login" /> | Login to Crossmint |
| `crossmint logout` <ExternalLink href="/cli/logout" /> | Logout from Crossmint |
| `crossmint whoami` <ExternalLink href="/cli/whoami" /> | Show current user and environment |
| `crossmint help` <ExternalLink href="/cli/help" /> | List and explains all commands |
| `crossmint keys create` <ExternalLink href="/cli/keys/create" /> | Create a new API Key |
| `crossmint keys list [type]`<ExternalLink href="/cli/keys/list" /> | List all API Keys (optionally filter by type: server\|client) |
| `crossmint keys delete <key-id>` <ExternalLink href="/cli/keys/delete" /> | Delete an API Key |
| `crossmint keys edit <key-id>` <ExternalLink href="/cli/keys/edit" /> | Edit the scopes of an API Key |
| `crossmint projects create`<ExternalLink href="/cli/projects/create" /> | Create a new project |
| `crossmint projects select [project-id]`<ExternalLink href="/cli/projects/select" /> | Select a project |
| `crossmint projects list`<ExternalLink href="/cli/projects/list" /> | List all projects |
| `crossmint projects details`<ExternalLink href="/cli/projects/details" /> | Show project details |

Refer to the individual command documentation for more detailed information on each command.


# Crossmint keys create
Source: https://docs.crossmint.com/cli/keys/create

Create a new API key

The keys create command allows you to create a new API key for your Crossmint project.

To use it, run the following command from your terminal

```bash theme={null}
crossmint keys create
```

<Note>
  **Server-side keys** are view-once in Production, make sure to copy your API key secret when it’s displayed, as it
  won’t be shown again.
</Note>

<Note>
  **Client-side keys** require selecting the app type and adding allowed origins—use domain URLs for web or
  package/bundle IDs for mobile.
</Note>

## Example

Start the API key creation process:

```bash theme={null}
crossmint keys create
```

Select the type of key you want to create:

```
? Select Key Usage: (Use arrow keys)
  Server side
> Client side
```

For client-side keys, select the application type:

```
? Select client platform: (Use arrow keys)
> Web
  Mobile
```

Specify the allowed origins for your key.

* For web enter the domain, eg: [https://crossmint.com](https://crossmint.com)
* For mobile enter your Android Package name or IOS Bundle ID, eg: com.company.appname

<Tip>Enter multiple domains or app identifiers separated by a comma.</Tip>

```
? Enter whitelisted domain or localhost (e.g., https://www.yourdomain.com) (separate multiple domains with a comma):
https://www.crossmint.com
```

Select the scopes you want to add to the key by pressing space. Once you are ready, press enter to create the key:

```
? Select scopes for client key:
● Read wallet (wallets.read)
● Create wallet (wallets.create)
○ Create Transaction (wallets.transactions.create)
○ Sign Transaction (wallets.transactions.sign)
○ Read Transactions (wallets.transactions.read)
○ Create Wallet Signatures (wallets.signatures.create)
```

The CLI will display the created API key information, this includes the Key ID and Client Secret:

```
 ✅ API Key created successfully!
Key ID: 67ff9c388687868382...
🔒 Key Secret: ck_production_3218u5TFZMGkK16uLbKfxDsJ4xtwSd2xtZRa9A8cbe64oRMe1J148XTGbuSvqmxB4k9TspLUAbKyt2RTqbArGBdkvARxkCg8S1tgwb4ie3gUNFw74vTuCUhSpu7ojkjGxY6epj...
```


# Crossmint keys delete
Source: https://docs.crossmint.com/cli/keys/delete

Delete an API key

The keys delete command allows you to delete an existing API key from your Crossmint project.

To use it, run the following command from your terminal

```bash theme={null}
crossmint keys delete <key-id>
```

Where `<key-id>` is the ID of the API key you want to delete.
You can get the key id by running `keys list` command

## Example

Delete an API key:

```bash theme={null}
crossmint keys delete sk_test_abcd1234
```

You will be prompted to confirm the deletion:

```
? Are you sure you want to delete this API key? This action cannot be undone. (y/N)
```

After confirming, you'll see a success message:

```
✅ API Key deleted successfully!
```

**Note:** Once an API key is deleted, any applications or services using that key will no longer be able to authenticate with the Crossmint API.


# Crossmint keys edit
Source: https://docs.crossmint.com/cli/keys/edit

Edit an API key

The keys edit command allows you to modify the scopes of an existing server API key.

To use it, run the following command from your terminal

```bash theme={null}
crossmint keys edit <key-id>
```

Where `<key-id>` is the ID of the API key you want to edit. You can get the key id by running `keys list` command.

## Example

Edit an API key:

```bash theme={null}
crossmint keys edit sk_test_abcd1234
```

For client-side keys, edit the allowed origins for your key. Press `<tab>` for editing or `<enter>` for confirming the value.

* For web enter the domain, eg: [https://crossmint.com](https://crossmint.com)
* For mobile enter your Android Package name or IOS Bundle ID, eg: com.company.appname

<Tip>Enter multiple domains or app identifiers separated by a comma.</Tip>

```
? Enter whitelisted domain or localhost (e.g., https://www.yourdomain.com) (separate multiple domains with a comma):
Press <tab> to edit or <enter> to confirm current value  (https://www.crossmint.com)
```

The CLI will display the current scopes and prompt you to select new ones:

```
Current scopes: Wallets
? Select the new scopes for this key: (Press <space> to select, <a> to toggle all, <i> to invert selection, and <enter> to proceed)
❯◉ Wallets
 ◉ Minting
 ◯ Payments
 ◯ Authentication
```

After selecting the new scopes, you'll see a confirmation message:

```
✅ API Key updated successfully!
```


# Crossmint keys list
Source: https://docs.crossmint.com/cli/keys/list

List all API keys

The keys list command displays all API keys associated with your Crossmint project.

To use it, run the following command from your terminal

```bash theme={null}
crossmint keys list [type]
```

Where `[type]` is an optional parameter to filter keys by type (server or client).

## Example

List all API keys:

```bash theme={null}
crossmint keys list
```

```
=========

1. Key ID: 67d444369323ea298a4ef9f8
   Key Secret: ******************4jTa

Type                 Server
Created By           guille.a@paella.dev
Created              3/14/2025, 3:59:02 PM
Scopes               wallets.read, wallets.create, wallets:transactions.create, wallets:transactions.sign, wallets:transactions.read, wallets:signatures.create, wallets:signatures.read, wallets:nfts.read, wallets:balance.read, wallets.fund, wallets:messages.sign

=========

2. Key ID: 679217c403723242bd87d3e75
   Key Secret: ck_production_AGUysPdnSg3rW2opefTqWAbfXRaCLtEBiYCSNL7
Jbm9L

Type                 Client
Created              1/23/2025, 11:19:48 AM
Scopes               wallets.read, wallets.create, wallets:nfts.read, wallets:transactions.create
Whitelisted App IDs  com.company.appname

=========
```

List only server API keys:

```bash theme={null}
crossmint keys list server
```

```
=========

1. Key ID: 67d444369bbbea298a4ef932
   Key Secret: ******************4jTa

Type                 Server
Created By           guille.a@paella.dev
Created              3/14/2025, 3:59:02 PM
Scopes               wallets.read, wallets.create, wallets:transactions.create, wallets:transactions.sign, wallets:transactions.read, wallets:signatures.create, wallets:signatures.read, wallets:nfts.read, wallets:balance.read, wallets.fund, wallets:messages.sign

=========
```


# Crossmint login
Source: https://docs.crossmint.com/cli/login

Authenticate to the Crossmint platform

The login command authenticates you with the Crossmint platform. It allows you to access your account and manage API keys and projects through the CLI.

To use it, run the following command from your terminal

```bash theme={null}
crossmint login [options]
```

## Options

| Option | Description |
| - | - |
| `-e, --env <environment>` | Environment to login to (`staging` or `production`) |

## Example

Start the login process:

```bash theme={null}
crossmint login
```

Or specify the environment directly to skip the prompt:

```bash theme={null}
crossmint login --env production
```

Select an environment:

```
? Select environment: (Use arrow keys)
> Production
  Staging
```

The CLI will open a browser window to authorize your device. If you're not signed in to Crossmint in the browser, you'll need to login first. Once the device is authorized, you can close the browser and return to the terminal.

<img alt="Authorize Device Success" />

```
✅ Login successful! You are now authenticated in the Production environment.
```

You'll then be prompted to select a project:

```
? Select a project: (Use arrow keys)
> My Project
  Website Integration
  Mobile App
```


# Crossmint logout
Source: https://docs.crossmint.com/cli/logout

Sign out from the Crossmint platform

The logout command signs you out from the Crossmint platform by removing your session token from local storage.

To use it, run the following command from your terminal

```bash theme={null}
crossmint logout
```

## Example

Sign out from Crossmint:

```bash theme={null}
crossmint logout
```

After running the command, you'll see a confirmation message:

```
✅ Logout successful! You are no longer authenticated.
```

After logging out, you will need to use the `login` command to authenticate again before using other commands that require authentication.


# Crossmint projects create
Source: https://docs.crossmint.com/cli/projects/create

Create a new project in Crossmint

The projects create command allows you to create a new project in your Crossmint account.

To use it, run the following command from your terminal

```bash theme={null}
crossmint projects create [options]
```

## Options

| Option | Description |
| - | - |
| `-n, --name <name>` | Give your project a name |

## Example

Create a new project:

```bash theme={null}
crossmint projects create
```

You'll be prompted to enter a name for the project:

```
? Enter project name: My New Project
```

After entering a name, you'll see a confirmation message:

```
✔ ✅ Project created successfully!


📌 Project Details:
Name: New Project
ID: 4b0392a3-35c3-458c-a43e-32d2cdc65eda
```

You'll be ask to confirm if you want to select the created project for subsequent commands.

````
? Do you want to select this project? (Y/n)

```

You can also specify the project name directly using the `--name` option:

```bash
crossmint projects create --name "My New Project"
```


````


# Crossmint projects details
Source: https://docs.crossmint.com/cli/projects/details

View details of a project

The projects details command displays information about the currently selected project.

To use it, run the following command from your terminal

```bash theme={null}
crossmint projects details
```

## Example

View details of the current project:

```bash theme={null}
crossmint projects details
```

You'll see the information about your project:

```
📌 Project Details:
Name: New Project
ID: f5e37bee-1a81-4df1-8081-7670eee2a629
Wallet Type: Custodial
```

This command is useful for verifying which project you're currently working with and viewing its basic information.


# Crossmint projects list
Source: https://docs.crossmint.com/cli/projects/list

List all projects in your Crossmint account

The projects list command displays all projects associated with your Crossmint account.

To use it, run the following command from your terminal

```bash theme={null}
crossmint projects list
```

## Example

List all your projects:

```bash theme={null}
crossmint projects list
```

You'll see a list of all your projects with their IDs:

```
✔ Found 3 projects:

  1. My New Project
     ID: 4b0392a3-35c3-458c-a43e-32d2cdc65eda

  2. Website Integration
     ID: f5e37bee-1a81-4df1-8081-7670eee2a629

  3. Mobile App
     ID: 9a1b2c3d-4e5f-6789-abcd-ef0123456789
```

This command is useful for viewing all available projects and retrieving project IDs, which can then be passed to `crossmint projects select` for non-interactive project selection.


# Crossmint projects select
Source: https://docs.crossmint.com/cli/projects/select

Select a project to work with

The projects select command allows you to choose which Crossmint project you want to work with for subsequent commands.

To use it, run the following command from your terminal

```bash theme={null}
crossmint projects select [project-id]
```

## Arguments

| Argument | Description |
| - | - |
| `[project-id]` | Optional. The ID of the project to select (for non-interactive use) |

## Example

### Interactive selection

Select a project interactively:

```bash theme={null}
crossmint projects select
```

You'll be presented with a list of your projects:

```
? Select a project: (Use arrow keys)
> My New Project
  Website Integration
  Mobile App
  Test Project
```

After selecting a project, you'll see a confirmation message:

```
✅ Project My New Project selected
```

### Non-interactive selection

You can also pass a project ID directly to skip the interactive prompt. This is useful for scripting and agent-based workflows:

```bash theme={null}
crossmint projects select 4b0392a3-35c3-458c-a43e-32d2cdc65eda
```

```
✅ Project My New Project selected
```

<Tip>
  Use `crossmint projects list` to view all available projects and their IDs.
</Tip>

After selecting a project, commands that require a project context (like API key management) will use the selected project.


# Crossmint whoami
Source: https://docs.crossmint.com/cli/whoami

Display current user, environment and selected project

The whoami command displays information about the currently authenticated user, the environment you're working in and the selected project.

To use it, run the following command from your terminal

```bash theme={null}
crossmint whoami
```

## Example

Check your current authentication status:

```bash theme={null}
crossmint whoami
```

You'll see output showing your email and environment:

```
You are logged in to 🍀Crossmint as: user@example.com - Environment: Production - Selected Project: My New Project
```

This command is useful for verifying your authentication status, checking which environment and project you're working in.


# Data Requirements
Source: https://docs.crossmint.com/identity/data-requirements

Required data fields by activity type and region

The data required for each user depends on the type of regulated activity they want to perform, the KYC tier that applies, and the user's residency.

## KYC Tiers for On/Offramp

On/offramp verification is progressive. Crossmint applies a KYC tier based on cumulative transaction volume, transaction frequency, and risk profile, so a user does not have to provide the full data set up front for low-value activity.

| Tier | Applies when | What is required |
| :- | :- | :- |
| **Progressive (light) KYC** | Up to \$1,000 in total volume in the last 12 months and a low transaction count | `userDetails` and `kycData` only |
| **Full KYC** | Transacting over the progressive (light) KYC limits | Progressive KYC data plus `dueDiligence`, `verificationHistory`, an identity document, and a selfie |

Verification status is reported per tier: `onramp-light` / `offramp-light` for the progressive tier and `onramp` / `offramp` for the full tier. See [Onramp user onboarding](/onramp/introduction/user-onboarding) and [Offramp KYC & compliance](/offramp/concepts/kyc-and-compliance) for how and when each tier applies to each product, including regional differences.

<Note>Progressive (light) KYC is available for both the embedded (client-side) flow and the import-KYC-data (server-side) API flow. Availability can vary by region.</Note>

### Additional Document Requests

Independently of the tier, Crossmint's compliance team may request a specific document from a user at any time — a proof of address, a source of wealth document, or an identity document. Each is requested on its own, only for the users that need it, and surfaces through the verification status API as `requires-data` with the document listed in `missingDocuments`. Upload the document and re-trigger verification to resolve it — see [the quickstart](/identity/quickstart#additional-document-requests) for the full flow.

## Requirements for Non-US Residents

The following tables show what information is required for each activity type and tier for users residing outside the United States. To see the specific fields required for each object follow the [Create User API](/api-reference/users/upsert-user) documentation.

### Data Requirements

| Object | Payouts | On/offramp (progressive) | On/offramp (full) |
| - | :-: | :-: | :-: |
| userDetails | ✅ | ✅ | ✅ |
| kycData | | ✅ | ✅ |
| dueDiligence | | | ✅ |
| verificationHistory | | | ✅ |

### Document Requirements

No documents are required for progressive (light) KYC. Documents are only requested once a user reaches the Full KYC tier. Use the [Upload Document API](/api-reference/users/upload-document) to upload the necessary materials.

| Document Type | Payouts | On/offramp (progressive) | On/offramp (full) |
| - | :-: | :-: | :-: |
| Identity document | | | ✅ |
| Selfie | | | ✅ |

Proof of address (`proof-of-address`) and source of wealth (`source-of-wealth`) are never part of a standard tier — upload them only when Crossmint's compliance team requests them from a specific user (see [Additional Document Requests](#additional-document-requests)).

<Note>
  Under progressive (light) KYC an identity **number** may still be required inside `kycData.identityDocument` — an ID number for EU/EEA residents (optional for the rest of the world). This is a data field, not a document upload; passport, ID card, selfie, and other document uploads are only requested at the Full KYC tier.
</Note>

<Note>
  **Identity document types for non-US residents:**

  * For residents of countries outside of EU/EEA, only passport (`id-passport`) is accepted. Driving licenses or local ID cards are not accepted.
  * For residents of EU/EEA countries, passport (`id-passport`), ID cards (`id-idcard-front`, `id-idcard-back`), or residency permit (`id-residency-permit`, Spain residents only) are accepted.
</Note>

## Requirements for US Residents

There are no KYC tiers for US residents: the required data does not change with transaction volume. What is required depends on the user's state of residence.

### Data Requirements

| Object | Most states | NY, NC, TN, TX, VA |
| - | :-: | :-: |
| userDetails | ✅ | ✅ |
| kycData | ✅ | ✅ |
| dueDiligence | | ✅ |
| verificationHistory | ✅ | ✅ |

US-specific field rules:

* `kycData.phoneNumber` is **required** (it is optional for non-US residents)
* Identity is provided via SSN in the `kycData.identityDocument` field (type `"ssn"`)
* When the `dueDiligence` object is included, its `estimatedYearlyIncome` field is **required** (it is optional for non-US residents). In states that do not require due diligence, omit the `dueDiligence` object entirely.

### Document Requirements

No identity document upload or selfie is required for standard on/offramp — identity is verified through the SSN provided in `kycData`.

Crossmint's compliance team may still request documents from specific US users (see [Additional Document Requests](#additional-document-requests)). For US residents, an identity document request is satisfied with a passport (`id-passport`) or driver's license (`id-idcard-front`, `id-idcard-back`); a proof of address may also be requested. Source of wealth is generally not requested from US residents.

## Next Steps

<CardGroup>
  <Card title="Quickstart" icon="bolt" href="/identity/quickstart">
    Register your first user and upload documents in minutes.
  </Card>

  <Card title="Talk to an expert" icon="message" href="https://www.crossmint.com/contact/sales">
    Contact the Crossmint sales team for support.
  </Card>
</CardGroup>


# Failure Reasons
Source: https://docs.crossmint.com/identity/failure-reasons

Reference for the machine-readable codes returned on a rejected identity verification

A `rejected` eligibility entry from the [Get Identity Verification Status](/api-reference/users/get-identity-verification) endpoint may include a `failureReasons` array with more detail about why the verification failed:

```json theme={null}
{
    "type": "offramp",
    "status": "rejected",
    "failureReasons": [
        {
            "code": "id-document-expired",
            "message": "The ID document provided is expired. Please submit a currently valid ID."
        }
    ]
}
```

Each entry in the array is a `{code, message}` object. `code` is a machine-readable identifier your integration can branch on; `message` is returned as-is by the API and can be shown directly to your users.

<Note>
  Not every `rejected` entry includes `failureReasons`. Its absence usually means the rejection was risk-based and not retriable.
</Note>

## Reason Codes

The `message` column below is quoted verbatim from the API response, not paraphrased, since partners may display it as-is.

| Code | Message |
| :- | :- |
| `id-document-expired` | The ID document provided is expired. Please submit a currently valid ID. |
| `id-document-unsupported-type` | This type of ID document is not supported. Please submit a different government-issued ID (e.g. passport or national ID). |
| `id-document-country-mismatch` | The ID document's issuing country does not match the declared country. Please review the submitted information or provide an ID issued by the declared country. |
| `id-document-unreadable` | The document image could not be read. Please upload a clear, complete photo of the document (all corners visible, no glare). |
| `proof-of-address-outdated` | The proof of address provided is too old. Please submit one issued within the accepted period. |
| `proof-of-address-invalid` | The proof of address document could not be read or does not contain the required information. Please submit a valid, readable proof of address. |
| `source-of-wealth-outdated` | The source of wealth document provided is too old. Please submit one issued within the accepted period. |
| `source-of-wealth-invalid` | The source of wealth document could not be read or does not contain the required information. Please submit a valid, readable document. |
| `supporting-document-outdated` | The supporting document provided is too old. Please submit one issued within the accepted period. |
| `supporting-document-invalid` | The supporting document could not be read or does not contain the required information. Please submit a valid, readable document. |
| `selfie-failed` | The selfie could not be verified. Please retake it in good lighting, facing the camera directly, without face coverings. |
| `selfie-document-mismatch` | The selfie does not match the photo on the ID document. Please retake the selfie or provide the correct person's ID. |
| `address-verification-failed` | The address provided could not be verified. Please review it or provide a previous address. |
| `age-requirement-not-met` | The user does not meet the minimum age requirement. |
| `unsupported-geo` | This service is not available in the user's region. |

<Info>
  `code` is an open enum: new values may be added over time. Treat an unrecognized `code` as a generic failure, and display the returned `message` rather than your own copy.
</Info>


# Overview
Source: https://docs.crossmint.com/identity/overview

Register your customers' user data to enable their access to regulated Crossmint products

Crossmint requires certain user identity information from your customers to provide regulated products. The required data varies by product and can be collected through several supported methods.

Crossmint supports progressive onboarding, with lighter verification for eligible users up to \$1,000 in transaction volume.

<Note>
  **KYB or KYC — which do you need?**

  * **KYB** (Know Your Business) verifies **your company**. You complete it once, with the Crossmint team, before you get production access for the products that require it. See [Account Verification](/introduction/platform/account-verification).
  * **KYC** (Know Your Customer), covered on this page, verifies **your users**. You complete it per product, as shown below.
  * KYB and KYC are separate checks — passing one does not satisfy the other.
</Note>

## Products That Require Identity Data

| Product | KYC Required |
| - | - |
| [Onramps](/onramp/overview) / [Offramps](/offramp/overview) | Yes |
| [Payouts](/stablecoin-orchestration/regulated-transfers/overview) | • Regulated payouts: Minimal user data required (not full KYC).<br />• Self-custodial transfers: Not required.<br /><br />More information [here](/stablecoin-orchestration/regulated-transfers/overview). |
| [Wallets](/wallets/overview) | Not required. |

<Info>
  See the data requirements per product [here](/identity/data-requirements).
</Info>

## KYC Collection Methods

Crossmint supports three ways to collect the required identity data. Choose the method that best fits your compliance model and UX requirements:

| Method | Best For | How It Works |
| - | - | - |
| **Crossmint-hosted** | Fastest integration | Users complete KYC on Crossmint's screens, shown inside the embedded checkout or [in your own view](/onramp/guides/decouple-identity-verification). The screens follow your checkout `appearance` in both cases; see [UI Customization](/identity/ui-customization) |
| **API data imports** | Already verifying users with your own identity provider | Pass verified user data to Crossmint via API. Crossmint will use the information you have already collected to perform the required compliance checks |
| **Token-sharing (coming soon)** | Reusing a verified user token | Share a verified user token from a supported IDV provider |

## Getting Started

<CardGroup>
  <Card title="Quickstart" icon="bolt" href="/identity/quickstart">
    Register your first user
  </Card>

  <Card title="Data Requirements" icon="table" href="/identity/data-requirements">
    See required data by product
  </Card>

  <Card title="UI Customization" icon="palette" href="/identity/ui-customization">
    Style the Crossmint-hosted KYC screens
  </Card>
</CardGroup>

## FAQs

<AccordionGroup>
  <Accordion title="Which identity verification vendors are available?">
    Crossmint supports Persona and Sumsub as identity verification (IDV) vendors. To use any other vendor, you must get it approved first—raise it with your Customer Success Engineer (CSE).
  </Accordion>

  <Accordion title="Does Crossmint support token sharing?">
    Token sharing is not yet supported. If this is something you need, reach out to your Customer Success Engineer (CSE).
  </Accordion>

  <Accordion title="Can I combine Crossmint KYC with my own KYC (hybrid approach)?">
    A hybrid approach is not yet supported. You either run your own identity verification and pass that data to Crossmint, or use Crossmint's embedded KYC in the checkout.
  </Accordion>

  <Accordion title="Can I register a business as a user, rather than an individual?">
    Not yet. The [Create or Update User](/api-reference/users/upsert-user) endpoint accepts identity data for individuals only (name, date of birth, nationality, identity document, and so on) — there is no business or entity user type. Support for business users is coming soon. If your users are companies, reach out to your Customer Success Engineer (CSE).
  </Accordion>
</AccordionGroup>


# Quickstart ⚡
Source: https://docs.crossmint.com/identity/quickstart

Register users and upload documents to enable regulated product access.

<CardGroup>
  <Snippet />
</CardGroup>

<Snippet />

This quickstart guide walks you through registering a user, uploading documents, and fetching document details using Crossmint's APIs. These steps enable your users to access regulated products like onramp, offramp, and payouts.

<Snippet />

User locators use the `userId:` format, a unique identifier you choose for the user, for example `userId:johnd-123`.

<Steps>
  <Step title="User accepts Crossmint's Privacy Policy">
    Before sharing any user KYC data with Crossmint, you must ensure your users have accepted Crossmint's <a href="https://www.crossmint.com/legal/privacy-policy">Privacy Policy</a>. This is a prerequisite for companies sharing their customer's KYC data with Crossmint.

    Consent must be collected in your app through a compliant flow (explicit checkbox, exact wording, visible Crossmint logo, re-consent on policy updates). See [Register User Data](/identity/register-user-data) for the full consent-collection requirements.

    <Warning>
      Meeting these requirements is mandatory for sharing user KYC data with Crossmint. Only record acceptance through the API below after the user has granted consent this way. Crossmint audits data-sharing integrations for compliance with these requirements.
    </Warning>

    Once the user has accepted the privacy policy, record their acceptance using the following API call:

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request PUT \
          --url 'https://staging.crossmint.com/api/2025-06-09/users/userId:johnd-123/legal-documents' \
          --header 'X-API-KEY: <your-server-api-key>' \
          --header 'Content-Type: application/json' \
          --data '{
              "type": "crossmint-privacy-policy",
              "acceptedAt": "2025-10-05T14:48:00Z"
          }'
      ```

      ```javascript Node.js theme={null}
      const userLocator = "userId:johnd-123";

      const options = {
          method: 'PUT',
          headers: {'X-API-KEY': '<your-server-api-key>', 'Content-Type': 'application/json'},
          body: JSON.stringify({
              type: "crossmint-privacy-policy",
              acceptedAt: "2025-10-05T14:48:00Z" // ISO 8601 date string
          })
      };

      fetch(`https://staging.crossmint.com/api/2025-06-09/users/${userLocator}/legal-documents`, options)
          .then(response => response.json())
          .then(response => console.log(response))
          .catch(err => console.error(err));
      ```

      ```python Python theme={null}
      import requests

      user_locator = "userId:johnd-123"

      url = f"https://staging.crossmint.com/api/2025-06-09/users/{user_locator}/legal-documents"

      payload = {
          "type": "crossmint-privacy-policy",
          "acceptedAt": "2025-10-05T14:48:00Z"  # ISO 8601 date string
      }
      headers = {
          "X-API-KEY": "<your-server-api-key>",
          "Content-Type": "application/json"
      }

      response = requests.put(url, json=payload, headers=headers)

      print(response.json())
      ```
    </CodeGroup>

    <Note>This call also creates a user with the specified `userLocator` if one does not already exist.</Note>
  </Step>

  <Step title="Register user information">
    Register a user with Crossmint by specifying their `userLocator`, their personal details, and KYC data using the [Create User](/api-reference/users/upsert-user) endpoint

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request PUT \
          --url 'https://staging.crossmint.com/api/2025-06-09/users/userId:johnd-123' \
          --header 'X-API-KEY: <your-server-api-key>' \
          --header 'Content-Type: application/json' \
          --data '{
              "userDetails": {
                  "firstName": "John",
                  "lastName": "Doe",
                  "dateOfBirth": "1995-01-01",
                  "countryOfResidence": "DE"
              }
          }'
      ```

      ```javascript Node.js theme={null}
      const userLocator = "userId:johnd-123"; 

      const options = {
          method: 'PUT',
          headers: {'X-API-KEY': '<your-server-api-key>', 'Content-Type': 'application/json'},
          body: JSON.stringify({
              userDetails: {
                  firstName: "John",
                  lastName: "Doe",
                  dateOfBirth: "1995-01-01",
                  countryOfResidence: "DE"
              }
          })
      };

      fetch(`https://staging.crossmint.com/api/2025-06-09/users/${userLocator}`, options)
          .then(response => response.json())
          .then(response => console.log(response))
          .catch(err => console.error(err));
      ```

      ```python Python theme={null}
      import requests

      user_locator = "userId:johnd-123"

      url = f"https://staging.crossmint.com/api/2025-06-09/users/{user_locator}"

      payload = {
          "userDetails": {
              "firstName": "John",
              "lastName": "Doe",
              "dateOfBirth": "1995-01-01",
              "countryOfResidence": "DE"
          }
      }
      headers = {
          "X-API-KEY": "<your-server-api-key>",
          "Content-Type": "application/json"
      }

      response = requests.put(url, json=payload, headers=headers)

      print(response.json())
      ```
    </CodeGroup>
  </Step>

  <Step title="Run identity verification">
    Once you have registered relevant user information you can trigger checks via the [Trigger Identity Verification](/api-reference/users/trigger-identity-verification) endpoint.

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request PUT \
          --url 'https://staging.crossmint.com/api/2025-06-09/users/userId:johnd-123/identity-verification' \
          --header 'X-API-KEY: <your-server-api-key>'
      ```

      ```javascript Node.js theme={null}
      const userLocator = "userId:johnd-123";

      const options = {
          method: 'PUT',
          headers: {
              'X-API-KEY': '<your-server-api-key>'
          }
      };

      fetch(`https://staging.crossmint.com/api/2025-06-09/users/${userLocator}/identity-verification`, options)
          .then(response => response.json())
          .then(response => console.log(response))
          .catch(err => console.error(err));
      ```

      ```python Python theme={null}
      import requests

      user_locator = "userId:johnd-123"

      url = f"https://staging.crossmint.com/api/2025-06-09/users/{user_locator}/identity-verification"

      headers = {
          "X-API-KEY": "<your-server-api-key>"
      }

      response = requests.put(url, headers=headers)

      print(response.json())
      ```
    </CodeGroup>

    The response will include the eligibility status for each verification type (`regulated-transfer`, `onramp`, `onramp-light`, `offramp`, `offramp-light`):

    * `not-started`: Verification has not been initiated
    * `pending-privacy-policy`: User has not yet accepted Crossmint's Privacy Policy
    * `requires-data`: Additional user data or documents are needed
    * `pending-review`: Verification is in progress
    * `pending-manual-review`: Verification requires manual review by Crossmint's compliance team
    * `verified`: User has passed verification
    * `rejected`: User has failed verification. May include a `failureReasons` array with a machine-readable cause; see [Failure Reasons](/identity/failure-reasons).

    Once a product reads `verified`, the user can use it. A `verified` `offramp` status, for example, means the user can cash out through [Offramp](/offramp/overview).

    If any of them return `requires-data`, you must aggregate the `missingData` and `missingDocuments` arrays from those specific eligibility objects. Then, update the user's information using the [Update User](/api-reference/users/upsert-user) endpoint and/or upload additional documents using the [Upload Document](/api-reference/users/upload-document) endpoint, and finally re-trigger the verification.

    ```json theme={null}
    {
        "eligibility": [
            {
                "type": "regulated-transfer",
                "status": "pending-review" // or "verified"
            },
            {
                "type": "onramp",
                "status": "requires-data",
                "missingData": ["kyc-data", "due-diligence", "verification-history"],
                "missingDocuments": ["id", "selfie-front"] // Crossmint may also request "proof-of-address" or "source-of-wealth" for specific users
            },
            {
                "type": "onramp-light",
                "status": "requires-data",
                "missingData": ["kyc-data"] // light KYC requires less data and no document uploads
            },
            {
                "type": "offramp",
                "status": "requires-data",
                "missingData": ["kyc-data", "due-diligence", "verification-history"],
                "missingDocuments": ["id", "selfie-front"] // Crossmint may also request "proof-of-address" or "source-of-wealth" for specific users
            },
            {
                "type": "offramp-light",
                "status": "requires-data",
                "missingData": ["kyc-data"] // light KYC requires less data and no document uploads
            }
        ]
    }
    ```
  </Step>

  <Step title="Update user information">
    Register additional user information with Crossmint so the user can access onramp and offramp services.

    <Note> Calling this endpoint again with the same `userLocator` will update the existing user's information. The endpoint is not additive so specify all relevant user information when updating the user.</Note>

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request PUT \
          --url 'https://staging.crossmint.com/api/2025-06-09/users/userId:johnd-123' \
          --header 'X-API-KEY: <your-server-api-key>' \
          --header 'Content-Type: application/json' \
          --data '{
              "userDetails": {
                  "firstName": "John",
                  "lastName": "Doe",
                  "dateOfBirth": "1995-01-01",
                  "countryOfResidence": "DE"
              },
              "kycData": {
                  "nationality": "DE",
                  "addressOfResidence": {
                      "line1": "123 Hauptstrasse",
                      "line2": "Apt 5",
                      "city": "Berlin",
                      "stateOrRegion": "Berlin",
                      "postalCode": "10115"
                  },
                  "email": "johnd@example.com",
                  "identityDocument": {
                      "type": "passport",
                      "number": "AS12321",
                      "issuingCountryCode": "DE"
                  },
                  "ipAddresses": ["203.0.113.1"]
              },
              "dueDiligence": {
                  "employmentStatus": "full-time",
                  "sourceOfFunds": "salary-disbursement",
                  "industry": "financial-institution",
                  "expectedYearlyTxVolume": "volume-0-25k"
              },
              "verificationHistory": {
                  "idVerificationTimestamp": "2024-01-15T10:30:00Z",
                  "livenessVerificationTimestamp": "2024-01-15T10:32:00Z"
              }
          }'
      ```

      ```javascript Node.js theme={null}
      const userLocator = "userId:johnd-123"; 

      const options = {
          method: 'PUT',
          headers: {'X-API-KEY': '<your-server-api-key>', 'Content-Type': 'application/json'},
          body: JSON.stringify({
              userDetails: {
                  firstName: "John",
                  lastName: "Doe",
                  dateOfBirth: "1995-01-01",
                  countryOfResidence: "DE"
              },
              kycData: {
                  nationality: "DE",
                  addressOfResidence: {
                      line1: "123 Hauptstrasse",
                      line2: "Apt 5",
                      city: "Berlin",
                      stateOrRegion: "Berlin",
                      postalCode: "10115"
                  },
                  email: "johnd@example.com",
                  identityDocument: {
                      type: "passport",
                      number: "AS12321",
                      issuingCountryCode: "DE"
                  },
                  ipAddresses: ["203.0.113.1"]
              },
              dueDiligence: {
                  employmentStatus: "full-time",
                  sourceOfFunds: "salary-disbursement",
                  industry: "financial-institution",
                  expectedYearlyTxVolume: "volume-0-25k"
              },
              verificationHistory: {
                  idVerificationTimestamp: "2024-01-15T10:30:00Z",
                  livenessVerificationTimestamp: "2024-01-15T10:32:00Z"
              }
          })
      };

      fetch(`https://staging.crossmint.com/api/2025-06-09/users/${userLocator}`, options)
          .then(response => response.json())
          .then(response => console.log(response))
          .catch(err => console.error(err));
      ```

      ```python Python theme={null}
      import requests

      user_locator = "userId:johnd-123"

      url = f"https://staging.crossmint.com/api/2025-06-09/users/{user_locator}"

      payload = {
          "userDetails": {
              "firstName": "John",
              "lastName": "Doe",
              "dateOfBirth": "1995-01-01",
              "countryOfResidence": "DE"
          },
          "kycData": {
              "nationality": "DE",
              "addressOfResidence": {
                  "line1": "123 Hauptstrasse",
                  "line2": "Apt 5",
                  "city": "Berlin",
                  "stateOrRegion": "Berlin",
                  "postalCode": "10115"
              },
              "email": "johnd@example.com",
              "identityDocument": {
                  "type": "passport",
                  "number": "AS12321",
                  "issuingCountryCode": "DE"
              },
              "ipAddresses": ["203.0.113.1"]
          },
          "dueDiligence": {
              "employmentStatus": "full-time",
              "sourceOfFunds": "salary-disbursement",
              "industry": "financial-institution",
              "expectedYearlyTxVolume": "volume-0-25k"
          },
          "verificationHistory": {
              "idVerificationTimestamp": "2024-01-15T10:30:00Z",
              "livenessVerificationTimestamp": "2024-01-15T10:32:00Z"
          }
      }
      headers = {
          "X-API-KEY": "<your-server-api-key>",
          "Content-Type": "application/json"
      }

      response = requests.put(url, json=payload, headers=headers)

      print(response.json())
      ```
    </CodeGroup>
  </Step>

  <Step title="Upload a document">
    Upload identity or supporting documents for the user using the [Upload Document](/api-reference/users/upload-document) endpoint. Documents are associated with the user via their `userLocator`.

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request POST \
          --url 'https://staging.crossmint.com/api/2025-06-09/documents' \
          --header 'X-API-KEY: <your-server-api-key>' \
          --header 'Content-Type: application/json' \
          --data '{
              "reference": {
                  "userLocator": "userId:johnd-123"
              },
              "documentType": "id-passport",
              "data": "<base64-encoded-image>",
              "expiresAt": "2030-12-31"
          }'
      ```

      ```javascript Node.js theme={null}
      const options = {
          method: 'POST',
          headers: {'X-API-KEY': '<your-server-api-key>', 'Content-Type': 'application/json'},
          body: JSON.stringify({
              reference: {
                  userLocator: "userId:johnd-123"
              },
              documentType: "id-passport",
              data: "<base64-encoded-image>",
              expiresAt: "2030-12-31"
          })
      };

      fetch('https://staging.crossmint.com/api/2025-06-09/documents', options)
          .then(response => response.json())
          .then(response => console.log(response))
          .catch(err => console.error(err));
      ```

      ```python Python theme={null}
      import requests

      url = "https://staging.crossmint.com/api/2025-06-09/documents"

      payload = {
          "reference": {
              "userLocator": "userId:johnd-123"
          },
          "documentType": "id-passport",
          "data": "<base64-encoded-image>",
          "expiresAt": "2030-12-31"
      }
      headers = {
          "X-API-KEY": "<your-server-api-key>",
          "Content-Type": "application/json"
      }

      response = requests.post(url, json=payload, headers=headers)

      print(response.json())
      ```
    </CodeGroup>

    **Supported document types:**

    * Identity documents: `id-passport`, `id-idcard-front`, `id-idcard-back`, `id-residency-permit` (Spain residents only)
    * Supporting documents: `proof-of-address`, `source-of-wealth`
    * Selfie documents: `selfie-front`, `selfie-left`, `selfie-right`

    <Note>US residents must include `kycData.phoneNumber`, and provide their identity via SSN in `kycData.identityDocument`. No identity document upload or selfie is needed for standard on/offramp. If Crossmint's compliance team requests an identity document from a US user, upload a passport (`id-passport`) or driver's license (`id-idcard-front`, `id-idcard-back`). Source of wealth is generally not requested from US users.</Note>

    <Note>Uploading again with the same `userLocator` and `documentType` replaces the previous upload — the most recent document is the one used for verification.</Note>
  </Step>

  <Step title="Run identity verification">
    Once you have registered the user's information and uploaded the required documents, trigger the KYC verification process using the [Trigger Identity Verification](/api-reference/users/trigger-identity-verification) endpoint.

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request PUT \
          --url 'https://staging.crossmint.com/api/2025-06-09/users/userId:johnd-123/identity-verification' \
          --header 'X-API-KEY: <your-server-api-key>'
      ```

      ```javascript Node.js theme={null}
      const userLocator = "userId:johnd-123";

      const options = {
          method: 'PUT',
          headers: {
              'X-API-KEY': '<your-server-api-key>'
          }
      };

      fetch(`https://staging.crossmint.com/api/2025-06-09/users/${userLocator}/identity-verification`, options)
          .then(response => response.json())
          .then(response => console.log(response))
          .catch(err => console.error(err));
      ```

      ```python Python theme={null}
      import requests

      user_locator = "userId:johnd-123"

      url = f"https://staging.crossmint.com/api/2025-06-09/users/{user_locator}/identity-verification"

      headers = {
          "X-API-KEY": "<your-server-api-key>"
      }

      response = requests.put(url, headers=headers)

      print(response.json())
      ```
    </CodeGroup>

    The response will include the eligibility status for each verification type (`regulated-transfer`, `onramp`, `onramp-light`, `offramp`, `offramp-light`):

    ```json theme={null}
    {
        "eligibility": [
            {
                "type": "regulated-transfer",
                "status": "verified"
            },
            {
                "type": "onramp",
                "status": "pending-review"
            },
            {
                "type": "onramp-light",
                "status": "pending-review"
            },
            {
                "type": "offramp",
                "status": "pending-review"
            },
            {
                "type": "offramp-light",
                "status": "pending-review"
            }
        ]
    }
    ```
  </Step>

  <Step title="Check verification status">
    Verification runs asynchronously. After triggering it, poll the [Get Identity Verification Status](/api-reference/users/get-identity-verification) endpoint until the relevant product status reads `verified`. It usually completes within a minute, and the transient state may be `not-started` or `pending-review`.

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request GET \
          --url 'https://staging.crossmint.com/api/2025-06-09/users/userId:johnd-123/identity-verification' \
          --header 'X-API-KEY: <your-server-api-key>'
      ```

      ```javascript Node.js theme={null}
      const userLocator = "userId:johnd-123";

      const options = {
          method: 'GET',
          headers: {
              'X-API-KEY': '<your-server-api-key>'
          }
      };

      fetch(`https://staging.crossmint.com/api/2025-06-09/users/${userLocator}/identity-verification`, options)
          .then(response => response.json())
          .then(response => console.log(response))
          .catch(err => console.error(err));
      ```

      ```python Python theme={null}
      import requests

      user_locator = "userId:johnd-123"

      url = f"https://staging.crossmint.com/api/2025-06-09/users/{user_locator}/identity-verification"

      headers = {
          "X-API-KEY": "<your-server-api-key>"
      }

      response = requests.get(url, headers=headers)

      print(response.json())
      ```
    </CodeGroup>
  </Step>

  <Step title="Fetch user information">
    You can fetch a user's information at any time to see their current status, including when they last accepted valid legal documents. Use the Get User endpoint to retrieve this information:

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request GET \
          --url 'https://staging.crossmint.com/api/2025-06-09/users/userId:johnd-123' \
          --header 'X-API-KEY: <your-server-api-key>'
      ```

      ```javascript Node.js theme={null}
      const userLocator = "userId:johnd-123";

      const options = {
          method: 'GET',
          headers: {
              'X-API-KEY': '<your-server-api-key>'
          }
      };

      fetch(`https://staging.crossmint.com/api/2025-06-09/users/${userLocator}`, options)
          .then(response => response.json())
          .then(response => console.log(response))
          .catch(err => console.error(err));
      ```

      ```python Python theme={null}
      import requests

      user_locator = "userId:johnd-123"

      url = f"https://staging.crossmint.com/api/2025-06-09/users/{user_locator}"

      headers = {
          "X-API-KEY": "<your-server-api-key>"
      }

      response = requests.get(url, headers=headers)

      print(response.json())
      ```
    </CodeGroup>

    The response includes the `legalDocuments` array, which shows the status of legal document acceptances:

    ```json theme={null}
    {
        "email": "john.doe@example.com",
        "phoneNumber": "+1234567890",
        "userId": "usr_1234567890",
        "userDetails": true,
        "kycData": false,
        "dueDiligence": false,
        "verificationHistory": false,
        "legalDocuments": [
            {
                "type": "crossmint-privacy-policy",
                "acceptedAt": "2024-01-15T10:30:00Z",
                "validVersion": true
            }
        ]
    }
    ```

    The `validVersion` field indicates whether the user has accepted the current version of the legal document. If `validVersion` is `false`, you should prompt the user to accept the updated terms.
  </Step>
</Steps>

## Additional Document Requests

Crossmint's compliance team may request a specific additional document from a user at any time, even after verification — a proof of address, a source of wealth document, or an identity document. Each is requested independently, only for the users that need it.

When a document is requested:

1. The verification status for the affected products reads `requires-data`, with the document listed in `missingDocuments` (e.g. `["proof-of-address"]`).
2. Upload the document via the [Upload Document](/api-reference/users/upload-document) endpoint (`documentType: "proof-of-address"`, `"source-of-wealth"`, or an identity document type).
3. Re-trigger verification via the [Trigger Identity Verification](/api-reference/users/trigger-identity-verification) endpoint — the same call as after any other data update. The status moves to `pending-review` while the document is reviewed.
4. Poll the [Get Identity Verification Status](/api-reference/users/get-identity-verification) endpoint. If the document is accepted, the status moves on to whatever else is required for that product. If it is not accepted, the status becomes `rejected` — for document requests this is retryable: upload a fresh document and re-trigger verification to start a new review.

If a document of the requested type is already on file, nothing is listed as missing and the status reads `not-started` until you re-trigger verification.

## Handling a `rejected` status

A `rejected` entry may include a `failureReasons` array with more detail about why the verification failed, when available. See [Failure Reasons](/identity/failure-reasons) for the full list of codes and how to handle each one.

## Launching in Production

For production, the steps are almost identical, but some changes are required:

1. Create a developer account on the <a href="https://www.crossmint.com/console">production console</a>
2. Create a production server API key on the <a href="https://www.crossmint.com/console/projects/apiKeys">API Keys</a> page with the API scopes `users.create`, `users.read`
3. Replace your test API key with the production key
4. Replace `staging.crossmint.com` with `www.crossmint.com` in the API URLs

## Learn More

<CardGroup>
  <Card title="Data Requirements" icon="table" href="/identity/data-requirements">
    See what data is required for each activity and region.
  </Card>

  <Card title="Talk to an expert" icon="message" href="https://www.crossmint.com/contact/sales">
    Contact the Crossmint sales team for support.
  </Card>
</CardGroup>


# Register User Data
Source: https://docs.crossmint.com/identity/register-user-data

Provide personal information about recipients in order to comply with regulation

Register the transfer recipient as a user in your Crossmint project, then attach the recipient data required for payouts.
Crossmint uses this data to screen recipients against Office of Foreign Assets Control (OFAC) sanctions lists.

## Requirements

* An API key
* A stable user identifier in your system (used as `userLocator`)
* A Crossmint wallet address for the recipient (or the ability to create one)

## Step 1: Accept Crossmint's Privacy Policy

Before sharing any user KYC data with Crossmint, you must ensure your users have accepted Crossmint's <a href="https://www.crossmint.com/legal/privacy-policy">Privacy Policy</a>. This is a prerequisite for any company sharing their customers' KYC data with Crossmint.

**Requirements for collecting consent**

Consent must be obtained following the guidelines below:

1. The user must have the ability to see the terms they must accept
2. The user must grant consent with a checkbox, unchecked by default
3. The user does not need to open the hyperlink to the privacy policy to view the terms
4. The user needs to see Crossmint's logo in the flow
5. The specific text that you must present to your end user is: **"I consent to my KYC data being processed by Crossmint in accordance with its <a href="https://www.crossmint.com/legal/privacy-policy">Privacy Policy</a>"**
6. The text can be localized but must link to the same privacy policy link provided above
7. If the privacy policy is updated, you must ask the user to agree to the above terms again

<Warning>
  Meeting these requirements is mandatory for sharing user KYC data with Crossmint. Only record acceptance through the API below after the user has granted consent this way. Crossmint audits data-sharing integrations for compliance with these requirements.
</Warning>

Once the user has accepted the privacy policy, record their acceptance using the [Accept Legal Document](/api-reference/users/accept-legal-document) endpoint:

<CodeGroup>
  ```bash cURL theme={null}
  curl --request PUT \
      --url 'https://staging.crossmint.com/api/2025-06-09/users/userId:johnd-123/legal-documents' \
      --header 'X-API-KEY: <your-server-api-key>' \
      --header 'Content-Type: application/json' \
      --data '{
          "type": "crossmint-privacy-policy",
          "acceptedAt": "2025-10-05T14:48:00Z"
      }'
  ```

  ```javascript Node.js theme={null}
  const userLocator = "userId:johnd-123";

  const options = {
      method: 'PUT',
      headers: {'X-API-KEY': '<your-server-api-key>', 'Content-Type': 'application/json'},
      body: JSON.stringify({
          type: "crossmint-privacy-policy",
          acceptedAt: "2025-10-05T14:48:00Z" // ISO 8601 date string
      })
  };

  fetch(`https://staging.crossmint.com/api/2025-06-09/users/${userLocator}/legal-documents`, options)
      .then(response => response.json())
      .then(response => console.log(response))
      .catch(err => console.error(err));
  ```

  ```python Python theme={null}
  import requests

  user_locator = "userId:johnd-123"

  url = f"https://staging.crossmint.com/api/2025-06-09/users/{user_locator}/legal-documents"

  payload = {
      "type": "crossmint-privacy-policy",
      "acceptedAt": "2025-10-05T14:48:00Z"  # ISO 8601 date string
  }
  headers = {
      "X-API-KEY": "<your-server-api-key>",
      "Content-Type": "application/json"
  }

  response = requests.put(url, json=payload, headers=headers)

  print(response.json())
  ```
</CodeGroup>

<Note>This call also creates a user with the specified `userLocator` if one does not already exist.</Note>

## Step 2: Create a User

Register the transfer recipient as a user in your Crossmint project and associate the user with a Crossmint wallet address.

There are two ways to create a user:

### Choose a Method

* Use Method 1 if you create the wallet and user in one API call
* Use Method 2 if you register the user first and create the wallet later

<AccordionGroup>
  <Accordion title="Method 1: On Wallet Creation" icon="wallet">
    Create a wallet for a user and associate it to a `userLocator` by setting the `owner` property. This method creates in a
    single API call both the wallet, and the user associated with it.

    The `owner` property accepts a `userLocator`. This associates the wallet with the user identifier in your system.

    <Snippet />

    <Tabs>
      <Tab title="REST">
        ```javascript theme={null}
        const userLocator = "userId:johnd-123";

        const options = {
            method: 'POST',
            headers: {'X-API-KEY': '<x-api-key>', 'Content-Type': 'application/json'},
            body: JSON.stringify({
                chainType: "evm",
                config: {
                    recoveryMethods: [
                        {
                            type: "email",
                            email: "johnd@example.com"
                        }
                    ]
                },
                owner: userLocator
            })
        };

        fetch('https://staging.crossmint.com/api/2025-06-09/wallets', options)
            .then(response => response.json())
            .then(response => console.log(response))
            .catch(err => console.error(err));
        ```
      </Tab>

      <Tab title="React">
        ```javascript theme={null}
        import { useWallet } from '@crossmint/client-sdk-react-ui';

        const { getOrCreateWallet } = useWallet();

        // The "owner" property is inferred by the JWT token, no need to specify it
        const wallet = await getOrCreateWallet({
            chain: "evm",
            signer: {
                type: "email",
                email: "johnd@example.com"
            }
        });
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Method 2: Register User First, Create Wallet Later" icon="user-plus">
    Register a user with Crossmint without creating a wallet yet. Later, when you create a wallet for that registered user,
    you can link the wallet's `owner` property to that user's registered `userLocator` value. This will associate the wallet with the user identifier in your system.

    <Snippet />

    **Step 1: Register the user**

    ```javascript theme={null}
    const userLocator = "userId:johnd-123";

    const options = {
        method: 'PUT',
        headers: {'X-API-KEY': '<x-api-key>', 'Content-Type': 'application/json'}
    };

    fetch(`https://staging.crossmint.com/api/2025-06-09/users/${userLocator}`, options)
        .then(response => response.json())
        .then(response => console.log(response))
        .catch(err => console.error(err));
    ```

    **Step 2: Create wallet and link to registered user**

    When you are ready to create a wallet for the registered user, use the same `userLocator` in the `owner` field:

    <Tabs>
      <Tab title="REST">
        ```javascript theme={null}
        const userLocator = "userId:johnd-123";

        const options = {
            method: 'POST',
            headers: {'X-API-KEY': '<x-api-key>', 'Content-Type': 'application/json'},
            body: JSON.stringify({
                chainType: "evm",
                config: {
                    recoveryMethods: [
                        {
                            type: "email",
                            email: "johnd@example.com"
                        }
                    ]
                },
                owner: userLocator
            })
        };

        fetch('https://staging.crossmint.com/api/2025-06-09/wallets', options)
            .then(response => response.json())
            .then(response => console.log(response))
            .catch(err => console.error(err));
        ```
      </Tab>

      <Tab title="React">
        ```javascript theme={null}
        import { useWallet } from '@crossmint/client-sdk-react-ui';

        const { getOrCreateWallet } = useWallet(); 

        // The "owner" property is inferred by the JWT token, no need to specify it
        const wallet = await getOrCreateWallet({
            chain: "evm",
            signer: {
                type: "email",
                email: "johnd@example.com"
            }
        });
        ```
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>

## Step 3: Register User Data

Use the [Create User API](/api-reference/users/upsert-user) to attach `userDetails` to the user.
To see data requirements by activity and region, see [Data Requirements](/identity/data-requirements).
For payouts, the only information needed is `userDetails`.

<CodeGroup>
  ```javascript REST theme={null}

  const userLocator = "userId:johnd-123";

  const options = {
     method: 'PUT',
     headers: {'X-API-KEY': '<x-api-key>', 'Content-Type': 'application/json'},
     body: JSON.stringify({
         userDetails: {
             firstName: "John",
             lastName: "Doe",
             dateOfBirth: "2007-01-01",
             countryOfResidence: "DE"
         }
     })
  };

  fetch(`https://staging.crossmint.com/api/2025-06-09/users/${userLocator}/`, options)
     .then(response => response.json())
     .then(response => console.log(response))
     .catch(err => console.error(err));
  ```
</CodeGroup>

## Guides

<CardGroup>
  <Card title="Data Requirements" icon="list-check" href="/identity/data-requirements" />

  <Card title="Quickstart" icon="bolt" href="/identity/quickstart" />
</CardGroup>


# UI Customization
Source: https://docs.crossmint.com/identity/ui-customization

Style the identity verification screens that Crossmint shows inside your app with the appearance settings you already use for checkout

When a user needs to verify their identity, Crossmint shows a set of KYC screens inside your app: a consent screen, personal details, address, and, for full verification, an ID document and selfie step. This guide covers which `appearance` settings apply to those screens, what each one changes, the default values, and how to place the screens on your page.

<Frame type="simple">
  <img alt="The same identity verification screen with the default light look on the left and the default dark look on the right" />
</Frame>

## Prerequisites

* **An integration that shows the KYC screens**: the [embedded checkout](/onramp/quickstarts/react) for onramp or offramp, or the [standalone verification component](/onramp/guides/decouple-identity-verification).

## Before You Start

* The KYC screens read the same `appearance` object that you pass to the embedded checkout. If checkout already uses your brand, the KYC screens use it too, and there is nothing else to configure.
* Every setting is optional. A setting that you do not set uses the Crossmint default.
* If one value is not valid (for example, a color with a typo), the screens ignore all of your settings and show the default look. No error message shows, so test after each change.
* The ID document and selfie step (full verification only) has one light look and one dark look. Your colors and fonts do not apply to it. See [Light and Dark Mode](#light-and-dark-mode).

## Apply Your Theme

Pass the `appearance` prop to the embedded checkout as described in the [embedded checkout UI customization guide](/payments/embedded/guides/ui-customization). The KYC screens pick it up automatically when the order requires verification.

```tsx theme={null}
import { CrossmintEmbeddedCheckout } from "@crossmint/client-sdk-react-ui";

// Order created on your server with POST /api/2022-06-09/orders
const order = { orderId: "YOUR_ORDER_ID", clientSecret: "YOUR_ORDER_CLIENT_SECRET" };

<CrossmintEmbeddedCheckout
    orderId={order.orderId}
    clientSecret={order.clientSecret}
    appearance={{
        fonts: [{ cssSrc: "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap" }],
        variables: {
            fontFamily: "Inter, system-ui, sans-serif",
            borderRadius: "12px",
            colors: {
                backgroundPrimary: "#FFFFFF",
                textPrimary: "#00150D",
                textSecondary: "#67797F",
                borderPrimary: "#D1D5DB",
                accent: "#0074D9",
                danger: "#DC2626",
            },
        },
        rules: {
            PrimaryButton: {
                colors: { background: "#0074D9", text: "#FFFFFF" },
                hover: { colors: { background: "#0063B8" } },
                disabled: { colors: { background: "#E7E9ED", text: "#67797F" } },
            },
        },
    }}
/>;
```

If you [render the KYC step in your own view](/onramp/guides/decouple-identity-verification), pass the same object to the `appearance` prop of `CrossmintIdentityVerification` (`@crossmint/client-sdk-react-ui` 4.10.0 or later). Earlier versions show the default look.

## Appearance Settings and Where They Apply

Each setting controls one part of the KYC screens. The numbers in the table match the labels on the example screen. Color settings live under `appearance.variables.colors`, and component rules under `appearance.rules`.

<Frame type="simple">
  <img alt="An identity verification screen with numbered labels pointing at the background, title, subtitle, icon, field border, error, button, and selected field" />
</Frame>

| # | Element | What it changes | Setting |
| :- | :- | :- | :- |
| 1 | Background | The background of all screens | `colors.backgroundPrimary` |
| 2 | Main text | Titles, field labels, and the text that the user types | `colors.textPrimary` |
| 3 | Secondary text | Subtitles, hints, and consent text | `colors.textSecondary` |
| 4 | Accent | Icons, links, the border of the selected field, and selected options. It does not change the button | `colors.accent` |
| 5 | Borders | Field borders | `colors.borderPrimary` |
| 6 | Errors | Error messages and the border of a field with an error | `colors.danger` |
| 7 | Main button | Background, text, hover, and disabled colors. Set your button color here | `rules.PrimaryButton` |
| 8 | Fields (optional) | Background, border, shadow, and placeholder of the fields. Without it, fields use the colors above | `rules.Input` |
| | Field labels (optional) | Font and color of the field labels. Without it, labels use `textPrimary` | `rules.Label` |

The checkout settings `variables.colors.warning`, `rules.Tab`, `rules.DestinationInput`, and `rules.ReceiptEmailInput` have no effect on the KYC screens.

## Default Colors

The screens use these colors when you do not set a value. Change only the colors that differ from your brand.

<Tabs>
  <Tab title="Light mode">
    | Element | Setting | Default |
    | :- | :- | :- |
    | Background | `backgroundPrimary` | `#FFFFFF` |
    | Main text | `textPrimary` | `#00150D` |
    | Secondary text | `textSecondary` | `#67797F` |
    | Accent | `accent` | `#04AA6D` |
    | Borders | `borderPrimary` | `#D1D5DB` |
    | Error | `danger` | `#DC2626` |
    | Button | `PrimaryButton.colors.background` | `#05B959` |
    | Button text | `PrimaryButton.colors.text` | `#FFFFFF` |
    | Button hover | `PrimaryButton.hover.colors.background` | `#0BAF5C` |
    | Disabled button | `PrimaryButton.disabled.colors.background` | `#E7E9ED` |
    | Disabled button text | `PrimaryButton.disabled.colors.text` | `#67797F` |
    | Icon tile fill | Calculated, not a setting | `#EDEFEE` |
  </Tab>

  <Tab title="Dark mode">
    | Element | Setting | Default |
    | :- | :- | :- |
    | Background | `backgroundPrimary` | `#1E2023` |
    | Main text | `textPrimary` | `#FFFFFF` |
    | Secondary text | `textSecondary` | `#939596` |
    | Accent | `accent` | `#04AA6D` |
    | Borders | `borderPrimary` | `#3E4043` |
    | Error | `danger` | `#DC2626` |
    | Button | `PrimaryButton.colors.background` | `#05B959` |
    | Button text | `PrimaryButton.colors.text` | `#FFFFFF` |
    | Button hover | `PrimaryButton.hover.colors.background` | `#0BAF5C` |
    | Disabled button | `PrimaryButton.disabled.colors.background` | `#282C2F` |
    | Disabled button text | `PrimaryButton.disabled.colors.text` | `#939596` |
    | Icon tile fill | Calculated, not a setting | `#2E3032` |
  </Tab>
</Tabs>

Both modes use the Inter font, 12px corners, and 16px field text. Fields use `backgroundPrimary` unless `rules.Input.colors.background` sets another color. The fill behind the icon on the first screen is 7% of `textPrimary` mixed into `backgroundPrimary`.

## Light and Dark Mode

There is no `theme` setting. The screens pick the light or dark defaults from `variables.colors.backgroundPrimary`:

* An opaque dark color (for example `#1E2023`) selects the dark defaults.
* A light color, a transparent or semi-transparent color, or no value selects the light defaults.

The colors that you set replace only those values. If your app has a light mode and a dark mode, send the `appearance` that matches the mode the user sees.

The ID document and selfie step reads the same `backgroundPrimary` to pick its light or dark look, so it matches the other screens. It does not apply your other colors or fonts.

<Tip>
  To get the dark look without picking every color yourself, set `backgroundPrimary` to a dark color and leave the rest unset.
</Tip>

## Fonts, Sizes, and Corners

| Setting | What it changes | Default |
| :- | :- | :- |
| `variables.fontFamily`, `fonts` | The typeface. Fonts load from Google Fonts only; a font served from your own domain does not load | Inter |
| `variables.borderRadius` | Corners of fields and the button | `12px` |
| `variables.fontSizeUnit` | Text size in fields and the button. The screens keep it between `4px` and `5px`: smaller field text makes iPhones zoom in on focus | `4px` (16px field text) |
| `variables.spacingUnit` | Space inside fields. The screens keep it between `2.5px` and `5px` | `3.33px` |

## Good Practices

Users type their name, date of birth, address, and ID number on these screens, often on a phone. These rules keep the screens easy to read.

<Frame type="simple">
  <img alt="Six cards showing good and bad examples of contrast, accent shade, button states, body fonts, error color, and background" />
</Frame>

* **Check contrast against the background.** Text colors need a contrast of at least 4.5:1 against `backgroundPrimary`. Accent and borders need at least 3:1.
* **Use a darker accent for a pale brand color.** Use the pale color on the button, with dark text. For `accent`, use a darker shade so links and field borders stay visible.
* **Set all button states.** Set background, text, hover, and disabled. The button stays disabled until the user fills the fields, so users see that state often.
* **Use a font made for body text.** The font shows at 16px in fields and smaller in hints. Thin or decorative fonts are hard to read at that size. Load the regular, medium, and semibold weights.
* **Keep the error color red.** Users must see a field with an error immediately. Do not use your brand color for `danger`.
* **Use one plain background color.** `backgroundPrimary` takes one color. Gradients and images are not possible. Put brand images on your page, outside the KYC screens.

## Place the Screens on Your Page

The KYC screens show inside an iframe on your page. The iframe shows one screen at a time. Its height changes from screen to screen, and each screen has its Continue button at the bottom.

<Frame type="simple">
  <img alt="A correct layout with a 24px safe area around the KYC iframe next to a wrong layout where fields touch the edges, a fixed height cuts off the button, and a cookie banner covers it" />
</Frame>

* **Safe area.** Leave 24px of space on all four sides of the iframe. The screens do not include it; your page must add it.
* **Height.** Let the iframe grow with the screen inside it. Do not set a fixed height, or the Continue button gets cut off.
* **Overlays.** Nothing should cover the Continue button, such as a cookie banner or a bottom bar.
* **Background.** Give your page the same background color as `backgroundPrimary`, or the edge of the iframe shows.
* **Width.** On phones, keep the 24px safe area on each side inside the screen width and let the iframe fill the remaining space. On desktop, use the same width as your checkout.
* **Camera.** The ID document and selfie step uses the camera. The Crossmint SDK allows it on the iframe. If you render the iframe without the SDK, allow the camera on it with `allow="camera"`.
* **Narrow phones.** Test on a screen 360px wide. Many Android phones have this width.

## What You Cannot Change

| Item | How it works today |
| :- | :- |
| Icon on the first screen | Crossmint icon, in the `accent` color |
| Text on the screens | Not editable. The language follows the user's browser, or the `locale` that you set |
| Order and layout of screens | The screens change with the user's country and the amount |
| ID document and selfie step | Light or dark only. For additional customizations, ask your Crossmint contact |
| Icon tile fill | Calculated from your text and background colors |

## Test Your Theme

Run these checks in staging before you go live.

* Your checkout settings show on the KYC screens.
* Light mode and dark mode, if your app has both.
* A full verification with a higher amount: the ID document and selfie step shows in the correct mode.
* An empty field and an incorrect value: the error color shows.
* The hover and disabled states of the button.
* A phone 360px wide and a desktop: the button is fully visible and the page does not scroll sideways.

## Next Steps

<CardGroup>
  <Card title="Embedded Checkout UI Customization" icon="palette" href="/payments/embedded/guides/ui-customization">
    Full list of appearance settings, with code
  </Card>

  <Card title="Embed the KYC Step in Your App" icon="id-card" href="/onramp/guides/decouple-identity-verification">
    Render the verification step in your own view
  </Card>
</CardGroup>


# Using AI Assistants
Source: https://docs.crossmint.com/introduction/ai-assistants



Integrate faster with Crossmint by ingesting the docs into your AI-based code helpers (like Cursor, GitHub Copilot, etc.).

<Card title="Markdown docs" icon="book" href="https://docs.crossmint.com/llms-full.txt">
  AI assistant ready docs
</Card>

## Integrate with Cursor

1. Navigate to Cursor Settings > Features > Docs

2. Select "Add new doc" and paste the following URL:

```text theme={null}
https://docs.crossmint.com/llms-full.txt
```

3. Use `@docs -> Crossmint` to reference Crossmint's docs in your code.

***

> To find navigation and other pages in this documentation, fetch the llms.txt file at: [https://docs.crossmint.com/llms.txt](https://docs.crossmint.com/llms.txt)

## Crossmint Docs MCP Server

<Note>
  The Crossmint Docs MCP server searches the documentation. To let an AI assistant manage your console projects,
  organizations, and API keys, use the [Crossmint MCP server](/mcp-server/connect).
</Note>

The Crossmint Docs MCP server lets your AI assistant search and read the Crossmint docs when it needs them. It returns only the sections that match the query, not the full docs.

* **URL:** `https://docs.crossmint.com/mcp`
* **Transport:** Streamable HTTP
* **Authentication:** none

### Installation

<Tabs>
  <Tab title="Claude Code">
    Run this command in your terminal:

    ```bash theme={null}
    claude mcp add --transport http crossmint-docs https://docs.crossmint.com/mcp
    ```
  </Tab>

  <Tab title="Cursor">
    Add the server to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):

    ```json mcp.json theme={null}
    {
        "mcpServers": {
            "crossmint-docs": {
                "url": "https://docs.crossmint.com/mcp"
            }
        }
    }
    ```
  </Tab>

  <Tab title="VS Code">
    Open the command palette (`Cmd/Ctrl + Shift + P`), select `MCP: Open User Configuration`, and add the server:

    ```json mcp.json theme={null}
    {
        "servers": {
            "crossmint-docs": {
                "type": "http",
                "url": "https://docs.crossmint.com/mcp"
            }
        }
    }
    ```
  </Tab>
</Tabs>

### Tools

The server gives your agent three tools. The agent selects the tool to use from your prompt.

| Tool | What it does |
| - | - |
| `search_crossmint_docs` | Searches the docs and returns the matching sections, each with a title, link, and content. |
| `query_docs_filesystem_crossmint_docs` | Reads full pages and OpenAPI specs with read-only commands such as `rg`, `cat`, `ls`, and `tree`. |
| `submit_feedback` | Reports an incorrect, outdated, or incomplete page to the Crossmint docs team. |

The server also exposes the Crossmint skill file as an MCP resource.

Example prompts:

* "How do I create non-custodial wallets for my users?"
* "How do I get a staging API key?"
* "Does Crossmint support Solana?"
* "How do I set up transfer webhooks?"


# Getting Started
Source: https://docs.crossmint.com/introduction/getting-started



Before you can start integrating Crossmint into your application, you need to create a Crossmint account and set up a new project in the Staging Console. This guide will walk you through those steps.

<Steps>
  <Step title="Create an account in staging">
    Open Crossmint's [staging console](https://staging.crossmint.com/console) and create an account

    <Note>
      **Ready for launch?**
      When it's time to go live, simply create an account in the [production console](https://www.crossmint.com/console) and replicate the resources you need.
    </Note>
  </Step>

  <Step title="Create your first project">
    If you've just created an account for the first time, you'll be taken directly to project creation process. Add the name to your project and continue.
  </Step>

  <Step title="Get your API keys">
    In the [overview of your project](https://staging.crossmint.com/console/overview) you will find the client and server API keys you need to integrate Crossmint into your application.
  </Step>

  <Step title="Start building">
    Now that your project is created in the Console, you can start integrating Crossmint products into your application.

    <CardGroup>
      <Card title="Wallets" icon="wallet" href="/wallets/overview">
        Create wallets for users, agents, and companies.
      </Card>

      <Card title="Authentication" icon="at" href="/authentication/introduction">
        Authenticate users with email, socials, or wallets.
      </Card>

      <Card title="Checkout" icon="cart-shopping" href="/payments/introduction">
        Accept card and cryptocurrency payments.
      </Card>

      <Card title="Onramps" icon="credit-card" href="https://www.crossmint.com/products/onramps-and-offramps">
        Fund wallets with stablecoins or crypto.
      </Card>

      <Card title="Tokenization" icon="cube" href="/minting/introduction">
        Mint, distribute, and manage tokens at scale.
      </Card>

      <Card title="Verifiable Credentials" icon="id-card" href="/minting/quickstarts/credentials">
        Issue and verify W3C credentials.
      </Card>
    </CardGroup>
  </Step>
</Steps>


# Glossary
Source: https://docs.crossmint.com/introduction/glossary

Key terms and definitions used across the Crossmint documentation.

A reference of key terms used throughout the Crossmint documentation. If you encounter an unfamiliar term in any guide or concept page, check here first.

| Term | Definition |
| - | - |
| **Smart contract wallet** | A wallet deployed as a smart contract on a public blockchain. It lives onchain — not inside Crossmint's servers — and its behavior is governed by auditable code. On EVM chains, Crossmint wallets implement [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337) with [ERC-7579](https://eips.ethereum.org/EIPS/eip-7579) modular extensions. See [Architecture](/wallets/architecture). |
| **Signer** | A cryptographic identity authorized to approve actions on a wallet. Signers are separate from the wallet itself and can be added, removed, or rotated without changing the wallet's address. See [Signers](/wallets/concepts/signers). |
| **Operational signer** | A signer added to a wallet for day-to-day transaction authorization. Operational signers are registered by a recovery method and can be scoped with specific permissions. Examples: a device key for user wallets, a server signer for company wallets. See [Signers](/wallets/concepts/signers). |
| **Delegated signer** | The previous term for **operational signer**. Still used in current SDK method names (`addDelegatedSigner`, `delegatedSigners`) but being renamed in the next breaking release. |
| **Recovery method** | A way for the wallet owner to prove ownership and regain access when the operational signer is lost — for example, when a user gets a new phone. Recovery methods authorize the enrollment of a new operational signer without changing the wallet address. See [Recovery Methods](/wallets/concepts/recovery). |
| **Recovery signer** | A technical synonym for **recovery method**, retained in SDK and onchain terminology. |
| **Admin signer** | The legacy/API field name for **recovery method**. You may still encounter this term in API responses. |
| **Custody** | An entity has custody of a wallet if it can **unilaterally execute transactions** on the wallet or **unilaterally block transactions** on the wallet. See [Custody Models](/wallets/concepts/custody-models) for full details. |
| **Non-custodial** | A wallet configuration where your company cannot unilaterally move or block funds. Users control their own signers. See [Custody Models](/wallets/concepts/custody-models). |
| **Wallet locator** | A human-readable identifier for a wallet, following the format `email:user@example.com:evm` or `userId:abc123:solana`. Used in API calls instead of raw wallet addresses. |
| **Signer locator** | A human-readable identifier for a signer, such as `external-wallet:0x1234...` or `email:user@example.com`. Used when registering or referencing signers in API calls. |
| **Secure enclave** | The secure storage built into a user's phone, computer, or browser — such as the iOS Secure Enclave, Android Keystore, or the browser's built-in credential store. Cryptographic keys generated inside a secure enclave are non-extractable and never leave the device. Crossmint uses device secure enclaves to back [device key signers](/wallets/guides/signers/device-signer). |
| **TEE (Trusted Execution Environment)** | A hardware-attested secure enclave (e.g., Intel TDX) where sensitive cryptographic operations occur. Crossmint uses TEEs for email and SMS recovery methods — master secrets are derived inside the TEE and never exposed to Crossmint or the host application. |
| **Onchain** | Deployed to or enforced by the blockchain. In Crossmint wallets, signer permissions and wallet logic are onchain and publicly auditable. |


# Platform Overview
Source: https://docs.crossmint.com/introduction/platform-overview



Crossmint is an all-in-one platform to integrate [wallets](/wallets/overview), [stablecoins](/stablecoin-orchestration/overview), and other blockchain primitives into your product. Trusted by the world's largest financial institutions including MoneyGram and Santander Bank, and thousands of start-ups.

At its core, Crossmint abstracts the hardest parts of blockchain—wallets, keys, gas, compliance, and payments—into simple APIs, SDKs, and dashboards. This allows teams to focus on user experience and business logic while Crossmint handles the underlying complexity.

## How the Platform Is Structured

Crossmint is designed as a modular platform composed of interoperable building blocks. You can use them independently or combine them into an end-to-end system:

| Product | Description |
| :- | :- |
| [Wallets](/wallets/overview) | Embedded wallets for user-facing applications and [treasury wallets](/wallets/concepts/treasury) for businesses. Wallets support flexible custody models, programmable permissions, and abstract away private keys and gas. Extensions such as [yield](/wallets/guides/wallet-extensions/yield-xyz), trading, and [cards](/wallets/guides/wallet-extensions/credit-cards) can be added on top of core wallet functionality. |
| [Payments](/stablecoin-orchestration/overview) | Stablecoin infrastructure, including [onramps](/onramp/overview) and offramps, [payouts and transfers](/stablecoin-orchestration/regulated-transfers/overview), and [checkout](/payments/introduction). These APIs let your platform onramp, offramp, convert, and settle onchain across 150+ countries through a single integration. |
| [Tokenization](/minting/introduction) | Issuance and distribution of tokens at scale. |

The platform includes built-in compliance infrastructure across the regulated products, covering [KYC, AML and sanctions screening](/identity/overview), and travel rule compliance—so you can build compliant products without running these systems yourself.

## What You Can Build

Crossmint's building blocks are designed to be combined into complete, end-to-end solutions. Teams can mix and match wallets, payments, and embedded finance modules to support a wide range of products and workflows, like remittances and consumer fintech apps.

<Card title="Explore the solutions" icon="lightbulb" href="/solutions/overview">
  Browse guides tailored to your business vertical or use case
</Card>

## How Teams Integrate

Crossmint is API-first, with dashboards for monitoring and daily operations.

For customers building complex systems, Crossmint provides **forward-deployed engineers** and **solution architects** who partner closely with teams to design architecture, checkout experiences, and compliance setup, reducing implementation risk and time to launch.

## What Makes Crossmint Unique

* **All-in-one platform**: You don't have to orchestrate 5-10 vendors. In addition to the products above, Crossmint saves you from separate integrations with RPCs, data APIs, AML screening providers, KYC, and other ancillary providers, offering everything you need in a fully integrated platform.

* **Make the blockchain invisible to your users**: No gas fees, passphrases, transaction approval prompts, or other blockchain gimmicks.

* **Easy-to-use APIs**: Don't require blockchain experience to get you started in minutes. Crossmint optionally takes care of gas fees and bills you in fiat, so you don't have to touch crypto or set up a treasury wallet.

* **No vendor lock-in**: Change providers anytime with minimal user disruption.

* **Bank-grade security**: Battle-tested and trusted by some of the largest financial institutions in the world.

## Learn more

<CardGroup>
  <Card title="Supported blockchains" icon="link" href="/introduction/supported-chains">
    View all 50+ supported chains
  </Card>

  <Card title="Quickstarts" icon="bolt" href="/introduction/getting-started">
    Get started in minutes
  </Card>

  <Card title="Contact us" icon="message" href="https://www.crossmint.com/contact">
    Talk to our team
  </Card>
</CardGroup>


# Account Verification
Source: https://docs.crossmint.com/introduction/platform/account-verification

Learn how to get your account verified

Access to certain Crossmint products is subject to compliance review.

| Product | Requirement |
| - | - |
| Wallets | No KYB required. |
| Stablecoin Orchestration | Signed Order Form and KYB required. |
| Onramps | Signed Order Form and KYB required. |
| Checkout | Signed Order Form and KYB required. Collection whitelisting also required for memecoins and primary NFT sales. |
| Tokenization | No KYB required. |

<Note>
  Reviews are only required in production. Staging does not require an Order Form, KYB, or collection review for any product.
  Each distinct project you create via the Crossmint Console requires a separate review.
</Note>

## How Production Access Works

For products that require it, production access follows the same sequence:

<Steps>
  <Step title="Sign an Order Form">
    Work with the Crossmint <a href="https://www.crossmint.com/contact/sales">sales team</a> to sign an Order Form. The Order Form is the commercial agreement and includes the KYB obligation.
  </Step>

  <Step title="Complete KYB">
    Crossmint's compliance team runs KYB (Know Your Business) verification as part of onboarding. The review covers entity formation, beneficial ownership, and business purpose.
  </Step>

  <Step title="Production Access Opens">
    Production is enabled once KYB passes. There is no separate request to make — a successful KYB unlocks the production environment for your account.
  </Step>
</Steps>

<Note>
  Staging is self-serve. You can build and test against staging with only a <a href="https://staging.crossmint.com/console">staging console</a> account — no Order Form, no KYB, and no manual approval.
</Note>

## KYB for Sole Proprietors and Individual Sellers

KYB is designed for registered legal entities. If you do not operate through one (for example, you sell as a sole proprietor or individual entrepreneur), eligibility and the documents you need are confirmed case by case and depend on your jurisdiction. Raise your situation with the <a href="https://www.crossmint.com/contact/sales">sales team</a> before signing the Order Form so the compliance team can tell you what applies to you.

In the meantime, you can build and test your full integration in staging, which does not require KYB. See [Staging vs Production Environments](/introduction/platform/staging-vs-production).


# Client-side Keys
Source: https://docs.crossmint.com/introduction/platform/api-keys/client-side

How to create and use client-side API keys

## Create a Client-side Key

Navigate to the API Keys section of the developer console and click the "Create new key" button in the client-side keys section.

* [Staging API Keys](https://staging.crossmint.com/console/projects/apiKeys)
* [Production API Keys](https://www.crossmint.com/console/projects/apiKeys)

<Frame type="simple">
  <img alt="create client-side API key in Crossmint developer console" />
</Frame>

### Setting Authorized Origins

Client-side keys are exposed in the application and thus require additional security measures. The minimum requirement is to whitelist URLs that requests can be sent from. Client-side keys support two types of origins:

<Warning>
  You can only register either web origins or mobile app identifiers for a single API key, not both. If you need both
  types, you will need to create separate API keys.
</Warning>

#### Web Origins

For web applications, you need to add the domains that requests will be sent from. In development, you will need to add the local domain you test your application from. This is commonly `http://localhost` followed by a port number such as `3000`, `5173`, etc. For example, when developing with NextJS, the default origin you need to authorize is `http://localhost:3000`.

The expected format for web origins is a full URL with protocol, such as `https://www.yourdomain.com` or `http://localhost:3000`.

#### Mobile App Identifiers

For mobile applications, you need to add the bundle identifiers for iOS apps or package names for Android apps. The expected format is:

* iOS: Bundle ID (e.g., `com.company.appname`)
* Android: Package name (e.g., `com.company.appname`)

<Warning>
  Mobile app identifiers can be arbitrarily spoofed by malicious actors, as the headers sent from mobile applications can be modified. Do not rely solely on mobile app identifiers for security. Consider implementing additional authentication mechanisms such as JWT authentication for sensitive operations.
</Warning>

#### Desktop/CLI Applications

For desktop applications and CLI tools where origin headers cannot be reliably set, you can select the "Desktop/CLI" app type when creating your client-side API key. This option allows the key to be used without origin restrictions.

<Warning>
  **Security Warning**: Desktop/CLI keys have no origin-based protection. This means:

  * The key can be used from any origin or application
  * If the key is leaked, it can be used by anyone without restriction
  * Consider enabling JWT authentication for additional security
  * Only use this option when absolutely necessary (e.g., CLI tools, desktop apps, AI agents)

  For most use cases, Crossmint recommends using web origins or mobile app identifiers instead.
</Warning>

To create a Desktop/CLI key:

1. Select "Desktop/CLI" as the app type when creating or editing a client-side key
2. Consider enabling JWT authentication for additional security
3. Store the key securely and rotate it regularly

When you create a production API key you will need to authorize your production domain or app identifiers to use the API key. You can add multiple authorized domains or app identifiers for an API key to make requests from. Type in the domain or app identifier that you want to authorize and then click the "+ Add new origin" button.

<Frame type="simple">
  <img alt="add authorized origin to API key in Crossmint developer console" />
</Frame>

### Select Scopes

Within the modal that opens, toggle the required scopes you want to enable. You may need to expand an accordion for the product area you are working on to expose additional scope options.

<Frame type="simple">
  <img alt="select client-side API scopes in Crossmint developer console" />
</Frame>

For more information on API Key scopes visit the scopes page or the API Reference.

<CardGroup>
  <Card title="API Scopes" icon="bullseye" href="/introduction/platform/api-keys/scopes">
    Complete list of available API scopes
  </Card>

  <Card title="API Reference" icon="paper-plane" href="/api-reference/introduction">
    Detailed docs for all API endpoints
  </Card>
</CardGroup>

### JWT Authentication

Finally, select the option to require a JWT if your application or use case requires it. Enabing this setting will require that users are authenticated to permit API requests.

<Frame type="simple">
  <img alt="enable JWT Authentication in Crossmint developer console" />
</Frame>

<Tip>
  The [Wallets SDK](/sdk-reference/wallets/typescript/overview) requires this option to be enabled. It is optional for other
  client side APIs. For more information on the options, refer to the [JWT
  Authentication](/introduction/platform/api-keys/jwt-authentication) section.
</Tip>

If you choose to enable JWT Authentication for your client-side API key, there are additional configurations that must be made. You can choose between Crossmint authentication (ideal for staging and getting started fast), third party auth providers such as Auth0, Stytch, Firebase, Kinde, or Supabase (recommended for production), or custom solutions where you generate your own JWTs (also recommended for production).

You can find more information and guidance in the [JWT Authentication](/introduction/platform/api-keys/jwt-authentication) section.

***

## Using a Client-side Key

There are a few different approaches to using a client-side key. The most common option is passing it to the `init` function for a supported SDK. There are also some cases where you will pass the key as a header in a raw API call from custom code, similar to how a server-side key works.

### Initializing an SDK

The most common way you will leverage a client-side API key is by passing it to the `init` function for a supported SDK. See the examples below.

<CodeGroup>
  ```typescript crossmint-wallets-sdk.ts theme={null}
  import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";

  const crossmint = createCrossmint({
  apiKey: process.env.NEXT_PUBLIC_CLIENT_SIDE_KEY ?? "",
  });

  const crossmintWallets = CrossmintWallets.from(crossmint);

  const wallet = await crossmintWallets.getOrCreateWallet({
  chain: "<your-chain>",
  signer: {
  type: "<signer-type>",
  },
  });

  ```

  ```typescript credentials-init.ts theme={null}
  import * as sdk from '@crossmint/client-sdk-verifiable-credentials';

  sdk.CrossmintAPI.init(process.env.NEXT_PUBLIC_CLIENT_SIDE_KEY);
  ```

  ```tsx auth-example.tsx theme={null}
  import { CrossmintProvider, CrossmintAuthProvider } from "@crossmint/client-sdk-react-ui";

  export default function RootLayout({
      children,
  }: Readonly<{
      children: React.ReactNode;
  }>) {
      return (
          <html lang="en">
              <body className={inter.className}>
                  <CrossmintProvider apiKey={process.env.NEXT_PUBLIC_CLIENT_SIDE_KEY ?? ""}>
                      <CrossmintAuthProvider loginMethods={["email", "google"]}>{children}</CrossmintAuthProvider>
                  </CrossmintProvider>
              </body>
          </html>
      );
  }
  ```
</CodeGroup>

### Direct API Call From Client

The Headless Checkout is one example where you may be writing custom API calls from your application to create orders. In this case, you set the client-side API key as a header named `X-API-KEY`, much like you would when making a server-side API call.

```typescript theme={null}
const createOrder = async (orderInput: any) => {
    try {
        const res = await fetch(`https://staging.crossmint.com/api/2022-06-09/orders`, {
            method: "POST",
            headers: {
                "Content-Type": "application/json",
                "x-api-key": process.env.NEXT_PUBLIC_CLIENT_SIDE_KEY,
            },
            body: JSON.stringify(orderInput),
        });

        const order = await res.json();

        setOrder(order.order);
        setClientSecret(order.clientSecret);
    } catch (e) {
        console.error(e);
        throw new Error("Failed to create order");
    }
};
```


# JWT Authentication
Source: https://docs.crossmint.com/introduction/platform/api-keys/jwt-authentication

Enable advanced security for client-side API Keys

JWT-based authentication is a mechanism in which you can authorize a call to a Crossmint API, scoping such calls to impact resources related to a single end-user on your platform. You have three options available when enabling this option.

1. **Crossmint Authentication** - A quick-to-integrate auth solution, ideal for staging environments and getting started fast. Crossmint handles the generation of JWTs and you're able to quickly create a working application with user access controls. **For production, options 2 or 3 below are recommended.**
2. **Third Party Authentication providers** *(recommended for production)* - There are several quality authentication providers in the market and you may already be using one of them. You can continue to use your existing auth tooling and enable Crossmint Wallets on top of them with minimal changes. Supported providers include Auth0, Firebase, Supabase, Stytch, and Kinde.
3. **Custom JWT** *(recommended for production)* - This option is for providers not yet included with turn-key support or custom built solutions where you issue your own JWTs. You must be able to provide a JWKS endpoint to enable Crossmint to authenticate tokens.

<Tip>Crossmint's Wallets SDK **requires** JWT Authentication be enabled.</Tip>

## Crossmint Authentication

This option makes the most sense if you're getting started quickly and want to prototype or test in a staging environment. Crossmint Auth is great for demos and quickstarts, but for production applications a [third-party auth provider](/wallets/guides/bring-your-own-auth) or custom JWT is recommended for full control over your user management.

To use this option, select the Crossmint Auth option within the JWT Authentication section of the API keys page in the Developer Console.

<Frame type="simple">
  <img alt="select Crossmint Auth in Crossmint developer console" />
</Frame>

## Third Party Authentication

For projects that have already implemented authentication using one of the supported providers, you can provide Crossmint with the appropriate project/environment/app ID from the settings page of the third party. Supported providers include: Dynamic, Auth0, Stytch, Privy, Firebase, Kinde, and Supabase.

To use this option, select the 3P Auth providers option, then choose your provider from the dropdown. Next, you'll need to find the appropriate ID that your provider gives you to identify your project. This can typically be found within the settings pane of their web interface.

<Frame type="simple">
  <img alt="select third party Auth in Crossmint developer console" />
</Frame>

## Custom JWT Auth

If your project is using an auth provider not listed in the 3P providers list or is a home-grown JWT solution, you can choose the Custom tokens option. You will need to be able to provide a <Tooltip>JWKS endpoint</Tooltip> that Crossmint can use to authenticate the JWTs.

<Frame type="simple">
  <img alt="select third party Auth in Crossmint developer console" />
</Frame>

For a detailed guide on implementing this approach, check out the [Custom JWT Authentication Guide](/introduction/platform/api-keys/custom-jwt-auth-guide).


# Overview
Source: https://docs.crossmint.com/introduction/platform/api-keys/overview

Get your keys in seconds and start building

API keys are required to authorize requests against the Crossmint APIs. By using an API key, Crossmint knows which project is making the call, and can deduct credits from your balance.

## Staging vs. Production Keys

First, determine if you need a staging (testing) or production API key.

<CardGroup>
  <Card title="Staging API Keys" icon="flask-gear" href="https://staging.crossmint.com/console/projects/apiKeys">
    Generate API keys for testing in the staging developer console
  </Card>

  <Card title="Production API Keys" icon="bolt" href="https://www.crossmint.com/console/projects/apiKeys">
    Generate API keys for going live in the production developer console
  </Card>
</CardGroup>

## Server-side vs. Client-side Keys

Server-side API keys are used in server-to-server communications or in code running on a server. These keys are not exposed to the end users and can have broader permissions because they are considered more secure, being stored and used in controlled environments.

<Note>
  The majority of Crossmint APIs require a server-side API key. For a comprehensive list of APIs available refer to
  the [API Reference](/api-reference/introduction).
</Note>

Client-side API keys are used in code that runs on the client-side, such as in web browsers or mobile apps. These keys are exposed to the end user and are therefore less secure. They typically have more restrictive permissions to minimize security risks. When creating a client-side API key, you also need to configure authorized origins that are allowed to make calls to the endpoint.

<Check>
  Client-side keys are required for building with the [Wallets SDK](/sdk-reference/wallets/typescript/overview), Authentication, and [Headless Checkout](/payments/headless/overview).

  You can also perform some custodial wallet actions with these key types. Finally, the [Verifiable Credentials SDK](/verifiable-credentials/introduction) also offers some features via client-side keys.
</Check>

## More information

<CardGroup>
  <Card title="Rate Limits" icon="ruler" href="/introduction/platform/api-keys/rate-limits">
    Information about standard rate limits and exceptions
  </Card>

  <Card title="API Scopes" icon="bullseye" href="/introduction/platform/api-keys/scopes">
    Complete list of available API scopes
  </Card>

  <Card title="Server-side Keys" icon="server" href="/introduction/platform/api-keys/server-side">
    How to create and use server-side API keys
  </Card>

  <Card title="Client-side Keys" icon="browser" href="/introduction/platform/api-keys/client-side">
    How to create and use client-side API keys
  </Card>
</CardGroup>


# Rate Limits
Source: https://docs.crossmint.com/introduction/platform/api-keys/rate-limits

Understand the throughput available for API calls

Rate limits prevent individual users from clogging the network. If a limit is exceeded, Crossmint will respond with HTTP 429 and require a brief waiting period before making additional requests.

The rate limits on self-serve plans are the following:

<Check>To increase the base rate limits, <a href="https://www.crossmint.com/contact/sales">contact us</a>.</Check>

### Base Limits

| Method(s) | Rate Limit |
| :- | :- |
| POST | 120 requests per minute per project |
| PUT | Same as above |
| PATCH | Same as above |
| DELETE | Same as above |
| GET | 360 requests per minute per project |

### Exceptions

| API | Route | Method | Rate Limit |
| :- | :- | :- | :- |
| [Mint NFT](/api-reference/minting/nfts/mint-nft) | /api/2022-06-09/collections/\{collectionId}/nfts | POST | 600 req/min/project |
| [Mint NFT (Idempotent)](/api-reference/minting/nfts/mint-nft-idempotent) | /api/2022-06-09/collections/\{collectionId}/nfts/\{nftName} | PUT | 600 req/min/project |
| [Collection Info](/api-reference/minting/collection/get-collection) | /api/2022-06-09/collections/\{collectionId} | GET | 600 req/min/project |
| [Mint Status](/api-reference/minting/nfts/mint-status) | /api/2022-06-09/collections/\{collectionId}/nfts/\{id} | GET | 600 req/min/project |
| [Get All Tokens](/api-reference/headless/get-all-tokens) | /api/2024-09-26/tokens | GET | 3000 req/min/project |
| [Check Token Support](/api-reference/headless/check-token-support) | /api/2024-09-26/tokens/\{tokenLocator} | GET | 3000 req/min/project |
| [Get User](/api-reference/users/get-user) | /api/2025-06-09/users/\{userLocator} | GET | 80 req/min/project |
| [Create or Update User](/api-reference/users/upsert-user) | /api/2025-06-09/users/\{userLocator} | PUT | 50 req/min/project |
| [Get Identity Verification](/api-reference/users/get-identity-verification) | /api/2025-06-09/users/\{userLocator}/identity-verification | GET | 80 req/min/project |
| [Trigger Identity Verification](/api-reference/users/trigger-identity-verification) | /api/2025-06-09/users/\{userLocator}/identity-verification | PUT | 50 req/min/project |
| [Accept Legal Document](/api-reference/users/accept-legal-document) | /api/2025-06-09/users/\{userLocator}/legal-documents | PUT | 50 req/min/project |
| [Upload User Document](/api-reference/users/upload-document) | /api/2025-06-09/documents | POST | 50 req/min/project |
| [Get User Document](/api-reference/users/get-document) | /api/2025-06-09/documents/\{documentId} | GET | 80 req/min/project |


# Scopes
Source: https://docs.crossmint.com/introduction/platform/api-keys/scopes

Enabling required permissions for API calls

Below is a complete list of the API scopes available. You can also find the scope a specific API requires in the [API Reference](/api-reference/introduction) section.

## Wallet APIs

| Scope | Description | Server Key | Client Key |
| - | - | - | - |
| `wallets.read` | Retrieve all wallets for a user. | ✅ | ✅ |
| `wallets.create` | Create a wallet for a user. | ✅ | ✅ |
| `wallets:nfts.read` | Fetch the NFTs owned by a specific wallet address. | ✅ | ✅ |
| `wallets:balance.read` | Get the balance of a specific wallet address. | ✅ | ✅ |
| `wallets:transactions.create` | Create a transaction from a user's wallet. | ✅ | ✅ |
| `wallets:transactions.sign` | Sign a transaction from a user's wallet. | ✅ | ✅ |
| `wallets:transactions.read` | Read transactions from a user's wallet. | ✅ | ✅ |
| `wallets:signatures.create` | Create a signature for a wallet. | ✅ | ✅ |
| `wallets:signatures.read` | Read a signature for a wallet. | ✅ | ✅ |
| `wallets.fund` | Send funds to a wallet. | ✅ | ✅ |
| `wallets.export` | Export a wallet's encrypted private key material. | | ✅ |
| `wallets:nfts.transfer` | Transfer an NFT from a user's wallet. | ✅ | |
| `wallets:messages.sign` | Sign a message from a user's wallet. | ✅ | |

<Note>When using the [Wallets SDK](/sdk-reference/wallets/typescript/overview) you **must** use a client-side API key.</Note>

## Authentication

| Scope | Description | Server Key | Client Key |
| - | - | - | - |
| `users.create` | Create users / allow them to sign up. | | ✅ |
| `users.read` | Get profile info for user accounts. | | ✅ |

## Tokenization (Minting) APIs

| Scope | Description | Server Key | Client Key |
| - | - | - | - |
| `nfts.create` | Mint your NFTs and deliver them to a wallet or to an email address. | ✅ | |
| `nfts.update` | Update a minted NFT's metadata on IPFS (image, description, name...). | ✅ | |
| `nfts.read` | Retrieve all metadata for an NFT. | ✅ | |
| `nfts.delete` | Burn a specific NFT within a collection. | ✅ | |
| `nfts.transfer` | Transfer an NFT to a different wallet. | ✅ | |
| `collections.create` | Create a collection of NFTs. | ✅ | |
| `collections.update` | Update information for an existing collection (image, name, royalties...). | ✅ | |
| `collections.read` | Retrieve the information about a specific collection. | ✅ | |
| `credentials.read` | Fetch credentials, some endpoints will only work with a server side key. | ✅ | ✅ |
| `credentials.decrypt` | Decrypt credentials, mainly used by the client-side SDK. | ✅ | ✅ |
| `credentials:templates.create` | Create a template for your credentials. | ✅ | |
| `credentials.create` | Issue your credentials and create credential types | ✅ | |
| `credentials.delete` | Revoke a credential issued to a subject. | ✅ | |

## Checkout APIs

| Scope | Description | Server Key | Client Key |
| - | - | - | - |
| `orders.create` | Create an order for headless checkout. | ✅ | ✅ |
| `orders.read` | Get an existing order for headless checkout. | ✅ | ❌ |
| `orders.update` | Update an existing order for headless checkout. | ✅ | ❌ |

<Note>
  Client-side API keys only have access to the `orders.create` scope. When reading or updating order status from the
  client-side, you must pass the `clientSecret` returned in the create-order call as an `authorization` header for
  subsequent order operations (get-order, update-order). The `clientSecret` provides the authorization and an API Key
  is not required in this use case. See [this
  guide](/payments/headless/guides/client-or-server#client-side-example-code) in the Headless Checkout docs.
</Note>

## Project Administration

| Scope | Description | Server Key | Client Key |
| - | - | - | - |
| `billing.readonly` | Get balance in credits for a project. | ✅ | |
| `projects:usage.read` | Get usage for the different products in a project | ✅ | |


# Server-side Keys
Source: https://docs.crossmint.com/introduction/platform/api-keys/server-side

How to create and use server-side API keys

<Warning>
  **Server-side API keys must be stored securely!**

  Enable only the scopes you need, and no more, and do NOT expose your keys on the frontend of your app, or your github code repository.
</Warning>

## Create a Server-side Key

Navigate to the API Keys section of the developer console and click the "Create new key" button in the server-side keys section.

* [Staging API Keys](https://staging.crossmint.com/console/projects/apiKeys)
* [Production API Keys](https://www.crossmint.com/console/projects/apiKeys)

<Frame type="simple">
  <img alt="create server-side API key in Crossmint developer console" />
</Frame>

### Select Scopes

<Info>
  **Production server-side keys follow a "view once" policy**

  When you create a server-side API key in the production environment, the key secret will only be shown once during creation. After you close the dialog or navigate away, **you will not be able to view the key secret again.**
</Info>

Within the modal that opens, toggle the required scopes on and click the "Create server key" button at the bottom. You may need to expand an accordion for the product area you're working on to expose additional scope options.

<Frame type="simple">
  <img alt="select server-side API scopes in Crossmint developer console" />
</Frame>

You can determine the scopes you need by visiting the API reference page for the API(s) you need to interact with.

<CardGroup>
  <Card title="API Scopes" icon="bullseye" href="/introduction/platform/api-keys/scopes">
    Complete list of available API scopes
  </Card>

  <Card title="API Reference" icon="paper-plane" href="/api-reference/introduction">
    Detailed docs for all API endpoints
  </Card>
</CardGroup>

## Using a Server-side Key

If you're using the [API Playground](/api-reference) you can add your API key in the Authorization section and this will set it as a header when making the request.

<Frame type="simple">
  <img alt="Set x-api-key screenshot" />

  <img alt="Set x-api-key screenshot" />
</Frame>

When calling the APIs from server-side code, you set the `X-API-KEY` header however the target language or library expects it. See some examples below:

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://staging.crossmint.com/api/v1-alpha1/wallets \
    --header 'Content-Type: application/json' \
    --header 'X-API-KEY: YOUR_API_KEY' \
    --data '{
    "email": "test@test.com",
    "chain": "polygon-amoy"
  }'
  ```

  ```javascript Node.js theme={null}
  const options = {
    method: 'POST',
    headers: {
      'X-API-KEY': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: '{
      "email":"test@test.com",
      "chain":"polygon-amoy"
    }'
  };

  fetch('https://staging.crossmint.com/api/v1-alpha1/wallets', options)
    .then(response => response.json())
    .then(response => console.log(response))
    .catch(err => console.error(err));
  ```
</CodeGroup>

All of the API routes in the [API Reference](/api-reference/introduction) include code examples for many popular programming languages.


# Organizations
Source: https://docs.crossmint.com/introduction/platform/organizations

How an organization groups your projects, your team, and the security settings that apply to them

An organization is the top-level container in the Crossmint console. It holds your projects and the team that works on them.

* A **project** contains the resources you build with: token collections, user wallets, API keys, billing information, and more.
* An **organization** contains one or more projects, plus the members, roles, and security settings that apply to all of them.

Every project belongs to exactly one organization. You invite people to the organization once, and they get access to every project it contains.

## Personal and Team Organizations

Every account starts with a personal organization. It is your own space, you are its only member, and it never changes hands.

A team organization is the one you create to work with other people. Create it from the organization menu in the console, name it, and invite your teammates. You can belong to several organizations at once, for example your own and your employer's, and switch between them from the same menu. Each organization keeps its own projects, and the project list in the sidebar always shows the organization you are in.

<Note>Organizations follow the environment boundary described in [Staging vs Production](/introduction/platform/staging-vs-production): an organization in staging and an organization in production are separate, each with its own members, invitations, and authentication setup.</Note>

## Roles

Each member holds one role in each organization. The same person can be an admin in one organization and a developer in another.

| | Developer | Admin | Owner |
| - | :-: | :-: | :-: |
| Work in the organization's projects and manage their API keys | ✅ | ✅ | ✅ |
| Create projects | ✅ | ✅ | ✅ |
| Invite members, change their role, and remove them | ❌ | ✅ | ✅ |
| Edit the organization's settings and security | ❌ | ✅ | ✅ |
| Transfer ownership | ❌ | ❌ | ✅ |

Developer is the least privileged role and the default for a new invitation. Ownership is never handed out as a role: an organization has exactly one owner at a time.

## Project Access Follows the Organization

Every member of an organization has access to all of its projects; there are no per-project invitations. Adding someone to the organization grants that access, removing them revokes it, and their organization role decides what they can do in each project. Admins and owners can also manage who is listed on a project.

A project can additionally be shared with someone outside the organization. That person is listed on the project itself, with a Developer or an Admin role, and sees only that project.

The Members tab of a project therefore shows two kinds of rows:

* **Members of the organization**: they have access to the project through the organization. Change their role or remove them in the organization settings, not on the project.
* **Members listed on the project**: shared with this project alone. Change their role or remove them on the project.

<Note>A member of the organization can also be listed on a project itself, and that row decides what they can do there: an admin of the organization listed as a developer on a project is a developer in that project.</Note>

## Transferring Projects Between Organizations

A project moves to another organization from the Transfer card in its **Settings > General** page. It can go between any two organizations you belong to in the same environment, personal or team, one project at a time.

<video />

Transferring a project takes two roles:

* **Admin of the project**: an owner or admin of the organization the project is in, or a member listed on the project as an admin.
* **Owner or admin of the destination organization**: only these organizations appear in the list of destinations.

After you confirm, the console switches to the destination organization, where the project is now listed.

A transfer changes who reaches the project through an organization, and nothing else:

* The API keys, wallets, and billing of the project stay the same.
* Everyone listed on the project keeps their access and their role.
* Every member of the destination organization gets access, with the role they hold there.
* Members of the previous team organization who are not listed on the project lose access.

<Warning>You cannot transfer the only project in an organization. Create another project there first.</Warning>

## Invitations

Admins and owners invite people by email address from the members section of the organization settings, and pick the role each one starts with.

* The invited person does not need a Crossmint account yet. The email links to the console, where they sign in or create the account that accepts the invitation.
* A pending invitation waits in the organization menu of the person invited, so they can accept it whenever they next sign in.
* Admins and owners resend or revoke a pending invitation from the same members section.

## MFA and SSO support

Crossmint offers extra authentication features to enterprise organizations: two-factor authentication with an authenticator app (TOTP), and single sign-on through your own identity provider.

<Snippet />

## Ownership

A team organization has exactly one owner, and only the owner transfers ownership, from the members list. The member who receives it becomes the owner, and the previous owner stays in the organization as an admin. A personal organization cannot be transferred.

## See Also

<CardGroup>
  <Card title="Project and Team Management" icon="folder-tree" href="/introduction/platform/projects-and-user-management">
    What a project holds, and the privacy policy it needs to show user data
  </Card>

  <Card title="Staging vs Production" icon="code-branch" href="/introduction/platform/staging-vs-production">
    Why your staging and production accounts are entirely separate
  </Card>

  <Card title="API Keys Overview" icon="key" href="/introduction/platform/api-keys/overview">
    The keys a project issues, and the scopes they carry
  </Card>

  <Card title="Account Verification" icon="badge-check" href="/introduction/platform/account-verification">
    Verifying your account before going live in production
  </Card>
</CardGroup>


# Project and Team Management
Source: https://docs.crossmint.com/introduction/platform/projects-and-user-management

Manage your projects and their members

<Tabs>
  <Tab title="Projects">
    ## Managing Projects

    A project contains the resources you build with: token collections, user wallets, API keys, billing information, and more.

    Every project belongs to one [organization](/introduction/platform/organizations), which holds the team that has access to it.

    If you are working with different teams or clients, you can create different projects to seggregate sensitive information and tool access. Alternatively, you can issue different API keys within the same project, but bear in mind they will share the same billing account.

    Every developer account automatically includes a project named `Default Project`. You can create new projects and alternate between them using the selector within the console, as illustrated in the screenshot below.

    <Frame type="simple">
      <img alt="Crossmint developer console overview map" />
    </Frame>

    ## Privacy Policy

    Projects have an option to register a link to your company's privacy policy. If set, this link will be shown to your users when they're using any Crossmint-managed user interface, such as the Checkout, where user information is collected. A privacy policy is required by law if you want to later those users' personally identifiable information, such as their email address.

    If you don't already have a privacy policy, you can generate and host one using tools like [Termly](https://termly.io/).

    > **Note:** Failure to add a privacy policy will result in email addresses being hidden.

    #### Cases Requiring a Privacy Policy to Access User Data

    | Use Case | Privacy Policy Required |
    | - | - |
    | Payments (payment button) | Yes |
    | Payments (embedded checkout) | Yes |
    | Payments (headless checkout) | No |
    | Mint API or console | No |
    | Wallet APIs or console | No |

    ### Steps to Add a Privacy Policy Link

    1. **Go to the General Settings tab**

       * Access the Settings page from the sidear.

    2. **Include the Privacy Policy Link**

    <Frame type="simple">
      <img alt="Include Privacy Policy link" />
    </Frame>

    * In the project settings, locate the section for adding a privacy policy.
    * Paste the URL of your privacy policy generated from Termly or any other source.

    4. **Verify Email Visibility**
       * After adding the privacy policy link, check to ensure that email addresses are now visible.
       * If the link is not included, emails will remain hidden to protect user data.

    Following these steps will ensure compliance with data protection laws and enable the visibility of email addresses in your project settings.

    ***

    ## FAQs

    <AccordionGroup>
      <Accordion title="Why does Crossmint require my project's privacy policy?">
        Crossmint requires your project's privacy policy to comply with data protection laws and ensure the privacy and
        security of user data. Without it, email addresses and other sensitive information will be hidden.
      </Accordion>

      <Accordion title="I have already configured the privacy policy URL, why can't I see the user identifier of some users?">
        Older users who joined before the privacy policy was added haven't accepted the new policy. Therefore, their
        identifiers remain hidden.
      </Accordion>

      <Accordion title="Why can't I delete the privacy policy of my project?">
        Deleting the privacy policy is restricted to ensure compliance with data protection laws and maintain user
        privacy and security.
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Team Members">
    ## Who Has Access to a Project

    Access to a project comes from its organization: every member of the organization has access to every project it contains. You invite people once, to the organization, and their role there decides what they can do in its projects. See [Organizations](/introduction/platform/organizations) for the roles and the invitation flow.

    A project can additionally be shared with someone outside the organization. Invite them by email from the Members tab of the project, and give them one of two roles:

    * **Developer**: works in the project, including its settings, API keys, collections, and integrations
    * **Admin**: everything a developer can do, and invites, removes, and assigns roles to the members listed on the project

    The Members tab lists both kinds of people. A member who has access to the project through the organization is managed in the organization settings, so the project offers no role change or removal for that row.
  </Tab>
</Tabs>


# Staging vs Production Environments
Source: https://docs.crossmint.com/introduction/platform/staging-vs-production

Understand the difference between staging and production environments before building

Crossmint's console and APIs operate in two fully separate environments:

* **Staging:** free, for development and testing. Connected to blockchain **testnets**.
* **Production:** for your live application. Connected to blockchain **mainnets**. Real assets and real costs apply.

You access them at <a href="https://staging.crossmint.com">[https://staging.crossmint.com](https://staging.crossmint.com)</a> and <a href="https://www.crossmint.com">[https://www.crossmint.com](https://www.crossmint.com)</a>.

The two environments are isolated: each has its own console login, its own API keys, and its own wallets. Data does not cross between them. You typically build your integration in staging, then replicate it in production when you are ready to launch.

<Tip>Staging provides free self-serve access to most functionality, so you can build a complete integration before spending anything.</Tip>

## Differences Between the Environments

| | **Staging** | **Production** |
| - | - | - |
| URL | <a href="https://staging.crossmint.com">staging.crossmint.com</a> | <a href="https://www.crossmint.com">[www.crossmint.com](http://www.crossmint.com)</a> |
| API keys | Start with `ck_staging_` (client) or `sk_staging_` (server) | Start with `ck_production_` (client) or `sk_production_` (server) |
| Blockchains | Testnets like Base Sepolia and Polygon Amoy | Mainnets like Base and Polygon |
| Wallets | Live on testnets only | Live on mainnets only |
| Gas fees | Sponsored by Crossmint at no cost | Sponsored by Crossmint, billed to your account |
| Tokens | Test tokens with no value (for example, USDXM) | Real assets (for example, USDC) |
| Payments | Test credit cards | Real credit cards |
| Verification | No KYC or collection verification required | KYC and collection verification required |

## Blockchain Networks and Wallet Addresses

Staging operates on testnets, and production operates on mainnets. When you create a wallet in staging on a chain like Polygon, it is deployed on the corresponding testnet (Polygon Amoy) rather than Polygon mainnet. See [Supported Chains](/introduction/supported-chains) for the mainnet and testnet targeted by each chain.

Because the two environments are isolated, a wallet you create in staging **does not share its address with production**. Addresses are derived per environment, so the same signer or configuration produces different addresses in staging and production.

This has one important consequence:

<Warning>
  Never send real (mainnet) funds to a wallet address generated in staging. Staging wallets exist only on testnets, and Crossmint cannot access or recover assets sent to that address on a mainnet. Use only test tokens with staging wallets.
</Warning>

## Gas Fees

Crossmint sponsors gas fees for wallet transactions in both environments, so your users never need to hold native tokens. In staging, this sponsorship is free. In production, Crossmint still sponsors the gas but bills the cost to your account, so it becomes a real operating expense to plan for. You can adjust or disable this behavior in the [gas sponsorship](/wallets/guides/gas-sponsorship) settings.

## Test Tokens vs Real Assets

In staging you fund wallets with test tokens that have no monetary value, so you can simulate transfers, balances, and gas without financial risk. USDXM is Crossmint's staging stablecoin — think of it as the USDC of testnets. See [Fund a Staging Wallet](/wallets/guides/fund-staging-wallet) for the ways to get it.

In production, wallets hold real assets such as USDC. USDXM is not available in production. When you move over, update any token references (for example, from `usdxm` to `usdc`) alongside the chain and API key changes below.

## Moving to Production

When your integration works in staging, launching in production requires a few deliberate changes:

1. Create a production account and project at <a href="https://www.crossmint.com/console">[www.crossmint.com/console](http://www.crossmint.com/console)</a>
2. Create a production API key with the scopes your integration needs
3. Update your API endpoint from `staging.crossmint.com` to `www.crossmint.com`
4. Replace your staging API key with the production key
5. Switch chains from testnets to their mainnet equivalents (for example, `base-sepolia` to `base`)
6. Replace test tokens with real assets (for example, `usdxm` to `usdc`)
7. Re-create your wallets in production, since staging wallets and their addresses do not carry over
8. Account for gas sponsorship as a real cost, and fund your wallets with real assets

## FAQ

<AccordionGroup>
  <Accordion title="Does staging activity appear in production, and vice versa?">
    No. The environments are isolated. Wallets, collections, and API keys created in one environment do not appear in the other. You typically develop in staging, then replicate and launch in production when you are ready.
  </Accordion>

  <Accordion title="Is my staging wallet address the same in production?">
    No. Wallet addresses are derived per environment, so a staging wallet has a different address than a production wallet, even with the same signer or configuration. Re-create your wallets when you move to production.
  </Accordion>

  <Accordion title="What happens if I send real funds to a staging wallet address?">
    Staging wallets live only on testnets. If you send mainnet assets to a staging wallet address, Crossmint has no wallet at that address on the mainnet and cannot access or recover the funds. Only use test tokens with staging wallets.
  </Accordion>

  <Accordion title="Do I pay for gas in staging?">
    No. Gas is sponsored for free in staging. In production, Crossmint sponsors gas by default but bills the cost to your account.
  </Accordion>
</AccordionGroup>


# Add an Endpoint
Source: https://docs.crossmint.com/introduction/platform/webhooks/add-endpoint

Configure an endpoint to receive webhook messages.

To add an endpoint, provide a URL you control and select the event types you want to listen to.

1. Navigate to the Webhooks page in the console.
2. Click **Add Endpoint**.
3. Provide the URL where you want to receive messages.
4. Select the event types you want to listen to.
5. Click **Create**.

<img alt="Add an endpoint" />

### FAQs

<AccordionGroup>
  <Accordion title="What types of events can I subscribe to with webhooks?">
    There are many events available to subscribe to from all Crossmint products. Some examples include:

    * Collection creation
    * NFT minting
    * NFT edits
    * Transaction confirmations
    * Transaction failures

    You can see the full list of events in the Crossmint Console, under Integrate > Webhooks and the **Event Catalog** tab.
  </Accordion>

  <Accordion title="How can I verify that a webhook request is legitimate?">
    To verify a webhook request is legitimate, you need to verify the signature and timestamp. You can learn more about it in the [Verify webhooks](/introduction/platform/webhooks/verify-webhooks) section.
  </Accordion>

  <Accordion title="How do I handle webhook retries?">
    Crossmint automatically retries webhooks if your endpoint doesn't acknowledge its receipt, or throws an error. Crossmint attempts to deliver the webhook 8 times:

    * Immediately
    * 5 seconds
    * 5 minutes
    * 30 minutes
    * 2 hours
    * 5 hours
    * 10 hours
    * 10 hours (in addition to the previous)

    If the message cannot be delivered after these attempts, it is marked as failed. Inside the Webhooks page, you can manually resend the webhook.

    <img alt="Resend a webhook" />
  </Accordion>

  <Accordion title="What HTTP response code should my webhook endpoint return?">
    To indicate that a webhook has been processed, return a 2xx (status code 200-299) response to the webhook message within a 15 seconds timeframe.
  </Accordion>

  <Accordion title="Why are my webhooks failing?">
    Some typical reasons why webhooks fail are:

    * Check that the enpdpoint URL is correct and that it's expecting a POST request
    * Check that the endpoint is reachable from the public internet. Make sure that CSRF protection is disabled for this endpoint.
    * Check that the endpoint is returning a 2xx response code
    * Check that the payload signature and timestamp are verified correctly. Remember not to modify the body string of the webhook before processing it.
  </Accordion>
</AccordionGroup>


# Best Practices
Source: https://docs.crossmint.com/introduction/platform/webhooks/best-practices

Best practices for implementing reliable webhook handlers

Follow these best practices to ensure your webhook implementation is reliable, secure, and performant.

## Idempotency

Crossmint webhooks follow an at-least-once delivery guarantee. Duplicate deliveries can occur (for example, if a previous attempt didn't receive a 2xx response quickly enough). Implement idempotency by:

1. Using the webhook `id` field as a unique identifier
2. Storing processed webhook IDs in your database
3. Checking if a webhook has already been processed before taking action

> **Note:** The following code examples are pseudocode for illustration purposes.

```javascript theme={null}
async function handleWebhook(webhookId, data) {
  // Check if we've already processed this webhook
  const existing = await db.webhooks.findOne({ id: webhookId });
  if (existing) {
    console.log('Webhook already processed:', webhookId);
    return;
  }
  
  // Process the webhook
  await processWebhook(data);
  
  // Mark as processed
  await db.webhooks.create({ id: webhookId, processedAt: new Date() });
}
```

## Response Time

Your webhook endpoint must respond within 15 seconds, otherwise the webhook will be resent. For long-running operations:

<Important>
  If your endpoint doesn't return a 2xx status code within 15 seconds, the delivery attempt is marked as failed and Crossmint will automatically retry with exponential backoff. This can result in duplicate deliveries (at-least-once semantics). After repeated failures, the message is marked as undeliverable and you can manually trigger redelivery from the Console. See [Add an Endpoint](/introduction/platform/webhooks/add-endpoint) for the full retry schedule.
</Important>

1. Immediately acknowledge the webhook with a 200 response
2. Queue the processing work for asynchronous execution
3. Process the webhook data in a background job

> **Note:** The following code examples are pseudocode for illustration purposes.

```javascript theme={null}
app.post('/webhooks/your-endpoint', async (req, res) => {
  // Verify signature first
  const payload = verifyWebhook(req);
  
  // Immediately acknowledge receipt
  res.status(200).json({ received: true });
  
  // Queue for background processing
  await jobQueue.add('process-webhook', {
    webhookId: payload.id,
    type: payload.type,
    data: payload.data,
  });
});
```

## Error Handling

Implement proper error handling to ensure reliable webhook delivery:

* **Return 2xx within 15 seconds** after verifying the signature to acknowledge receipt
* **Return 400** for invalid signatures to reject the webhook
* **Return 5xx** for transient internal errors to trigger automatic retries

See [Verify Webhooks](/introduction/platform/webhooks/verify-webhooks) for more details on signature verification and error handling.

## Signature Verification

Always verify webhook signatures to ensure requests are legitimate and come from Crossmint. Never process webhooks without verifying their signatures first.

See [Verify Webhooks](/introduction/platform/webhooks/verify-webhooks) for detailed instructions on signature verification.

## Related Resources

* [Add an Endpoint](/introduction/platform/webhooks/add-endpoint) - Configure webhook endpoints
* [Verify Webhooks](/introduction/platform/webhooks/verify-webhooks) - Verify webhook signatures
* [Overview](/introduction/platform/webhooks/overview) - Learn about webhooks


# Overview
Source: https://docs.crossmint.com/introduction/platform/webhooks/overview

Listen for events across wallets, payments, minting, and credentials to automatically trigger reactions in your application

Crossmint's platform operations—including wallet transactions, checkout, NFT minting, and credential issuance—often require blockchain interactions or other asynchronous processing. These operations can take anywhere from a few seconds to several minutes depending on network conditions. Webhooks allow you to listen for events across Crossmint's platform and automatically trigger reactions in your application when these operations complete.

Some cases where you may want to listen for event notifications include:

* **Wallet operations**: Track transfer approvals, transaction completions, failures, or private key exports
* **Checkout**: Monitor checkout lifecycle from quote creation to delivery completion
* **Minting operations**: Get notified when mints succeed, collections are created, or tokens are transferred
* **Credential issuance**: Receive updates when verifiable credentials are successfully issued
* **Database updates**: Automatically update your records with transaction IDs, token details, or user information
* **Customer notifications**: Send emails or push notifications when operations complete

Webhooks are how services notify each other of events. At their core, they are simply POST requests to a pre-determined endpoint. The endpoint can be any URL you choose, and you can [add them from the console](/introduction/platform/webhooks/add-endpoint).

<Tip>Your server must return a 2xx HTTP status quickly so the webhook is marked as delivered.</Tip>

## Next Steps

* [Add an Endpoint](/introduction/platform/webhooks/add-endpoint) - Configure your webhook endpoint
* [Verify Webhooks](/introduction/platform/webhooks/verify-webhooks) - Learn how to verify webhook signatures
* [Best Practices](/introduction/platform/webhooks/best-practices) - Implement reliable webhook handlers


# Verify Webhooks
Source: https://docs.crossmint.com/introduction/platform/webhooks/verify-webhooks

Verify the signature and timestamp when processing webhooks

Because of the way webhooks work, attackers can impersonate services by simply sending a fake webhook to an endpoint. Think about it: it’s just an HTTP POST from an unknown source. This can create a potential security vulnerability for many applications, or at the very least, a source of errors.

To prevent this, Crossmint signs every webhook and its metadata with a unique key for each endpoint. Use this signature to verify that the webhook indeed comes from Crossmint, and process it only if it does.

You can get the signing key secret from the Webhooks page in the console. To find it, go to the endpoint details and look for the Signing Secret section.

<img alt="Signing Secret" />

<Tabs>
  <Tab title="Using a library">
    This guide uses the Svix open-source library to verify webhooks. First, install the relevant libraries for your language:

    <CodeGroup>
      ```js JavaScript theme={null}
      npm install svix
      // Or
      yarn add svix
      ```

      ```python Python theme={null}
      pip install svix
      ```

      ```rust Rust theme={null}
      http = "1.0.0"
      svix = "1.20.0"
      ```

      ```go Go theme={null}
      go get github.com/svix/svix-webhooks/go
      ```

      ```java Java theme={null}
      // Gradle: Add this dependency to your project's build file:
      implementation "com.svix:svix:0.x.y"

      // Maven: Add this dependency to your project's POM file:
      <dependency>
      <groupId>com.svix</groupId>
      <artifactId>svix</artifactId>
      <version>0.x.y</version>
      </dependency>
      ```

      ```kotlin Kotlin theme={null}
      // Gradle: Add this dependency to your project's build file:
      implementation "com.svix.kotlin:svix-kotlin:0.x.y"

      // Maven: Add this dependency to your project's POM file:
      <dependency>
      <groupId>com.svix.kotlin</groupId>
      <artifactId>svix-kotlin</artifactId>
      <version>0.x.y</version>
      </dependency>
      ```

      ```ruby Ruby theme={null}
      gem install svix
      ```

      ```csharp C# theme={null}
      dotnet add package Svix
      ```

      ```php PHP theme={null}
      composer require svix/svix
      ```

      ```bash CLI theme={null}
      # On macOS install via Homebrew:
      brew install svix/svix/svix

      # On Linux install via Scoop:
      scoop bucket add svix https://github.com/svix/scoop-svix.git
      scoop install svix
      ```
    </CodeGroup>

    Next, verify webhooks using the code below. The payload is the raw (string) body of the request, and the headers are the headers passed in the request.

    <Warning>
      You need to use the **raw request body** when verifying webhooks, as the cryptographic signature is sensitive to even the slightest changes. Watch out for frameworks that parse the request as JSON and then stringify it, as this will break the signature verification.

      See examples below for how to get the raw request body with different frameworks.
    </Warning>

    Remember to get the signature secret from the endpoint details in the console.

    <CodeGroup>
      ```js JavaScript theme={null}
      import { Webhook } from "svix";

      const secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";

      // These were all sent from the server
      const headers = {
      "svix-id": "msg_p5jXN8AQM9LWM0D4loKWxJek",
      "svix-timestamp": "1614265330",
      "svix-signature": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=",
      };
      const payload = '{"test": 2432232314}';

      const wh = new Webhook(secret);
      // Throws on error, returns the verified content on success
      const payload = wh.verify(payload, headers);
      ```

      ```python Python theme={null}
      from svix.webhooks import Webhook

      secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"

      # These were all sent from the server
      headers = {
      "svix-id": "msg_p5jXN8AQM9LWM0D4loKWxJek",
      "svix-timestamp": "1614265330",
      "svix-signature": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=",
      }
      payload = '{"test": 2432232314}'

      wh = Webhook(secret)
      # Throws on error, returns the verified content on success
      payload = wh.verify(payload, headers)
      ```

      ```rust Rust theme={null}
      use svix::webhooks::Webhook;

      let secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw".to_string();

      let mut headers = http::HeaderMap::new();
      headers.insert("svix-id", "msg_p5jXN8AQM9LWM0D4loKWxJek");
      headers.insert("svix-timestamp", "1614265330");
      headers.insert(
          "svix-signature",
          "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=",
      );

      let payload = b"{\"test\": 2432232314}";

      let wh = Webhook::new(&secret)?;
      wh.verify(&payload, &headers)?;
      // returns Ok on success, Err otherwise
      ```

      ```go Go theme={null}
      import (
          svix "github.com/svix/svix-webhooks/go"
      )

      secret := "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"

      // These were all sent from the server
      headers := http.Header{}
      headers.Set("svix-id", "msg_p5jXN8AQM9LWM0D4loKWxJek")
      headers.Set("svix-timestamp", "1614265330")
      headers.Set("svix-signature", "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=")

      payload := []byte(`{"test": 2432232314}`)

      wh, err := svix.NewWebhook(secret)
      err := wh.Verify(payload, headers)
      // returns nil on success, error otherwise
      ```

      ```java Java theme={null}
      import com.svix.Webhook;

      String secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";

      // These were all sent from the server
      HashMap<String, List<String>> headerMap = new HashMap<String, List<String>>();
      headerMap.put("svix-id", Arrays.asList("msg_p5jXN8AQM9LWM0D4loKWxJek"));
      headerMap.put("svix-timestamp", Arrays.asList("1614265330"));
      headerMap.put("svix-signature", Arrays.asList("v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE="));
      HttpHeaders headers = HttpHeaders.of(headerMap, BiPredicate<String, String>)

      String payload = "{\"test\": 2432232314}";

      Webhook webhook = new Webhook(secret);

      webhook.verify(payload, headers)
      // throws WebhookVerificationError exception on failure.
      ```

      ```kotlin Kotlin theme={null}
      import com.svix.kotlin.Webhook

      val secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";

      // These were all sent from the server
      val headersMap = mapOf(
          "svix-id" to listOf("msg_p5jXN8AQM9LWM0D4loKWxJek"),
          "svix-timestamp" to listOf("1614265330"),
          "svix-signature" to listOf("v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=")
      )
      val headers = HttpHeaders.of(headersMap) { _, _ -> true }

      val payload = "{\"test\": 2432232314}";

      val webhook = Webhook(secret);

      webhook.verify(payload, headers)
      // throws WebhookVerificationError exception on failure.
      ```

      ```ruby Ruby theme={null}
      require 'svix'


      # These were all sent from the server
      headers = {
      "svix-id" => "msg_p5jXN8AQM9LWM0D4loKWxJek",
      "svix-timestamp" => "1614265330",
      "svix-signature" => "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE="
      }
      payload = '{"test": 2432232314}'

      wh = Svix::Webhook.new("whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw")
      # Raises on error, returns the verified content on success
      json = wh.verify(payload, headers)
      ```

      ```csharp C# theme={null}
      using Svix;
      using System.Net;

      // These were all sent from the server
      var headers = new WebHeaderCollection();
      headers.Set("svix-id", "msg_p5jXN8AQM9LWM0D4loKWxJek");
      headers.Set("svix-timestamp", "1614265330");
      headers.Set("svix-signature", "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=");
      var payload = "{\"test\": 2432232314}";

      var wh = new Webhook("whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw/Je4ZJEGP1QFb");

      // Throws on error
      wh.Verify(payload, headers);
      ```

      ```php PHP theme={null}
      // import using composers autoload
      require_once('vendor/autoload.php');
      // or manually
      require_once('/path/to/svix/php/init.php');

      // These were all sent from the server
      $payload = '{"test": 2432232314}';
      $header = array(
              'svix-id'  => 'msg_p5jXN8AQM9LWM0D4loKWxJek',
              'svix-timestamp' => '1614265330',
              'svix-signature' => 'v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=',
          );

      // Throws on error, returns the verified content on success
      $wh = new \Svix\Webhook('whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw');
      $json = $wh->verify($payload, $header);
      ```

      ```bash CLI theme={null}
      export SVIX_AUTH_TOKEN="AUTH_TOKEN"
      svix verify --secret whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw --msg-id msg_p5jXN8AQM9LWM0D4loKWxJek --timestamp 1614265330 --signature v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE= '{"test": 2432232314}'
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Manual verification">
    <Note>
      This is a manual verification process. Crossmint recommends using a library to verify webhooks automatically.
    </Note>

    If you need to verify manually, follow these instructions.

    Each webhook call includes three headers with additional information that are used for verification:

    * `svix-id`: The unique message identifier for the webhook message. This identifier is unique across all messages, but will be the same when the same webhook is resent (e.g., due to a previous failure).
    * `svix-timestamp`: Timestamp in seconds since epoch.
    * `svix-signature`: The Base64 encoded list of signatures (space delimited).

    ### Constructing the Signed Content

    The content to sign is composed by concatenating the ID, timestamp, and payload, separated by the full-stop character (`.`). In code, it will look something like this:

    ```js theme={null}
    const signedContent = `${svix_id}.${svix_timestamp}.${body}`;
    ```

    Where `body` is the raw body of the request. The signature is sensitive to any changes, so even a small change in the body will cause the signature to be completely different. This means that you should not change the body in any way before verifying.

    <Warning>
      Ensure you use the **raw request body** for verification. Parsing and re-stringifying JSON will alter the content and cause verification failure.
    </Warning>

    ### Determining the Expected Signature

    Crossmint uses HMAC with SHA-256 to sign webhooks.

    To calculate the expected signature, HMAC the `signedContent` from above using the base64 portion of your signing secret (this is the part after the `whsec_` prefix) as the key. For example, if your secret is `whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw`, use `MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw`.

    For example, this is how you can calculate the signature in Node.js:

    ```js theme={null}
    const crypto = require('crypto');

    const signedContent = `${svix_id}.${svix_timestamp}.${body}`;
    const secret = "whsec_5WbX5kEWLlfzsGNjH64I8lOOqUB6e8FH";

    // Need to base64 decode the secret
    const secretBytes = Buffer.from(secret.split('_')[1], "base64");
    const signature = crypto
    .createHmac('sha256', secretBytes)
    .update(signedContent)
    .digest('base64');

    console.log(signature);
    ```

    This generated signature should match one of the ones sent in the `svix-signature` header.

    The `svix-signature` header is a list of space-delimited signatures with version identifiers. The list is typically one item but can contain multiple signatures, like this:

    ```text theme={null}
    v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE= v1,bm9ldHUjKzFob2VudXRob2VodWUzMjRvdWVvdW9ldQo= v2,MzJsNDk4MzI0K2VvdSMjMTEjQEBAQDEyMzMzMzEyMwo=
    ```

    Make sure to remove the version prefix and delimiter (e.g. `v1,`) before verifying the signature.

    To compare the signatures, use a constant-time string comparison method to prevent timing attacks.

    ### Verify timestamp

    Crossmint includes the timestamp of the attempt in the `svix-timestamp` header. Compare this timestamp against your system timestamp to ensure it’s within an acceptable tolerance to prevent replay attacks.
  </Tab>
</Tabs>


# Supported Chains
Source: https://docs.crossmint.com/introduction/supported-chains

Tap into 50+ blockchains in one single integration

Refer to the table below to see which chains are supported for which product categories.

| Blockchain | Wallets | Checkout | Onramp | Tokenization | Offramp | Mainnet Label | Testnet Label |
| :- | :-: | :-: | :-: | :-: | :-: | :-: | :-: |
| ApeChain | ✅ | ✅ | ✱ | ✅ | - | `apechain` | `curtis` |
| Arc | ✅ | ✱ | ✱ | ✱ | - | `arc` | `arc-testnet` |
| Aptos | ✱ | ✱ | ✱ | ✅ | - | `aptos` | `aptos` |
| Arbitrum One | ✅ | ✅ | ✱ | ✅ | - | `arbitrum` | `arbitrum-sepolia` |
| Arbitrum Nova | ✅ | ✅ | ✱ | ✅ | - | `arbitrumnova` | `arbitrum-sepolia` |
| Avalanche | ✱ | ✅ | ✱ | ✅ | - | `avalanche` | `avalanche-fuji` |
| Avalanche Subnets | ✱ | ✱ | ✱ | ✱ | - | `avalanche-subnet` | `avalanche-subnet-testnet` |
| Base | ✅ | ✅ | ✅ | ✅ | ✅ | `base` | `base-sepolia` |
| BSC | ✅ | ✱ | ✱ | ✱ | - | `bsc` | `bsc-testnet` |
| Chiliz | ✱ | ✅ | ✱ | ✅ | - | `chiliz` | `chiliz-spicy-testnet` |
| Ethereum | ✱ | ✅ | ✱ | ✱ | - | `ethereum` | `ethereum-sepolia` |
| Flow | ✱ | ✅ | ✱ | ✅ | - | `flow` | `flow-testnet` |
| Mantle | ✅ | ✅ | ✱ | ✅ | - | `mantle` | `mantle-testnet` |
| Monad | ✱ | ✱ | ✱ | ✱ | - | `monad` | `monad-testnet` |
| Optimism | ✅ | ✅ | ✱ | ✅ | - | `optimism` | `optimism-sepolia` |
| Polygon | ✅ | ✅ | ✅ | ✅ | ✅ | `polygon` | `polygon-amoy` |
| Robinhood Chain | ✱ | ✱ | ✱ | ✱ | - | `robinhood-chain` | `robinhood-chain-testnet` |
| Sei | ✅ | ✅ | ✱ | ✅ | - | `sei-pacific-1` | `sei-atlantic-2-testnet` |
| Scroll | ✅ | ✅ | ✱ | ✅ | - | `scroll` | `scroll-sepolia` |
| Solana | ✅ | ✅ | ✅ | ✅ | ✅ | `solana` | `solana` |
| Stellar | ✅ | ✱ | ✅ | ✱ | - | `stellar` | `stellar-testnet` |
| Shape | ✅ | ✅ | ✱ | ✅ | - | `shape` | `shape-sepolia` |
| SKALE | ✱ | ✅ | ✱ | ✅ | - | `skale-nebula` | `skale-nebula-testnet` |
| Story | ✅ | ✱ | ✱ | ✅ | - | `story-mainnet` | `story-testnet` |
| Sui | ✱ | ✱ | ✱ | ✅ | - | `sui` | - |
| Tempo | ✅ | ✱ | ✱ | ✱ | - | `tempo` | `tempo-testnet` |
| Xion | ✱ | ✅ | ✱ | ✅ | - | `xion` | `xion-testnet` |
| Zora | ✅ | ✅ | ✱ | ✅ | - | `zora` | `zora-sepolia` |
| Other EVM chains | ✱ | ✱ | ✱ | ✱ | - | | |

**Legend:**

* `✅` Supported
* `✱` Available, but not self-serve. <a href="https://www.crossmint.com/contact/sales">Contact us</a> to request it for your project.
* `-` Not supported

Notes:

* Fungible token checkout available self service only in Solana. <a href="https://www.crossmint.com/contact/sales">Contact us</a> for other chains.
* **Offramp availability:** Solana, Polygon, and Base.
* **Onramp availability:** Solana, Polygon, and Base are supported in all regions (EU, US, and Rest of World). Stellar is supported in the EU and Rest of World, but not the US. For all other chains, <a href="https://www.crossmint.com/contact/sales">contact sales</a> to request onramp support.

<Card title="Building on a different chain?" icon="comment" href="https://www.crossmint.com/contact/sales">
  Contact us. Crossmint launches new chains regularly and yours is likely in the pipeline.
</Card>

## Testnets

You can access testnets by using the <a href="https://staging.crossmint.com/console">staging console</a>. Read more about the different environments [here](/introduction/platform/staging-vs-production).

Please refer to the supported chains table above for details about which testnet the staging environment targets. If there is not a specific testnet listed for a chain it is not supported in staging.


# Connect the Crossmint MCP Server
Source: https://docs.crossmint.com/mcp-server/connect

Let AI assistants manage your Crossmint console projects, organizations, and API keys

The Crossmint MCP server lets AI assistants such as Claude, ChatGPT, Cursor, Claude Code, and Gemini manage your Crossmint console for you. Once connected, an assistant or AI agent can list and create projects, switch organizations, and create, edit, and delete API keys on your behalf.

The server is hosted by Crossmint. There is nothing to install: you add its URL to your AI client and sign in with your Crossmint console account.

<Note>
  This server manages your console. To let an AI assistant search the Crossmint documentation instead, use the [Crossmint Docs MCP server](/introduction/ai-assistants#crossmint-docs-mcp-server).
</Note>

## Prerequisites

* **Crossmint console account**: An account in the <a href="https://staging.crossmint.com/console">staging console</a>, the <a href="https://www.crossmint.com/console">production console</a>, or both. See [Staging vs Production](/introduction/platform/staging-vs-production).
* **MCP client**: An AI client that supports remote MCP servers with OAuth.

## Server Details

| Property | Value |
| - | - |
| URL | `https://mcp.crossmint.com/mcp` |
| Transport | Streamable HTTP |
| Authentication | OAuth with dynamic client registration |
| OAuth metadata | `https://mcp.crossmint.com/.well-known/oauth-authorization-server` |

Your client registers itself and opens the Crossmint sign-in in your browser. You do not need an API key to connect.

## Add the Server to Your Client

<Tabs>
  <Tab title="Claude">
    Claude.ai and Claude Desktop add remote MCP servers as custom connectors. Free plans are limited to one custom connector.

    <Steps>
      <Step title="Add a custom connector">
        Go to **Customize > Connectors**, select **+ Add**, then **Add custom connector**. On Team and Enterprise plans, an Owner first adds the connector in **Organization settings > Connectors**.
      </Step>

      <Step title="Enter the server URL">
        Name the connector `Crossmint`, enter `https://mcp.crossmint.com/mcp`, and select **Continue**. Keep the authentication settings Claude detects.
      </Step>

      <Step title="Connect and enable">
        Finish adding the connector and [sign in](#sign-in). In a conversation, enable the connector from the **+** button, then **Connectors**.
      </Step>
    </Steps>

    Source: <a href="https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp">Claude custom connectors</a>.
  </Tab>

  <Tab title="ChatGPT">
    ChatGPT adds remote MCP servers as custom MCP servers. Account and workspace policies apply.

    <Steps>
      <Step title="Add a custom MCP server">
        Go to <a href="https://chatgpt.com/plugins">ChatGPT Plugins</a>, select the plus button, then **Add custom MCP server**.
      </Step>

      <Step title="Enter the server details">
        Enter `Crossmint` as the name and `https://mcp.crossmint.com/mcp` as the URL under **Connection**. Choose OAuth authentication, review the risk warning, and select **I understand and want to continue**.
      </Step>

      <Step title="Create and sign in">
        Select **Create as a plugin** and [sign in](#sign-in). In a conversation, type `@` and select the Crossmint plugin.
      </Step>
    </Steps>

    Source: <a href="https://developers.openai.com/apps-sdk/deploy/connect-chatgpt">Connect from ChatGPT</a>.
  </Tab>

  <Tab title="Cursor">
    <a href="cursor://anysphere.cursor-deeplink/mcp/install?name=crossmint&config=eyJ1cmwiOiJodHRwczovL21jcC5jcm9zc21pbnQuY29tL21jcCJ9">Add the Crossmint MCP server to Cursor</a> with one click, or add it to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):

    ```json mcp.json theme={null}
    {
        "mcpServers": {
            "crossmint": {
                "url": "https://mcp.crossmint.com/mcp"
            }
        }
    }
    ```

    When Cursor connects to the server for the first time, complete the [sign-in](#sign-in).

    Source: <a href="https://cursor.com/docs/mcp">Cursor MCP</a> and <a href="https://cursor.com/docs/mcp/install-links">Cursor install links</a>.
  </Tab>

  <Tab title="Claude Code">
    Add the server:

    ```bash theme={null}
    claude mcp add --transport http crossmint https://mcp.crossmint.com/mcp
    ```

    Start Claude Code, run `/mcp`, select `crossmint`, and [sign in](#sign-in). You can also sign in from your shell with `claude mcp login crossmint`.

    Source: <a href="https://code.claude.com/docs/en/mcp">Claude Code MCP</a>.
  </Tab>

  <Tab title="VS Code">
    Run **MCP: Add Server** from the Command Palette, choose **HTTP**, enter `https://mcp.crossmint.com/mcp`, and name the server `crossmint`. To share the server with your team, add it to `.vscode/mcp.json` in your project:

    ```json .vscode/mcp.json theme={null}
    {
        "servers": {
            "crossmint": {
                "type": "http",
                "url": "https://mcp.crossmint.com/mcp"
            }
        }
    }
    ```

    When VS Code starts the server for the first time, complete the [sign-in](#sign-in).

    Source: <a href="https://code.visualstudio.com/docs/copilot/customization/mcp-servers">VS Code MCP servers</a>.
  </Tab>

  <Tab title="Codex">
    Add the server and sign in:

    ```bash theme={null}
    codex mcp add crossmint --url https://mcp.crossmint.com/mcp
    codex mcp login crossmint
    ```

    Source: <a href="https://developers.openai.com/codex/mcp">Codex MCP</a>.
  </Tab>

  <Tab title="Gemini CLI">
    Add the server:

    ```bash theme={null}
    gemini mcp add --transport http crossmint https://mcp.crossmint.com/mcp
    ```

    Start Gemini CLI and run `/mcp auth crossmint` to [sign in](#sign-in).

    Source: <a href="https://geminicli.com/docs/tools/mcp-server/">Gemini CLI MCP servers</a>.
  </Tab>

  <Tab title="Windsurf">
    Open the MCP settings in Windsurf and add the server to `~/.codeium/windsurf/mcp_config.json`:

    ```json mcp_config.json theme={null}
    {
        "mcpServers": {
            "crossmint": {
                "serverUrl": "https://mcp.crossmint.com/mcp"
            }
        }
    }
    ```

    When Windsurf connects to the server for the first time, complete the [sign-in](#sign-in).

    Source: <a href="https://docs.windsurf.com/windsurf/cascade/mcp">Windsurf MCP</a>.
  </Tab>

  <Tab title="Other clients">
    Clients that support remote MCP servers with OAuth connect to `https://mcp.crossmint.com/mcp` directly. For clients that only run local MCP servers, use the <a href="https://www.npmjs.com/package/mcp-remote">mcp-remote</a> proxy, which runs locally and opens the [sign-in](#sign-in) in your browser:

    ```json theme={null}
    {
        "mcpServers": {
            "crossmint": {
                "command": "npx",
                "args": ["-y", "mcp-remote", "https://mcp.crossmint.com/mcp"]
            }
        }
    }
    ```
  </Tab>
</Tabs>

## Sign In

When your client connects for the first time, it opens the Crossmint sign-in in your browser.

<Steps>
  <Step title="Choose an environment">
    Select **Production** or **Staging**. The connection works in that environment only. See [Staging vs Production](/introduction/platform/staging-vs-production).
  </Step>

  <Step title="Sign in to the Crossmint console">
    Sign in to the console of the environment you selected, as you do in the browser.
  </Step>

  <Step title="Choose an organization">
    Select the organization the connection starts in, then select **Authorize**. If the organization requires MFA or SSO, the console asks you to complete it.
  </Step>
</Steps>

When the browser shows **You are all set**, return to your client. To check the connection, ask the assistant which Crossmint account it is connected to. The assistant calls `whoami`, which returns your email, environment, and organization.

<Warning>
  The connection has full access to the organization you select: read and write access to all of its projects, with the permissions of your console account. That includes creating and deleting API keys.
</Warning>

## Switch Organization or Environment

A connection works in one environment and one organization at a time.

* **Organization**: Ask the assistant to switch organization. It calls `orgs_list` and `orgs_select`. If the organization requires MFA or SSO, the assistant returns a link instead: open it in your browser and complete the step in the console.
* **Environment**: Ask the assistant to work in the other environment. It calls `env_select`, which returns a link: open it in your browser, sign in to that environment with the same email, and choose an organization. You can also remove the server from your client and connect again.

Links from `orgs_select` and `env_select` work once and expire after 10 minutes. After a switch, project IDs from the previous organization or environment no longer apply: ask the assistant to list the projects again.

## Example Prompts

* "Which Crossmint organization am I connected to?"
* "List my Crossmint projects."
* "Create a project called Loyalty App and a server API key in it with the `wallets.read` and `wallets.create` scopes."
* "Show me the client keys of my Loyalty App project."
* "Switch to my Acme organization."
* "Delete the API key I created yesterday in Loyalty App."

For the full list of tools and parameters, see [Crossmint MCP Server Tools](/mcp-server/tools).

## Security

* **Review tool calls**: Keep your client set to ask for approval before it runs tools, and review each call before you approve it, especially in production.
* **Deleting keys cannot be undone**: `keys_delete` only deletes a key when called with `confirm: true`. Any application that uses a deleted key stops working.
* **Production server secrets are shown once**: `keys_create` returns the secret of a production server key, and `keys_list` masks it afterwards. Store the secret before you close the conversation, and treat the conversation history as sensitive.
* **Prompt injection**: Content from other tools, files, or websites can contain instructions aimed at your assistant. Do not connect the Crossmint MCP server alongside sources you do not trust.
* **Use staging to experiment**: Connect to staging when you try the server out or automate tasks for the first time.
* **Use the official URL**: Only connect to `https://mcp.crossmint.com/mcp`.

A connection stays signed in for up to 30 days. Removing the server from your client stops that client from using it, but the server only revokes the connection credentials when the client sends a revocation request. Credentials that are not revoked expire within 30 days.

## Troubleshooting

<AccordionGroup>
  <Accordion title="This sign-in expired or was started in another browser">
    The sign-in must finish in the browser where it started, within 10 minutes. Connect again from your client and complete the sign-in in the browser it opens.
  </Accordion>

  <Accordion title="This link expired or was already used">
    Links from `orgs_select` and `env_select` work once and expire after 10 minutes. Ask the assistant for a new link.
  </Accordion>

  <Accordion title="Signed in as another account">
    An environment switch link belongs to the email the connection is signed in with. Sign out of the console of that environment, sign in with the same email, and open the link again.
  </Accordion>

  <Accordion title="The assistant cannot find a project">
    Project IDs belong to one organization and environment. Ask the assistant to call `whoami` and list the projects again.
  </Accordion>

  <Accordion title="The Crossmint session has ended">
    A connection stays signed in for up to 30 days. When the console session ends, connect again from your client.
  </Accordion>

  <Accordion title="Too many sign-in attempts">
    Wait a few minutes, then connect again.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Tools Reference" icon="wrench" href="/mcp-server/tools">
    Every tool the Crossmint MCP server exposes
  </Card>

  <Card title="Crossmint CLI" icon="terminal" href="/cli/install">
    Manage projects and API keys from your terminal
  </Card>
</CardGroup>


# Crossmint MCP Server Tools
Source: https://docs.crossmint.com/mcp-server/tools

Reference for the tools the Crossmint MCP server exposes to AI assistants

The Crossmint MCP server exposes the following tools. Your AI assistant chooses which tool to call based on your request. To connect a client, see [Connect the Crossmint MCP Server](/mcp-server/connect).

A connection is signed in to one environment (production or staging) and one organization. Every tool runs in that environment and organization.

## Session

| Tool | Description | Parameters |
| - | - | - |
| `whoami` | Returns the signed-in email, the environment, and the active organization. | None |
| `env_select` | Returns a link to open in a browser to move the connection to another environment. In the browser, you sign in to that environment and choose an organization. | `environment`: `production` or `staging` |

## Organizations

| Tool | Description | Parameters |
| - | - | - |
| `orgs_list` | Lists the organizations you belong to and the ID of the active one. | None |
| `orgs_current` | Returns the active organization. | None |
| `orgs_select` | Switches the connection to another organization. For an organization that requires MFA or SSO, returns a link to open in a browser instead. | `organizationId`: as listed by `orgs_list` |

## Projects

The server does not keep a selected project. `projects_details` and every API key tool take the `projectId` of the project to work on, as returned by `projects_list` or `projects_create`. Project IDs belong to one organization and environment: after a switch, list the projects again.

| Tool | Description | Parameters |
| - | - | - |
| `projects_list` | Lists the projects in the active organization. | None |
| `projects_details` | Returns the details of a project. | `projectId` |
| `projects_create` | Creates a Smart Wallets project in the active organization and returns its ID. | `name` |

## API Keys

| Tool | Description | Parameters |
| - | - | - |
| `keys_list` | Lists the API keys of a project. Production server key secrets are masked. | `projectId`, `type` (optional): `server` or `client` |
| `keys_create` | Creates an API key in a project. A production server key secret is only returned in this response. | `projectId`, `usageOrigin`, `scopes`, `clientType`, `whitelistedOrigins`, `whitelistedAppIdentifiers` |
| `keys_edit` | Replaces the scopes of an API key. | `projectId`, `keyId`, `scopes` |
| `keys_delete` | Deletes an API key. The deletion cannot be undone. | `projectId`, `keyId`, `confirm`: must be `true` |

### `keys_create` Parameters

| Parameter | Description |
| - | - |
| `projectId` | The project to create the key in. |
| `usageOrigin` | `server` for a key used from a backend, or `client` for a key used from an app. |
| `scopes` | The [API key scopes](/introduction/platform/api-keys/scopes), for example `wallets.read`. The server rejects scopes the key cannot have and returns the allowed list. |
| `clientType` | Client keys only: `web`, `mobile`, or `desktop`. |
| `whitelistedOrigins` | Web client keys only: the allowed origins, for example `https://www.yourdomain.com`. |
| `whitelistedAppIdentifiers` | Mobile client keys only: the iOS bundle IDs or Android package names allowed to use the key. |

`keys_edit` replaces the full list of scopes. To add a scope, pass the existing scopes and the new one.

## See Also

<CardGroup>
  <Card title="Connect the MCP Server" icon="plug" href="/mcp-server/connect">
    Add the Crossmint MCP server to your AI client
  </Card>

  <Card title="API Keys" icon="key" href="/introduction/platform/api-keys/scopes">
    Scopes available to server and client keys
  </Card>
</CardGroup>


# Overview
Source: https://docs.crossmint.com/minting/introduction

Mint and distribute tokens at scale, reliably

**It takes months to build secure and reliable minting infrastructure:**

1. Write and maintain token smart contracts
2. Build a backend for orchestrating all blockchain transactions
3. Securely administer keys and crypto balances to pay for gas fees
4. Add queueing, batching, RPC redundancy, priority gas fee estimations, and e2e observability

**Crossmint manages all of this for you via a suite of APIs to create, update, delete and manage tokens of any type through REST APIs, available on any chain.**

## Key Characteristics

<CardGroup>
  <Card title="Get started in 5 minutes" icon="bolt">
    Simple APIs to help you launch faster.
  </Card>

  <Card title="No blockchain experience required" icon="lightbulb">
    Forget about smart contracts, IPFS, wallets, and admin key management.
  </Card>

  <Card title="Modular platform" icon="unlock-keyhole">
    Let Crossmint handle all the infrastructure, or combine it with your own.
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Best-in-class security" icon="shield">
    SOC-II certified with audited smart contracts.
  </Card>

  <Card title="Ready to scale" icon="gauge-high">
    Handle millions of tokens an hour and save on customer support.
  </Card>

  <Card title="Multi-chain" icon="wand-magic-sparkles">
    Tap into 50+ chains with one single integration.
  </Card>
</CardGroup>

## Quickstarts

<CardGroup>
  <Card title="Non-Fungible Tokens (NFTs)" icon="bolt" href="/minting/quickstarts/nfts">
    Mint and verify unique digital assets you can own, transfer, and verify in under minutes.
  </Card>

  <Card title="Semi-Fungible Tokens (SFTs)" icon="bolt" href="/minting/quickstarts/sfts">
    Mint limited sets of identical digital assets in under 5 minutes.
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Verifiable Credentials (VCs)" icon="bolt" href="/minting/quickstarts/credentials">
    Mint credentials that users control, share, and verify anywhere in under 5 minutes.
  </Card>

  <Card title="Intellectual Property (IP)" icon="bolt" href="/minting/quickstarts/ip">
    Mint IP credentials for creators to secure their work, in under 5 minutes.
  </Card>
</CardGroup>

## Get Started

<CardGroup>
  <Card title="Console" icon="table-columns" href="https://www.crossmint.com/console">
    Get API keys and manage collections.
  </Card>

  <Card title="API Reference" icon="terminal" href="/api-reference/minting/nfts/mint-nft">
    Test any API in seconds directly from the docs.
  </Card>

  <Card title="Talk to an expert" icon="message" href="https://www.crossmint.com/contact/sales">
    Contact our sales team for advanced support.
  </Card>
</CardGroup>

## FAQs

<AccordionGroup>
  <Accordion title="Is there vendor lock-in?">
    No, you can migrate providers anytime, transfering ownership of the smart contracts to an external wallet.
  </Accordion>

  <Accordion title="Can I transfer ownership of the smart contract to an external wallet?">
    Yes, you can transfer ownership at any time. However, note that Crossmint APIs (eg. minting, editing NFTs) may
    stop working on that contract unless you whitelist Crossmint on the contract to continue executing those
    actions. If you transfer ownership of the contract to your own wallet, you are responsible for ensuring the
    security of that wallet.
  </Accordion>

  <Accordion title="How does Crossmint manage billing?">
    When you create an account, Crossmint automatically creates a gas station to manage network fees on your behalf. You will be billed in fiat and Crossmint will ensure you never run out of funds to support customer operations. This eliminates the need to build a cryptoaccounting system, execute recurring and expensive crypto purchases, holding the FX risk, and automating treasury operations.
  </Accordion>

  <Accordion title="How does Crossmint manage minting keys?">
    When you create an account, Crossmint will automatically create a dedicated MPC vault to secure your token contracts which you can manage via API. You get one vault per <Tooltip>project</Tooltip>, in case you are working with multiple teams. You can <Tooltip>transfer ownership</Tooltip> of the contracts to an external wallet at any time.
  </Accordion>
</AccordionGroup>


# Bring Your Own Contract
Source: https://docs.crossmint.com/minting/nfts/integrate/bring-your-own-contract

Use Crossmint's infrastructure with your own smart contract

Crossmint allows you to use your own smart contract while leveraging our infrastructure for minting NFTs. This guide will walk you through the process of integrating your custom smart contract with Crossmint.

## Prerequisites

Before you can use your own smart contract with Crossmint, ensure that:

1. Your smart contract has a **free minting function** that allows Crossmint to mint NFTs without paying any fees.
2. Your smart contract complies with the **ERC721 standard** (for NFTs) or **ERC1155 standard** (for SFTs).

<Warning>
  Currently, this feature is only available for EVM chains. Support for Solana and other chains is coming soon.
</Warning>

## Integration Guide

### 1. Register Your Smart Contract

First, you need to register your smart contract at the Crossmint Console:

1. Navigate to **Token collections** > **New Collection**
2. Enter the required collection information
3. Select **Import an existing contract**
4. Pick the chain, provide the contract address, and fill in the necessary information (i.e. ABI, mint function)
5. Keep track of the Crossmint collection ID generated for future mint calls

### 2. Contract Review

After registering your contract, the Crossmint team will review it to ensure compatibility with our infrastructure. This typically takes 1-2 business days.

<Note>
  During the review process, we'll verify that your contract has the necessary free minting function and complies with
  the required standards.
</Note>

### 3. Mint NFTs

Once your contract is approved, you can start minting NFTs using Crossmint's [Mint API](/api-reference/minting/nfts/mint-nft) and passing the following:

1. `recipient`, which is the recipient's wallet/email/X account user locators
2. `contractArguments`, which is an object where the keys are the argument names from the mint function, and the values are their values. Omit the recipient argument from this object

```bash cURL theme={null}
curl --request POST \
  --url https://staging.crossmint.com/api/2022-06-09/collections/{collectionId}/nfts \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '{
  "recipient": "polygon-amoy:0x123...",
  "contractArguments": {
    "tokenId": "42"
  }
}'
```

## Best Practices

When using your own smart contract with Crossmint:

1. **Test Thoroughly**: Test your contract integration in the staging environment before moving to production.
2. **Function Visibility**: Ensure your minting function has the appropriate visibility and access controls.
3. **Gas Optimization**: Optimize your contract to minimize gas costs for minting operations.
4. **Error Handling**: Implement proper error handling in your contract to provide meaningful error messages.

## FAQs

<AccordionGroup>
  <Accordion title="Can I use an existing deployed contract?">
    Yes, you can use an existing deployed contract as long as it meets the prerequisites mentioned above.
  </Accordion>

  <Accordion title="What if my contract doesn't have a free minting function?">
    Your contract must have a function that allows Crossmint to mint NFTs without paying any fees. If your contract
    doesn't have this, you'll need to modify it or deploy a new version.
  </Accordion>

  <Accordion title="Can I use Crossmint's email delivery with my own contract?">
    Yes, you can still use Crossmint's email delivery system with your own contract. Just specify an email recipient
    in the mint request.
  </Accordion>

  <Accordion title="How do I handle token IDs with my custom contract?">
    Token ID management depends on your contract implementation. You can either pass a specific token ID as a
    parameter or let your contract handle token ID assignment internally.
  </Accordion>
</AccordionGroup>


# Configure Admin Functions
Source: https://docs.crossmint.com/minting/nfts/integrate/configure-admin-functions

Manage token controls including admin burn and admin transfer

Crossmint provides admin functions that allow you to control your NFTs throughout their lifecycle.

## Admin Transfer

The NFT Admin Transfer API allows collection owners to transfer NFTs between user wallets.

<Note>
  Admin transfers only work for Solana cNFTs. [Contact us](https://www.crossmint.com/contact/sales) if you want to
  access to this API.
</Note>

## Admin Burn

The [Burn NFT API](/api-reference/minting/nfts/burn-nft) allows collection owners to permanently remove NFTs from circulation.

<Warning>Once an NFT is burned, this action cannot be reversed.</Warning>

## Requirements

To use admin functions:

1. Your collection must be of a supported type (Solana cNFTs for transfers, Solana cNFTs or EVM for burns)
2. Your API key must have the appropriate scopes (`nfts.transfer` for transfers, `nfts.delete` for burns)
3. You must be the collection owner or have admin privileges


# Create Collections
Source: https://docs.crossmint.com/minting/nfts/integrate/create-collections

Deploy smart contracts and NFT collections

A collection is a container of NFTs, used by applications like marketplaces and wallets to group NFTs together.

Crossmint allows you to create managed collections via API or directly from the console. Crossmint has a library of pre-audited smart contracts which work for most major use cases. However, you can also [bring your own contract](/minting/nfts/integrate/bring-your-own-contract) if you already have one.

Crossmint supports non-fungible and semi-fungible tokens (editions), free and paid mints, and builds on open ERC and Metaplex standards. On EVM chains, ERC-721 and ERC-1155 contracts are supported, while on Solana, Metaplex standard programs and compressed NFT programs are supported.

<Note>See the list of supported blockchains [here](/introduction/supported-chains)</Note>

## 1. Create and Deploy an NFT collection

The first time you mint an NFT on a specific blockchain, Crossmint will assign it, and any subsequent mints, to a default collection for that chain. You can create additional collections from the console or in a single API call (requires the API key scope `collections.create`):

```bash cURL theme={null}
curl --request POST \
     --url https://staging.crossmint.com/api/2022-06-09/collections/ \
     --header 'content-type: application/json' \
     --header 'x-api-key: <X_API_KEY>' \
     --data '
{
  "chain": "polygon",
  "metadata": {
    "name": "A new collection",
    "imageUrl": "https://www.crossmint.com/assets/crossmint/logo.png",
    "description": "A new collection with its own dedicated smart contract"
  }
}
'
```

<Note>
  The collection details you provide will be displayed to your customers on marketplaces and other interfaces.
</Note>

<Accordion title="Sell your collection items">
  If you intend to sell the NFTs in your collection, read the guide on [how to enable
  payments](/minting/nfts/integrate/list-for-sale) first.
</Accordion>

## 2. Check the status of your collection

It takes a few seconds (up to a minute, depending on the blockchain and how congested it is) to deploy a collection.

You can use the following API to check what the status of a collection is. For example:

<CodeGroup>
  ```bash cURL theme={null}
  # Set your variables
  API_KEY="<YOUR_API_KEY>"
  ENV="staging" # or "www" for production
  ACTION_ID="<ACTION_ID>"

  curl --request GET \
    --url "https://${ENV}.crossmint.com/api/2022-06-09/actions/${ACTION_ID}" \
    --header "X-API-KEY: ${API_KEY}"
  ```

  ```javascript checkStatus.js theme={null}
  const apiKey = "<YOUR_API_KEY>";
  const env = "staging"; // or "www" for production
  const actionId = "<ACTION_ID>";

  const url = `https://${env}.crossmint.com/api/2022-06-09/actions/${actionId}`;
  const options = {
      method: "GET",
      headers: { "X-API-KEY": apiKey },
  };

  fetch(url, options)
      .then((response) => response.json())
      .then((response) => console.log(response))
      .catch((err) => console.error(err));
  ```
</CodeGroup>

## 3. List all collections under your project

```bash cURL theme={null}
curl --request GET \
     --url https://staging.crossmint.com/api/2022-06-09/collections/ \
     --header 'x-client-secret: <CLIENT_SECRET>' \
     --header 'x-project-id: <PROJECT_ID>'
```

<CardGroup>
  <Card title="API Reference" icon="terminal" href="/api-reference/minting/collection/create-collection">
    Test any API in seconds directly from the docs.
  </Card>

  <Card title="Talk to an expert" icon="message" href="https://www.crossmint.com/contact/sales">
    Contact our sales team for support.
  </Card>
</CardGroup>


# Define Metadata
Source: https://docs.crossmint.com/minting/nfts/integrate/define-metadata

Understand NFT metadata standards & storage options

Metadata in the context of NFTs includes essential information such as the name, description, and media (e.g., images, videos) associated with the asset.

### Metadata Standards

Collection and NFT metadata (e.g. title, description, image) must be specified in JSON format and follow industry conventions to ensure it renders appropriately across wallets and marketplaces.

Crossmint supports rich metadata like audio, video, and HTML. To include rich metadata, simply populate `animation_url` as specified in the links below.

<Card title="File size limits" icon="file">
  Crossmint's standard plan has a **10mb** file size limit. For larger uploads, you must upgrade to a [premium
  plan](https://www.crossmint.com/contact/sales) or handle the upload yourself.
</Card>

Metadata standards differ slightly across blockchains:

<Tabs>
  <Tab title="EVM chains">
    EVM chains follow the OpenSea standard. Refer to their <a href="https://docs.opensea.io/docs/metadata-standards#metadata-structure">official documentation</a> to see what attributes can be included and how. Note that `name` and `image` are mandatory fields.

    ```json EVM Metadata Example theme={null}
    {
      "name": "Crossmint Test NFT",
      "description": "Created with the Crossmint minting API",
      "image": "https://bafkreiexjl6kw4khdxkrt6dojgacscnzvrys47t472l2t7d6r2ss65kifq.ipfs.nftstorage.link/",
      "external_url": "https://docs.crossmint.com",
      "attributes":  [
        {
          "trait_type": "background",
          "value": "black"
        },
        {
          "trait_type": "flavor",
          "value": "minty"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Solana">
    Solana follows the Metaplex Metadata Standard. For more information, refer to the <a href="https://docs.metaplex.com/programs/token-metadata/changelog/v1.0#json-structure">official Metaplex documentation</a> - see the JSON structure section.

    ```json Solana Metadata Example theme={null}
    {
      "name": "Crossmint Test NFT",
      "symbol": "XMINT",
      "description": "Created with the Crossmint minting API",
      "seller_fee_basis_points": 5000,
      "image": "https://bafkreiexjl6kw4khdxkrt6dojgacscnzvrys47t472l2t7d6r2ss65kifq.ipfs.nftstorage.link/",
      "attributes": [
        {
          "trait_type": "background",
          "value": "black"
        },
        {
          "trait_type": "flavor",
          "value": "minty"
        }
      ],
      "properties": {
        "files": [
          {
            "uri": "https://bafkreiexjl6kw4khdxkrt6dojgacscnzvrys47t472l2t7d6r2ss65kifq.ipfs.nftstorage.link/",
            "type": "image/png"
          }
        ],
        "category": "image",
        "creators": [
          {
            "address": "xm2Mc3HEd2bGJXeqJEBrek4bj79gxzYkBaEobnpFraH",
            "share": 100
          }
        ]
      }
    }
    ```
  </Tab>

  <Tab title="Aptos">
    Aptos follows the Aptos Legacy Token Standard. For more information, refer to the <a href="https://aptos.dev/standards/aptos-token/">official Aptos Documentation</a> - see the JSON structure section.

    ```json Aptos Metadata Example theme={null}
    {
      "name": "Crossmint Test NFT",
      "description": "Aptos Attributes Test",
      "image": "https://www.arweave.net/abcd5678?ext=png",
      "animation_url": "https://www.arweave.net/efgh1234?ext=mp4",
      "external_url": "https://petra.app/",
      "attributes": [
        {
          "trait_type": "web",
          "value": "yes"
        },
        {
          "trait_type": "mobile",
          "value": "yes"
        },
        {
          "trait_type": "extension",
          "value": "yes"
        }
      ],
      "properties": {
        "files": [
          {
            "uri": "https://www.arweave.net/abcd5678?ext=png",
            "type": "image/png"
          },
          {
            "uri": "https://watch.videodelivery.net/9876jkl",
            "type": "unknown",
            "cdn": true
          },
          {
            "uri": "https://www.arweave.net/efgh1234?ext=mp4",
            "type": "video/mp4"
          }
        ],
        "category": "video"
      }
    }
    ```
  </Tab>
</Tabs>

## Crossmint Metadata Storage

Metadata must be stored somewhere to be accessible and verifiable on the blockchain. Crossmint automatically uploads and validates metadata for you on decentralized storage solutions, ensuring a seamless minting experience.

### Supported Storage Providers

Crossmint supports two primary storage providers:

* **IPFS (InterPlanetary File System)** (Default): A widely adopted decentralized storage standard ensuring compatibility across blockchain ecosystems by enabling peer-to-peer file storage and retrieval.
* **Walrus Network**: A new decentralized storage solution designed for efficient and scalable metadata hosting. Walrus is currently not supported for EVM NFT templates.

<Note>If you are interested in using **Arweave** for metadata storage, please contact us for further information.</Note>

### Configuring Storage

By default, Crossmint uses IPFS to store metadata and media. However, if you prefer to use Walrus, you can configure this in the [Crossmint Console](https://staging.crossmint.com/console) under **Settings > General**.

<img alt="Storage Providers" />

<Note>
  If you prefer to upload and manage media files independently, you can pass a direct URL to the [Mint API](/api-reference/minting/nfts/mint-nft)
  and set the `reuploadLinkedFiles` flag to `false`. This prevents Crossmint from automatically reuploading media files
  to decentralized storage.
</Note>

***

## FAQs

<AccordionGroup>
  <Accordion title="What type of files can I store?">
    You may store any text and image file. Additionally, you may include multi-media files such as GLTF, GLB, WEBM, MP4, M4V, OGV, and OGG, along with the audio-only extensions MP3, WAV, and OGA. Please stored them as `animation_url`.

    In addition, `animation_url` also supports HTML pages, allowing you to build rich experiences and interactive NFTs using JavaScript canvas, WebGL, and more. Scripts and relative paths within the HTML page are also supported. However, access to browser extensions is not supported.
  </Accordion>

  <Accordion title="What's the maximum file size?">
    The maximum file size is 10mb. For larger files, you must upgrade to an enterprise plan or upload the metadata yourself and pass the URI to the API.
  </Accordion>

  <Accordion title="Can I store the metadata on a centralized server?">
    Yes. You must handle the upload yourself and pass the URL to the API.
  </Accordion>
</AccordionGroup>


# List for Sale
Source: https://docs.crossmint.com/minting/nfts/integrate/list-for-sale

Configure royalties and marketplace profiles for your NFT collections

When selling NFTs on secondary markets, you can configure royalties to receive a percentage of each sale and optimize your collection's marketplace profile to attract buyers.

## Sell Tokens

The [Mint Tokens guide](/minting/nfts/integrate/mint-tokens) showed you how to create different types of non-fungible assets.
In this guide you will learn how to enable Crossmint's Checkout so you
can sell them to your customers using cryptocurrency or credit card.

### How It Works

* You can set a price in crypto (ETH, MATIC, SOL or USDC).
* For imported and secondary collections, payouts arrive instantly. For managed collections, payouts arrive after a 24-hour withholding period.
* Your customers can pay with crypto or credit card.
* You pay credits for NFT gas, user pays only for the item.

### Configure a Collection for Sale

<Tabs>
  <Tab title="Using the console">
    1. [Create an NFT collection](/minting/nfts/integrate/create-collections) and navigate
       to it in the console.

    2. Upload NFT "templates" for all the NFTs you wish to list for sale. You
       can do so from the "NFTs" tab in the console, or by using
       [the API](/api-reference/minting/template/create-template).

    3. Navigate to the `Checkout` entry on the navbar in the collections page.
       Follow the wizard to enable payments.

    4. (Production only) [Verify your account and collection](/introduction/platform/account-verification). Not required in staging.

    5. Share the url or QR code with your users.
  </Tab>

  <Tab title="Using the API">
    **Enable at collection creation time**

    Pass a `payments` object to the [Collection Creation
    API](/api-reference/minting/collection/create-collection) with the<Tooltip>
    `price`</Tooltip>, <Tooltip>
    `recipientAddress`</Tooltip> and <Tooltip>`currency`</Tooltip>. You can optionally set up a <Tooltip>
    `supplyLimit`</Tooltip> to cap the collection supply.

    <Accordion title="See example">
      The following snippet creates a new sales-enabled collection:

      <CodeGroup>
        ```bash cURL theme={null}
        curl --request POST \
            --url https://staging.crossmint.com/api/2022-06-09/collections/ \
            --header 'Content-Type: application/json' \
            --header 'X-API-KEY: <api-key>' \
            --data '{
            "chain": "polygon",
            "fungibility": "non-fungible",
            "metadata": {
            "description": "This is a sample NFT collection",
            "imageUrl": "https://www.crossmint.com/assets/crossmint/logo.png",
            "name": "Sample NFT Collection",
            },
            "payments": {
            "price": "<string>",
            "recipientAddress": "<string>",
            "currency": "usdc"
            },
            "supplyLimit": 123
        }'
        ```
      </CodeGroup>
    </Accordion>

    **Enable on an existing collection**

    If you had already created a collection, use the [Update Collection API](/api-reference/minting/collection/update-collection) to enable sales on it.

    <Note>Enabling sales in production requires [verifying your account](/introduction/platform/account-verification).</Note>
  </Tab>
</Tabs>

***

### Set Up a Checkout

Now that your collection accepts payments, the next step is to integrate one of
Crossmint's [Checkout](/payments/introduction) variants into your app
or website, and start accepting sales.

There are two ways to integrate:

<CardGroup>
  <Card title="Hosted Checkout" icon="toggle-on" href="/payments/pay-button/overview">
    Add a button to your site which opens a checkout in a pop-up or new tab.
  </Card>

  <Card title="Embedded Checkout" icon="object-group" href="/payments/embedded/overview">
    Insert a checkout inside your site for maximum control over the user experience.
  </Card>
</CardGroup>

## Set Collection Royalties

With royalties, you can receive revenue when your NFTs are traded on secondary markets. Crossmint allows you to configure royalties for a collection via API and (soon) directly from the console. You just have to specify the % of royalties and where you want those funds to be sent.

Royalties are defined at the collection level, not at the NFT level. Updating the royalties of a collection will update all NFTs, including the ones which have already been minted.

This API follows royalty standards compatible with virtually all marketplaces. However, note that some marketplaces have determined to not honor royalties, so transactions occuring there may not generate additional revenue.

<Warning>
  Available self-serve for ERC-721 collections in EVM chains. Please [contact
  us](https://www.crossmint.com/contact/sales) for ERC-1155 or Solana support.
</Warning>

| Endpoint | Description | |
| :- | :- | :- |
| [Add / Edit Royalties](/api-reference/minting/collection/set-royalties) | Add or edit royalties | |
| [Get Royalty Information](/minting/nfts/integrate/list-for-sale#get-royalty-information) | Get royalty information | |
| [Disable Royalties](/minting/nfts/integrate/list-for-sale#disable-royalties) | Disable royalties | |

### Add / Edit Royalties

To add or edit royalties for a collection, use the following API endpoint:

```bash cURL theme={null}
curl --request POST \
  --url https://staging.crossmint.com/api/v1-alpha1/minting/collections/{collectionId}/royalties \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '{
  "recipients": [
    {
      "address": "0x123...",
      "basisPoints": 5
    }
  ]
}'
```

### Get Royalty Information

To retrieve the current royalty configuration for a collection:

```bash cURL theme={null}
curl --request GET \
  --url https://staging.crossmint.com/api/v1-alpha1/minting/collections/{collectionId}/royalties \
  --header 'X-API-KEY: <api-key>'
```

### Disable Royalties

To disable royalties for a collection:

```bash cURL theme={null}
curl --request DELETE \
  --url https://staging.crossmint.com/api/v1-alpha1/minting/collections/{collectionId}/royalties \
  --header 'X-API-KEY: <api-key>'
```

## Implementation Examples

<Accordion title="Setting up royalties for a new collection">
  ```javascript theme={null}
  // Example: Setting up royalties for a new collection
  const apiKey = "YOUR_API_KEY";
  const collectionId = "your-collection-id";
  const env = "staging"; // or "www" for production

  // Define royalty recipients
  const royaltyRecipients = [
    {
      address: "0x123abc...", // Creator wallet
      basisPoints: 5 // 5% royalty
    },
    {
      address: "0x456def...", // Community fund wallet
      basisPoints: 2.5 // 2.5% royalty
    }
  ];

  // Set up royalties
  const url = `https://${env}.crossmint.com/api/v1-alpha1/minting/collections/${collectionId}/royalties`;
  const options = {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-KEY": apiKey
    },
    body: JSON.stringify({
      recipients: royaltyRecipients
    })
  };

  fetch(url, options)
    .then(response => response.json())
    .then(data => console.log("Royalties configured:", data))
    .catch(error => console.error("Error configuring royalties:", error));
  ```
</Accordion>

## Marketplace Profile

Optimizing your collection's profile on marketplaces like OpenSea, Rarible, and others can significantly impact your NFT sales and visibility.

At this time, updating your collection profile on OpenSea, Rarible, and other marketplaces requires manual work and is limited to <a href="https://www.crossmint.com/contact/sales">enterprise</a> clients.

### Key Marketplace Profile Elements

When working with our enterprise team to configure your marketplace profile, consider these important elements:

1. **Collection Banner**: A high-quality banner image that represents your brand
2. **Collection Logo**: A distinctive logo that's recognizable at small sizes
3. **Collection Description**: A compelling description of your project and its value
4. **External Links**: Links to your website, social media, and community channels
5. **Category Tags**: Appropriate categories that help collectors discover your NFTs

## FAQs

<AccordionGroup>
  <Accordion title="How are royalties enforced on different marketplaces?">
    Royalty enforcement varies by marketplace. Some marketplaces like OpenSea have made royalties optional, while
    others still enforce them. Crossmint implements royalties according to blockchain standards, but cannot
    guarantee enforcement across all marketplaces.
  </Accordion>

  <Accordion title="Can I set different royalty percentages for different NFTs in the same collection?">
    No, royalties are set at the collection level and apply to all NFTs within that collection. If you need
    different royalty structures, consider creating separate collections.
  </Accordion>

  <Accordion title="How quickly do royalty changes take effect?">
    Royalty changes take effect immediately for new listings. For existing listings on marketplaces, the timing
    depends on how frequently each marketplace refreshes metadata.
  </Accordion>

  <Accordion title="What's the maximum royalty percentage I can set?">
    While technically there's no upper limit, most marketplaces and collectors expect royalties between 2.5% and
    10%. Setting royalties too high may discourage secondary market activity.
  </Accordion>
</AccordionGroup>


# Manage Delivery
Source: https://docs.crossmint.com/minting/nfts/integrate/manage-delivery

Configure recipient options and customize email delivery notifications

Crossmint provides flexible options for delivering NFTs to recipients and customizing the delivery experience. This guide covers how to specify different types of recipients and how to customize the email notifications they receive.

## Specify Recipients

You can deliver NFTs to three kinds of recipients when using minting APIs:

* [Wallet address](#send-nft-to-wallet-address): directly specify a wallet address, which could be a user owned wallet (e.g. MetaMask, Phantom, etc.) or a wallet you manage.
* [Email address](#send-nft-to-email-address): in this modality, Crossmint automatically generates a secure MPC backed custodial wallet for the email, and delivers the NFT inside.
* [User identifier](#send-nft-by-userid): in this modality, Crossmint automatically generates a wallet and associates it with an user ID from your application, and delivers the NFT inside. You must build the interface for users to access this wallet.

<Check>
  Check out the [create-wallet](/api-reference/wallets/create-wallet) endpoint in the API reference if you wish to
  pre-create a wallet prior to invoking the mint API.
</Check>

### Send NFT to Wallet Address

To mint an NFT directly to an existing blockchain address, the following `recipient` format is used:

```bash theme={null}
<chain>:<address>
```

<Note>For a full list of chain names, refer to the [Supported Chains](/introduction/supported-chains) page.</Note>

#### Examples

* EVM: `polygon:0x123...`
* Solana: `solana:3Q5...`
* Aptos: `aptos:0x0f07...`

### Send NFT to Email Address

To mint an NFT and send it to an email address, the following `recipient` format is used:

```bash theme={null}
email:<email_address>:<chain>
```

#### Examples

* EVM: `email:demo@test.com:polygon`
* Solana: `email:demo@test.com:solana`

<Note>Minting to an email address is not currently supported on Aptos.</Note>

The NFT can then be accessed by logging into Crossmint with the specified email address:

* for `staging/testnet` NFTs: <a href="https://staging.crossmint.com/user/collection">[https://staging.crossmint.com/user/collection](https://staging.crossmint.com/user/collection)</a>
* for `mainnet` NFTs: <a href="https://www.crossmint.com/user/collection">[https://www.crossmint.com/user/collection](https://www.crossmint.com/user/collection)</a>

### Send NFT to a Twitter/X account

To mint an NFT to a Twitter/X account, the following `recipient` format is used:

```bash theme={null}
twitter:<twitter_handle>:<chain>
```

#### Examples

* EVM: `twitter:@username:polygon`
* Solana: `twitter:@username:solana`

### Send NFT by `userId`

This method allows you to deliver NFTs by directly specifying the user identifier of the recipient in your system. Crossmint will fetch a custodial wallet linked to that user identifier inside your project or, if none exists, create one on the fly. Then the NFT will be delivered there. This way, you don't need to keep a mapping between your user identifiers and their wallets, just pass your user id and crossmint takes care of the rest.

<Snippet />

<Note>Wallets created with the `userId` option cannot be accessed by logging into Crossmint.com.</Note>

To mint an NFT to this type of recipient, follow this format:

```bash theme={null}
userId:<userIdentifier>:<chain>
```

#### Examples

* EVM: `userId:user1234:polygon`
* Solana: `userId:user1234:solana`

## Customize Delivery Emails

Email delivery notifications can be customized to align with your branding and communication needs. This section will walk you through how to configure your email template.

### Edit the email template

To adjust the visual presentation and branding of your email notifications:

1. In the Crossmint Console, click on Settings, and navigate to the **Branding** tab.
2. Select **Deliver NFT via email** from the dropdown options.
3. Here, you can customize:
   * The **logo** displayed in the email with your logo. This will default to Crossmint's logo, unless specified otherwise.
   * The main **button's color** . This will default to #04AA6D (Crossmint's green).
   * The **display name** textbox to include your brand's name. This will be empty, by default.

As you make adjustments, you can preview the changes. Once satisfied, save your changes and now they will apply to all future minting email notifications, related to this project. Emails now reflect your project's brand identity while providing essential delivery information to recipients.

<img alt="Customize email template" />

### Enable email delivery

You should make sure email delivery notifications are enabled for the customized email to reach your users. For new projects created after Sep 16, 2024, the "sendNotification" parameter is set to `true` by default, meaning mint recipients will automatically receive email notifications.

For legacy projects, created before Sep 16 2024, "sendNotification" is set to `false` until March 14, 2025. If you choose so, you can enable email notifications for legacy projects by explicitly turning the feature on via API or via the Console.

#### Console

To send email notifications to NFT recipients:

1. Navigate to an **unminted NFT** part of a Collection in the Crossmint Console.
2. Click on the **more options** button and select **Mint & send NFT**.
3. Ensure the **Notify recipient via email** option is selected.
4. Enter the **recipient's email address** and press Mint.

The recipient will receive an email delivery notification for their newly minted NFT.

#### API

To do the same programmatically, you can configure two new parameters:

1. **sendNotification** (boolean): Determines whether the recipient will receive an email notification.
   * Default value: `true` for new projects created after Sep 16, 2024.
   * For legacy projects (created before Sep 16, 2024), this feature will default to `false` until March 14, 2025, unless explicitly set to `true`.
2. **locale** (string): Specifies the language for the email content. Default is `en-US` for English. We support all locales (i.e. "es-ES" for Spanish).

## FAQs

<AccordionGroup>
  <Accordion title="Can recipients change their email preferences?">
    Yes, recipients can manage their email preferences through their Crossmint account settings.
  </Accordion>

  <Accordion title="What happens if an email address is invalid?">
    If an email address is invalid, the NFT will still be minted but the notification will fail to deliver. The NFT
    will be associated with the email address in Crossmint's system, but the recipient won't receive a notification.
  </Accordion>

  <Accordion title="Can I send NFTs to multiple recipients at once?">
    Currently, each API call mints to a single recipient. For bulk operations, you'll need to make multiple API
    calls. See the [Mint In Bulk](/minting/nfts/integrate/mint-in-bulk) guide for more information.
  </Accordion>

  <Accordion title="How do I track if an email notification was delivered?">
    Crossmint doesn't currently provide delivery tracking for email notifications. For critical notifications,
    consider implementing your own email delivery system alongside Crossmint's.
  </Accordion>
</AccordionGroup>


# Mint In Bulk
Source: https://docs.crossmint.com/minting/nfts/integrate/mint-in-bulk

Scale your NFT operations with bulk minting capabilities

Crossmint's infrastructure is designed to handle high-volume minting operations efficiently, allowing you to scale your NFT projects to serve thousands or even millions of users.

## Enterprise Solutions

For enterprise customers with very high volume requirements, Crossmint offers additional capabilities:

<Warning>
  Enterprise bulk minting features are available for high-volume projects. Please [contact
  us](https://www.crossmint.com/contact/sales) to discuss your specific requirements.
</Warning>

## Bulk Minting Capabilities

Crossmint's platform offers several advantages for bulk minting operations:

* **High Throughput**: Mint thousands of NFTs per hour with optimized transaction batching
* **Cost Efficiency**: Reduce gas costs through intelligent transaction scheduling
* **Queue Management**: Automatic handling of transaction queues and retries
* **Observability**: Track the status of all minting operations in real-time
* **Gas Optimization**: Automatic gas price adjustments based on network conditions

## Bulk Minting via Crossmint Console

The Crossmint Console provides an easy-to-use interface for uploading and minting NFTs in bulk. Here's how to use it:

### Step 1: Access the Batch Upload Feature

In the Crossmint Console, navigate to your collection and select the "Batch upload" option.

<img alt="Batch Upload Option" />

### Step 2: Prepare Your Metadata

Before uploading your assets, you need to prepare them properly:

1. You can upload up to 1,000 NFT collectibles at once
2. Download the example CSV file provided by Crossmint to use as a template
3. Prepare your metadata according to the template format

<img alt="Batch Upload Interface" />

### Step 3: Upload Your Metadata CSV

1. Add a CSV file named `metadata.csv` with your NFT metadata
2. Click the "Upload CSV" button to upload your prepared file

<img alt="Batch Upload Interface" />

### Step 4: Upload Media Files

1. Prepare your NFT media files (images, animations, videos)
2. Crossmint supports various formats (PNG, JPEG, GIF etc.)
3. Each file must be under 10MB in size
4. All media files should be in the same folder, not in subfolders
5. Click "Upload media files" to upload your prepared media

<img alt="Batch Upload Interface" />

### Step 5: Complete the Upload

After uploading both your metadata CSV and media files, click the "Upload" button to start the batch minting process.

<img alt="Batch Upload Interface" />

## Monitoring Bulk Operations

When minting in bulk, it's essential to track the status of your operations:

1. **Webhooks**: Set up [webhooks](/minting/nfts/integrate/webhooks-and-status-apis) to receive real-time notifications about mint completions and failures
2. **Status API**: Use the [action status API](/minting/nfts/integrate/webhooks-and-status-apis) to check the status of individual minting operations
3. **Console Dashboard**: Monitor your minting operations through the Crossmint Console


# Mint Tokens
Source: https://docs.crossmint.com/minting/nfts/integrate/mint-tokens

Create and distribute tokens at scale

<Tabs>
  <Tab title="Unique Assets (ERC-721)">
    To mint and airdrop unique digital assets, you can follow the guide on the [Quickstart](/minting/quickstarts/nfts). For more detail, please check the [API reference](/api-reference/minting/nfts/mint-nft). You can watch a quick video tutorial for this [here](https://youtu.be/yYJRW35zqUQ?si=b6PQTbZ7zqYVGwXw).
  </Tab>

  <Tab title="Editions (ERC-1155)">
    SFTs (semifungible tokens) follow the ERC-1155 standard. Each token is a replica of a predefined template. Each collection (smart contract) can contain multiple templates, which can contain many tokens.

    To get started, it's recommended to read the [Introduction](/minting/introduction) for general information on how the minting product works.

    <Warning>This API only supports EVM chains self-serve. Contact us if you need support for another chain.</Warning>

    ## 1. Create an SFT collection to hold your templates

    ```bash cURL theme={null}
      curl --request POST \
        --url https://staging.crossmint.com/api/2022-06-09/collections \
        --header 'accept: application/json' \
        --header 'content-type: application/json' \
        --header 'x-api-key: YOUR_API_KEY' \
        --data '
    {
        "chain": "polygon-amoy",
        "fungibility": "semi-fungible",
        "metadata": {
          "name": "My New Collection",
          "imageUrl": "https://www.crossmint.com/assets/crossmint/logo.png",
          "description": "A new collection with its own dedicated smart contract"
        }
    }'
    ```

    <Accordion title="See example response">
      ```json JSON theme={null}
        {
          "id": "5263650e-6d43-4ed3-9e31-0cf593d076a4",
          "metadata": {
            "name": "Test Collection",
            "description": "Test",
            "imageUrl": "https://cdn.io/metadata.json",
            "symbol": "XMINT"
          },
          "fungibility": "semi-fungible",
          "onChain": {
            "chain": "polygon-amoy",
            "type": "erc-1155"
          },
          "actionId": "5263650e-6d43-4ed3-9e31-0cf593d076a4"
        }
      ```
    </Accordion>

    ## 2. Create a template within that collection

    ```bash cURL theme={null}
    curl --request POST \
      --url https://staging.crossmint.com/api/2022-06-09/collections/{collectionId}/templates \
      --header 'accept: application/json' \
      --header 'content-type: application/json' \
      --header 'x-api-key: YOUR_API_KEY' \
      --data '
      {
        "onChain": {
          "tokenId": "2"
        },
        "supply": {
          "limit": 10
        },
        "metadata": {
          "name": "My template",
          "image": "https://www.crossmint.com/assets/crossmint/logo.png",
          "description": "A new token template for my ERC1155 collection"
        }
      }'
    ```

    <Accordion title="See example response">
      ```json JSON theme={null}
      {
        "templateId": "58b0c1aa-e457-48dd-bb55-5a27e6a92f74",
        "metadata": {
          "name": "My template",
          "image": "ipfs://bafkreigbqsmxzkbjgbwtj6exfdt5z3t3swgoysf7hr6vjzddqnmykj6x2u",
          "description": "A new token template for my ERC1155 collection"
        },
        "onChain": {
          "tokenId": "1"
        },
        "supply": {
          "limit": "10",
          "minted": "0"
        }
      }
      ```
    </Accordion>

    ## 3. Mint an SFT from a template

    Mint SFTs from the template and send them to wallets or email addresses.

    ```bash cURL theme={null}
      curl --request POST \
        --url https://staging.crossmint.com/api/2022-06-09/collections/{collectionId}/sfts \
        --header 'accept: application/json' \
        --header 'content-type: application/json' \
        --header 'x-api-key: YOUR_API_KEY' \
        --data '
        {
          "templateId": "58b0c1aa-e457-48dd-bb55-5a27e6a92f74",
          "recipient": "email:user@example.com:polygon-amoy",
          "amount": 1
        }'
    ```

    <Accordion title="See example response">
      ```json JSON theme={null}
      {
        "actionId": "a91c15e3-60f2-4a45-bf1a-cee508981667",
        "action": "nfts.create",
        "status": "pending",
        "data":
        {
          "chain": "polygon-amoy",
          "collection":
          {
            "id": "84e3d617-9c1b-4e7a-9686-522a9ea7c520",
            "contractAddress": "0x9b8ab8949bd7E73E61945b88F7fe12151f98ad3C"
          },
          "recipient":
          {
            "walletAddress": "0xcFDc00Cf926A5053f9Cdf004e6DF17e6dEB2E146",
            "email": "testy@crossmint.com"
          },
          "token":
          {
            "id": "a91c15e3-60f2-4a45-bf1a-cee508981667"
          }
        },
        "startedAt": "2024-01-02T22:05:01.000Z",
        "resource": "https://staging.crossmint.com/api/2022-06-09/actions/a91c15e3-60f2-4a45-bf1a-cee508981667"
      }
      ```
    </Accordion>

    **All set!**

    To confirm delivery, use the [transaction status API](/minting/nfts/integrate/webhooks-and-status-apis) or set up a [webhook](/minting/nfts/integrate/webhooks-and-status-apis).
  </Tab>

  <Tab title="Compressed NFTs">
    ## What are Compressed NFTs?

    Compressed NFTs are a new standard on the Solana blockchain, for minting NFTs with the lowest cost amongst L1 and L2 blockchains, and the highest throughput (thousands of NFTs per second). Read more details about how it works [here](https://www.metaplex.com/posts/expanding-digital-assets-with-compression-for-nfts).

    Using this standard to mint NFTs is extremely complicated if you manage everything on your own. On top of the intrinsic complexity usually required to mint a regular NFT, compressed NFTs require deploying and managing Merkle trees, batching, and dealing with nascent infrastructure. Crossmint also supports updating the NFT metadata after minting. Please refer to this [doc page](/minting/nfts/integrate/update-nfts).

    Here's where Crossmint can help: we've done all the hard work so that minting compressed NFTs is no harder than minting regular ones: all it takes is a single API call, and you can even use one of Crossmint's no-code tools to do so.

    ## Current Protocol Limitations

    * There's a 10-30 second delay between when an NFT is minted and it shows in wallets.

    ## How to use the Minting API with Compressed NFTs

    The Minting API for Compressed NFTs is exactly the same as for regular NFTs, but it only works on the Solana blockchain.

    POST `https://staging.crossmint.com/api/2022-06-09/collections/<collection-id>/nfts`

    <Note>You can mint both compressed and non-compressed NFTs on the same collection.</Note>

    ```bash cURL theme={null}
    curl --request POST \
      --url https://staging.crossmint.com/api/2022-06-09/collections/default-solana/nfts \
      --header 'Content-Type: application/json' \
      --header 'X-API-KEY: <x-api-key>' \
      --data '{
        "recipient": "email:john.doe@example.com:solana",
        "metadata": {
          "name": "Crossmint Example NFT",
          "image": "https://www.crossmint.com/assets/crossmint/logo.png",
          "description": "My NFT created via the mint API!"
        },
        "compressed": true,
        "reuploadLinkedFiles": false
      }'
    ```

    The above will return an NFT ID. Use it in the next call to retrieve the mint status.

    ```bash cURL theme={null}
    curl --request GET \
      --url https://staging.crossmint.com/api/2022-06-09/collections/{collectionId}/nfts/{nftId} \
      --header 'X-API-KEY: X_API_KEY'
    ```

    Be sure to replace:

    * `X_API_KEY`, `{collectionId}` and `{nftId}`
    * Recipient: change `VALID_WALLET_ADDRESS` with the wallet you want to send the NFT to
    * Metadata: add the name, image, and description.

    <Card title="To explore compressed NFTs on the blockchain, you must use Orb, powered by Helius" icon="magnifying-glass" href="https://xray.helius.xyz/">
      Other explorers, like Solscan, still have not added support.
    </Card>
  </Tab>

  <Tab title="Non-transferrable NFTs">
    There are two ways to set the transferrability of NFTs:

    1. Defining it at the smart contract level
    2. If you are using custodial wallets, enabling or disabling transfers from the frontend

    If you want to configure it at the smart contract level, see the following endpoints:

    | Endpoint | Chain | Description |
    | - | - | - |
    | [Set Transferability](/api-reference/minting/collection/set-transferability) | EVM and Aptos | Set transferability to on or off |
    | [Get Transferability](/api-reference/minting/collection/get-transferability) | EVM and Aptos | Get transferability configuration |

    <Note>For Solana or other non-EVM chain support, [contact us](https://www.crossmint.com/contact/sales)</Note>
  </Tab>
</Tabs>

***

<Note>
  The API also has an idempotent version which prevents you from calling the same API action multiple times and
  mitigates the risk of unwanted NFT duplicates.
</Note>

## Advanced Guides

<CardGroup>
  <Card title="Dynamic NFTs" icon="pencil" href="/minting/nfts/integrate/update-nfts" />

  <Card title="List for Sale" icon="money-bill" href="/minting/nfts/integrate/list-for-sale" />

  <Card title="Webhooks & Status APIs" icon="atom" href="/minting/nfts/integrate/webhooks-and-status-apis" />

  <Card title="Bring your own Contract" icon="file-import" href="/minting/nfts/integrate/bring-your-own-contract" />
</CardGroup>


# Pricing
Source: https://docs.crossmint.com/minting/nfts/integrate/pricing

Crossmint Mint API Pricing

## Chain operations pricing

*All values shown in USD.*

| Chain | Create Collection | Update Collection | Mint NFTs | Update Royalty | Update Metadata |
| :- | -: | -: | -: | -: | -: |
| Aptos | \$0.10 | Not supported | \$0.01 | Not supported | Not supported |
| Arbitrum\* | \$0.03 + gas | \$0.03 + gas | \$0.03 + gas | \$0.03 + gas | \$0.03 + gas |
| Arbitrum Nova\* | \$0.01 + gas | \$0.01 + gas | \$0.01 + gas | \$0.01 + gas | \$0.01 + gas |
| Avalanche\* | \$0.10 + gas | \$0.10 + gas | \$0.10 + gas | \$0.10 + gas | \$0.10 + gas |
| Base\* | \$0.08 + gas | \$0.08 + gas | \$0.08 + gas | \$0.08 + gas | \$0.08 + gas |
| BSC\* | \$0.01 + gas | \$0.01 + gas | \$0.01 + gas | \$0.01 + gas | \$0.01 + gas |
| Chiliz | \$1 | \$0.20 | \$0.50 | \$0.20 | \$0.20 |
| Optimism\* | \$0.06 + gas | \$0.06 + gas | \$0.06 + gas | \$0.06 + gas | \$0.06 + gas |
| Polygon | \$0.50 | \$0.50 | \$0.10 | \$0.50 | \$0.05 |
| Sei | \$0.05 | \$0.01 | \$0.01 | \$0.01 | \$0.01 |
| Shape | \$2 | \$2 | \$2 | \$2 | \$2 |
| Solana | \$8 | Not supported | \$0.02 | Not supported | \$0.02 |
| Skale Nebula | \$0.01 | \$0.01 | \$0.01 | \$0.01 | \$0.01 |
| Zora\* | \$0.08 + gas | \$0.08 + gas | \$0.08 + gas | \$0.08 + gas | \$0.08 + gas |

\*For some chains (Arbitrum, Arbitrum Nova, Avalanche, Base, BSC, Optimism, and Zora), gas fees are added to the base price. Gas fees are determined at the time the operation is submitted and depend on blockchain network congestion.

For more details, or to discuss custom pricing for large operations volumes, [contact our sales team](https://www.crossmint.com/contact/sales).


# Update NFTs
Source: https://docs.crossmint.com/minting/nfts/integrate/update-nfts

Make your NFTs change over time

Dynamic NFTs are tokens whose content changes over time. There are two ways to achieve this with Crossmint:

1. Using Crossmint's [Edit NFT API](/api-reference/minting/nfts/edit-nft)
2. Storing the metadata offchain and updating it on your database. To use this option, set the property `reuploadLinkedFiles` to `false` when minting an NFT.

## Using the Edit NFT API

The [Edit NFT API](/api-reference/minting/nfts/edit-nft) allows you to update the metadata of an existing NFT, including its name, description, image, and attributes. This is useful for creating NFTs that evolve over time or need to be updated based on external events.

### Prerequisites

* Ensure your API key is a server-side key with the `nfts.update` scope
* You need the collection ID and NFT ID from the minting process

### Implementation

```bash cURL theme={null}
curl --request PATCH \
  --url https://staging.crossmint.com/api/2022-06-09/collections/{collectionId}/nfts/{nftId} \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '{
  "metadata": {
    "description": "My updated NFT description!",
    "image": "https://www.crossmint.com/assets/crossmint/updated-image.png",
    "name": "Evolved NFT",
    "attributes": [
      {
        "trait_type": "level",
        "value": "2"
      }
    ]
  },
  "reuploadLinkedFiles": true
}'
```

## Using Off-chain Metadata

You can also store the metadata off-chain and update it directly:

1. When minting the NFT, set `reuploadLinkedFiles` to `false`
2. Use your own server to host the metadata
3. Update the metadata on your server as needed

```javascript theme={null}
// Example: Minting with off-chain metadata
const apiKey = "YOUR_API_KEY";
const chain = "polygon-amoy"; // or "ethereum-sepolia", "base-sepolia", etc.
const env = "staging"; // or "www" for production
const recipientEmail = "TEST_EMAIL_ADDRESS";
const recipientAddress = `email:${recipientEmail}:${chain}`;

// The URL to your metadata server
const metadataImgUrl = "https://your-server.com/metadata/token123.png";

const url = `https://${env}.crossmint.com/api/2022-06-09/collections/default/nfts`;
const options = {
    method: "POST",
    headers: {
        accept: "application/json",
        "content-type": "application/json",
        "x-api-key": apiKey,
    },
    body: JSON.stringify({
        recipient: recipientAddress,
        metadata: {
            name: "Dynamic NFT",
            description: "This NFT will update over time",
            image: metadataImgUrl,
        },
        reuploadLinkedFiles: false,
    }),
};

fetch(url, options)
    .then((response) => response.json())
    .then((data) => console.log(data))
    .catch((error) => console.error("Error:", error));
```

## Use Cases for Dynamic NFTs

Dynamic NFTs enable a wide range of applications:

* **Game Assets**: NFTs that evolve as players progress
* **Membership Passes**: NFTs that update based on membership status
* **Event Tickets**: NFTs that change before, during, and after events
* **Digital Collectibles**: NFTs that evolve based on real-world events
* **Loyalty Programs**: NFTs that update based on customer activity

## Best Practices

When implementing dynamic NFTs:

1. **Plan for Updates**: Design your NFT with future updates in mind
2. **Versioning**: Consider including version information in your metadata
3. **Event Triggers**: Define clear conditions for when updates should occur
4. **User Communication**: Inform users about how and when their NFTs might change
5. **Testing**: Thoroughly test update mechanisms before implementation

## FAQs

<AccordionGroup>
  <Accordion title="How often can I update an NFT?">
    With Crossmint's Edit API, you can update NFTs as needed, but consider blockchain transaction costs and network
    congestion. For very frequent updates, consider using off-chain metadata.
  </Accordion>

  <Accordion title="Will updates to an NFT affect its provenance or value?">
    Updates don't change the token ID or ownership history, but the perceived value may change based on the nature
    of the updates. It's important to communicate your update policy to collectors.
  </Accordion>

  <Accordion title="Can I schedule updates to happen automatically?">
    Crossmint doesn't provide native scheduling, but you can implement scheduled updates using your own backend
    services that call the Edit API at specified times.
  </Accordion>

  <Accordion title="Do all marketplaces support dynamic NFTs?">
    Most marketplaces will display the current state of your NFT's metadata, but the frequency of metadata refreshes
    may vary by marketplace.
  </Accordion>
</AccordionGroup>


# Webhooks and Status APIs
Source: https://docs.crossmint.com/minting/nfts/integrate/webhooks-and-status-apis

Listen for updates in mints, edits, collection creations and other async events

Creating NFT collections and minting or [editing NFTs](/minting/nfts/integrate/update-nfts) are operations that must be sent to a blockchain. Transaction confirmation on the blockchain can take a few seconds, but during network congestion, it may take several minutes. Webhooks and the action status API allow you to stay up to date on the status of these asynchronous operations.

Some cases where you may want to listen to when transactions are confirmed include:

* Notifying your customers via email that their NFT is ready to access
* Updating your database with the NFT id for the user
* Showing in your website that that the mint has been successful

### Ways to check the status of an action

| Model | Best for | Mechanism |
| - | - | - |
| Pull (query for updates) | Quick testing | Action Status API |
| Push (get notified) | Scalable apps in production | Webhooks |

<Tabs>
  <Tab title="Action Status APIs">
    ## Action Status APIs

    Call the following API to check the status of an action:

    ```bash cURL theme={null}
    # Set your variables
    env=staging  # or "www" for production
    YOUR_API_KEY=<ENTER_YOUR_API_KEY>
    actionId=<ENTER_YOUR_actionId>

    # Execute the curl command
    curl --request GET \
    --url "https://${env}.crossmint.com/api/2022-06-09/actions/${actionId}" \
    --header 'accept: application/json' \
    --header "x-api-key: ${YOUR_API_KEY}"
    ```

    <Card title="API Reference" icon="terminal" href="/api-reference/common/get-action-status" />

    <Accordion title="Where can I find the actionId and API_KEY?">
      * `actionID` is returned from any async API calls you perform.
      * `YOUR_API_KEY` can be found in the `Developers -> API Keys` tab of the [Production](https://www.crossmint.com/console/projects/apiKeys) or [Staging](https://staging.crossmint.com/console/projects/apiKeys) consoles.
    </Accordion>
  </Tab>

  <Tab title="Webhooks">
    ## Webhooks

    In this guide, we will use nodejs to create an API endpoint to listen for and parse webhook events:

    ### 1. Create an endpoint route

    Using a standard nodejs API server, create an endpoint.

    <Accordion title="I don't have a webserver or want to test locally">
      You can test locally by installing [ngrok](https://ngrok.com/docs/getting-started/) and creating a routed endpoint to a specified port.
    </Accordion>

    ### 2. Configure the endpoint to read and parse webhook events

    On this endpoint, modify the code to handle POST requests only. When a POST request comes through, parse the webhook event of the request body. Ensure your webhook listener responds with a `200` status code. Otherwise the webhook may be sent until you acknowledge it.

    The snippet below is an example handler that parses webhook events:

    ```javascript theme={null}
    // endpoint.js

    // listen to webhook ingestion
    export default function handler(req, res) {
      if (req.method === "POST") {
        console.log(`[webhook] Successfully minted ${req.body.id}`);
      }
      res.status(200).json({});
    }
    ```

    <Warning>
      Don't be strict with payload validations as Crossmint may add new fields to
      the webhooks as products evolve.
    </Warning>

    Here are some examples of the webhook results (with dummy data):

    <AccordionGroup>
      <Accordion title="collections.create.succeeded">
        <CodeGroup>
          ```json EVM theme={null}
          {
            "actionId": "897eadae-ee2d-43f9-a97b-1a9d9c682d6f",
            "startedAt": "2023-10-04T15:48:20.000Z",
            "completedAt": "2023-10-04T15:48:42.000Z",
            "type": "collections.create.succeeded",
            "data": {
              "chain": "polygon",
              "txId": "0x919ec33c1ceffd292d1d0cdd9675ffcc0af31a1f34622edd4865a9ca9fa82aa1",
              "collection": {
                "id": "897eadae-ee2d-43f9-a97b-1a9d9c682d6f",
                "contractAddress": "0x59195995f248450267AD40CAc1d79fAAba290467"
              }
            },
            "resource": "https://crossmint.com/api/2022-06-09/collections/897eadae-ee2d-43f9-a97b-1a9d9c682d6f"
          }
          ```

          ```json Solana theme={null}
          {
            "actionId": "01ac4b77-9bc9-42d3-a110-b0572ec299fd",
            "startedAt": "2023-10-04T15:50:12.000Z",
            "completedAt": "2023-10-04T15:50:23.000Z",
            "type": "collections.create.succeeded",
            "data": {
              "chain": "solana",
              "txId": "2M4tFbGWFPWAjHmZdssoTiTRjxx43nRd3vt9RpQ3wLWsW69duUhvEQrDvsyfafnQNoh6LmDQg4KPLvffgCskkwoV",
              "collection": {
                "id": "01ac4b77-9bc9-42d3-a110-b0572ec299fd",
                "mintAddress": "JCpAQcjqWCwTpRPsMumsXtg3A4SGMXbxVbowu8qrntqt"
              }
            },
            "resource": "https://a5b6-181-167-232-117.ngrok-free.app/api/2022-06-09/collections/01ac4b77-9bc9-42d3-a110-b0572ec299fd"
          }
          ```
        </CodeGroup>
      </Accordion>

      <Accordion title="collections.update.succeeded">
        <CodeGroup>
          ```json EVM theme={null}
          {
            "actionId": "e0926e73-8212-4074-b934-4d6ac68cfcff",
            "startedAt": "2023-10-04T15:57:14.000Z",
            "completedAt": "2023-10-04T15:57:36.000Z",
            "type": "collections.update.succeeded",
            "data": {
              "chain": "polygon",
              "txId": "0x919ec33c1ceffd292d1d0cdd9675ffcc0af31a1f34622edd4865a9ca9fa82aa1",
              "collection": {
                "id": "897eadae-ee2d-43f9-a97b-1a9d9c682d6f",
                "contractAddress": "0x59195995f248450267AD40CAc1d79fAAba290467"
              },
              "changes": ["supplyLimit"]
            },
            "resource": "https://crossmint.com/api/2022-06-09/collections/e0926e73-8212-4074-b934-4d6ac68cfcff",
            "timestamp": 1696424259573
          }
          ```
        </CodeGroup>
      </Accordion>

      <Accordion title="nfts.create.succeeded">
        <CodeGroup>
          ```json EVM theme={null}
          {
            "type": "nfts.create.succeeded",
            "actionId": "771d7e38-2890-47d7-b733-a1462736b528",
            "startedAt": "2023-10-04T19:59:47.000Z",
            "completedAt": "2023-10-04T20:00:00.000Z",
            "data": {
              "chain": "polygon",
              "txId": "0x919ec33c1ceffd292d1d0cdd9675ffcc0af31a1f34622edd4865a9ca9fa82aa1",
              "collection": {
                "id": "default-polygon",
                "contractAddress": "0x2DdDDEe8dad8b2ec123F5ceEc3E8dA4E57C0ed29"
              },
              "recipient": {
                "walletAddress": "0x10324e5B8879CA6662ff83617F74b0AaD251b819",
                "email": "recipient@crossmint.com"
              },
              "token": {
                "id": "771d7e38-2890-47d7-b733-a1462736b528",
                "owner": {
                  "walletAddress": "0x10324e5B8879CA6662ff83617F74b0AaD251b819"
                },
                "tokenId": "15"
              }
            },
            "resource": "https://crossmint.com/api/2022-06-09/collections/default-polygon/nfts/771d7e38-2890-47d7-b733-a1462736b528"
          }
          ```

          ```json Solana theme={null}
          {
            "type": "nfts.create.succeeded",
            "actionId": "2c5f9ec6-ae68-4e17-a671-db4af2208a2d",
            "startedAt": "2023-10-04T20:01:21.000Z",
            "completedAt": "2023-10-04T20:01:27.000Z",
            "data": {
              "chain": "solana",
              "txId": "2M4tFbGWFPWAjHmZdssoTiTRjxx43nRd3vt9RpQ3wLWsW69duUhvEQrDvsyfafnQNoh6LmDQg4KPLvffgCskkwoV",
              "collection": {
                "id": "default-solana",
                "mintAddress": "qCTMcsRBYYt1YKDAkJnstjgXJU625YX5LBfwsUi1Mn4"
              },
              "recipient": {
                "walletAddress": "EjLpq6RAxzPuwjcwJ2C6ZjwrFZuqhu2CiVTDzkSSCE5B",
                "email": "recipient@crossmint.com"
              },
              "token": {
                "id": "2c5f9ec6-ae68-4e17-a671-db4af2208a2d",
                "owner": {
                  "walletAddress": "EjLpq6RAxzPuwjcwJ2C6ZjwrFZuqhu2CiVTDzkSSCE5B"
                },
                "mintHash": "Gec66rG8Rj6Q2nqaFpGRvggiAfriMb93o28qGSeeY1gJ"
              }
            },
            "resource": "https://staging.crossmint.com/api/2022-06-09/collections/default-solana/nfts/2c5f9ec6-ae68-4e17-a671-db4af2208a2d",
            "timestamp": 1696449687501
          }
          ```
        </CodeGroup>
      </Accordion>

      <Accordion title="nfts.create.failed">
        <CodeGroup>
          ```json EVM theme={null}
          {
            "actionId":"cf9985d3-3341-4fd6-bd0e-548ef97a3486",
            "startedAt":"2024-02-05T21:48:17.000Z",
            "type":"nfts.create.failed",
            "data":{
              "chain":"polygon",
              "collection":{
                "id":"297199ba-c763-4464-b592-26c2ca2dbe5d",
                "contractAddress":"0x2ADBeb5e1976615883D3c5F07234E38b50e09edB"
            },
            "contractArguments":{
              "key":28
            },
            "recipient":{
              "walletAddress":"0x78359E7dF948834caFEcBE0494B010C6f7f7fA74"
            },
            "token":{
              "id":"cf9985d3-3341-4fd6-bd0e-548ef97a3486"
            },
            "error":{
              "reason":"execution_reverted",
              "message":"Minting smart contract reverted. Check 'revertReason' for details",
              "revertReason":"execution reverted: Wrong value for key",
              "callInfo":{
                  "functionName":"mintTo",
                  "arguments":{
                    "key":28,
                    "recipient":"0x78359E7dF948834caFEcBE0494B010C6f7f7fA74"
                  },
                  "calldata":"0x449a52f800000000000000000000000078359e7df948834cafecbe0494b010c6f7f7fa74000000000000000000000000000000000000000000000000000000000000001c"
              }
            }
            },
            "resource":"https://1a7a-181-110-64-58.ngrok-free.app/api/2022-06-09/collections/297199ba-c763-4464-b592-26c2ca2dbe5d/nfts/cf9985d3-3341-4fd6-bd0e-548ef97a3486",
            "timestamp":1707158908733
          }
          ```
        </CodeGroup>
      </Accordion>

      <Accordion title="nfts.update.succeeded">
        <CodeGroup>
          ```json EVM theme={null}
          {
            "type": "nfts.update.succeeded",
            "actionId": "f7fedd17-2feb-4bc9-88fa-8890ea8f99e8",
            "startedAt": "2023-10-04T20:09:27.000Z",
            "completedAt": "2023-10-04T20:09:35.000Z",
            "data": {
              "chain": "polygon",
              "txId": "0x919ec33c1ceffd292d1d0cdd9675ffcc0af31a1f34622edd4865a9ca9fa82aa1",
              "collection": {
                "id": "default-polygon",
                "contractAddress": "0x2DdDDEe8dad8b2ec123F5ceEc3E8dA4E57C0ed29"
              },
              "token": {
                "id": "210a95ab-d59c-41ef-9f60-8e41550a753e",
                "owner": {
                  "walletAddress": "0x10324e5B8879CA6662ff83617F74b0AaD251b819"
                },
                "tokenId": "16"
              },
              "changes": ["metadata"]
            },
            "resource": "https://crossmint.com/api/2022-06-09/collections/default-polygon/nfts/f7fedd17-2feb-4bc9-88fa-8890ea8f99e8",
            "timestamp": 1696450175660
          }
          ```

          ```json Solana theme={null}
          {
            "type": "nfts.update.succeeded",
            "actionId": "57d3cedd-e8e8-4509-88bc-97d6baea478f",
            "startedAt": "2023-10-04T20:07:55.000Z",
            "completedAt": "2023-10-04T20:08:01.000Z",
            "data": {
              "chain": "solana",
              "txId": "2M4tFbGWFPWAjHmZdssoTiTRjxx43nRd3vt9RpQ3wLWsW69duUhvEQrDvsyfafnQNoh6LmDQg4KPLvffgCskkwoV",
              "collection": {
                "id": "default-solana",
                "mintAddress": "qCTMcsRBYYt1YKDAkJnstjgXJU625YX5LBfwsUi1Mn4"
              },
              "token": {
                "id": "1f3f0959-417d-43a7-95f8-39e6f22d5573",
                "owner": {
                  "walletAddress": "EjLpq6RAxzPuwjcwJ2C6ZjwrFZuqhu2CiVTDzkSSCE5B"
                },
                "mintHash": "BnyGQcmU4mXMi5NMUuKTjFdYkg79RZoBX3qCWdXZVcyb"
              },
              "changes": ["metadata"]
            },
            "resource": "https://crossmint.com/api/2022-06-09/collections/default-solana/nfts/57d3cedd-e8e8-4509-88bc-97d6baea478f",
            "timestamp": 1696450081841
          }
          ```
        </CodeGroup>
      </Accordion>
    </AccordionGroup>

    ### 3. Pre & post processing

    Add your pre and post processing logic when setting up your webhook listener. For example, you can call back to your database when a certain id has succeeded or even use <a href="https://sendgrid.com/">Sendgrid</a> or <a href="https://www.emailjs.com/">EmailJS</a> to send an email to a recipient when a mint completes.

    ### 4. Setting Up Webhooks on the Crossmint Console

    Add an endpoint for the event `mint.succeeded` by following [this guide](/introduction/platform/webhooks/add-endpoint).

    Once completed, you'll be redirected to the endpoint details page. Here, you can find the signing secret for [verifying webhooks](/introduction/platform/webhooks/verify-webhooks) and view a table of all triggered webhook events.

    <Frame type="simple">
      <img alt="Screenshot of webhooks status UI" />
    </Frame>

    The final step is to test the endpoint. To do so, mint one or two NFTs with the API and observe the responses to verify setup success.

    ## Webhook video walkthrough

    <Frame type="simple">
      <iframe />
    </Frame>
  </Tab>
</Tabs>


# Quickstart ⚡
Source: https://docs.crossmint.com/minting/quickstarts/credentials

Mint credentials that users control, share, and verify anywhere in under 5 minutes

In this quickstart you will learn how to create, issue, and verify credentials.

## What are credentials?

A digital credential is an electronic record issued by a trusted source that certifies specific information about a person or entity. Crossmint makes it easy to issue, manage, and verify credentials onchain, following the [W3C VC standard](https://www.w3.org/TR/vc-data-model-2.0/).

<Frame type="simple">
  <img alt="Verifiable Credentials API" />
</Frame>

<Note>
  Verifiable Credentials is an Enterprise feature. <a href="https://www.crossmint.com/contact/sales">Contact Sales</a>
  for access.
</Note>

## Integration steps

### 1. Create a Developer Account

<Snippet />

### 2. Get an API Key

<Snippet />

Within the "Server-side keys" section, click the "Create new key" button in the top right.
Then, check the scopes `credentials.create`, `credentials.read`, and `credentials:templates.create` under the "Verifiable Credentials"
category and create your key. Save this key for the next step.

### 3. Create a Credential Template

Every Verifiable Credential must belong to a template. Verifiable Credentials within a template share the same schema (referred to as "type" in the template definition), default-metadata, encryption, storage, and chain configurations. A credential template is equivalent to an NFT collection.

For the purpose of this quickstart, we will create a template with the following parameters:

* Type: `crossmint:bedea4c5-4cea-425b-99c7-797ecbc8bc13:CourseCompletionCertificate`. Types allow you to specify the attributes you are interested in certifying. They also act as a protective measure, preventing the addition of unauthorized fields and, as a result, the tampering of the Verifiable Credential. You can [define your own](/minting/verifiable-credentials/integrate/create-credential-types).

* Encryption: `none`. This means the Verifiable Credential data will be stored in plain text. To encrypt the data, read about the supported [encryption modalities](/minting/verifiable-credentials/integrate/encrypt-credentials).

* Storage: `crossmint`. This means the Verifiable Credential data will be stored by Crossmint. To store the data at the location of your choice, or in decentralized storage, read about the supported [storage modalities](/minting/verifiable-credentials/integrate/store-credentials).

The credential’s revocation state is stored in the chain provided (`polygon-amoy`), along with public (non-confidential) metadata related to your credential’s template.

```javascript createTemplate.js theme={null}
const apiKey = "YOUR_API_KEY";
const env = "staging"; // or "www"

const url = `https://${env}.crossmint.com/api/v1-alpha1/credentials/templates`;
const options = {
    method: "POST",
    headers: {
        accept: "application/json",
        "content-type": "application/json",
        "x-api-key": apiKey,
    },
    body: JSON.stringify({
        credentials: {
            type: "crossmint:bedea4c5-4cea-425b-99c7-797ecbc8bc13:CourseCompletionCertificate",
            encryption: "none",
            storage: "crossmint",
            subject: {
                properties: {
                    course: {
                        type: "string",
                        title: "Course",
                        description: "Course name",
                    },
                    grade: {
                        type: "string",
                        title: "Grade",
                        description: "Grade received",
                    },
                },
                required: ["course", "grade"],
            },
        },
        metadata: {
            name: "Certificate of Completion",
            description: "A certificate issued upon completion of a course",
            imageUrl: "https://www.crossmint.com/assets/crossmint/logo.png",
        },
        chain: "polygon-amoy",
    }),
};

fetch(url, options)
    .then((res) => res.json())
    .then((json) => console.log(json))
    .catch((err) => console.error("error:" + err));
```

<Accordion title="Example response">
  ```json JSON theme={null}
  {
    "id": "a9e3016b-66f0-40ab-8d72-6546fddc7b72",
    "metadata": {
      "description": "A certificate issued upon completion of a course",
      "name": "Certificate of Completion",
      "imageUrl": "ipfs://QmaToZn4VEjF7q4CAudPaNka6AD484xuuEZSXmTLJPDLVE"
    },
    "fungibility": "non-fungible",
    "onChain": { "chain": "polygon-amoy", "type": "erc-721" },
    "subscription": { "enabled": false },
    "actionId": "a9e3016b-66f0-40ab-8d72-6546fddc7b72"
  }
  ```
</Accordion>

Save the `id` from the response as your `TEMPLATE_ID` for the next step.

### 4. Issue a Credential

With a template created, we can start issuing credentials. To do this, we need to enter the subject’s email address, or wallet address, if they have one.

Then, we need to specify the exact data required by the Verifiable Credential type, i.e. course name and grade. The credential’s contents are identified by the “subject” key within the credential.

<Note>
  If you don't include an expiration date, the credential will not expire. You can always revoke the credential in the
  future, if necessary.
</Note>

```javascript issueCredential.js theme={null}
const apiKey = "YOUR_API_KEY";
const env = "staging"; // or "www"
const templateId = "YOUR_TEMPLATE_ID";
const recipientEmail = "TEST_EMAIL_ADDRESS";

const url = `https://${env}.crossmint.com/api/v1-alpha1/credentials/templates/${templateId}/vcs`;
const options = {
    method: "POST",
    headers: {
        accept: "application/json",
        "content-type": "application/json",
        "x-api-key": apiKey,
    },
    body: JSON.stringify({
        recipient: `email:${recipientEmail}:polygon-amoy`,
        credential: {
            // The CourseCompletionCertificate credential type requires course and grade declarations
            subject: {
                course: "Blockchain 101",
                grade: "A",
            },
            expiresAt: "2034-02-02",
        },
    }),
};

fetch(url, options)
    .then((res) => res.json())
    .then((json) => console.log(json))
    .catch((err) => console.error("error:" + err));
```

<Accordion title="Example response">
  ```json JSON theme={null}
  {
    "id": "6728f773-61af-4732-a34f-b5a50d8b9872",
    "onChain": {
      "status": "pending",
      "chain": "polygon-amoy",
      "contractAddress": "0x45c9597b5441289C134E554990cdb647f65df5FB"
    },
    "credentialId": "urn:uuid:e6b3dc76-a337-437b-ac1b-3d330e66e1a6",
    "actionId": "6728f773-61af-4732-a34f-b5a50d8b9872"
  }
  ```
</Accordion>

Save the credential `id` from the response for the next step.

### 5. Retrieve a Credential

​​You can retrieve a Verifiable Credential using different identifiers associated with the credential itself or the NFT associated with the credential.

* [Get Verifiable Credential by ID](/api-reference/verifiable-credentials/credentials/retrieve-credential-by-id) uses the format: `urn:uuid:<UUID>`
* [Get Verifiable Credential by NFT Locator](/api-reference/verifiable-credentials/credentials/retrieve-credential-by-nft-locator) uses the format: `<chain>:<contractAddress>:<tokenId>`
* [Get Verifiable Credential by NFT ID](/api-reference/verifiable-credentials/credentials/retrieve-credential-by-nft) uses crossmint's internal NFT ID

```javascript getCredential.js theme={null}
const apiKey = "YOUR_API_KEY";
const env = "staging"; // or "www"
const credentialId = "YOUR_CREDENTIAL_ID";

const url = `https://${env}.crossmint.com/api/v1-alpha1/credentials/${credentialId}`;
const options = {
    method: "GET",
    headers: {
        accept: "application/json",
        "x-api-key": apiKey,
    },
};

fetch(url, options)
    .then((res) => res.json())
    .then((json) => console.log(json))
    .catch((err) => console.error("error:" + err));
```

<Accordion title="Example response">
  ```json JSON theme={null}
  {
    "unencryptedCredential": {
      "id": "urn:uuid:e6b3dc76-a337-437b-ac1b-3d330e66e1a6",
      "credentialSubject": {
        "course": "Blockchain 101",
        "grade": "A",
        "id": "did:polygon-amoy:0x2da3151C266185c4861b45277dbbe56Cb613963e"
      },
      "validUntil": "2034-02-02",
      "nft": {
        "tokenId": "1",
        "chain": "polygon-amoy",
        "contractAddress": "0x45c9597b5441289C134E554990cdb647f65df5FB"
      },
      "issuer": {
        "id": "did:polygon-amoy:0x1785A5DE9e0F06791393739De496a0a2c9ACA855"
      },
      "type": ["VerifiableCredential", "Course completion"],
      "validFrom": "2025-05-28T14:31:03.514Z",
      "@context": ["https://www.w3.org/ns/credentials/v2"],
      "proof": {
        "verificationMethod": "did:polygon-amoy:0x1785A5DE9e0F06791393739De496a0a2c9ACA855#evmAddress",
        "created": "2025-05-28T14:31:03.514Z",
        "proofPurpose": "assertionMethod",
        "type": "EthereumEip712Signature2021",
        "proofValue": "0x17f624a23b620de2867dbefbeb5214e5693a4b470897302f91f870383d4f5ee7754600d1fb72b73c926fed56aac20724ce87d49e0078e0b13f02734a199ceaa61b",
        "eip712": [Object]
      }
    }
  }
  ```
</Accordion>

### 6. Verify a Credential

<Note>
  Verifying a credential can be done in different ways, the easiest one is to call the verify API route. You can also accomplish
  this with the [SDK](/sdk-reference/credentials/introduction).
</Note>

To verify a credential's validity via API use the following script:

```javascript verifyCredential.js theme={null}
const apiKey = "YOUR_API_KEY";
const env = "staging"; // or "www"
const credentialId = "YOUR_CREDENTIAL_ID";

const url = `https://${env}.crossmint.com/api/v1-alpha1/credentials/verification/verify`;
const options = {
    method: "POST",
    headers: {
        "accept": "application/json",
        "content-type": "application/json",
        "x-api-key": apiKey,
    },
    body: JSON.stringify({
        // paste credential object here
        credential : {
            id: "urn:uuid:e6b3dc76-a337-437b-ac1b-3d330e66e1a6",
            ...
        }
    })
};

fetch(url, options)
    .then((res) => res.json())
    .then((json) => console.log(json))
    .catch((err) => console.error("error:" + err));
```

<Accordion title="Example response">
  ```json JSON theme={null}
  { isValid: true }
  ```
</Accordion>

### 7. Revoke a Credential (Optional)

To revoke a credential, you can directly use the [revoke credential API](/api-reference/verifiable-credentials/credentials/revoke-credential):

```javascript revokeCredential.js theme={null}
const apiKey = "YOUR_API_KEY";
const env = "staging"; // or "www"
const credentialId = "YOUR_CREDENTIAL_ID";

const url = `https://${env}.crossmint.com/api/v1-alpha1/credentials/${credentialId}`;
const options = {
    method: "DELETE",
    headers: {
        accept: "application/json",
        "x-api-key": apiKey,
    },
};

fetch(url, options)
    .then((res) => res.json())
    .then((json) => console.log(json))
    .catch((err) => console.error("error:" + err));
```

<Accordion title="Example response">
  ```json JSON theme={null}
  {
    "actionId": "15bfe43c-3d5d-4d03-9e20-6dbaf01f038f",
    "action": "nfts.delete",
    "status": "pending",
    "data": {
      "chain": "polygon-amoy",
      "collection": {
        "id": "a9e3016b-66f0-40ab-8d72-6546fddc7b72",
        "contractAddress": "0x45c9597b5441289C134E554990cdb647f65df5FB"
      },
      "token": { 
        "id": "6728f773-61af-4732-a34f-b5a50d8b9872", 
        "tokenId": "1" 
      }
    },
    "startedAt": "2025-05-28T16:53:11.000Z",
    "resource": "https://staging.crossmint.com/api/2022-06-09/collections/a9e3016b-66f0-40ab-8d72-6546fddc7b72/nfts/15bfe43c-3d5d-4d03-9e20-6dbaf01f038f"
  }
  ```
</Accordion>

## Learn More

For more detailed information about Verifiable Credentials, please visit the dedicated [Verifiable Credentials section](/verifiable-credentials/introduction) which includes comprehensive guides on:

<CardGroup>
  <Card title="Create Credential Types" icon="file" href="/minting/verifiable-credentials/integrate/create-credential-types">
    Learn how to define the structure of your credentials.
  </Card>

  <Card title="Create Credential Templates" icon="cloud" href="/minting/verifiable-credentials/integrate/create-credential-templates">
    Create reusable templates for your credentials.
  </Card>

  <Card title="Issue Credentials" icon="file-pen" href="/minting/verifiable-credentials/integrate/issue-credentials">
    Issue credentials to users.
  </Card>

  <Card title="Verify Credentials" icon="shield-check" href="/minting/verifiable-credentials/integrate/verify-credentials">
    Verify the authenticity of credentials.
  </Card>
</CardGroup>


# Quickstart ⚡
Source: https://docs.crossmint.com/minting/quickstarts/ip

Mint IP credentials for creators to secure their work in under 5 minutes

In this quickstart you will learn how to create and manage intellectual property (IP) assets.

<Note>Contact [sales](https://www.crossmint.com/contact/sales) to enable this API on your project.</Note>

## What are IP credentials?

IP credentials are onchain records of intellectual property rights and authorship, enabled by Story Protocol's infrastructure and issued using Crossmint's APIs.

## Integration steps

### 1. Create a Developer Account

<Snippet />

### 2. Get an API Key

<Snippet />

Within the "Server-side keys" section, click the "Create new key" button in the top right.
Then, check the necessary scopes under the "Minting API" category: `nfts.create`, `nfts.read`, `collections.create`, `nfts.update` and create your key. Save this key for the next step.

### 3. Create an IP Collection

First, let's create an IP collection to hold our IP assets:

```javascript createIPCollection.js theme={null}
const apiKey = "YOUR_API_KEY";
const env = "staging"; // or "www"

const url = `https://${env}.crossmint.com/api/v1/ip/collections`;
const options = {
    method: "POST",
    headers: {
        accept: "application/json",
        "content-type": "application/json",
        "x-api-key": apiKey,
    },
    body: JSON.stringify({
        metadata: {
            description: "A collection of intellectual property assets",
            name: "My IP Collection",
            symbol: "MPA",
        },
        chain: "story-testnet",
    }),
};

fetch(url, options)
    .then((res) => res.json())
    .then((json) => console.log(json))
    .catch((err) => console.error("error:" + err));
```

<Accordion title="Example response">
  Here is an example response returned from the API call above:

  ```json JSON theme={null}
  {
      "id": "7f5e653d-2c9d-4025-98c8-8245c128ad10",
      "actionId": "7f5e653d-2c9d-4025-98c8-8245c128ad10",
      "metadata": {
          "name": "My IP Collection",
          "symbol": "MPA",
          "description": "A collection of intellectual property assets"
      },
      "onChain": {
          "chain": "story-testnet"
      }
  }
  ```
</Accordion>

Save the collection `id` from the response for the next step.

### 4. Create an IP Asset

Now, let's create an IP asset within our collection:

```javascript createIPAsset.js theme={null}
const apiKey = "YOUR_API_KEY";
const env = "staging"; // or "www"
const collectionId = "YOUR_COLLECTION_ID";

const url = `https://${env}.crossmint.com/api/v1/ip/collections/${collectionId}/ipassets`;
const options = {
    method: "POST",
    headers: {
        accept: "application/json",
        "content-type": "application/json",
        "x-api-key": apiKey,
    },
    body: JSON.stringify({
        owner: "email:creator@example.com:story-testnet",
        nftMetadata: {
            name: "Snowflake Funk",
            description: "A disco song for the winter holidays",
            image: "https://cdn2.suno.ai/image_large_c001fd6e-d6cd-474f-a7b6-6e6a9b3e2515.jpeg",
        },
        ipAssetMetadata: {
            title: "Snowflake Funk",
            createdAt: "2025-02-11T11:13:00",
            ipType: "music",
            image: "https://cdn2.suno.ai/image_large_example.jpeg",
            imageHash: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
            mediaUrl: "https://cdn1.suno.ai/c001fd6e-d6cd-474f-a7b6-6e6a9b3e2515.mp3",
            mediaHash: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
            mediaType: "audio/mpeg",
            creators: [
                {
                    name: "John Doe",
                    email: "john.doe@example.com",
                    crossmintUserLocator: "email:john.doe@example.com:story-testnet",
                    contributionPercent: 100,
                },
            ],
            media: [
                {
                    name: "Snowflake Funk",
                    url: "https://cdn1.suno.ai/c001fd6e-d6cd-474f-a7b6-6e6a9b3e2515.mp3",
                    mimeType: "audio/mpeg",
                },
            ],
            attributes: [
                {
                    key: "Suno Artist",
                    value: "InfluentialCoda427",
                },
                {
                    key: "Source",
                    value: "Suno.com",
                },
            ],
        },
    }),
};

fetch(url, options)
    .then((res) => res.json())
    .then((json) => console.log(json))
    .catch((err) => console.error("error:" + err));
```

<Accordion title="Example response">
  Here is an example response returned from the API call above:

  ```json JSON theme={null}
  {
      "id": "49b9e141-8fd8-45dc-9646-13a3439c6f20",
      "actionId": "49b9e141-8fd8-45dc-9646-13a3439c6f20",
      "nftMetadata": {
          "name": "Snowflake Funk",
          "image": "https://cdn2.suno.ai/image_large_c001fd6e-d6cd-474f-a7b6-6e6a9b3e2515.jpeg",
          "description": "A disco song for the winter holidays"
      },
      "ipAssetMetadata": {
          "title": "Snowflake Funk",
          "createdAt": "2025-02-11T11:13:00",
          "creators": [
              {
                  "name": "John Doe",
                  "email": "john.doe@example.com",
                  "crossmintUserLocator": "email:john.doe@example.com:story-testnet",
                  "contributionPercent": 100
              }
          ],
          "media": [
              {
                  "name": "Snowflake Funk",
                  "url": "https://cdn1.suno.ai/c001fd6e-d6cd-474f-a7b6-6e6a9b3e2515.mp3",
                  "mimeType": "audio/mpeg"
              }
          ],
          "attributes": [
              {
                  "key": "Suno Artist",
                  "value": "InfluentialCoda427"
              },
              {
                  "key": "Source",
                  "value": "Suno.com"
              }
          ],
          "ipType": "music"
      },
      "licenseTerms": [
          {
              "type": "non-commercial-social-remixing"
          }
      ],
      "onChain": {
          "chain": "story-testnet",
          "contractAddress": "0x82a72DfFb175DF8AB6d3C2E3888D5314a50C30D0",
          "status": "pending"
      }
  }
  ```
</Accordion>

Save the IP asset `id` from the response for the next steps.

### 5. Retrieve an IP Asset

To retrieve an IP asset:

```javascript getIPAsset.js theme={null}
const apiKey = "YOUR_API_KEY";
const env = "staging"; // or "www"
const collectionId = "YOUR_COLLECTION_ID";
const ipAssetId = "YOUR_IP_ASSET_ID";

const url = `https://${env}.crossmint.com/api/v1/ip/collections/${collectionId}/ipassets/${ipAssetId}`;
const options = {
    method: "GET",
    headers: {
        accept: "application/json",
        "x-api-key": apiKey,
    },
};

fetch(url, options)
    .then((res) => res.json())
    .then((json) => console.log(json))
    .catch((err) => console.error("error:" + err));
```

<Accordion title="Example response">
  Here is an example response returned from the API call above:

  ```json JSON theme={null}
  {
      "id": "49b9e141-8fd8-45dc-9646-13a3439c6f20",
      "actionId": "49b9e141-8fd8-45dc-9646-13a3439c6f20",
      "nftMetadata": {
          "name": "Snowflake Funk",
          "image": "ipfs://QmYA9HyvoPmxvsMx216MFkoydtrA1sSxX5A5ixeu5S9VKF",
          "description": "A disco song for the winter holidays"
      },
      "ipAssetMetadata": {
          "title": "Snowflake Funk",
          "createdAt": "2025-02-11T11:13:00",
          "creators": [
              {
                  "name": "John Doe",
                  "email": "john.doe@example.com",
                  "crossmintUserLocator": "email:john.doe@example.com:story-testnet",
                  "contributionPercent": 100
              }
          ],
          "media": [
              {
                  "name": "Snowflake Funk",
                  "url": "https://cdn1.suno.ai/c001fd6e-d6cd-474f-a7b6-6e6a9b3e2515.mp3",
                  "mimeType": "audio/mpeg"
              }
          ],
          "attributes": [
              {
                  "key": "Suno Artist",
                  "value": "InfluentialCoda427"
              },
              {
                  "key": "Source",
                  "value": "Suno.com"
              }
          ],
          "ipType": "music"
      },
      "licenseTerms": [
          {
              "type": "non-commercial-social-remixing",
              "uri": ""
          }
      ],
      "onChain": {
          "chain": "story-testnet",
          "contractAddress": "0x82a72DfFb175DF8AB6d3C2E3888D5314a50C30D0",
          "status": "success",
          "ipAssetId": "0xe20936B1C974E7C550b483243719A1B1886D2c6c",
          "tokenId": "1",
          "txId": "0x4e505bcd429960d3031bd8d1f27bb7ffd2cfa251498c12c16cf2375a14d2bd51",
          "owner": "0x1a042BBEFb116072E6AEF8304f9B7D15aA2b4BCF",
          "explorerLink": "https://aeneid.explorer.story.foundation/ipa/0xe20936B1C974E7C550b483243719A1B1886D2c6c"
      }
  }
  ```
</Accordion>

### 6. Update an IP Asset

If needed, you can update an IP asset:

```javascript updateIPAsset.js theme={null}
const apiKey = "YOUR_API_KEY";
const env = "staging"; // or "www"
const collectionId = "YOUR_COLLECTION_ID";
const ipAssetId = "YOUR_IP_ASSET_ID";

const url = `https://${env}.crossmint.com/api/v1/ip/collections/${collectionId}/ipassets/${ipAssetId}`;
const options = {
    method: "PATCH",
    headers: {
        accept: "application/json",
        "content-type": "application/json",
        "x-api-key": apiKey,
    },
    body: JSON.stringify({
        ipAssetMetadata: {
            title: "Snowflake Funk",
            createdAt: "2025-02-11T11:13:00",
            ipType: "music",
            creators: [
                {
                    name: "John Doe",
                    email: "john.doe@example.com",
                    crossmintUserLocator: "email:john.doe@example.com:story-testnet",
                    contributionPercent: 90,
                },
                {
                    name: "Frank L",
                    crossmintUserLocator: "email:frank.l@example.com:story-testnet",
                    contributionPercent: 10,
                },
            ],
        },
    }),
};

fetch(url, options)
    .then((res) => res.json())
    .then((json) => console.log(json))
    .catch((err) => console.error("error:" + err));
```

<Accordion title="Example response">
  Here is an example response returned from the API call above:

  ```json JSON theme={null}
  {
      "id": "75a45061-febb-4344-84d6-959276a5696a",
      "actionId": "75a45061-febb-4344-84d6-959276a5696a",
      "nftMetadata": {
          "name": "Snowflake Funk",
          "image": "ipfs://QmYA9HyvoPmxvsMx216MFkoydtrA1sSxX5A5ixeu5S9VKF",
          "description": "A disco song for the winter holidays"
      },
      "ipAssetMetadata": {
          "title": "Snowflake Funk",
          "createdAt": "2025-02-11T11:13:00",
          "creators": [ ... ],
          "ipType": "music"
      },
      "licenseTerms": [ { "type": "non-commercial-social-remixing", "uri": "" } ],
      "onChain": {
          "chain": "story-testnet",
          "contractAddress": "0x82a72DfFb175DF8AB6d3C2E3888D5314a50C30D0",
          "status": "pending"
      }
  }
  ```
</Accordion>

## Learn More

For more detailed information about IP assets, please refer to the API reference:

<CardGroup>
  <Card title="Create IP Collection" icon="file" href="/api-reference/ip/create-ip-collection">
    Learn how to create IP collections.
  </Card>

  <Card title="Create IP Asset" icon="cloud" href="/api-reference/ip/create-ip-asset">
    Create IP assets within collections.
  </Card>

  <Card title="Update IP Asset" icon="file-pen" href="/api-reference/ip/update-ip-asset">
    Update existing IP assets.
  </Card>

  <Card title="Get IP Assets" icon="magnifying-glass" href="/api-reference/ip/get-ip-assets">
    Retrieve IP assets from collections.
  </Card>
</CardGroup>


# Non-Fungible Tokens (NFTs)
Source: https://docs.crossmint.com/minting/quickstarts/nfts

Mint an NFT in under 5 minutes

In this quickstart you will learn how to create a unique NFT and deliver it to a wallet or email address.

<Frame type="simple">
  <img alt="Minting API" />
</Frame>

## Integration steps

<Tabs>
  <Tab title="EVM Chains">
    ### 1. Create a Developer Account

    <Snippet />

    ### 2. Get an API Key

    <Snippet />

    Within the "Server-side keys" section, click the "Create new key" button in the top right.
    Then, check the scopes `nfts.create` and `nfts.read` under the "Minting API"
    category and create your key. Save this key for the next step.

    ### 3. Mint an NFT

    We're almost there! With our key created, we're now going to write a small
    function that creates an NFT and delivers it to a user.

    Create a file (e.g. `mintNFT.js`) and enter this code into it:

    ```javascript mintNFT.js theme={null}
    const apiKey = "YOUR_API_KEY";
    const chain = "polygon-amoy"; // or "ethereum-sepolia", "base-sepolia", etc.
    const env = "staging"; // or "www"
    const recipientEmail = "TEST_EMAIL_ADDRESS";
    const recipientAddress = `email:${recipientEmail}:${chain}`;

    const url = `https://${env}.crossmint.com/api/2022-06-09/collections/default/nfts`;
    const options = {
        method: "POST",
        headers: {
            "accept": "application/json",
            "content-type": "application/json",
            "x-api-key": apiKey,
        },
        body: JSON.stringify({
            recipient: recipientAddress,
            metadata: {
                name: "Crossmint Test NFT",
                image: "https://picsum.photos/400",
                description: "My first NFT using Crossmint",
            },
        }),
    };

    fetch(url, options)
        .then((res) => res.json())
        .then((json) => console.log(json))
        .catch((err) => console.error("error:" + err));
    ```

    This code creates an NFT, uploads it to the blockchain, and delivers it to a <Tooltip>user wallet</Tooltip>, attached to the email address provided. Before running it, be sure to fill in values for:

    * `YOUR_API_KEY` with the key obtained in the prior step.
    * `TEST_EMAIL_ADDRESS` with an email address you control, for testing.

    Now, run the `mintNFT.js` script.

    ```bash theme={null}
    node mintNFT.js
    ```

    After a few seconds, it should return a response indicating the mint has
    started processing. Check the full response and save its <Tooltip>`actionId` property</Tooltip>, as you'll use it later.

    <Accordion title="Example response">
      Here is an example response returned from the API call above:

      ```json JSON theme={null}
      {
          "id": "b3f61f22-c30e-424d-a5ab-d0cbc5c41aab",
          "onChain": {
              "status": "pending",
              "chain": "polygon-amoy",
              "contractAddress": "0x921Bc21bf3Fd6568cdC2C904F75b83556062c3d0"
          },
          "actionId": "b3f61f22-c30e-424d-a5ab-d0cbc5c41aab"
      }
      ```
    </Accordion>

    ### 4. Confirm Delivery of the NFT

    The mint has started processing. However, blockchains can take a few seconds (or,
    at times of extreme network congestion, even minutes) to confirm the operation.

    Before showing the user a success screen, the next step is checking the
    status of the mint.

    To do this, grab the `actionId` received at the end of step 3 and use it
    alongside your API key in one of the snippets below.

    <CodeGroup>
      ```javascript mintStatus.js theme={null}
      const apiKey = "<YOUR_API_KEY>";
      const env = "staging"; // or "www"
      const actionId = "<MINT_ACTION_ID>";

      const url = `https://${env}.crossmint.com/api/2022-06-09/actions/${actionId}`;
      const options = {
          method: "GET",
          headers: { "X-API-KEY": apiKey },
      };

      fetch(url, options)
          .then((response) => response.json())
          .then((response) => console.log(response))
          .catch((err) => console.error(err));
      ```

      ```bash cURL theme={null}
      # Replace "staging" with "www" for production, and fill in your api key and mint action id
      ENV="staging"
      API_KEY="<YOUR_API_KEY>"
      MINT_ACTION_ID="<MINT_ACTION_ID>"
      curl --header "x-api-key: $API_KEY" \
        -X GET \
        https://${ENV}.crossmint.com/api/2022-06-09/actions/${MINT_ACTION_ID}
      ```
    </CodeGroup>

    <br />

    <Accordion title="Example response">
      Here is an example response from calling the status API:

      ```json JSON theme={null}
      {
        "actionId": "b3f61f22-c30e-424d-a5ab-d0cbc5c41aab",
        "action": "nfts.create",
        "status": "success",
        "data": {
          "collection": {...},
          "recipient": {...},
          "token": {...}
        },
        "startedAt": "2025-05-27T02:41:08.000Z",
        "completedAt": "2025-05-27T02:41:40.000Z",
        "resource": "https://staging.crossmint.com/api/2022-06-09/collections/default-polygon-amoy/nfts/b3f61f22-c30e-424d-a5ab-d0cbc5c41aab"
      }
      ```
    </Accordion>

    Pay attention to the "status" field. Once it says "success": <br /><br />
    **Congratulations. You have minted your first NFT** 🥷 🎉

    <Note>
      For scalable production applications, consider using [webhooks](/minting/nfts/integrate/webhooks-and-status-apis) to
      determine when your NFT has been minted, instead of periodically polling for its status via the API.
    </Note>
  </Tab>

  <Tab title="Solana">
    ### 1. Create a Developer Account

    <Snippet />

    ### 2. Get an API Key

    <Snippet />

    Within the "Server-side keys" section, click the "Create new key" button in the top right.
    Then, check the scopes `nfts.create` and `nfts.read` under the "Minting API"
    category and create your key. Save this key for the next step.

    ### 3. Mint an NFT

    We're almost there! With our key created, we're now going to write a small
    function that creates an NFT and delivers it to a user.

    Create a file (e.g. `mintNFT.js`) and enter this code into it:

    ```javascript mintNFT.js theme={null}
    const apiKey = "YOUR_API_KEY";
    const chain = "solana";
    const env = "staging"; // or "www"
    const recipientEmail = "TEST_EMAIL_ADDRESS";
    const recipientAddress = `email:${recipientEmail}:${chain}`;

    const url = `https://${env}.crossmint.com/api/2022-06-09/collections/default-solana/nfts`;
    const options = {
        method: "POST",
        headers: {
            "accept": "application/json",
            "content-type": "application/json",
            "x-api-key": apiKey,
        },
        body: JSON.stringify({
            recipient: recipientAddress,
            metadata: {
                name: "Crossmint Test NFT",
                image: "https://picsum.photos/400",
                description: "My first NFT using Crossmint",
            },
        }),
    };

    fetch(url, options)
        .then((res) => res.json())
        .then((json) => console.log(json))
        .catch((err) => console.error("error:" + err));
    ```

    This code creates an NFT, uploads it to the Solana blockchain, and delivers it to a <Tooltip>user wallet</Tooltip>, attached to the email address provided. Before running it, be sure to fill in values for:

    * `YOUR_API_KEY` with the key obtained in the prior step.
    * `TEST_EMAIL_ADDRESS` with an email address you control, for testing.

    Now, run the `mintNFT.js` script.

    ```bash theme={null}
    node mintNFT.js
    ```

    After a few seconds, it should return a response indicating the mint has
    started processing. Check the full response and save its <Tooltip>`actionId` property</Tooltip>, as you'll use it later.

    <Accordion title="Example response">
      Here is an example response returned from the API call above:

      ```json JSON theme={null}
      {
          "id": "cace8d7d-e4dd-483d-a780-faf6aa9f761a",
          "onChain": {
              "status": "pending",
              "chain": "solana"
          },
          "actionId": "cace8d7d-e4dd-483d-a780-faf6aa9f761a"
      }
      ```
    </Accordion>

    ### 4. Confirm Delivery of the NFT

    The mint has started processing. However, blockchains can take a few seconds (or,
    at times of extreme network congestion, even minutes) to confirm the operation.

    Before showing the user a success screen, the next step is checking the
    status of the mint.

    To do this, grab the `actionId` received at the end of step 3 and use it
    alongside your API key in one of the snippets below.

    <CodeGroup>
      ```javascript mintStatus.js theme={null}
      const apiKey = "<YOUR_API_KEY>";
      const env = "staging"; // or "www"
      const actionId = "<MINT_ACTION_ID>";

      const url = `https://${env}.crossmint.com/api/2022-06-09/actions/${actionId}`;
      const options = {
          method: "GET",
          headers: { "X-API-KEY": apiKey },
      };

      fetch(url, options)
          .then((response) => response.json())
          .then((response) => console.log(response))
          .catch((err) => console.error(err));
      ```

      ```bash cURL theme={null}
      # Replace "staging" with "www" for production, and fill in your api key and mint action id
      ENV="staging"
      API_KEY="<YOUR_API_KEY>"
      MINT_ACTION_ID="<MINT_ACTION_ID>"
      curl --header "x-api-key: $API_KEY" \
        -X GET \
        https://${ENV}.crossmint.com/api/2022-06-09/actions/${MINT_ACTION_ID}
      ```
    </CodeGroup>

    <br />

    <Accordion title="Example response">
      Here is an example response from calling the status API:

      ```json JSON theme={null}
      {
        "actionId": "cace8d7d-e4dd-483d-a780-faf6aa9f761a",
        "action": "nfts.create",
        "status": "success",
        "data": {
          "chain": "solana",
          "txId": "5KQHjcEq7DWnD1Rzo7RW7rknY3NFeKsJ9Lxkrd1DBPPwxbv9k4JAgxELWW5rqWMd5sXrHDwYzsRMeUok3tqYvTLa",
          "collection": {...},
          "recipient": {...},
          "token": {...}
        },
        "startedAt": "2025-05-27T03:04:23.000Z",
        "completedAt": "2025-05-27T03:04:49.000Z",
        "resource": "https://staging.crossmint.com/api/2022-06-09/actions/cace8d7d-e4dd-483d-a780-faf6aa9f761a"
      }
      ```
    </Accordion>

    Pay attention to the "status" field. Once it says "success": <br /><br />
    **Congratulations. You have minted your first NFT** 🥷 🎉

    <Note>
      For scalable production applications, consider using [webhooks](/minting/nfts/integrate/webhooks-and-status-apis) to
      determine when your NFT has been minted, instead of periodically polling for its status via the API.
    </Note>
  </Tab>

  <Tab title="Compressed NFTs (Solana)">
    ### 1. Create a Developer Account

    <Snippet />

    ### 2. Get an API Key

    <Snippet />

    Within the "Server-side keys" section, click the "Create new key" button in the top right.
    Then, check the scopes `nfts.create` and `nfts.read` under the "Minting API"
    category and create your key. Save this key for the next step.

    ### 3. Mint a Compressed NFT

    We're almost there! With our key created, we're now going to write a small
    function that creates a compressed NFT and delivers it to a user.

    <Note>
      Compressed NFTs are a new standard on the Solana blockchain, for minting NFTs with the lowest cost amongst L1 and L2 blockchains, and the highest throughput (thousands of NFTs per second).
    </Note>

    Create a file (e.g. `mintCompressedNFT.js`) and enter this code into it:

    ```javascript mintCompressedNFT.js theme={null}
    const apiKey = "YOUR_API_KEY";
    const chain = "solana";
    const env = "staging"; // or "www"
    const recipientEmail = "TEST_EMAIL_ADDRESS";
    const recipientAddress = `email:${recipientEmail}:${chain}`;

    const url = `https://${env}.crossmint.com/api/2022-06-09/collections/default-solana/nfts`;
    const options = {
        method: "POST",
        headers: {
            "accept": "application/json",
            "content-type": "application/json",
            "x-api-key": apiKey,
        },
        body: JSON.stringify({
            recipient: recipientAddress,
            metadata: {
                name: "Crossmint Compressed NFT",
                image: "https://picsum.photos/400",
                description: "My first compressed NFT using Crossmint",
            },
            compressed: true,
            reuploadLinkedFiles: false
        }),
    };

    fetch(url, options)
        .then((res) => res.json())
        .then((json) => console.log(json))
        .catch((err) => console.error("error:" + err));
    ```

    This code creates a compressed NFT, uploads it to the Solana blockchain, and delivers it to a <Tooltip>user wallet</Tooltip>, attached to the email address provided. Before running it, be sure to fill in values for:

    * `YOUR_API_KEY` with the key obtained in the prior step.
    * `TEST_EMAIL_ADDRESS` with an email address you control, for testing.

    Now, run the `mintCompressedNFT.js` script.

    ```bash theme={null}
    node mintCompressedNFT.js
    ```

    <Warning>
      Current Protocol Limitations:

      * There's a 10-30 second delay between when a compressed NFT is minted and it shows in wallets.
    </Warning>

    After a few seconds, it should return a response indicating the mint has
    started processing. Check the full response and save its <Tooltip>`actionId` property</Tooltip>, as you'll use it later.

    <Accordion title="Example response">
      Here is an example response returned from the API call above:

      ```json JSON theme={null}
      {
          "actionId": "de26f73e-b0ae-4ac6-8784-39f20527d39d",
          "onChain": {
              "status": "pending",
              "chain": "solana"
          },
          "id": "de26f73e-b0ae-4ac6-8784-39f20527d39d"
      }
      ```
    </Accordion>

    ### 4. Confirm Delivery of the NFT

    The mint has started processing. However, blockchains can take a few seconds (or,
    at times of extreme network congestion, even minutes) to confirm the operation.

    Before showing the user a success screen, the next step is checking the
    status of the mint.

    To do this, grab the `actionId` received at the end of step 3 and use it
    alongside your API key in one of the snippets below.

    <CodeGroup>
      ```bash cURL theme={null}
      # Replace "staging" with "www" for production, and fill in your api key and mint action id
      ENV="staging"
      API_KEY="<YOUR_API_KEY>"
      MINT_ACTION_ID="<MINT_ACTION_ID>"
      curl --header "x-api-key: $API_KEY" \
        -X GET \
        https://${ENV}.crossmint.com/api/2022-06-09/actions/${MINT_ACTION_ID}
      ```

      ```javascript mintStatus.js theme={null}
      const apiKey = "<YOUR_API_KEY>";
      const env = "staging"; // or "www"
      const actionId = "<MINT_ACTION_ID>";

      const url = `https://${env}.crossmint.com/api/2022-06-09/actions/${actionId}`;
      const options = {
          method: "GET",
          headers: { "X-API-KEY": apiKey },
      };

      fetch(url, options)
          .then((response) => response.json())
          .then((response) => console.log(response))
          .catch((err) => console.error(err));
      ```
    </CodeGroup>

    <br />

    <Accordion title="Example response">
      Here is an example response from calling the status API:

      ```json JSON theme={null}
      {
        "actionId": "de26f73e-b0ae-4ac6-8784-39f20527d39d",
        "action": "nfts.create",
        "status": "success",
        "data": {
          "chain": "solana",
          "txId": "dLFcyYtgFrrX7VkXh8U8JUmECNykH7VASzovNzM67NPRypCzMkTnx1ffv7dB99N4YrAT2mDRqszGofKunnazbXX",
          "collection": {...},
          "recipient": {...},
          "token": {...}
        },
        "startedAt": "2025-05-27T03:09:47.000Z",
        "completedAt": "2025-05-27T03:09:52.000Z",
        "resource": "https://staging.crossmint.com/api/2022-06-09/actions/de26f73e-b0ae-4ac6-8784-39f20527d39d"
      }
      ```
    </Accordion>

    Pay attention to the "status" field. Once it says "success": <br /><br />
    **Congratulations. You have minted your first compressed NFT** 🥷 🎉

    <Card title="To explore compressed NFTs on the blockchain, you must use X-Ray" icon="magnifying-glass" href="https://xray.helius.xyz/">
      Other explorers, like Solscan, still have not added support.
    </Card>

    <Note>
      For scalable production applications, consider using [webhooks](/minting/nfts/integrate/webhooks-and-status-apis) to
      determine when your NFT has been minted, instead of periodically polling for its status via the API.
    </Note>
  </Tab>
</Tabs>

## View your NFTs

1. If the NFTs were delivered to an <Tooltip>**email address**</Tooltip>, the recipient can see them by:

   * Logging into their wallet from Crossmint's [website](https://www.crossmint.com). For staging, they must use [https://staging.crossmint.com](https://staging.crossmint.com).
   * From your website if you use [embedded wallets](/wallets/overview). See the API for [getting the NFTs](/api-reference/wallets/get-nfts-from-wallet) in a wallet.

2. If the NFTs were delivered to a **wallet address**, the user will be able to see them there directly, connecting to testnet if needed, or on the testnet blockchain explorer.

And voilá, there's your NFT! Now think of all the cool things you can build
with this, at scale :)

## Launching in Production

For production, the steps are almost identical, but some changes are required:

1. Create a developer account on the [production console](https://www.crossmint.com/console).
2. Add credits to your account from [Billing & Usage](https://www.crossmint.com/console/billing).
3. Then, create a production key on the [API Keys](https://www.crossmint.com/console/projects/apiKeys) page with the
   same API scopes.
4. Modify all code snippets with `const env = "www"`, so they use the production APIs. You may also need to change the
   `chain` variable to match your production blockchain.
5. Check the guide with [best practices](/minting/advanced/best-practices)

## Learn More

<CardGroup>
  <Card title="Create collections" icon="FILE" href="/minting/nfts/integrate/create-collections">
    Learn how to create and manage NFT collections.
  </Card>

  <Card title="Mint NFTs and other tokens" icon="cloud" href="/minting/nfts/integrate/mint-tokens">
    Check out more advanced options for minting digital assets.
  </Card>

  <Card title="Edit NFTs" icon="file-pen" href="/minting/nfts/integrate/update-nfts">
    Update and delete tokens after minting.
  </Card>
</CardGroup>


# Semi-Fungible Tokens (SFTs)
Source: https://docs.crossmint.com/minting/quickstarts/sfts

Mint and send limited sets of identical digital assets in under 5 minutes

In this quickstart you will learn how to create semi-fungible tokens (SFTs) and deliver them to a wallet or email address.

## What are SFTs?

SFTs (semi-fungible tokens) follow the ERC-1155 standard. Each token is a replica of a predefined template. Each collection (smart contract) can contain multiple templates, which can contain many tokens.

<Warning>This API only supports EVM chains self-serve. Contact us if you need support for another chain.</Warning>

## Integration steps

### 1. Create a Developer Account

<Snippet />

### 2. Get an API Key

<Snippet />

Within the "Server-side keys" section, click the "Create new key" button in the top right.
Then, check the scopes `nfts.create`, `nfts.read`, and `collections.create` under the "Minting API"
category and create your key. Save this key for the next step.

### 3. Create an SFT collection

With our key created, we're now going to create an SFT collection to hold our templates.

```javascript createCollection.js theme={null}
const apiKey = "YOUR_API_KEY";
const env = "staging"; // or "www"

const url = `https://${env}.crossmint.com/api/2022-06-09/collections`;
const options = {
    method: "POST",
    headers: {
        accept: "application/json",
        "content-type": "application/json",
        "x-api-key": apiKey,
    },
    body: JSON.stringify({
        chain: "polygon-amoy",
        fungibility: "semi-fungible",
        metadata: {
            name: "My SFT Collection",
            imageUrl: "https://www.crossmint.com/assets/crossmint/logo.png",
            description: "A new collection with its own dedicated smart contract",
        },
    }),
};

fetch(url, options)
    .then((res) => res.json())
    .then((json) => console.log(json))
    .catch((err) => console.error("error:" + err));
```

<Accordion title="Example response">
  ```json JSON theme={null}
  {
    "id": "5263650e-6d43-4ed3-9e31-0cf593d076a4",
    "metadata": {
      "name": "My SFT Collection",
      "description": "A new collection with its own dedicated smart contract",
      "imageUrl": "https://www.crossmint.com/assets/crossmint/logo.png",
      "symbol": "XMINT"
    },
    "fungibility": "semi-fungible",
    "onChain": {
      "chain": "polygon-amoy",
      "type": "erc-1155"
    },
    "actionId": "5263650e-6d43-4ed3-9e31-0cf593d076a4"
  }
  ```
</Accordion>

Save the `id` from the response as your `COLLECTION_ID` for the next steps.

### 4. Create a template within that collection

Now, let's create a template within our collection:

```javascript createTemplate.js theme={null}
const apiKey = "YOUR_API_KEY";
const env = "staging"; // or "www"
const collectionId = "YOUR_COLLECTION_ID";

const url = `https://${env}.crossmint.com/api/2022-06-09/collections/${collectionId}/templates`;
const options = {
    method: "POST",
    headers: {
        accept: "application/json",
        "content-type": "application/json",
        "x-api-key": apiKey,
    },
    body: JSON.stringify({
        onChain: {
            tokenId: "1",
        },
        supply: {
            limit: 10,
        },
        metadata: {
            name: "My template",
            image: "https://www.crossmint.com/assets/crossmint/logo.png",
            description: "A new token template for my ERC1155 collection",
        },
    }),
};

fetch(url, options)
    .then((res) => res.json())
    .then((json) => console.log(json))
    .catch((err) => console.error("error:" + err));
```

<Accordion title="Example response">
  ```json JSON theme={null}
  {
    "templateId": "58b0c1aa-e457-48dd-bb55-5a27e6a92f74",
    "metadata": {
      "name": "My template",
      "image": "ipfs://bafkreigbqsmxzkbjgbwtj6exfdt5z3t3swgoysf7hr6vjzddqnmykj6x2u",
      "description": "A new token template for my ERC1155 collection"
    },
    "onChain": {
      "tokenId": "1"
    },
    "supply": {
      "limit": "10",
      "minted": "0"
    }
  }
  ```
</Accordion>

Save the `templateId` from the response for the next step.

### 5. Mint an SFT from a template

Now, let's mint an SFT from our template and send it to a wallet or email address:

```javascript mintSFT.js theme={null}
const apiKey = "YOUR_API_KEY";
const env = "staging"; // or "www"
const collectionId = "YOUR_COLLECTION_ID";
const templateId = "YOUR_TEMPLATE_ID";
const recipientEmail = "TEST_EMAIL_ADDRESS";

const url = `https://${env}.crossmint.com/api/2022-06-09/collections/${collectionId}/sfts`;
const options = {
    method: "POST",
    headers: {
        accept: "application/json",
        "content-type": "application/json",
        "x-api-key": apiKey,
    },
    body: JSON.stringify({
        templateId: templateId,
        recipient: `email:${recipientEmail}:polygon-amoy`,
        amount: 1,
    }),
};

fetch(url, options)
    .then((res) => res.json())
    .then((json) => console.log(json))
    .catch((err) => console.error("error:" + err));
```

<Accordion title="Example response">
  ```json JSON theme={null}
  {
    "actionId": "a91c15e3-60f2-4a45-bf1a-cee508981667",
    "action": "nfts.create",
    "status": "pending",
    "data":
    {
      "chain": "polygon-amoy",
      "collection":
      {
        "id": "84e3d617-9c1b-4e7a-9686-522a9ea7c520",
        "contractAddress": "0x9b8ab8949bd7E73E61945b88F7fe12151f98ad3C"
      },
      "recipient":
      {
        "walletAddress": "0xcFDc00Cf926A5053f9Cdf004e6DF17e6dEB2E146",
        "email": "test@example.com"
      },
      "token":
      {
        "id": "a91c15e3-60f2-4a45-bf1a-cee508981667"
      }
    },
    "startedAt": "2024-01-02T22:05:01.000Z",
    "resource": "https://staging.crossmint.com/api/2022-06-09/actions/a91c15e3-60f2-4a45-bf1a-cee508981667"
  }
  ```
</Accordion>

### 6. Confirm Delivery of the SFT

The mint has started processing. However, blockchains can take a few seconds (or,
at times of extreme network congestion, even minutes) to confirm the operation.

Before showing the user a success screen, the next step is checking the
status of the mint.

To do this, grab the `actionId` received at the end of step 5 and use it
alongside your API key in one of the snippets below.

<CodeGroup>
  ```javascript mintStatus.js theme={null}
  const apiKey = "<YOUR_API_KEY>";
  const env = "staging"; // or "www"
  const actionId = "<MINT_ACTION_ID>";

  const url = `https://${env}.crossmint.com/api/2022-06-09/actions/${actionId}`;
  const options = {
      method: "GET",
      headers: { "X-API-KEY": apiKey },
  };

  fetch(url, options)
      .then((response) => response.json())
      .then((response) => console.log(response))
      .catch((err) => console.error(err));
  ```

  ```bash cURL theme={null}
  # Replace "staging" with "www" for production, and fill in your api key and mint action id
  ENV="staging"
  API_KEY="<YOUR_API_KEY>"
  MINT_ACTION_ID="<MINT_ACTION_ID>"
  curl --header "x-api-key: $API_KEY" \
    -X GET \
    https://${ENV}.crossmint.com/api/2022-06-09/actions/${MINT_ACTION_ID}
  ```
</CodeGroup>

<br />

<Accordion title="Example response">
  Here is an example response from calling the status API:

  ```json JSON theme={null}
  {
    "actionId": "a91c15e3-60f2-4a45-bf1a-cee508981667",
    "action": "nfts.create",
    "status": "success",
    "data": {
      "collection": {},
      "recipient": {},
      "token": {}
    },
    "startedAt": "2024-01-02T22:05:01.000Z",
    "completedAt": "2024-01-02T22:06:04.000Z", 
    "resource": "https://staging.crossmint.com/api/2022-06-09/actions/a91c15e3-60f2-4a45-bf1a-cee508981667"
  }
  ```
</Accordion>

Pay attention to the "status" field. Once it says "success": <br /><br />
**Congratulations. You have minted your first SFT** 🥷 🎉

<Note>
  For scalable production applications, consider using [webhooks](/minting/nfts/integrate/webhooks-and-status-apis) to
  determine when your SFT has been minted, instead of periodically polling for its status via the API.
</Note>

## View your SFTs

1. If the SFTs were delivered to an <Tooltip>**email address**</Tooltip>, the recipient can see them by:

   * Logging into their wallet from Crossmint's [website](https://www.crossmint.com). For staging, they must use [https://staging.crossmint.com](https://staging.crossmint.com).
   * From your website if you use [embedded wallets](/wallets/overview). See the API for [getting the NFTs](/api-reference/wallets/get-nfts-from-wallet) in a wallet.

2. If the SFTs were delivered to a **wallet address**, the user will be able to see them there directly, connecting to testnet if needed, or on the testnet blockchain explorer.

And voilá, there's your SFT! Now think of all the cool things you can build
with this, at scale :)

## Launching in Production

For production, the steps are almost identical, but some changes are required:

1. Create a developer account on the [production console](https://www.crossmint.com/console).
2. Add credits to your account from [Billing & Usage](https://www.crossmint.com/console/billing).
3. Then, create a production key on the [API Keys](https://www.crossmint.com/console/projects/apiKeys) page with the
   same API scopes.
4. Modify all code snippets with `const env = "www"`, so they use the production APIs. You may also need to change the
   `chain` variable to match your production blockchain.
5. Check the guide with [best practices](/minting/advanced/best-practices)

## Learn More

<CardGroup>
  <Card title="Create collections" icon="FILE" href="/minting/nfts/integrate/create-collections">
    Learn how to create and manage SFT collections.
  </Card>

  <Card title="Mint NFTs and other tokens" icon="cloud" href="/minting/nfts/integrate/mint-tokens">
    Check out more advanced options for minting.
  </Card>

  <Card title="Edit & Burn NFTs" icon="file-pen" href="/minting/guides/edit-and-burn-nfts">
    Update and delete tokens after minting.
  </Card>
</CardGroup>


# Create Credential Templates
Source: https://docs.crossmint.com/minting/verifiable-credentials/integrate/create-credential-templates

Create Verifiable Credential templates with a single API call

A Verifiable Credential template is equivalent to an NFT collection. Similar to how a NFT collection groups NFTs together, a Verifiable Credential template references the credential type and additional credential configurations that credentials adhere to. Every Verifiable Credential must belong to a template.

When defining a template, the issuer initially specifies a **credentials** object. Within that the following needs to be provided:

* **type** (required): A credential's private data schema is referred to as "type". Types act as a protective measure, preventing the addition of unauthorized fields and, as a result, the tampering of the Verifiable Credential. You can [define your own](/minting/verifiable-credentials/integrate/create-credential-types).

* **encryption** (required): The method chosen to protect the credential's private data. If set to `none` the credential's private data will be stored in plain text. To encrypt and protect the credential's private data, read about the supported [encryption modalities](/minting/verifiable-credentials/integrate/encrypt-credentials).

* **storage** (required): The location where credentials defined by this template will be stored. Such storage can be on Crossmint, another company's database, or decentralized storage. Read about the supported [storage modalities](/minting/verifiable-credentials/integrate/store-credentials).

The template issuer must then specify the template's public metadata:

* **metadata** (required): A template's public name, description and imageUrl. Name is required, while the other attributes are optional.

Finally, the issuer provides information on:

* **chain** (required): The blockchain where the credential's contract and associated NFTs will be registered. Verifiable Credentials supports all EVM chains. Interested in launching your verifiable credentials on a specific blockchain? [Get in touch](https://www.crossmint.com/contact/sales).

* **delegatedSignature** (optional): A non-custodial wallet of choice to be used for signing credential issuance. By default, the issuer's Crossmint-managed custodial wallet will be used. Read more about delegated signatures [here](/minting/verifiable-credentials/integrate/delegated-signatures).

## 1. Create a Credential Template

To issue a Verifiable Credential you have to first create the template that this credential will adhere to. You can do so via a single API call (requires the API key scope `templates.create`):

```javascript createTemplate.js theme={null}
const myApiKey = "<YOUR_API_KEY>"; // Replace with key from step 2

const templateParams = {
    credentials: {
        type: "crossmint:5fe6040e-07a1-48bb-97a3-b588a7e927d2:CourseCompletionCertificate",
        encryption: "none",
        storage: "crossmint",
    },
    metadata: {
        name: "Satoshi University Credentials",
        description: "Credentials accredited by Satoshi University",
        imageUrl: "https://picsum.photos/400",
    },
    chain: "polygon-amoy",
};

const options = {
    method: "POST",
    headers: {
        "X-API-KEY": myApiKey,
        "Content-Type": "application/json",
    },
    body: JSON.stringify(templateParams),
};

fetch("https://staging.crossmint.com/api/v1-alpha1/credentials/templates/", options)
    .then((response) => response.json())
    .then((response) => console.log(JSON.stringify(response)))
    .catch((err) => console.error(err));
```

The template's metadata will be used by default for the NFT metadata, unless explicitly set when issuing a new credential.

## 2. Check the status of your template

It takes a few seconds (up to a minute, depending on the blockchain and how congested it is) to deploy a template.

To check the template's status, you will need the `nfts.create` API scope and run the following code.

```typescript checkTemplateStatus.js theme={null}
const templateId = "<YOUR_TEMPLATE_ID>";
const options = { method: "GET", headers: { "X-API-KEY": "<YOUR_API_KEY>" } };

fetch(`https://staging.crossmint.com/api/2022-06-09/actions/${templateId}`, options)
    .then((response) => response.json())
    .then((response) => console.log(response))
    .catch((err) => console.error(err));
```

<CardGroup>
  <Card title="API Reference" icon="terminal" href="/api-reference/verifiable-credentials/templates/create-template">
    Test any API in seconds directly from the docs.
  </Card>

  <Card title="Talk to an expert" icon="message" href="https://www.crossmint.com/contact/sales">
    Contact our sales team for support.
  </Card>
</CardGroup>


# Create Credential Types
Source: https://docs.crossmint.com/minting/verifiable-credentials/integrate/create-credential-types

Specify the schema that the Verifiable Credential adheres to

In the realm of Verifiable Credentials, each credential must be associated with a schema. The credential's schema is referred to as "type".

Credential types outline the attributes and their respective data types that the credential contains. The purpose of types is to ensure the credential's authenticity. Types allow you to specify the attributes you are interested in certifying and act as a protective measure, preventing the addition of unauthorized attributes and, as a result, the tampering of the Verifiable Credential.

It's important to note that all credentials within a single template will share the same type. Trying to issue or verify a credential with different field names or types will result in an error.

By adhering to this structure, we maintain the integrity and verifiability of the credentials, ensuring they serve their purpose effectively.

## Example Types

Credentials play a crucial role in verifying and validating various aspects of identity, achievement, and authorization. Below are some examples of credential types you can create and manage through Crossmint:

### Proof of Employment

* Purpose: Issued to individuals that want to prove their employment.
* Name: `ProofOfEmployment`

```typescript theme={null}
ProofOfEmployment {
    position: string;
    department: string;
    startDate: string;
}
```

The payload used to create this type is the following:

```json theme={null}
{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "title": "Proof of Employment",
    "description": "Schema for verifying employment details",
    "type": "object",
    "properties": {
        "credentialSubject": {
            "type": "object",
            "properties": {
                "position": {
                    "type": "string"
                },
                "department": {
                    "type": "string"
                },
                "startDate": {
                    "type": "string"
                }
            },
            "required": ["position", "department", "startDate"],
            "additionalProperties": false
        }
    }
}
```

To reference this example type in your credential template definition, use `crossmint:bfb292e7-2700-4924-9213-478f3d71f2d8:ProofOfEmployment`.

### Course Completion Certificates

* Purpose: Issued to students upon the successful completion of a course. The certificate may indicate that the student has mastered a specific skill or knowledge.
* Type: `CourseCompletionCertificate`

```typescript theme={null}
CourseCompletionCertificate {
    course: string;
    grade: string;
}
```

If you want to use this example type in your credential template definition, you can reference it as `crossmint:bfb292e7-2700-4924-9213-478f3d71f2d8:CourseCompletionCertificate`.

### Membership Credentials

* Purpose: Provided to individuals who are members of a specific organization or club. The certificate may grant access to exclusive resources and events.
* Name: `Membership`

```typescript theme={null}
Membership {
  organizationName: string;
  membershipType: string;
  issueDate: string;
  benefits: string[];
  status: string;
}
```

If you want to use this example type in your credential template definition, you can reference it as `crossmint:bfb292e7-2700-4924-9213-478f3d71f2d8:Membership`.

### Event Participation Certificates

* Purpose: Issued to individuals who attend or participate in specific events.
* Name: `EventParticipation`

```typescript theme={null}
EventParticipation {
  eventName: string;
  eventDate: string;
  location: string;
  description: string;
}
```

If you want to use this example type in your credential template definition, you can reference it as `crossmint:bfb292e7-2700-4924-9213-478f3d71f2d8:EventParticipation`.

## Types Creation Quickstart

This example creates a custom type, `CourseCompletionCertificate`, for a credential that represents a course completion. The credential will contain two fields: `course` and `passed`.

<CodeGroup>
  ```javascript createType.js theme={null}
  const typeName = "CourseCompletionCertificate";

  const schema = {
      $schema: "https://json-schema.org/draft/2020-12/schema",
      title: "Course completion",
      description: "Describes the course completed and the assigned grade",
      type: "object",
      properties: {
          credentialSubject: {
              type: "object",
              properties: {
                  course: {
                      type: "string",
                  },
                  grade: {
                      type: "string",
                  },
                  id: {
                      // Optional, will be added automatically
                      type: "string",
                  },
              },
              required: ["course", "grade"],
              additionalProperties: false,
          },
      },
  };

  const options = {
      method: "PUT",
      headers: {
          "X-API-KEY": "YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      body: JSON.stringify(schema),
  };

  fetch(`https://staging.crossmint.com/api/v1-alpha1/credentials/types/${typeName}`, options)
      .then((response) => response.json())
      .then((response) => console.log(JSON.stringify(response)))
      .catch((err) => console.error(err));
  ```
</CodeGroup>

Copy the `createType.js` file in the tab above, add your API key to the `X-API-KEY` header (or [create one](/minting/quickstarts/credentials#2-get-an-api-key) if you haven't already) and run via node.

```shell theme={null}
node createType.js
```

The response, shown below, includes the credential type name.

```json Response theme={null}
{
    "id": "crossmint:bfb292e7-2700-4924-9213-478f3d71f2d8:CourseCompletionCertificate", // Internal type id
    "typeSchema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "title": "Course completion", // Veryfiable credential `type` name.
        "description": "Describes the course completed and the assigned grade",
        "type": "object",
        "properties": {
            "credentialSubject": {
                "type": "object",
                "properties": {
                    "course": {
                        "type": "string"
                    },
                    "grade": {
                        "type": "string"
                    },
                    "id": {
                        "type": "string"
                    }
                },
                "required": ["course", "grade"],
                "additionalProperties": false
            }
        },
        "$id": "https://staging.crossmint.com/api/v1-alpha1/credentials/types/crossmint:bfb292e7-2700-4924-9213-478f3d71f2d8:CourseCompletionCertificate" // External schema URI
    }
}
```

The type id defined will be used when you create your [credential template](/minting/verifiable-credentials/integrate/create-credential-templates).

You can also utilize the `POST /credentials/types/` endpoint to generate a random uuid for the new credential type.

<Warning>
  For internal use within Crossmint, reference the type using `id`. The `$id` will be included as the credentials
  schema by Crossmint but should not be used to reference the type in Crossmint APIs.
</Warning>

Example of a credentials using the type `"crossmint:bfb292e7-2700-4924-9213-478f3d71f2d8:CourseCompletionCertificate"` just created.

```json Example Credential theme={null}
 {
    "id": "urn:uuid:820b09e8-bd6d-4680-b2b1-b564169fde8a",
    "credentialSubject": {
        "course": "Math",
        "grade": "A",
        "id": "did:polygon-amoy:0x1B887669437644aA348c518844660ef8d63bd643"
    },
    "nft": {
        "tokenId": "7",
        "chain": "polygon-amoy",
        "contractAddress": "0xb14Bf8EEa68026a2746350059389Bd119CFB8E29"
    },
    "issuer": {
        "id": "did:polygon-amoy:0xd9d8BA9D5956f78E02F4506940f42ac2dAB9DABd"
    },
    "type": [
        "VerifiableCredential",
        "Course completion" // Schema.title
    ],
    "validFrom": "2024-11-19T18:41:30.503Z",
    "@context": [
        "https://www.w3.org/ns/credentials/v2"
    ],
    "credentialSchema": {
        "id": "https://staging.crossmint.com/api/v1-alpha1/credentials/types/crossmint:bfb292e7-2700-4924-9213-478f3d71f2d8:CourseCompletionCertificate", // Schema.$id
        "type": "JsonSchema"
    },
    "proof": { ... }
}
```

## Types Creation Deep Dive

In the realm of Verifiable Credentials, types are defined using the JSON schema. For more details, refer to the [W3C VC JSON Schema](https://www.w3.org/TR/vc-json-schema/).
When calling the create type API an invalid JSON schema will result in an error.

### Type schema structure

Below is an example of a JSON schema structure for defining a credential type:

```json Example Schema Payload theme={null}
{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "title": "Example nested schema",
    "description": "A schema capturing a human name and a nested `additionalInfo` object",
    "type": "object",
    "properties": {
        "credentialSubject": {
            "type": "object",
            "properties": {
                "firstName": {
                    "type": "string"
                },
                "id": {
                    // This will be added automatically, is not necessary
                    "type": "string"
                },
                "additionalInfo": {
                    "type": "object",
                    "properties": {
                        "age": {
                            "type": "integer"
                        },
                        "isActive": {
                            "type": "boolean"
                        },
                        "tags": {
                            // Optional, therefore is not added to `required`
                            "type": "array",
                            "items": {
                                "type": "string"
                            }
                        }
                    },
                    "required": ["age", "isActive"],
                    "additionalProperties": false // Needs to be repeated for each nested object
                }
            },
            "required": ["firstName", "additionalInfo"],
            "additionalProperties": false
        }
    }
}
```

#### Explanation of Each Part:

* **\$schema**: This should always be set to "[https://json-schema.org/draft/2020-12/schema](https://json-schema.org/draft/2020-12/schema)".
* **\$id**: This field should NOT be defined, will be generated by Crossmint and returned in the response.
* **title**: Represents the name of the type.
* **description**: A brief description of the schema.
* **type**: Must be set to "object".
* **properties**: Must include `credentialSubject` as an object.

#### Important Notes:

* The credential subject is the section that needs to be defined. Any field or nested field can be added, as long as it is valid JSON schema.
* The `credentialSubject.properties.id` will be automatically added with the type "string", this is used to specify the wallet and therefore the identity of the subject.
* `additionalProperties` should always be set to `false` to prevent unauthorized fields from being added.
* All specified fields should be marked as `required` unless they are optional. This ensures that missing fields will trigger an error during schema validation.
* `additionalProperties` and `required` apply only at the level they are specified. For nested objects, these need to be repeated.

### Type import

If you already have a JSON schema type, you can easily import it by calling the same endpoint with the following structure:

```javascript importType.js theme={null}
const payload = {
    $id: "https://raw.githubusercontent.com/decentralized-identity/credential-schemas/main/schemas/ExampleEntity/ExampleNameSchema.json",
};
const options = {
    method: "POST",
    headers: {
        "X-API-KEY": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    body: JSON.stringify(schema),
};

fetch(`https://staging.crossmint.com/api/v1-alpha1/credentials/types`, options)
    .then((response) => response.json())
    .then((response) => console.log(JSON.stringify(response)))
    .catch((err) => console.error(err));
```

```json Response theme={null}
{
    "id": "crossmint:e62564a7-06eb-4f65-b389-eb3b7a4f6f98:10ede8a6",
    "typeSchema": {
        "$id": "https://raw.githubusercontent.com/decentralized-identity/credential-schemas/main/schemas/ExampleEntity/ExampleNameSchema.json",
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "title": "Example Name schema",
        "description": "A schema capturing a human name",
        "type": "object",
        "properties": {
            "credentialSubject": {
                "type": "object",
                "properties": {
                    "firstName": {
                        "type": "string"
                    },
                    "id": {
                        "type": "string"
                    }
                },
                "required": ["firstName"],
                "additionalProperties": false
            }
        }
    }
}
```

#### Important Notes for Import:

* All notes for type creation apply here as well.
* `credentialSubject.properties.id` will not be added for imported schemas. If the original schema does not include this specification, the resulting credentials will not include the user wallet in the `subject.id`. To know the subject of a credential, checking the NFT owner will be necessary.

<Note>
  To follow along and test the API calls use a tool like Postman or our [API
  playground](/api-reference/verifiable-credentials/types/create-named-type).
</Note>

<CardGroup>
  <Card title="API Reference" icon="terminal" href="/api-reference/verifiable-credentials/types/create-named-type">
    Test any API in seconds directly from the docs.
  </Card>

  <Card title="Talk to an expert" icon="message" href="https://www.crossmint.com/contact/sales">
    Contact our sales team for support.
  </Card>
</CardGroup>


# Decrypt Credentials
Source: https://docs.crossmint.com/minting/verifiable-credentials/integrate/decrypt-credentials

Decrypt credentials you care about

As a credential issuer you can use the [retrieval endpoints](/minting/verifiable-credentials/integrate/retrieve-credentials) and Crossmint will autodecrypt the credential for you.

As a verifier, however, working with [encryption modalities](/minting/verifiable-credentials/integrate/encrypt-credentials) to decrypt credentials requires deep understanding of their APIs, managing cryptographic operations securely, and handling user signature interactions.

The Verifiable Credentials SDK encapsulates all this functionality for verifiers, ensuring secure and seamless decryption.

* Upon a verifier's request, the SDK prompts the credential subject to sign a message proving they are the credential subject, and approving the credential's decryption.
* Once the subject approves, Crossmint decrypts the credential for the verifier to verify.

If the credentials are encrypted using the Lit protocol, in order to decrypt them, the SDK provides a `Lit.decrypt(encryptedCredential)` function.

If the credentials are encrypted using Crossmint, the SDK provides a `CrossmintMetamaskDecrypt().decrypt(encryptedCredential)` function that decrypts the credential, assuming the user has a Metamask wallet. For the support of additional wallets during decryption, review our SDK reference.

A Crossmint API key (`credentials.decrypt`) is needed when:

* Crossmint has encrypted the data (`crossmint-recoverable` encryption modality)
* Data is encrypted via Lit but the verifier wants to delegate Lit network billing to Crossmint

<Warning>Decryption will not work server-side when using Lit.</Warning>

In both cases, the user will be prompted to sign a message with their wallet to authenticate the decryption, then the credential will be decrypted.

<CodeGroup>
  ```typescript decrypt.ts theme={null}
  import * as sdk from '@crossmint/client-sdk-verifiable-credentials';

  sdk.CrossmintAPI.init('YOUR_API_KEY');

  const encryptedCredential = <encryptedCredentialObject>;

  if (collection.metadata.credentialMetadata.encryption.type==VerifiableCredentialEncryptionType.DECENTRALIZED_LIT){
    const decryptedData = await new sdk.Lit("staging").decrypt(encryptedCredential);
  }else if (collection.metadata.credentialMetadata.encryption.type==VerifiableCredentialEncryptionType.CROSSMINT_RECOVERABLE){
    const decryptedData = await new sdk.CrossmintMetamaskDecrypt().decrypt(encryptedCredential);
  } else {
    throw new Error("Not supported")
  }

  console.log("Decrypted credential:", decryptedData);

  ```

  ```json Response theme={null}
  {
    "unencryptedCredential": {
      "id": "urn:uuid:4c9c41af-8410-4265-9fe4-3674d74e80d9",
      "credentialSubject": {
        "course": "Blockchain 101",
        "grade": "A",
        "id": "did:polygon-amoy:0xbFB0d0F9d49d80062103199c5aD309CE7a808039"
      },
      "validUntil": "2034-02-02",
      "nft": {
        "tokenId": "1",
        "chain": "polygon-amoy",
        "contractAddress": "0x288AAbb7D72A041Ea10719d2d676B65D2E9689F5"
      },
      "issuer": { "id": "did:polygon-amoy:0xB658f974Fe3744A6F9344810BC88e021E31B4d3e" },
      "type": [
        "VerifiableCredential",
        "crossmint:5fe6040e-07a1-48bb-97a3-b588a7e927d2:courseCompletionQuickstart"
      ],
      "validFrom": "2024-09-14T13:59:34.918Z",
      "@context": [
        "https://www.w3.org/2018/credentials/v1"
      ],
      "proof": {
        "verificationMethod": "did:polygon-amoy:0xB658f974Fe3744A6F9344810BC88e021E31B4d3e#evmAddress",
        "created": "2024-09-14T13:59:34.918Z",
        "proofPurpose": "assertionMethod",
        "type": "EthereumEip712Signature2021",
        "proofValue": "0x80587c5e9a801f4eed5bca95c48083277fc2ffe2fc1254f230f1b8c11cab59f63afaaa29bf29007129068243feb0069c46a8e583a64e64ff2517a2e3babd18101b",
        "eip712": {
          "domain": {
            "name": "Crossmint",
            "version": "0.1",
            "chainId": 4,
            "verifyingContract": "0xD8393a735e8b7B6E199db9A537cf27C61Aa74954"
          },
          "types": {
            "VerifiableCredential": [
              { "name": "@context", "type": "string[]" },
              { "name": "type", "type": "string[]" },
              { "name": "id", "type": "string" },
              { "name": "issuer", "type": "Issuer" },
              { "name": "credentialSubject", "type": "CredentialSubject" },
              { "name": "validFrom", "type": "string" },
              { "name": "validUntil", "type": "string" },
              { "name": "nft", "type": "Nft" }
            ],
            "CredentialSubject": [
              { "name": "id", "type": "string" },
              { "name": "course", "type": "string" },
              { "name": "grade", "type": "string" }
            ],
            "Issuer": [
              { "name": "id", "type": "string" }
            ],
            "Nft": [
              { "name": "tokenId", "type": "string" },
              { "name": "contractAddress", "type": "string" },
              { "name": "chain", "type": "string" }
            ]
          },
          "primaryType": "VerifiableCredential"
        }
      }
    }
  }
  ```
</CodeGroup>

The decrypted credential content can now be reviewed and verified by the verifier.


# Delegated Signature
Source: https://docs.crossmint.com/minting/verifiable-credentials/integrate/delegated-signatures

Sign credentials with your wallet of choice

Credential issuers, by default, sign credentials using their custodial wallet, managed by Crossmint. This means that Crossmint handles the management of the wallet used for signing, providing a default and streamlined solution for issuers.

If an issuer wants to sign credentials using a separate wallet they own, they can do so by providing a signing endpoint. This endpoint is essentially a service or URL that the issuer can set up, which Crossmint will use to access the issuer's chosen wallet for signing credentials.

<Warning>
  Delegated signature and encryption are not concurrently supported for the moment, so it is advised to also use
  [delegated storage](/minting/verifiable-credentials/integrate/store-credentials#delegated-storage) for sensitive
  data.
</Warning>

## Template Creation

Upon template creation, customers can specify parameters that configure the `delegatedSignature` specification:

* `issuerDid`: The desired issuer DID represents the entity that will be issuing the credentials.
* `endpoint`: The signing endpoint is the URL or endpoint where the credential signing process takes place
* `token`: The Auth token for the endpoint is a secure token used to authenticate requests to the signing endpoint. This token ensures that only authorized entities can access the signing endpoint.

```json theme={null}
{
  ...standard_template_params,
  delegatedSignature: {
    issuerDid: "did:polygon:<0xADDRESS>",
    endpoint: "string",
    token: "string"
  }
}
```

The credential issuance process remains unchanged, except for one crucial modification. Instead of directly calling `wallet.signTypedData(payload)` using Crossmint's wallet, Crossmint sends the payload to a designated endpoint. This endpoint is responsible for wrapping the `signTypedData` call and performing the necessary security checks to ensure only authorized payloads are processed, preventing arbitrary or malicious data from being signed.

## Request Payload

Crossmint will POST to the given endpoint with the following payload:

```json theme={null}
{
    "issuer": "did:polygon:<0xADDRESS>",
    "domain": "ethers.TypedDataDomain",
    "types": "Record<string, Array<ethers.TypedDataField>>",
    "message": "<credential_object_to_sign>",
    "token": "<auth_token>"
}
```

## Response Format

The endpoint should return a response with the following format:

```json theme={null}
{
    "credential": "<credential_object_to_sign>",
    "issuer": "<address>",
    "signature": "string"
}
```

## DID

The issuer's identity is represented by a [DID](https://www.w3.org/TR/did-core/). The DID is a string that uniquely identifies the issuer.
The easiest way to provide a DID is to send the issuer's wallet address as DID, setting issuerDid to `"did:{chain}:{address}"`.

### Web DID

Crossmint also supports [Web DID](https://w3c-ccg.github.io/did-method-web/). This allows issuer's to be identified by a domain name, setting issuerDid to `"did:web:issuer.com"`. webDID leverages existing web domain reputation to establish trust around decentralized identities.

The issuer must have a [DID Document](https://www.w3.org/TR/did-core/#did-documents) hosted at `https://issuer.com/.well-known/did.json` for the webDID mapping to work properly.
The DID document, among other useful information, needs to contain the "service" attribute, stating the issuer's wallet address:
The issuer's wallet is the wallet that will be used to sign the credential and verifiers can recognize this wallet by its related webDID.

```json theme={null}
{
    "id": "did:web:myissuer.com",
    "service": [
        {
            "id": "did:web:myissuer.com#wallet",
            "type": "wallet",
            "serviceEndpoint": "chain:<0xADDRESS>"
        }
    ]
    // ... other properties like verificationMethod, authentication, etc.
}
```


# Credential Encryption
Source: https://docs.crossmint.com/minting/verifiable-credentials/integrate/encrypt-credentials

Encrypt private credential data

Verifiable Credentials can be used to store sensitive information. In such cases, it's crucial to use encrypted credentials to ensure data privacy and security.

The encryption process is designed so that *only* the credential subject and the credential issuer can decrypt the credential. This ensures that sensitive information is only accessible to the relevant parties.

Once the credential is decrypted, it can be verified by anyone. This allows for the credential's authenticity to be confirmed while still maintaining the privacy of its content.

The process of encryption and decryption can be automated using the Crossmint API and SDK. This provides a seamless and secure way to handle sensitive information within Verifiable Credentials.

<Note>Encryption will make credential issuance and retrieval slower due to the encryption and decryption process.</Note>

## Create an encrypted credential template

When creating a [template](/minting/verifiable-credentials/integrate/create-credential-templates), you can specify an `encryption` parameter to determine the encryption modality you will use. The possible values for this parameter are:

* `crossmint-recoverable`: This option is ideal when users prioritize the convenience and security of having a fallback recovery mechanism. Crossmint will take care of encrypting the credential. The user will be required to prove ownership of the subject wallet to decrypt the credential. As a fallback mechanism, the key is also shared with the credential issuer.
* `decentralized-lit`: This option is better suited for users who prioritize full decentralization and privacy. The credential is encrypted and decrypted using the [Lit protocol](https://www.litprotocol.com/). The user will be required to prove ownership of the subject wallet to decrypt the credential.
* `none`: The certificate is not encrypted.

For example, the `encryption` field part of the template creation request below is set to `crossmint-recoverable`.

```json theme={null}
{
    "metadata": {
        "name": "Template Name",
        "description": "Encrypted credentials template"
    },
    "chain": "polygon",
    "credentials": {
        "type": "MyCustomType",
        "encryption": "crossmint-recoverable"
    }
}
```

During credential creation, the Crossmint API encrypts the credential and sets an access rule that only the credential subject and the credential issuer can decrypt the credential.

Credentials issued from this template will be encrypted for you. Behind the scenes:

* The Crossmint API encrypts the certificate's private data and sets an access rule that only the credential subject and issuer can decrypt the credential.
* Crossmint triggers a webhook to the issuer after a successful credential creation.
* Issuer receives via webhook the credential content and the encryption key.
* As a fallback a copy of the encryption key is sent to the issuer.

## Encrypted credential object

An encrypted credential consists of a 'credentialId' and a base64 encoded encrypted payload.

```json theme={null}
{
    "credentialId": "urn:uuid:<credential_id>",
    "payload": "base64_encoded_cipher_text"
}
```

## Retrieve an encrypted credential

You can leverage the standard retrieval Crossmint API endpoint to retrieve an encrypted credential:
`GET https://staging.crossmint.com/api/v1-alpha1/credentials/{credentialId}`

<Note>
  Hitting the `GET credentials/{credentialId}` endpoint as the issuer will automatically decrypt the credential for
  you and return both the clear and ciphertext.
</Note>

In case of successful autodecryption, the response object will be:

```json theme={null}
{
    "encryptedCredential": {
        "credentialId": "urn:uuid:<credential_id>",
        "payload": "base64_encoded_cipher_text"
    },
    "unencryptedCredential": "<credential_obj>",
    "decryptionError": undefined
}
```

For information on how to decrypt a credential, see [here](/minting/verifiable-credentials/integrate/decrypt-credentials).


# Issue Credentials
Source: https://docs.crossmint.com/minting/verifiable-credentials/integrate/issue-credentials

Specify the credential's values and a recipient to send it to

With both a credential type and template defined, we can proceed to issue a credential.

## 1. Issue a Credential

First and foremost, the issuer must specify a valid recipient for the credential:

* **recipient** (required): Issuer must specify a credential recipient. This can be done via `email:${userEmail}:${chain}` or `{wallet address}`.

In addition, the issuer must specify a **credential** object containing:

* **subject** (required): Object matching a defined credential type's schema, with values relevant to the recipient. The credential's contents are identified by the "subject" key within the credential, following [W3C naming standards](https://www.w3.org/TR/vc-data-model-2.0/#credential-subject).

<Warning>
  The credential subject (credential.subject) must respect the schema of the chosen Verifiable Credential type. You
  cannot add additional fields, nor exclude any that were previously set.
</Warning>

* **expiresAt** (required): Specify date, in form such as `2034-02-02` (ISO) or `none` to imply infinite expiration.

<Warning>If you don't include an expiration date, you must revoke the credential via burning to invalidate it.</Warning>

Finally, the issuer can provide optional public metadata related to the specific credential, as such:

* **metadata** (optional): NFT metadata is inherited from the VC template metadata. Metadata attributes can be set by the customer to override metadata definition inherited by baseURI.

To issue your first credential, copy the `issueCredential.js` file from below, add your API key, and templateId (that was returned to you in the previous step), and run the file from your terminal.

<CodeGroup>
  ```javascript issueCredential.js theme={null}
  const userEmail = "user@email.com"; // Replace with recipient email
  const templateId = "YOUR_TEMPLATE_ID"; // Replace with ID from previous step

  const credentialParams = {
      recipient: `email:${userEmail}:polygon-amoy`,
      credential: {
          // The CourseCompletionCertificate credential type requires course and grade declarations
          subject: {
              course: "Blockchain 101",
              grade: "A",
          },
          expiresAt: "2034-02-02",
      },
  };

  const options = {
      method: "POST",
      headers: {
          "X-API-KEY": "YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      body: JSON.stringify(credentialParams),
  };

  fetch(`https://staging.crossmint.com/api/v1-alpha1/credentials/templates/${templateId}/vcs`, options)
      .then((response) => response.json())
      .then((response) => console.log(JSON.stringify(response)))
      .catch((err) => console.error(err));
  ```

  ```json Response theme={null}
  {
      "id": "d7eb777b-e9b4-4f34-ab5f-ce199111166a",
      "onChain": {
          "status": "pending",
          "chain": "polygon-amoy",
          "contractAddress": "0xdC444A3F4768185497Dae6250E2F348b99bE89F3"
      },
      "credentialId": "urn:uuid:64f9877d-a19a-4205-8d61-f8c2abed5766",
      "actionId": "d7eb777b-e9b4-4f34-ab5f-ce199111166a"
  }
  ```
</CodeGroup>

```shell theme={null}
node issueCredential.js
```

## 2. Check the status of your credential

You can [set up a webhook](/minting/verifiable-credentials/integrate/webhooks) to know when the Verifiable Credential NFT minting is completed, or call the
[action status API](/api-reference/common/get-action-status) with the returned `actionId`.

To check the template's status you will need the `nfts.create` API scope and run the following code.

```typescript checkTemplateStatus.js theme={null}
const actionId = "<YOUR_ACTION_ID>"; // Returned from previous step
const options = { method: "GET", headers: { "X-API-KEY": "<YOUR_API_KEY>" } };

fetch(`https://staging.crossmint.com/api/2022-06-09/actions/${actionId}`, options)
    .then((response) => response.json())
    .then((response) => console.log(response))
    .catch((err) => console.error(err));
```

<CardGroup>
  <Card title="API Reference" icon="terminal" href="/api-reference/verifiable-credentials/credentials/issue-credential">
    Test any API in seconds directly from the docs.
  </Card>

  <Card title="Talk to an expert" icon="message" href="https://www.crossmint.com/contact/sales">
    Contact our sales team for support.
  </Card>
</CardGroup>


# Retrieve Credentials
Source: https://docs.crossmint.com/minting/verifiable-credentials/integrate/retrieve-credentials

Get access to credentials you care about

Retrieving and effectively presenting credentials is essential for issuers, verifiers, and credential subjects. However, doing so requires interfacing with the blockchain, 3rd party services to fetch NFTs, all while at the same time struggling with unpredictable network issues, and data inconsistency.

Crossmint’s Verifiable Credentials API and SDK simplify credential management, allowing you to seamlessly retrieve and use verifiable credentials where they matter most.

## Verifiable Credential API

Crossmint's Verifiable Credentials API is primarily meant to be used by issuers. It's designed for robust backend operations, enabling seamless, automated credential retrieval without requiring user interaction.

The API integrates with your existing server-side infrastructure, ensuring efficient and scalable credential management. With the API, you can implement complex business logic, providing unparalleled control and customization.

​​You can retrieve a Verifiable Credential via the Crossmint API using different identifiers associated with the credential itself, or the NFT associated with the credential.

* [Get Verifiable Credential by ID](/api-reference/verifiable-credentials/credentials/retrieve-credential-by-id) uses the format: `urn:uuid:<UUID>`
* [Get Verifiable Credential by NFT Locator](/api-reference/verifiable-credentials/credentials/retrieve-credential-by-nft-locator) uses the format: `<chain>:<contractAddress>:<tokenId>`
* [Get Verifiable Credential by NFT ID](/api-reference/verifiable-credentials/credentials/retrieve-credential-by-nft) uses crossmint's internal NFT ID

<Warning>
  There is no access control on credential retrieval. Credential data is public and can be retrieved by anyone. Choose
  to [encrypt your credentials](/minting/verifiable-credentials/integrate/encrypt-credentials) if you need to protect
  your data.
</Warning>

<Warning>
  Credential retrieval via the crossmint API will not work for [delegated
  storage](/minting/verifiable-credentials/integrate/store-credentials).
</Warning>

To retrieve the credential, copy the `retrieveCredential.js` file from below, use your API key, the `credentialId`, and run the file from your terminal.

<CodeGroup>
  ```javascript retrieveCredential.js theme={null}
  const options = {
      method: "GET",
      headers: {
          "X-API-KEY": "YOUR_API_KEY",
      },
  };

  fetch(`https://staging.crossmint.com/api/v1-alpha1/credentials/${credentialId}`, options)
      .then((response) => response.json())
      .then((response) => console.log(JSON.stringify(response)))
      .catch((err) => console.error(err));
  ```

  ```json Response theme={null}
  {
      "unencryptedCredential": {
          "id": "urn:uuid:4c9c41af-8410-4265-9fe4-3674d74e80d9",
          "credentialSubject": {
              "course": "Blockchain 101",
              "grade": "A",
              "id": "did:polygon-amoy:0xbFB0d0F9d49d80062103199c5aD309CE7a808039"
          },
          "validUntil": "2034-02-02",
          "nft": {
              "tokenId": "1",
              "chain": "polygon-amoy",
              "contractAddress": "0x288AAbb7D72A041Ea10719d2d676B65D2E9689F5"
          },
          "issuer": { "id": "did:polygon-amoy:0xB658f974Fe3744A6F9344810BC88e021E31B4d3e" },
          "type": ["VerifiableCredential", "crossmint:5fe6040e-07a1-48bb-97a3-b588a7e927d2:courseCompletionQuickstart"],
          "validFrom": "2024-09-14T13:59:34.918Z",
          "@context": ["https://www.w3.org/2018/credentials/v1"],
          "proof": {
              "verificationMethod": "did:polygon-amoy:0xB658f974Fe3744A6F9344810BC88e021E31B4d3e#evmAddress",
              "created": "2024-09-14T13:59:34.918Z",
              "proofPurpose": "assertionMethod",
              "type": "EthereumEip712Signature2021",
              "proofValue": "0x80587c5e9a801f4eed5bca95c48083277fc2ffe2fc1254f230f1b8c11cab59f63afaaa29bf29007129068243feb0069c46a8e583a64e64ff2517a2e3babd18101b",
              "eip712": {
                  "domain": {
                      "name": "Crossmint",
                      "version": "0.1",
                      "chainId": 4,
                      "verifyingContract": "0xD8393a735e8b7B6E199db9A537cf27C61Aa74954"
                  },
                  "types": {
                      "VerifiableCredential": [
                          { "name": "@context", "type": "string[]" },
                          { "name": "type", "type": "string[]" },
                          { "name": "id", "type": "string" },
                          { "name": "issuer", "type": "Issuer" },
                          { "name": "credentialSubject", "type": "CredentialSubject" },
                          { "name": "validFrom", "type": "string" },
                          { "name": "validUntil", "type": "string" },
                          { "name": "nft", "type": "Nft" }
                      ],
                      "CredentialSubject": [
                          { "name": "id", "type": "string" },
                          { "name": "course", "type": "string" },
                          { "name": "grade", "type": "string" }
                      ],
                      "Issuer": [{ "name": "id", "type": "string" }],
                      "Nft": [
                          { "name": "tokenId", "type": "string" },
                          { "name": "contractAddress", "type": "string" },
                          { "name": "chain", "type": "string" }
                      ]
                  },
                  "primaryType": "VerifiableCredential"
              }
          }
      }
  }
  ```
</CodeGroup>

```shell theme={null}
node retrieveCredential.js
```

## Verifiable Credentials SDK

Crossmint's Verifiable Credentials SDK is primarily meant to be used by verifiers. Using the Verifiable Credentials client-side SDK is advantageous in scenarios where direct interaction with the user's wallet is preferred, directly integrating their credentials with your browser-based application.

* **Wallet Integration**: The Verifiable Credentials SDK is designed to work smoothly with any wallet, providing a streamlined experience for both users and verifiers. This reduces friction and improves the user experience.
* **Efficient Retrieval**: Once the wallet is connected, the SDK can directly interact with it to retrieve credentials. Instead of dealing with multiple API calls, the SDK surfaces credential retrieval capabilities that matter most to verifiers, such as fetching credentials based on specific filter conditions, i.e. type and issuer.
* **User Approvals**: The SDK takes care of prompting the user, when applicable, to approve transactions, such as decryption requests, enhancing security and the user's confidence in the application.

Using the SDK requires a Crossmint developer account and a client-side API key scoped to `credentials.read` and `credentials.decrypt`. Go to the `Developers -> API Keys` tab, click on `New API Key` in the `Client-side keys` section, and select the API key scopes.

<Note>
  You can download the SDK [here](https://www.npmjs.com/package/@crossmint/client-sdk-verifiable-credentials).
</Note>

The SDKs offer functions to easily retrieve and filter NFTs associated with credentials. For example, the `getCredentialNFTs` function fetches all VC NFTs in a wallet and lets you filter by credential type or issuer.

Below, we show how easy it is to retrieve academic credentials from a user's wallet.

<CodeGroup>
  ```typescript index.ts theme={null}
  import * as sdk from '@crossmint/client-sdk-verifiable-credentials';

  sdk.CrossmintAPI.init('YOUR_API_KEY');

  const wallet = "USER_WALLET";
  const filters = {
      // typeId represents an academic credential schema
      type: <typeId>
  };

  const credentials = await sdk.getCredentialNFTs(
      "polygon",
      wallet,
      filters
  );

  console.log('Academic credentials retrieved successfully:', credentials);

  ```

  ```json Response theme={null}
  [
   {
          "contractAddress": "0x5E1ab2aC27f1a0AD28f1b0DDb0E00baF2677725e",
          "chain": "polygon-amoy",
          "nfts": [
              {
                  "chain": "polygon-amoy",
                  "contractAddress": "0x5E1ab2aC27f1a0AD28f1b0DDb0E00baF2677725e",
                  "tokenId": "1"
              }
          ],
          "metadata": {
              "name": "Crossmint Tickets",
              "description": "Access Crossmint Events",
              "image": "ipfs://Qme551yKU6a5Cptsk8hxcMtWwTrKkHArZtTTwFSvu19eFD",
              "credentialMetadata": {
                  "type": [
                      "VerifiableCredential",
                      "userName"
                  ],
                  "encryption": {
                      "type": "crossmint-recoverable"
                  },
                  "credentialsEndpoint": "ipfs://bafybeidmfu6xmdpxddads6nsyxfg6hd5ylj2drrywhzvfi2bbq45owklsa",
                  "issuerDid": "did:polygon:0xd9d8BA9D5956f78E02F4506940f42ac2dAB9DABd"
              }
          }
      },
      {
          "contractAddress": "0x38989746BF435d5f6Dc7C8DdE6038b5a17E62cE2",
          "chain": "polygon-amoy",
          "nfts": [
              {
                  "chain": "polygon-amoy",
                  "contractAddress": "0x38989746BF435d5f6Dc7C8DdE6038b5a17E62cE2",
                  "tokenId": "1"
              }
          ],
          "metadata": {
              "name": "Crossmint Tickets",
              "description": "Access Crossmint Events",
              "image": "ipfs://Qme551yKU6a5Cptsk8hxcMtWwTrKkHArZtTTwFSvu19eFD",
              "credentialMetadata": {
                  "type": [
                      "VerifiableCredential",
                      "userName"
                  ],
                  "encryption": {
                      "type": "crossmint-recoverable"
                  },
                  "credentialsEndpoint": "a",
                  "issuerDid": "did:polygon:0xd9d8BA9D5956f78E02F4506940f42ac2dAB9DABd"
              }
          }
      }
  ]
  ```
</CodeGroup>

Now that the credential is retrieved, it's important to decrypt it and verify it.

<Note>In case the endpoint is called by the issuer the credential will be automatically decrypted.</Note>

<CardGroup>
  <Card title="API Reference" icon="terminal" href="/api-reference/verifiable-credentials/credentials/retrieve-credential-by-id">
    Test any API in seconds directly from the docs.
  </Card>

  <Card title="Talk to an expert" icon="message" href="https://www.crossmint.com/contact/sales">
    Contact our sales team for support.
  </Card>
</CardGroup>


# Revoke Credentials
Source: https://docs.crossmint.com/minting/verifiable-credentials/integrate/revoke-credentials

Invalidate a credential, rendering it no longer trustworthy or verifiable

To revoke a credential, you can directly use the [revoke credential API](/api-reference/verifiable-credentials/credentials/revoke-credential). Burning the NFT associated with the credential via the [burn-nft](/api-reference/minting/nfts/burn-nft) API accomplishes the same result.

Issuers can revoke a Verifiable Credential without the subject's intermediation.

To revoke the credential, copy the `revokeCredential.js` file from below, use your API key, the credentialId, and run the file from your terminal.

```javascript revokeCredential.js theme={null}
const options = {
    method: "DELETE",
    headers: {
        "X-API-KEY": "YOUR_API_KEY",
    },
};

fetch(`https://staging.crossmint.com/api/v1-alpha1/credentials/${credentialId}`, options)
    .then((response) => response.json())
    .then((response) => console.log(JSON.stringify(response)))
    .catch((err) => console.error(err));
```

```shell theme={null}
node revokeCredential.js
```

<CardGroup>
  <Card title="API Reference" icon="terminal" href="/api-reference/verifiable-credentials/credentials/revoke-credential">
    Test any API in seconds directly from the docs.
  </Card>

  <Card title="Talk to an expert" icon="message" href="https://www.crossmint.com/contact/sales">
    Contact our sales team for support.
  </Card>
</CardGroup>


# Credential Storage
Source: https://docs.crossmint.com/minting/verifiable-credentials/integrate/store-credentials

Choose how to store credential data

When creating a [template](/minting/verifiable-credentials/integrate/create-credential-templates), you can specify a `storage` parameter to determine where the credential payload will be stored. The possible values for this parameter are:

* `crossmint`
* `crossmint-private`
* `delegated`
* `decentralized-ipfs`

## Crossmint

With this option, credentials are stored on the Crossmint database. This is the most flexible solution and is compatible with all other features.

<Warning>
  There is not access control on credential retrieval, credential data is public and can be retrieved by anyone, use
  [encrypted credentials](/minting/verifiable-credentials/integrate/encrypt-credentials) if you need to protect the
  data.
</Warning>

## Crossmint Private

This option is designed for integrated systems in which the issuer is also the verifier. Credentials are stored by Crossmint, but only the issuer can retrieve the credential payload. Because the credential issuer is also the credential verifier, there is no need to encrypt the credentials.

## Decentralized Storage

This option is the most open and transparent solution as it will store the credential to a decentralized storage (IPFS). All retrieval API endpoints will still be available and will proxy the request to ipfs.

[Encrypting the payload](/minting/verifiable-credentials/integrate/encrypt-credentials) is suggested to avoid private credential data being exposed to be public.

<Note> Credential issuance will be slower than other storage options.</Note>

## Delegated Storage

This option is designed for the enterprise, giving the issuer full control over the credentials. With delegated storage, no reference to the data is stored on Crossmint databases. The credential is returned to the issuer via the [webhook](/minting/verifiable-credentials/integrate/webhooks) and the issuer is responsible for storing it.

All Crossmint retrieval endpoints will consequently be disabled. A `delegatedStorageEndpoint` parameter must be added when creating the credential template that specifies the endpoint where the credential can be retrieved (can be set to a dummy value like "unknown" if not desired).

This endpoint will be saved in the contract metadata and can be used by users to retrieve the credential associated with their NFT. Issuers can protect content privacy by encrypting the payload.

<Note>
  For delegated storage, if the credential is not catched by the webhook, it will be lost. Read more about webhooks
  [here](/minting/verifiable-credentials/integrate/webhooks).
</Note>


# Verify Credentials
Source: https://docs.crossmint.com/minting/verifiable-credentials/integrate/verify-credentials

Ensure that the credential is valid

Verification is a crucial step in the process of handling Verifiable Credentials. To ensure a credential is valid, the following checks are performed:

* Credential Structure: The credential should not be malformed. It must adhere to the correct structure as defined by the [credential type](/minting/verifiable-credentials/integrate/create-credential-types) .

* Signature Validation: The credential’s signature must be valid and match the identity of the issuer. This ensures that the credential was indeed issued by the claimed issuer and hasn’t been tampered with.

* Attribute Check: No additional attributes should have been added to the credential beyond what’s defined in its schema. This prevents unauthorized modifications to the credential.

* Expiration Check: The credential should not have expired. Credentials often have a validity period after which they are no longer considered valid.

* Revocation Check: The credential should not have been revoked by the issuer. Even if a credential is valid and hasn’t expired, it may have been revoked by the issuer for various reasons.

By performing these checks, we can ensure the authenticity and validity of a Verifiable Credential. Verifying a credential can happen either via the Crossmint API or SDK.

## API

To verify a credential on the server-side use the Crossmint API and the following endpoint, passing the [retrieved](/minting/verifiable-credentials/integrate/retrieve-credentials) unencrypted credential JSON.

<CodeGroup>
  ```javascript verifyCredential.js theme={null}
  const options = {
      method: "POST",
      headers: {
          "X-API-KEY": "YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      body: `{"credential": ${JSON.stringify(credential.unencryptedCredential)}}`,
  };

  fetch("https://staging.crossmint.com/api/v1-alpha1/credentials/verification/verify", options)
      .then((response) => response.json())
      .then((response) => console.log(JSON.stringify(response)))
      .catch((err) => console.error(err));
  ```

  ```json Response theme={null}
  {
      "isValid": true
  }
  ```
</CodeGroup>

<Note> Verifying a credential via the API will require a Crossmint developer account.</Note>

## SDK

With the Verifiable Credentials client-side SDK, the verification process is performed locally, eliminating the need for interaction with Crossmint. Consequently, there is no need for a Crossmint developer account to verify the credential.

Install the `@crossmint/client-sdk-verifiable-credentials` [npm package](https://www.npmjs.com/package/@crossmint/client-sdk-verifiable-credentials) and call the `verifyCredential` function passing a `VerifiableCredential` object, as shown below.

<CodeGroup>
  ```typescript decrypt.ts theme={null}
  import * as sdk from '@crossmint/client-sdk-verifiable-credentials';

  sdk.CrossmintAPI.init('YOUR_API_KEY');

  const decryptedCredential = <CredentialObject>;

  const verificationResult = await sdk.verifyCredential(decryptedCredential);

  console.log('Verification result:', verificationResult);

  ```

  ```json Response theme={null}
  {
      "isValid": true
  }
  ```
</CodeGroup>

<Note>
  Verifying the status of the NFT related to the credential requires connection to the internet in order to access
  blockchain state.
</Note>

For details on the SDK functionality, review our [SDK reference documentation](/sdk-reference/credentials/introduction).

## Independent Verification

Since Crossmint’s Verifiable Credentials are based on the [W3C standard](https://www.w3.org/TR/vc-data-model-2.0/), you can use any library that supports this standard to verify a credential.

The W3C Verifiable Credentials standard ensures interoperability across different platforms and systems, enhancing the reliability and security of the credential verification process.

<Note>
  Crossmint verification is stricter and performs additional checks that are not part of the W3C standard. For example, that no additional fields have been added to the credential.
</Note>

<CardGroup>
  <Card title="API Reference" icon="terminal" href="/api-reference/verifiable-credentials/credentials/verify-credential">
    Test any API in seconds directly from the docs.
  </Card>

  <Card title="Talk to an expert" icon="message" href="https://www.crossmint.com/contact/sales">
    Contact our sales team for support.
  </Card>
</CardGroup>


# Webhook
Source: https://docs.crossmint.com/minting/verifiable-credentials/integrate/webhooks

Receive updates about your credentials

Webhooks are a critical component in the management and distribution of verifiable credentials, providing real-time notifications and seamless integration for issuers. Here’s why webhooks enhance the credential issuance process:

* **Automatic Credential Retrieval**: Upon issuance, the credential is sent directly to the issuer through the webhook payload. This eliminates the need for issuers to manually call `getCredential()`. This functionality is especially crucial when the issuer opts for delegated storage; without catching the webhook, the credential could be lost, as there would be no subsequent retrieval.
* **Notification of Credential Issuance Failure**: Webhooks provide immediate alerts if the credential issuance process fails. This enables issuers to quickly identify and address issues, ensuring a reliable and efficient credential issuance process.
* **Secure Storage of Encryption Keys**: In scenarios involving encryption via the "crossmint-recoverable" encryption type, the webhook stores the encryption key for the recipient subject. This ensures that, in case of any fallback, the key is readily available, maintaining the security and accessibility of the encrypted credentials.
* **Immediate Access to Credential Pass Links**: Issuers can instantly receive a link to the wallet credential pass via the webhook. This link can then be forwarded to the subject, ensuring a swift and efficient delivery of credentials.

If you choose not to use a webhook, you can query for the credential's status via the [status API](https://docs.crossmint.com/api-reference/minting/nfts/mint-status).

## Setting Up a Webhook

First, you need to [setup a webhook](https://docs.crossmint.com/docs/mintapi-webhooks) in the developer console. Once that is done either programmatically or via the Dev Console, the webhook payload received, looks as follows:

```json theme={null}
data:{
    credential: credentialObject or encryptedCredentialObjcet
    pass: wallet pass object
    secret: encryption key
}
```

The events you can monitor are:

* `credential.creation.succeeded`
  Will be emitted when the credential creation process is complete.
  The issued credential, credential pass, and encryption key will be contained in the `data.credential` field, `data.pass` field, and `data.secret` field, respectively.
  In case of encrypted credential templates, the issued credential returned will be encrypted.

* `credential.creation.failed`
  Will be emitted when the credential creation process fails. The error will be contained in the `data.error` field.


# Create Order
Source: https://docs.crossmint.com/offramp/api-reference/create-order

api-reference/_open-api/OfframpAPIs.json POST /2022-06-09/orders
Creates an offramp order to cash out stablecoins to fiat. The order returns on-chain deposit instructions that the payer wallet broadcasts to fund the fiat payout.



# Get Order
Source: https://docs.crossmint.com/offramp/api-reference/get-order

api-reference/_open-api/OfframpAPIs.json GET /2022-06-09/orders/{orderId}
Retrieves an offramp order by its ID to track its progress from the on-chain deposit through to the fiat payout.



# List Orders
Source: https://docs.crossmint.com/offramp/api-reference/list-orders

api-reference/_open-api/OfframpAPIs.json GET /2022-06-09/orders
Retrieve a paginated list of offramp orders for your project to track and reconcile payouts.



# Create Payment Method
Source: https://docs.crossmint.com/offramp/api-reference/payment-methods/create-payment-method

api-reference/_open-api/OfframpAPIs.json POST /unstable/payment-methods
Save a bank account payout method so offramp orders can settle fiat to it.

Saves a bank account payout method for a user so offramp orders can settle to it.

<Info>
  Account numbers and IBANs are tokenized by the PCI-compliant vault, so create requests must be submitted through `vault.crossmint.com`.
</Info>

## Returns

Returns a [PaymentMethod](/offramp/api-reference/payment-methods/payment-method-object) object.


# Delete a Payment Method
Source: https://docs.crossmint.com/offramp/api-reference/payment-methods/delete-payment-method

api-reference/_open-api/OfframpAPIs.json DELETE /unstable/payment-methods/{paymentMethodId}
Soft-delete a payout method. The record is retained for compliance but can no longer be used.

Deletes a payout method. The record is retained internally but can no longer be used for payouts.

## Returns

Returns the [PaymentMethod](/offramp/api-reference/payment-methods/payment-method-object) object.


# Retrieve a Payment Method
Source: https://docs.crossmint.com/offramp/api-reference/payment-methods/get-payment-method

api-reference/_open-api/OfframpAPIs.json GET /unstable/payment-methods/{paymentMethodId}
Fetch a single bank account payout method by its ID.

Retrieves a bank account payout method by its ID.

## Returns

Returns a [PaymentMethod](/offramp/api-reference/payment-methods/payment-method-object) object.


# List Payment Methods by User
Source: https://docs.crossmint.com/offramp/api-reference/payment-methods/list-payment-methods

api-reference/_open-api/OfframpAPIs.json GET /unstable/payment-methods
Retrieve the bank account payout methods saved for a given user.

Returns a paginated list of the bank account payout methods saved for a given user.

## Returns

An object with a `data` array of [PaymentMethod](/offramp/api-reference/payment-methods/payment-method-object) objects. Use the `cursor` parameter to paginate; when `nextCursor` is present, more pages are available.


# The Payment Method Object
Source: https://docs.crossmint.com/offramp/api-reference/payment-methods/payment-method-object

Attributes and structure of a saved bank account payout method

PaymentMethod objects represent the bank account payout methods that offramp orders settle fiat to. Save one with the [Create Payment Method](/offramp/api-reference/payment-methods/create-payment-method) endpoint, then reference its `paymentMethodId` as the recipient when creating an offramp order.

## Type Values

`type` names the **account identifier** (the capture schema Crossmint collects and validates) — never the payment rail, scheme, or clearing house. The same saved account can be paid over multiple rails; rail selection happens at payout execution time.

| Value | Description |
| - | - |
| `bank-account-us` | US bank account (routing number + account number). |
| `bank-account-sepa-iban` | Bank account identified by an IBAN within the supported SEPA scope. |
| `bank-account-co` | Colombian bank account (institution ID + account number + national document). |
| `bre-b` | Colombian Bre-B key: an `@handle`, a mobile number, an e-mail, an identity document, or a commerce code. |
| `bank-account-id` | Indonesian bank account (institution ID + account number), paid out over BI-FAST. |
| `bank-account-mx-clabe` | Mexican bank account, identified by an 18-digit CLABE (Clave Bancaria Estandarizada). |
| `bank-account-ng` | Nigerian bank account (institution ID + 10-digit NUBAN, the Nigeria Uniform Bank Account Number), paid out over NIP. |
| `bank-account-ph` | Philippine bank account (institution ID + account number), paid out over InstaPay or PESONet. |
| `bank-account-th` | Thai bank account (institution ID + account number), paid out over PromptPay. |
| `bank-account-vn` | Vietnamese bank account (institution ID + account number), paid out over Napas 247 or CITAD. |

## Attributes

<ResponseField name="paymentMethodId" type="string">
  Unique identifier for the payout method.
</ResponseField>

<ResponseField name="default" type="boolean">
  Whether this is the user's default payout method. Returned for `bank-account-sepa-iban` only.
</ResponseField>

<ResponseField name="displayName" type="string">
  Server-derived label, returned for `bank-account-sepa-iban` only (e.g. `"SEPA Account ••6789"`). Absent on every other payout method; read `label` there.
</ResponseField>

<ResponseField name="type" type="string">
  Payout method type. One of `bank-account-us`, `bank-account-sepa-iban`, `bank-account-co`, `bre-b`, `bank-account-id`, `bank-account-mx-clabe`, `bank-account-ng`, `bank-account-ph`, `bank-account-th`, or `bank-account-vn`.
</ResponseField>

<ResponseField name="status" type="string">
  Bank accounts and Bre-B keys only. Readiness of the destination, not user approval, ownership, or a guaranteed payout. One of:

  * `pending`: initial readiness checks are running.
  * `active`: required readiness checks passed. Orders still run their own eligibility checks.
  * `rejected`: the destination cannot receive a supported payout. The initial checks ended without a usable record, a provider refused the account, or the bank returned a payout to it. Retrying requires a new payment method.
  * `deleted`: removed by the client. Never reactivates.

  `pending` moves to `active`, `rejected`, or `deleted`; `active` moves to `rejected` or `deleted`; `rejected` moves only to `deleted`. Creation starts the readiness checks once; reads, label edits, and orders never restart them. Treat an unrecognized status as not ready for orders. See [Manage Payment Methods](/offramp/guides/collect-bank-accounts#statuses).
</ResponseField>

<ResponseField name="statusReason" type="string | null">
  Always `null` except on a `rejected` method, where it may be `destination-not-found`, `destination-closed`, `destination-cannot-receive`, or `no-rail-available`. `null` when no safe destination condition was established. Never carries provider errors or compliance detail. Codes are extensible, so tolerate unknown values.
</ResponseField>

<ResponseField name="bankAccount" type="object">
  Bank account details. Absent when `type` is `bre-b`, which returns `breB` instead.

  <Expandable title="common properties">
    <ResponseField name="accountHolder" type="object">
      The person or company that owns the account. Always the value the client sent, never the bank's record of the holder. Derived from `billing` when the record predates this field.

      <Expandable title="properties">
        <ResponseField name="name" type="string">
          Full legal name.
        </ResponseField>

        <ResponseField name="email" type="string">
          E-mail address.
        </ResponseField>

        <ResponseField name="phoneNumber" type="string">
          Phone number (E.164 format).
        </ResponseField>

        <ResponseField name="address" type="object">
          Holder address, without a country: the account's own `country` is the bank's jurisdiction. Present only on types that collect one. Never on `bank-account-mx-clabe`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="bankName" type="string | null">
      Name of the bank. `null` if not resolvable. Absent for `bank-account-co`, `bank-account-id`, `bank-account-mx-clabe`, `bank-account-ng`, `bank-account-ph`, `bank-account-th`, and `bank-account-vn`.
    </ResponseField>

    <ResponseField name="accountSuffix" type="string">
      Last four digits of the account number, CLABE, or IBAN.
    </ResponseField>

    <ResponseField name="currency" type="string">
      ISO 4217 currency code (e.g. `usd`, `mxn`, `eur`, `cop`).
    </ResponseField>

    <ResponseField name="country" type="string">
      ISO 3166-1 alpha-2 country code.
    </ResponseField>

    <ResponseField name="entityType" type="string">
      Account holder type. `individual` or `business`. Required on creation. May be absent on records created before the field was enforced.
    </ResponseField>
  </Expandable>

  <Expandable title="US-specific properties (bank-account-us)">
    <ResponseField name="bankAddress" type="object">
      Bank branch address.
    </ResponseField>

    <ResponseField name="routingNumber" type="string">
      Nine-digit ABA routing number.
    </ResponseField>

    <ResponseField name="accountType" type="string">
      `checking` or `savings`.
    </ResponseField>
  </Expandable>

  <Expandable title="SEPA-specific properties (bank-account-sepa-iban)">
    <ResponseField name="bic" type="string">
      BIC/SWIFT code (8 or 11 characters).
    </ResponseField>
  </Expandable>

  <Expandable title="CO-specific properties (bank-account-co)">
    <ResponseField name="institutionId" type="string">
      Identifier of the bank that holds the account, for example `co-bancolombia`. See [Bank Institution IDs](/offramp/guides/bank-institution-ids).
    </ResponseField>

    <ResponseField name="accountType" type="string">
      `checking`, `savings`, or `electronic-deposit`.
    </ResponseField>

    <ResponseField name="accountHolder.document" type="object">
      The holder's national document. The full number is never returned.

      <Expandable title="properties">
        <ResponseField name="type" type="string">
          One of `cc`, `nit`, `ce`, `pa`, `ppt`, `ti`, `rc`, `te`, or `die`.
        </ResponseField>

        <ResponseField name="suffix" type="string">
          Last four digits of the document number.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>

  <Expandable title="Local bank properties (bank-account-id, bank-account-ng, bank-account-ph, bank-account-th, bank-account-vn)">
    <ResponseField name="institutionId" type="string">
      Identifier of the bank that holds the account, for example `id-bca`. See [Bank Institution IDs](/offramp/guides/bank-institution-ids).
    </ResponseField>

    <ResponseField name="accountType" type="string">
      `checking` or `savings`. Present when sent on creation.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="breB" type="object">
  Bre-B key details. Present when `type` is `bre-b`, in place of `bankAccount`. The key itself is never returned.

  <Expandable title="properties">
    <ResponseField name="accountHolder" type="object">
      The person or company that owns the key. Always the value the client sent.

      <Expandable title="properties">
        <ResponseField name="name" type="string">
          Full legal name.
        </ResponseField>

        <ResponseField name="email" type="string">
          E-mail address.
        </ResponseField>

        <ResponseField name="phoneNumber" type="string">
          Phone number (E.164 format).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="accountSuffix" type="string">
      Masked form of the key. An e-mail key is masked in place. Every other key shows its last four characters.
    </ResponseField>

    <ResponseField name="currency" type="string">
      Always `cop`. Bre-B only settles in Colombian pesos.
    </ResponseField>

    <ResponseField name="country" type="string">
      Always `CO`.
    </ResponseField>

    <ResponseField name="entityType" type="string">
      Key holder type. `individual` or `business`.
    </ResponseField>

    <ResponseField name="keyType" type="string">
      Category of the key, derived from its format. One of `alphanumeric`, `phone`, `email`, `identification`, or `commerce`. A client-supplied value is refused.
    </ResponseField>

    <ResponseField name="institutionName" type="string">
      Display name of the institution that holds the key. Absent until a name source answers.
    </ResponseField>

    <ResponseField name="rails" type="object">
      Read-only. The payout rails a currently-available provider advertises for this key. Absent when no provider serves the key.

      <Expandable title="properties">
        <ResponseField name="supported" type="string[]">
          Rail values this key supports. Bre-B carries `supported` alone, without the `status` and `pending` fields an ordinary bank account returns.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="label" type="string">
  The client's own name for this payout method, when one was sent on creation. At most 255 characters.
</ResponseField>

<ResponseField name="lastPayoutAt" type="string">
  Read-only. ISO 8601 timestamp of the most recent successful offramp payout funded by this account. Absent until the first payout.
</ResponseField>

<ResponseExample>
  ```json US Bank Account theme={null}
  {
    "paymentMethodId": "f2ecef7e-91af-4fa7-93f9-12db856c227f",
    "type": "bank-account-us",
    "bankAccount": {
      "bankName": "Chase",
      "accountSuffix": "7899",
      "currency": "usd",
      "country": "US",
      "entityType": "individual",
      "bankAddress": {
        "line1": "123 Main St",
        "city": "New York",
        "stateOrRegion": "NY",
        "postalCode": "10001",
        "country": "US"
      },
      "routingNumber": "071000013",
      "accountType": "checking"
    }
  }
  ```

  ```json SEPA theme={null}
  {
    "paymentMethodId": "3323460b-d9d2-4ec6-b380-8a3e01e3f226",
    "default": false,
    "displayName": "SEPA Account ••6789",
    "type": "bank-account-sepa-iban",
    "bankAccount": {
      "bankName": null,
      "accountSuffix": "6789",
      "currency": "eur",
      "country": "DE",
      "entityType": "individual",
      "bic": "COBADEFFXXX"
    }
  }
  ```

  ```json CO Bank Account theme={null}
  {
    "paymentMethodId": "1cad2281-bd3d-4219-8787-7dfea94c60b1",
    "type": "bank-account-co",
    "bankAccount": {
      "accountSuffix": "7320",
      "institutionId": "co-bancolombia",
      "accountType": "checking",
      "currency": "cop",
      "country": "CO",
      "entityType": "individual",
      "accountHolder": { "name": "Camila Restrepo", "document": { "type": "cc", "suffix": "4050" } },
      "rails": { "status": "pending", "supported": [], "pending": ["ach-credit"] }
    }
  }
  ```

  ```json CO Bre-B key theme={null}
  {
    "paymentMethodId": "9f1a6b2c-3d4e-4f50-9a61-2b3c4d5e6f70",
    "type": "bre-b",
    "status": "active",
    "statusReason": null,
    "breB": {
      "accountHolder": {
        "name": "Carlos Gómez",
        "phoneNumber": "+573001234567"
      },
      "accountSuffix": "CDKS",
      "currency": "cop",
      "country": "CO",
      "entityType": "individual",
      "keyType": "alphanumeric"
    }
  }
  ```

  ```json ID Bank Account theme={null}
  {
    "paymentMethodId": "7a3e5c91-2b4d-4f86-a1c0-9d8e7f6a5b42",
    "type": "bank-account-id",
    "bankAccount": {
      "accountSuffix": "7890",
      "institutionId": "id-bca",
      "currency": "idr",
      "country": "ID",
      "entityType": "individual",
      "accountHolder": { "name": "Budi Santoso" },
      "rails": { "status": "complete", "supported": ["bi-fast"], "pending": [] }
    }
  }
  ```

  ```json MX Bank Account theme={null}
  {
    "paymentMethodId": "27bacbe1-d0ff-4bc3-b37a-ca91cc64fa39",
    "type": "bank-account-mx-clabe",
    "bankAccount": {
      "accountHolder": {
        "name": "Luis Gomez Rios",
        "phoneNumber": "+525512345678"
      },
      "accountSuffix": "7899",
      "currency": "mxn",
      "country": "MX",
      "entityType": "individual"
    }
  }
  ```

  ```json NG Bank Account theme={null}
  {
    "paymentMethodId": "2e9b4d17-6a3c-4f85-b1d0-8c7e5a2f9b63",
    "type": "bank-account-ng",
    "bankAccount": {
      "accountSuffix": "7897",
      "institutionId": "ng-gt-bank",
      "currency": "ngn",
      "country": "NG",
      "entityType": "individual",
      "accountHolder": { "name": "Chinedu Okafor" },
      "rails": { "status": "complete", "supported": ["nip"], "pending": [] }
    }
  }
  ```

  ```json PH Bank Account theme={null}
  {
    "paymentMethodId": "5e2b7c41-9d0a-4f3b-8c6d-2a1b3c4d5e6f",
    "type": "bank-account-ph",
    "bankAccount": {
      "accountSuffix": "7890",
      "institutionId": "ph-bdo",
      "currency": "php",
      "country": "PH",
      "entityType": "individual",
      "accountHolder": { "name": "Maria Santos" },
      "rails": { "status": "complete", "supported": ["instapay", "pesonet"], "pending": [] }
    }
  }
  ```

  ```json TH Bank Account theme={null}
  {
    "paymentMethodId": "8a4c7e39-2f1b-4d96-b3e5-7c0d2a9f6b41",
    "type": "bank-account-th",
    "bankAccount": {
      "accountSuffix": "7890",
      "institutionId": "th-kasikorn-bank",
      "currency": "thb",
      "country": "TH",
      "entityType": "individual",
      "accountHolder": { "name": "Somchai Jaidee" },
      "rails": { "status": "complete", "supported": ["promptpay"], "pending": [] }
    }
  }
  ```

  ```json VN Bank Account theme={null}
  {
    "paymentMethodId": "3f7d1b86-9e2a-4c50-8d34-1a6e9b7c5f02",
    "type": "bank-account-vn",
    "bankAccount": {
      "accountSuffix": "4567",
      "institutionId": "vn-acb",
      "currency": "vnd",
      "country": "VN",
      "entityType": "individual",
      "accountHolder": { "name": "Nguyễn Văn An" },
      "rails": { "status": "complete", "supported": ["napas-247", "citad"], "pending": [] }
    }
  }
  ```
</ResponseExample>


# Update a Payment Method
Source: https://docs.crossmint.com/offramp/api-reference/payment-methods/update-payment-method

api-reference/_open-api/OfframpAPIs.json PATCH /unstable/payment-methods/{paymentMethodId}
Update the default status of an existing payout method.

Updates a payout method's default status. Only `default` can be changed.

## Returns

Returns the updated [PaymentMethod](/offramp/api-reference/payment-methods/payment-method-object) object.


# Submit Deposit
Source: https://docs.crossmint.com/offramp/api-reference/process-payment

api-reference/_open-api/OfframpAPIs.json POST /2022-06-09/orders/{orderId}/payment
Associates the broadcast on-chain stablecoin deposit with an offramp order by its transaction ID. This step is optional because Crossmint matches the deposit automatically by the order memo.



# How It Works
Source: https://docs.crossmint.com/offramp/concepts/how-it-works

How your users convert USDC into fiat and withdraw to their bank account

Crossmint Offramp lets your users convert USDC into fiat and withdraw it to their own bank account without leaving your app. You integrate once, and Crossmint handles compliance, conversion, and the bank payout. This page explains how the flow works end to end before you build it.

<img alt="Offramp flow diagram showing the end-to-end process from user verification through bank payout" />

## The Offramp Flow

<Steps>
  <Step title="Verify the user">
    Each user completes identity verification once. Verification runs asynchronously, so you trigger it and then poll until the user is verified. If your users are already KYC'd, you can bring them over by passing their identity data, so they skip the in-flow verification. See [KYC & Compliance](/offramp/concepts/kyc-and-compliance).
  </Step>

  <Step title="Save the user's bank account">
    The user's bank details are saved as a reusable payment method. Sensitive fields are tokenized at capture, so raw account numbers never touch your servers or Crossmint's.
  </Step>

  <Step title="Create an offramp order">
    Your backend creates an order specifying the amount of USDC to cash out and the bank account to pay. The order comes back with a prepared deposit transaction that already carries a memo tying the deposit to this order.
  </Step>

  <Step title="Send the deposit">
    Your app broadcasts the prepared transaction from the user's wallet. Crossmint matches the on-chain deposit to the order by its memo, so no extra confirmation call is needed.
  </Step>

  <Step title="Conversion and payout">
    Crossmint converts the USDC and pays out fiat to the user's bank account over local rails.
  </Step>

  <Step title="Completion">
    The order completes and the funds settle in the user's bank. You can track status by polling the order or via webhooks.
  </Step>
</Steps>

## Key Concepts

### Exact-In Amounts

You specify the **amount of USDC the user sends** (`exact-in`). The user sends exactly that amount of crypto, and the equivalent fiat, minus any applicable fees, is deposited into their bank account.

### First-Party Payouts

The destination bank account must belong to the same user who owns the wallet and completed verification. The wallet the user pays from is linked to that verified identity, and the order resolves KYC through it. Offramp pays users out to **their own** bank accounts, never to third parties.

### Settlement Timing

Once the USDC deposit is confirmed, fiat arrival depends on the payout rail, ranging from minutes to a few business days. Crossmint uses the account's default rail unless you pin one with `recipient.rail` when creating the order. See [Payment Schemes](/offramp/payment-methods) for the current rail catalog and settlement times.

In the staging environment, payouts are **simulated**, so you can run the full flow end to end without funds moving. Funds only move in production.

## What Crossmint Handles vs. What You Build

| Crossmint handles | You build |
| :- | :- |
| Identity screening and compliance | The in-app cash-out experience |
| Converting USDC to fiat | Collecting the user's bank account |
| Paying out over local bank rails | Creating orders and tracking status |
| Regulatory and licensing coverage | (Optional) passing KYC data you already hold |

## Next Steps

<CardGroup>
  <Card title="Quickstart" icon="bolt" href="/offramp/quickstarts/rest-api">
    Build your first offramp end to end
  </Card>

  <Card title="KYC & Compliance" icon="id-card" href="/offramp/concepts/kyc-and-compliance">
    How verification works for offramp
  </Card>
</CardGroup>


# KYC & Compliance
Source: https://docs.crossmint.com/offramp/concepts/kyc-and-compliance

How identity verification and compliance work for Crossmint Offramp

Every end user must pass KYC before they can withdraw funds through the Offramp. You can collect this verification with a Crossmint-hosted flow, or pass data you have already verified yourself. This page covers the onboarding models, the KYC tiers, and where to find the exact data requirements.

<Snippet />

## Choose Your Onboarding Model

| Model | Best for | How it works |
| :- | :- | :- |
| **Import KYC data** | Platforms that already verify users | You pass user data to Crossmint via API (Sumsub token-sharing coming soon) |
| **Crossmint-hosted** | Teams that want the fastest integration | The user completes KYC inside secure embedded components |

## How Verification Works

Verification runs asynchronously. You register the user, trigger verification, then poll until their `offramp` eligibility reads `verified`. Only verified users can save a payment method or create an order. The [Identity quickstart](/identity/quickstart) walks through the full sequence (accept the privacy policy, register the user, trigger verification, upload any required documents, and poll status), and its response reports eligibility per product, including `offramp` (full KYC) and `offramp-light` (progressive KYC). These endpoints use a `userId:` locator, a unique identifier you choose for the user.

## KYC Tiers

Crossmint applies KYC tiers based on cumulative transaction volume, transaction frequency, and risk profile — the same model used for [Onramp](/onramp/introduction/user-onboarding):

| Tier | Applies When | Data Required |
| :- | :- | :- |
| **Progressive (light) KYC** | Up to \$1,000 in total volume in the last 12 months | Name, date of birth, nationality, country, address, email, and phone number (phone required for US residents). An ID number or SSN is required for US (SSN) and EU/EEA residents; optional elsewhere. No document uploads. |
| **Full KYC** | Over \$1,000 in total volume in the last 12 months, or a high number of transactions | Progressive KYC data plus `dueDiligence`, `verificationHistory`, identity document, and selfie. See the [data requirements](/identity/data-requirements) page. |

<Note>Light KYC is available to non-US residents; US residents always complete Full KYC. Identity verification eligibility reports both tiers per user: `offramp-light` (progressive) and `offramp` (full).</Note>

<Note>Independently of the tier, Crossmint's compliance team may request a specific document from a user at any time — proof of address, source of wealth, or an identity document. See [additional document requests](/identity/quickstart#additional-document-requests).</Note>

## Guides

<CardGroup>
  <Card title="Import KYC Data" icon="file-import" href="/offramp/guides/import-user-kyc-data" />

  <Card title="Data Requirements" icon="list-check" href="/identity/data-requirements" />
</CardGroup>


# Manage Payment Methods
Source: https://docs.crossmint.com/offramp/guides/collect-bank-accounts

Save and manage your users' payout destinations as reusable payment methods

Before creating an offramp order, [save the destination bank account as a payment method](/offramp/api-reference/payment-methods/create-payment-method). Saved payment methods can be reused across Crossmint products, so users only need to enter their bank details once.

## Save a Payment Method

The request body depends on the payment method `type`. See [The Payment Method Object](/offramp/api-reference/payment-methods/payment-method-object) for the full list of types and fields.

The examples below use the staging URL, `https://vault.staging.crossmint.com`. In production, use `https://vault.crossmint.com`.

<Tabs>
  <Tab title="US">
    ```bash cURL theme={null}
    curl -X POST 'https://vault.staging.crossmint.com/api/unstable/payment-methods' \
      -H 'X-API-KEY: <YOUR_SERVER_API_KEY>' \
      -H 'Content-Type: application/json' \
      -d '{
        "type": "bank-account-us",
        "userLocator": "<USER_LOCATOR>",
        "label": "Wells Fargo Checking",
        "bankAccount": {
          "accountNumber": "<ACCOUNT_NUMBER>",
          "routingNumber": "091300010",
          "accountType": "checking",
          "entityType": "individual",
          "accountHolder": {
            "name": "Emily Carter"
          }
        }
      }'
    ```
  </Tab>

  <Tab title="Europe (SEPA)">
    ```bash cURL theme={null}
    curl -X POST 'https://vault.staging.crossmint.com/api/unstable/payment-methods' \
      -H 'X-API-KEY: <YOUR_SERVER_API_KEY>' \
      -H 'Content-Type: application/json' \
      -d '{
        "type": "bank-account-sepa-iban",
        "userLocator": "<USER_LOCATOR>",
        "label": "My Wise EUR",
        "bankAccount": {
          "iban": "BE05100052384175",
          "bic": "TRWIBEB1XXX",
          "entityType": "individual",
          "accountHolder": {
            "name": "Lukas Meier"
          }
        }
      }'
    ```
  </Tab>

  <Tab title="Colombia">
    ```bash cURL theme={null}
    curl -X POST 'https://vault.staging.crossmint.com/api/unstable/payment-methods' \
      -H 'X-API-KEY: <YOUR_SERVER_API_KEY>' \
      -H 'Content-Type: application/json' \
      -d '{
        "type": "bank-account-co",
        "userLocator": "<USER_LOCATOR>",
        "label": "Mi Bancolombia",
        "bankAccount": {
          "accountNumber": "2048817320",
          "institutionId": "co-bancolombia",
          "accountType": "checking",
          "entityType": "individual",
          "accountHolder": {
            "name": "Camila Restrepo",
            "document": { "type": "cc", "number": "1020304050" }
          }
        }
      }'
    ```
  </Tab>

  <Tab title="Colombia (Bre-B)">
    ```bash cURL theme={null}
    curl -X POST 'https://vault.staging.crossmint.com/api/unstable/payment-methods' \
      -H 'X-API-KEY: <YOUR_SERVER_API_KEY>' \
      -H 'Content-Type: application/json' \
      -d '{
        "type": "bre-b",
        "userLocator": "<USER_LOCATOR>",
        "label": "Nequi Ahorros",
        "breB": {
          "key": "@MQ7RK2PLTA",
          "entityType": "individual",
          "accountHolder": {
            "name": "Santiago Vargas"
          }
        }
      }'
    ```
  </Tab>

  <Tab title="Indonesia">
    ```bash cURL theme={null}
    curl -X POST 'https://vault.staging.crossmint.com/api/unstable/payment-methods' \
      -H 'X-API-KEY: <YOUR_SERVER_API_KEY>' \
      -H 'Content-Type: application/json' \
      -d '{
        "type": "bank-account-id",
        "userLocator": "<USER_LOCATOR>",
        "label": "My BCA account",
        "bankAccount": {
          "accountNumber": "1234567890",
          "institutionId": "id-bca",
          "entityType": "individual",
          "accountHolder": {
            "name": "Budi Santoso"
          }
        }
      }'
    ```
  </Tab>

  <Tab title="Mexico (CLABE)">
    ```bash cURL theme={null}
    curl -X POST 'https://vault.staging.crossmint.com/api/unstable/payment-methods' \
      -H 'X-API-KEY: <YOUR_SERVER_API_KEY>' \
      -H 'Content-Type: application/json' \
      -d '{
        "type": "bank-account-mx-clabe",
        "userLocator": "<USER_LOCATOR>",
        "label": "Mi cuenta Nu",
        "bankAccount": {
          "clabe": "646180527394108255",
          "entityType": "individual",
          "accountHolder": {
            "name": "Andrea Fuentes Lopez"
          }
        }
      }'
    ```
  </Tab>
</Tabs>

The response returns the saved payment method, including its `paymentMethodId` and a masked `accountSuffix`. Account numbers, IBANs, CLABEs, and Bre-B keys never appear in full. Pass the `paymentMethodId` as the `recipient` when you [create an order](/offramp/quickstarts/rest-api). The examples show a payment method after its checks complete. A create response has `status: pending`.

<Tabs>
  <Tab title="US">
    ```json theme={null}
    {
      "type": "bank-account-us",
      "paymentMethodId": "57d99e28-8fad-4158-b825-75a693e44b10",
      "status": "active",
      "statusReason": null,
      "label": "Wells Fargo Checking",
      "bankAccount": {
        "accountSuffix": "<LAST_4_DIGITS>",
        "routingNumber": "091300010",
        "accountType": "checking",
        "currency": "usd",
        "country": "US",
        "entityType": "individual",
        "accountHolder": {
          "name": "Emily Carter"
        },
        "rails": {
          "supported": [
            "ach-credit",
            "same-day-ach-credit"
          ],
          "pending": [
            "rtp-credit"
          ]
        }
      },
      "createdAt": "2026-08-20T19:10:00.000Z",
      "updatedAt": "2026-08-20T19:10:00.000Z"
    }
    ```

    The full account number is never returned. The response carries `bankAccount.accountSuffix`, the last four digits, while `routingNumber` comes back in full because it is not secret. A create that passes the structural checks, such as the ABA routing check digit, returns `status: "active"` straight away. This does not establish that the account exists or who owns it; those checks run when you create an order. The available rails depend on the addresses you supply: `fedwire` appears in `rails.supported` only when both `accountHolder.address` and `bankAddress` are provided. `rtp-credit` starts in `rails.pending` because not every US bank participates in the RTP network, and it moves to `rails.supported` once the receiving bank's participation is confirmed. `institutionName` is never populated for US accounts.
  </Tab>

  <Tab title="Europe (SEPA)">
    ```json theme={null}
    {
      "type": "bank-account-sepa-iban",
      "paymentMethodId": "19ee530a-80b3-401c-9a53-d6886c22fdd4",
      "status": "active",
      "reason": null,
      "default": false,
      "displayName": "Wise ••4175",
      "display": {
        "label": "Wise ••4175"
      },
      "lastPayoutAt": "2026-09-15T22:00:51.733Z",
      "bankAccount": {
        "accountHolder": {
          "name": "Lukas Meier"
        },
        "bankName": "Wise",
        "accountSuffix": "4175",
        "currency": "eur",
        "country": "BE",
        "entityType": "individual",
        "bic": "TRWIBEB1XXX",
        "rails": {
          "status": "complete",
          "supported": [
            "sepa"
          ],
          "pending": []
        }
      },
      "createdAt": "2026-09-15T19:04:06.788Z",
      "updatedAt": "2026-09-15T22:00:55.633Z"
    }
    ```

    The full IBAN is never returned. The response carries `bankAccount.accountSuffix`, the last four characters. SEPA validation is structural only (the IBAN mod-97 check), so a create that passes it returns `status: "active"` straight away. This does not establish that the account exists or who owns it. `currency` and `country` are read-only and derived from the IBAN. `bankName` is display-only and provider-sourced, so it stays absent when unknown.
  </Tab>

  <Tab title="Colombia">
    ```json theme={null}
    {
      "type": "bank-account-co",
      "paymentMethodId": "6b489a5d-3867-4ec9-bb76-072a89e1319d",
      "status": "pending",
      "statusReason": null,
      "label": "Mi Bancolombia",
      "bankAccount": {
        "accountSuffix": "7320",
        "institutionId": "co-bancolombia",
        "accountType": "checking",
        "currency": "cop",
        "country": "CO",
        "entityType": "individual",
        "accountHolder": {
          "name": "Camila Restrepo",
          "document": { "type": "cc", "suffix": "4050" }
        },
        "rails": { "status": "pending", "supported": [], "pending": ["ach-credit"] }
      },
      "createdAt": "2026-08-21T22:10:00.000Z",
      "updatedAt": "2026-08-21T22:12:11.000Z"
    }
    ```

    The full account and document numbers are never returned. The response carries `bankAccount.accountSuffix` and `accountHolder.document.suffix`, the last four digits of each. Crossmint rejects an `institutionId` that is not on the [Bank Institution IDs](/offramp/guides/bank-institution-ids) page with `422`. `accountType` is `checking`, `savings`, or `electronic-deposit`, and `accountHolder.document.type` is one of `cc`, `nit`, `ce`, `pa`, `ppt`, `ti`, `rc`, `te`, or `die`. `accountHolder.name` is always echoed back exactly as sent, and ownership is evaluated when you create an order, not on the payment method.
  </Tab>

  <Tab title="Colombia (Bre-B)">
    ```json theme={null}
    {
      "type": "bre-b",
      "paymentMethodId": "7fdf72b9-f627-4b89-b7d7-5795893aaf12",
      "status": "active",
      "statusReason": null,
      "label": "Nequi Ahorros",
      "breB": {
        "accountHolder": {
          "name": "Santiago Vargas"
        },
        "accountSuffix": "PLTA",
        "currency": "cop",
        "country": "CO",
        "entityType": "individual",
        "keyType": "alphanumeric",
        "rails": {
          "supported": [
            "bre-b"
          ]
        }
      },
      "createdAt": "2026-09-17T14:27:20.725Z",
      "updatedAt": "2026-09-17T14:27:21.410Z"
    }
    ```

    The key itself is never returned. The response carries `breB.accountSuffix` instead: the last four characters of the key's distinguishing part, which for `alphanumeric` keys is everything after the leading `@` and for `email` keys is the local part before the `@`. `keyType` is derived from the key format. `institutionName` is optional display metadata from a reliable bank directory and is omitted when unknown.
  </Tab>

  <Tab title="Indonesia">
    ```json theme={null}
    {
      "type": "bank-account-id",
      "paymentMethodId": "7a3e5c91-2b4d-4f86-a1c0-9d8e7f6a5b42",
      "status": "active",
      "statusReason": null,
      "label": "My BCA account",
      "bankAccount": {
        "accountSuffix": "7890",
        "institutionId": "id-bca",
        "currency": "idr",
        "country": "ID",
        "entityType": "individual",
        "accountHolder": {
          "name": "Budi Santoso"
        },
        "rails": { "status": "complete", "supported": ["bi-fast"], "pending": [] }
      },
      "createdAt": "2026-09-23T09:00:00.000Z",
      "updatedAt": "2026-09-23T09:00:12.000Z"
    }
    ```

    The five types take the same body. Change `type`, and take the `institutionId` from the country's section of the [Bank Institution IDs](/offramp/guides/bank-institution-ids) page. Crossmint rejects an account number that does not match its type with `422`:

    | `type` | `accountNumber` | `currency` | Rails |
    | - | - | - | - |
    | `bank-account-id` | 7 to 18 digits | `idr` | `bi-fast` |
    | `bank-account-ng` | 10 digits (a NUBAN, the Nigeria Uniform Bank Account Number); the last is the check digit for the bank | `ngn` | `nip` |
    | `bank-account-ph` | 6 to 18 digits | `php` | `instapay`, `pesonet` |
    | `bank-account-th` | 7 to 12 digits | `thb` | `promptpay` |
    | `bank-account-vn` | 1 to 20 letters or digits | `vnd` | `napas-247`, `citad` |

    The request carries no `currency` or `country`: the type sets both. `accountType` is optional, `checking` or `savings`. `accountHolder.address` is optional; when you send it, `line1` and `city` are required, `line1` is at most 100 characters, and a PO box or private mailbox is rejected. The full account number is never returned. `accountHolder.name` is always echoed back exactly as sent, and ownership is evaluated when you create an order, not on the payment method.
  </Tab>

  <Tab title="Mexico (CLABE)">
    ```json theme={null}
    {
      "type": "bank-account-mx-clabe",
      "paymentMethodId": "ba4280b4-8fe3-41e5-9c38-f72d453c950f",
      "status": "active",
      "statusReason": null,
      "label": "Mi cuenta Nu",
      "bankAccount": {
        "accountHolder": {
          "name": "Andrea Fuentes Lopez"
        },
        "accountSuffix": "8255",
        "currency": "mxn",
        "country": "MX",
        "entityType": "individual",
        "rails": {
          "status": "complete",
          "supported": [
            "spei"
          ],
          "pending": []
        }
      },
      "createdAt": "2026-09-17T14:16:38.552Z",
      "updatedAt": "2026-09-17T14:16:41.026Z"
    }
    ```

    The full CLABE is never returned. The response carries `bankAccount.accountSuffix`, the last four digits, and no bank field, because the CLABE identifies the bank. A malformed CLABE check digit is rejected synchronously with `422` and nothing is stored. Crossmint also rejects a request that sends `bankCode`, `bankName`, or `institutionId` with `422`. `accountHolder.name` is always echoed back exactly as sent, and ownership is evaluated when you create an order, not on the payment method.
  </Tab>
</Tabs>

<Note>Saving a payment method does not require the user to be verified yet, but creating an order does. Before you offramp to it, verify the user and link the wallet they will pay from. See the [Quickstart](/offramp/quickstarts/rest-api).</Note>

For a complete list of fields and supported payment method types, see [The Payment Method Object](/offramp/api-reference/payment-methods/payment-method-object) in the API reference.

## Statuses

Every payment method type shares one lifecycle. `status` describes whether the payment method has passed the readiness checks required for its type and can proceed to order-level eligibility checks. It does not describe user approval, ownership, or guaranteed payout success.

| Status | Meaning |
| - | - |
| `pending` | Initial readiness checks are running. |
| `active` | Required readiness checks passed. Orders still run their own eligibility checks. |
| `rejected` | The destination cannot receive a supported payout. The initial checks ended without a usable record, a provider refused the account, or the bank returned a payout to it. To retry, create a new payment method. |
| `deleted` | Removed by you. Never reactivates. |

### Status Changes

Creation always returns `pending`. Poll the payment method to get its latest status. A US or SEPA account usually becomes `active` within seconds. A Mexican CLABE or a Bre-B key can take several minutes, because a check with the bank runs first.

The allowed transitions are:

* `pending` → `active`, `rejected`, or `deleted`
* `active` → `rejected` when a provider refuses the account or the bank returns a payout to it, or `deleted`
* `rejected` → `deleted`

An order refuses a payment method that is not `active` with the error code `payments:payment-method.not-active`. If a provider refuses the account, an `active` payment method changes to `rejected`. When this happens while you create or update the order, that request fails with the error code `payments:payment-method.rejected-by-provider`. If the payment method is deleted after the order is created and before the payout starts, the order fails. A refund of the deposit starts, except when a Colombian payout was set up before the check. An order that waits for deposit instructions also fails when its payment method is no longer `active`.

When the bank returns a payout because the account cannot receive it, every payment method for that account in your project changes to `rejected`, for all of your users. A deleted one stays `deleted`. `statusReason` gives the reason. A new payment method for that account in the same project then fails with the error code `payments:payment-method.destination-blocked`, and the error response carries the same `statusReason`:

```json theme={null}
{
    "error": true,
    "message": "This bank account cannot receive payouts. Use a different bank account.",
    "code": "payments:payment-method.destination-blocked",
    "statusReason": "destination-closed"
}
```

Ask the user for a different account.

A deleted method never reactivates.

Readiness checks start when the method is created. Fetching it, editing its label, or using it in an order does not restart those checks. A failed transfer changes the payment-method status only when the bank returns the payout because the account cannot receive it.

### Status Reasons

`statusReason` is `null` unless the payment method is `rejected`. A rejected method may include one of the following reason codes:

| Code | Meaning |
| - | - |
| `destination-not-found` | The account or key is confirmed not to exist. |
| `destination-closed` | The account is confirmed closed. |
| `destination-cannot-receive` | The destination cannot receive supported payouts. |
| `no-rail-available` | No supported payout rail reaches the destination. This is not a temporary outage. |

Branch on `status`, never on `statusReason`. New codes can appear at any time, so tolerate values you do not recognize. `statusReason` never carries provider errors, ownership, or compliance detail. Ownership is evaluated when you create an order, not on the payment method.

## Rails

`rails.supported` lists the rails available to reach the destination straight away, and `rails.pending` lists rails that may become available once confirmed. `rails.supported` can list rails while the method is still `pending`. Only an `active` method accepts an order. A valid account with no rail to reach it is `rejected` with `statusReason: "no-rail-available"`.

## List, Update, and Remove

Reads and non-sensitive updates go through the standard API. Use it to [list a user's payment methods](/offramp/api-reference/payment-methods/list-payment-methods), [fetch one](/offramp/api-reference/payment-methods/get-payment-method), [update the label or other non-sensitive metadata](/offramp/api-reference/payment-methods/update-payment-method), or [remove a payment method](/offramp/api-reference/payment-methods/delete-payment-method).

## Next Steps

<CardGroup>
  <Card title="Quickstart" icon="bolt" href="/offramp/quickstarts/rest-api">
    Use a saved payment method in an offramp order
  </Card>

  <Card title="Institution IDs" icon="building-columns" href="/offramp/guides/institution-ids">
    Find the institutionId of a bank by country
  </Card>

  <Card title="Create Payment Method" icon="code" href="/offramp/api-reference/payment-methods/create-payment-method">
    Full request and response schema in the API reference
  </Card>
</CardGroup>


# Launch in Production
Source: https://docs.crossmint.com/offramp/guides/going-to-production

Move your offramp integration from staging to live payouts

Everything you build on staging runs end to end with simulated payouts. When you are ready to move funds to users' banks, switch to production.

## What Changes

| | Staging | Production |
| :- | :- | :- |
| API host | `staging.crossmint.com` | `www.crossmint.com` |
| Vault host | `vault.staging.crossmint.com` | `vault.crossmint.com` |
| API key | Staging server key | Production server key |
| Crypto | Testnet USDC | Mainnet USDC |
| Chain (`payment.method`) | Testnet (for example `base-sepolia`, `ethereum-sepolia`) | Mainnet (for example `base`, `solana`, `ethereum`) |
| Payout | Simulated | Fiat settles in the user's bank account |

Get your production API key from the <a href="https://www.crossmint.com/console">Crossmint console</a>. It needs the `orders`, `payment-methods`, `users.create`, and `users.read` scopes.

## Go-Live Checklist

<Steps>
  <Step title="Get production access">
    Production access requires a signed Order Form and completed KYB verification, and your project enabled for KYC data sharing. <a href="https://www.crossmint.com/contact/sales">Contact sales</a> to get set up, and see [account verification](/introduction/platform/account-verification) for what KYB involves.
  </Step>

  <Step title="Verify your users">
    Verify each user in production. If you import KYC data, confirm it meets the [data requirements](/identity/data-requirements) for each region you serve.
  </Step>

  <Step title="Handle order status">
    Wire up [order tracking](/offramp/guides/manage-orders) by polling or webhooks so your app reflects payout progress and surfaces failures.
  </Step>

  <Step title="Switch hosts and keys">
    Point your requests at the production hosts and swap in your production API key. Send mainnet USDC on a supported chain.
  </Step>
</Steps>

## Next Steps

<CardGroup>
  <Card title="Contact sales" icon="headset" href="https://www.crossmint.com/contact/sales">
    Enable production access
  </Card>

  <Card title="KYC & Compliance" icon="id-card" href="/offramp/concepts/kyc-and-compliance">
    Verification requirements
  </Card>
</CardGroup>


# Import User KYC Data
Source: https://docs.crossmint.com/offramp/guides/import-user-kyc-data

Pass your users' existing KYC data to Crossmint so they skip verification

If your platform already verifies your users, share that data with Crossmint so they skip in-flow verification and are ready to cash out. This guide covers passing that data and confirming the user is verified. For how verification works in depth, see [KYC & Compliance](/offramp/concepts/kyc-and-compliance).

<Snippet />

## Register and Verify the User

Each call uses a `userId:` locator, where `<USER_ID>` is a unique identifier you choose for the user and reuse across the calls below.

<Frame type="simple">
  <img alt="User KYC verification flow: record privacy policy, create user with KYC data, trigger verification, poll until verified" />
</Frame>

<Steps>
  <Step title="Record privacy policy acceptance">
    Before sharing any user KYC data with Crossmint, the user must accept Crossmint's <a href="https://www.crossmint.com/legal/privacy-policy">Privacy Policy</a> in your app. Consent must be collected with an explicit checkbox and specific wording — see [Register User Data](/identity/register-user-data) for the exact consent-collection requirements. Only once the user has accepted, record their consent:

    ```bash theme={null}
    curl -X PUT 'https://staging.crossmint.com/api/2025-06-09/users/userId:<USER_ID>/legal-documents' \
      -H 'X-API-KEY: <YOUR_SERVER_API_KEY>' \
      -H 'Content-Type: application/json' \
      -d '{ "type": "crossmint-privacy-policy", "acceptedAt": "2026-01-01T00:00:00.000Z" }'
    ```

    <Accordion title="Example response">
      ```json theme={null}
      {
        "acceptedAt": "2026-01-01T00:00:00.000Z"
      }
      ```
    </Accordion>
  </Step>

  <Step title="Create the user with KYC data">
    Send the user's details along with the KYC data you already hold.

    ```bash theme={null}
    curl -X PUT 'https://staging.crossmint.com/api/2025-06-09/users/userId:<USER_ID>' \
      -H 'X-API-KEY: <YOUR_SERVER_API_KEY>' \
      -H 'Content-Type: application/json' \
      -d '{
        "userDetails": {
          "firstName": "Alice",
          "lastName": "Smith",
          "dateOfBirth": "1990-01-15",
          "countryOfResidence": "US"
        },
        "kycData": {
          "email": "alice@example.com",
          "phoneNumber": "+13055551234",
          "nationality": "US",
          "addressOfResidence": {
            "line1": "701 S Miami Ave",
            "city": "Miami",
            "postalCode": "33156",
            "stateOrRegion": "FL"
          },
          "identityDocument": {
            "type": "ssn",
            "number": "123-45-6789",
            "issuingCountryCode": "US"
          },
          "ipAddresses": ["203.0.113.1"]
        },
        "verificationHistory": {
          "idVerificationTimestamp": "2026-01-01T00:00:00.000Z",
          "livenessVerificationTimestamp": "2026-01-01T00:00:00.000Z"
        }
      }'
    ```

    The booleans in the response show which sections were stored.

    <Note>
      **US residents:** include `kycData.phoneNumber` (required), and provide identity via SSN in `kycData.identityDocument` (no document upload is needed for standard offramp). The `dueDiligence` object is not required for standard US offramp in most states — include it only where required (see [Data Requirements](/identity/data-requirements)).
    </Note>

    <Accordion title="Example response">
      ```json theme={null}
      {
        "userId": "<USER_ID>",
        "userDetails": true,
        "kycData": true,
        "dueDiligence": false,
        "verificationHistory": true
      }
      ```
    </Accordion>
  </Step>

  <Step title="Trigger verification">
    Trigger verification so Crossmint runs its compliance checks against the data you provided.

    ```bash theme={null}
    curl -X PUT 'https://staging.crossmint.com/api/2025-06-09/users/userId:<USER_ID>/identity-verification' \
      -H 'X-API-KEY: <YOUR_SERVER_API_KEY>'
    ```

    The response returns the eligibility status per product, starting at `pending-review`.

    <Accordion title="Example response">
      ```json theme={null}
      {
        "eligibility": [
          { "type": "onramp", "status": "pending-review" },
          { "type": "onramp-light", "status": "pending-review" },
          { "type": "offramp", "status": "pending-review" },
          { "type": "offramp-light", "status": "pending-review" },
          { "type": "regulated-transfer", "status": "pending-review" }
        ]
      }
      ```
    </Accordion>
  </Step>

  <Step title="Poll until verified">
    Verification is asynchronous. Poll until the `offramp` eligibility reads `verified`. Only a verified user can save a payment method or create an order.

    If the status reads `requires-data` with a document listed in `missingDocuments`, Crossmint's compliance team has requested an additional document — upload it via the [Upload Document API](/api-reference/users/upload-document) and re-trigger verification. See [additional document requests](/identity/quickstart#additional-document-requests).

    ```bash theme={null}
    curl -X GET 'https://staging.crossmint.com/api/2025-06-09/users/userId:<USER_ID>/identity-verification' \
      -H 'X-API-KEY: <YOUR_SERVER_API_KEY>'
    ```

    <Accordion title="Example response">
      ```json theme={null}
      {
        "eligibility": [
          { "type": "onramp", "status": "verified" },
          { "type": "onramp-light", "status": "verified" },
          { "type": "offramp", "status": "verified" },
          { "type": "offramp-light", "status": "verified" },
          { "type": "regulated-transfer", "status": "verified" }
        ]
      }
      ```
    </Accordion>
  </Step>
</Steps>

The exact fields required vary by region. See the [Identity data requirements](/identity/data-requirements) for the full list, and the [Identity quickstart](/identity/quickstart) for uploading documents when a region requires them.

<Note>The account holder name on the user's saved bank account must match this verified identity. Offramp supports first-party payouts only.</Note>

## Next Steps

<CardGroup>
  <Card title="Manage Payment Methods" icon="building-columns" href="/offramp/guides/collect-bank-accounts">
    Save the verified user's bank account
  </Card>

  <Card title="Quickstart" icon="bolt" href="/offramp/quickstarts/rest-api">
    Build the full flow
  </Card>
</CardGroup>


# Institution IDs
Source: https://docs.crossmint.com/offramp/guides/institution-ids

The institutionId to send when you save a bank account in a country where the account number does not identify the bank

Some countries' account numbers do not say which bank holds them. For these countries, a [bank-account payment method](/offramp/guides/collect-bank-accounts) needs `bankAccount.institutionId`, a Crossmint ID for the bank. Show your users the bank names from the table below, and send the matching `institutionId`.

| Payment method type | Country | Needs `institutionId` |
| :- | :- | :- |
| `bank-account-us` | United States | No. The routing number identifies the bank |
| `bank-account-sepa-iban` | SEPA countries | No. The IBAN identifies the bank |
| `bank-account-co` | Colombia | Yes |
| `bank-account-id` | Indonesia | Yes |
| `bank-account-mx-clabe` | Mexico | No. The CLABE identifies the bank |
| `bank-account-ng` | Nigeria | Yes |
| `bank-account-ph` | Philippines | Yes |
| `bank-account-th` | Thailand | Yes |
| `bank-account-vn` | Vietnam | Yes |

For example, this request body saves a Bancolombia account for a Colombian user:

```json theme={null}
{
  "type": "bank-account-co",
  "userLocator": "email:ana@example.com",
  "bankAccount": {
    "accountNumber": "1013555555",
    "institutionId": "co-bancolombia",
    "accountType": "checking",
    "entityType": "individual",
    "accountHolder": {
      "name": "Ana Perez Garcia",
      "document": { "type": "cc", "number": "1017218529" }
    }
  }
}
```

## Rules

* Send the `institutionId` exactly as listed. It is an opaque ID: do not build or parse it.
* Do not send a national bank code such as `1007`. The request is rejected with `422`.
* An `institutionId` never changes once published, even if the bank is renamed.
* When a bank closes or becomes unavailable for payouts, it leaves the table and new requests with its ID return `422`. Saved payment methods keep their ID, so keep the bank name your user picked.
* The names are shown as the bank registers them, often in capitals. You may format them for display.

## Colombia

Banks for `bank-account-co`.

| Bank | `institutionId` |
| - | - |
| Alianza fiduciaria | `co-alianza-fiduciaria` |
| BAN100 S.A | `co-ban100` |
| BANCO AGRARIO | `co-banco-agrario` |
| BANCO AV VILLAS | `co-av-villas` |
| BANCO BTG PACTUAL | `co-btg-pactual` |
| BANCO CAJA SOCIAL BCSC SA | `co-banco-caja-social` |
| BANCO COOPERATIVO COOPCENTRAL | `co-coopcentral` |
| BANCO DAVIVIENDA SA | `co-davivienda` |
| BANCO DE BOGOTA | `co-banco-de-bogota` |
| BANCO DE LAS MICROFINANZAS - BANCAMIA S.A. | `co-bancamia` |
| BANCO DE OCCIDENTE | `co-banco-de-occidente` |
| BANCO FALABELLA S.A. | `co-banco-falabella` |
| BANCO FINANDINA S.A. | `co-banco-finandina` |
| BANCO GNB SUDAMERIS | `co-gnb-sudameris` |
| BANCO J.P. MORGAN COLOMBIA S.A. | `co-jp-morgan` |
| BANCO MUNDO MUJER | `co-banco-mundo-mujer` |
| BANCO PICHINCHA | `co-banco-pichincha` |
| BANCO POPULAR | `co-banco-popular` |
| BANCO SANTANDER DE NEGOCIOS COLOMBIA S.A | `co-santander` |
| BANCO SERFINANZA S.A | `co-banco-serfinanza` |
| BANCO UNION S.A | `co-banco-union` |
| BANCO W | `co-banco-w` |
| BANCOLDEX S.A. | `co-bancoldex` |
| BANCOLOMBIA | `co-bancolombia` |
| BANCOOMEVA | `co-bancoomeva` |
| BBVA COLOMBIA | `co-bbva` |
| BOLD CF | `co-bold` |
| CITIBANK | `co-citibank` |
| COINK | `co-coink` |
| COLTEFINANCIERA S.A | `co-coltefinanciera` |
| CONFIAR COOPERATIVA FINANCIERA | `co-confiar` |
| COOPERATIVA FINANCIERA DE ANTIOQUIA | `co-cfa` |
| COOTRAFA COOPERATIVA FINANCIERA | `co-cootrafa` |
| Crezcamos | `co-crezcamos` |
| Dale | `co-dale` |
| DAVIBANK | `co-davibank` |
| DAVIPLATA | `co-daviplata` |
| DING TECNIPAGOS SA | `co-ding` |
| FINANCIERA JURISCOOP S.A. COMPAÑIA DE FINANCIAMIENTO | `co-juriscoop` |
| GLOBAL66 | `co-global66` |
| IRIS | `co-iris` |
| ITAU | `co-itau` |
| JFK COOPERATIVA FINANCIERA | `co-jfk` |
| LULO BANK S.A. | `co-lulo-bank` |
| MIBANCO S.A. | `co-mibanco` |
| MOVII | `co-movii` |
| NEQUI | `co-nequi` |
| NU COLOMBIA | `co-nu` |
| PIBANK | `co-pibank` |
| POWWI | `co-powwi` |
| RAPPIPAY | `co-rappipay` |
| UALA | `co-uala` |

## Indonesia

Banks for `bank-account-id`.

| Bank | `institutionId` |
| - | - |
| Bank Aceh | `id-bank-aceh` |
| Bank Antardaerah | `id-bank-antardaerah` |
| Bank ANZ Indonesia | `id-anz` |
| Bank Artha Graha Internasional | `id-artha-graha` |
| Bank Banten | `id-bank-banten` |
| Bank BCA Syariah | `id-bca-syariah` |
| Bank BPD Bali | `id-bpd-bali` |
| Bank BPD DIY | `id-bpd-diy` |
| Bank BPD Papua | `id-bank-papua` |
| Bank BPR EKA | `id-bpr-eka` |
| Bank BRI Agroniaga | `id-bri-agroniaga` |
| Bank BRI Syariah | `id-bri-syariah` |
| Bank BTPN | `id-btpn` |
| BANK BTPN SYARIAH | `id-btpn-syariah` |
| Bank Bukopin | `id-bukopin` |
| Bank Bumi Arta | `id-bumi-arta` |
| Bank Capital Indonesia | `id-bank-capital` |
| Bank Central Asia (BCA) | `id-bca` |
| Bank Chinatrust Indonesia (CTBC) | `id-ctbc` |
| Bank CIMB Niaga | `id-cimb-niaga` |
| Bank Commonwealth | `id-commonwealth` |
| Bank Danamon | `id-danamon` |
| Bank DBS Indonesia | `id-dbs` |
| Bank DKI | `id-bank-dki` |
| Bank Ganesha | `id-bank-ganesha` |
| Bank HARDA Internasional | `id-bank-harda` |
| Bank HSBC Indonesia | `id-hsbc` |
| Bank IBK Indonesia (Bank Agris) | `id-ibk` |
| Bank ICBC Indonesia | `id-icbc` |
| Bank Ina Perdana | `id-bank-ina-perdana` |
| Bank Index | `id-bank-index` |
| Bank J Trust Indonesia | `id-j-trust` |
| Bank Jabar (BJB) | `id-bjb` |
| Bank Jabar Banten Syariah | `id-bjb-syariah` |
| Bank Jago | `id-bank-jago` |
| Bank Jambi | `id-bank-jambi` |
| Bank Jasa Jakarta | `id-bank-jasa-jakarta` |
| Bank Jateng | `id-bank-jateng` |
| Bank Jatim | `id-bank-jatim` |
| Bank Kalbar | `id-bank-kalbar` |
| Bank Kalsel | `id-bank-kalsel` |
| Bank Kalteng | `id-bank-kalteng` |
| Bank Kaltim | `id-bank-kaltim` |
| Bank Lampung | `id-bank-lampung` |
| Bank Maluku | `id-bank-maluku` |
| Bank Mandiri | `id-mandiri` |
| Bank Mandiri Taspen (Bank Mantap) | `id-bank-mantap` |
| Bank Maspion Indonesia | `id-bank-maspion` |
| Bank Mayapada International | `id-mayapada` |
| Bank Mayora | `id-bank-mayora` |
| Bank Mega | `id-bank-mega` |
| Bank Mega Syariah | `id-bank-mega-syariah` |
| Bank Mestika | `id-bank-mestika` |
| BANK MNC INTERNASIONAL (MNC BANK) | `id-mnc-bank` |
| Bank Muamalat | `id-muamalat` |
| Bank Multiarta Sentosa | `id-bank-multiarta-sentosa` |
| Bank Nagari | `id-bank-nagari` |
| Bank National NOBU | `id-nobu` |
| Bank Negara Indonesia (BNI) | `id-bni` |
| Bank Negara Indonesia Syariah | `id-bni-syariah` |
| Bank NTB | `id-bank-ntb` |
| Bank NTT | `id-bank-ntt` |
| Bank Nusantara Parahyangan | `id-bank-nusantara-parahyangan` |
| Bank OCBC NISP | `id-ocbc-nisp` |
| Bank Of China Indonesia | `id-bank-of-china` |
| Bank of India Indonesia | `id-bank-of-india` |
| Bank Of Tokyo Mitsubishi Ufj Ltd. The | `id-mufg` |
| Bank Oke Indonesia (Bank Dinar) | `id-bank-oke` |
| Bank Panin | `id-panin` |
| Bank Panin Syariah | `id-panin-syariah` |
| Bank Permata | `id-permata` |
| Bank Prima Master | `id-bank-prima-master` |
| Bank QNB Indonesia | `id-qnb` |
| Bank Rakyat Indonesia (BRI) | `id-bri` |
| Bank Riau Kepri | `id-bank-riau-kepri` |
| Bank Royal | `id-bank-royal` |
| Bank Sahabat Sampoerna | `id-bank-sampoerna` |
| Bank Sbi Indonesia | `id-bank-sbi` |
| Bank Shinhan Indonesia | `id-shinhan` |
| Bank Sinarmas | `id-bank-sinarmas` |
| Bank Sulselbar | `id-bank-sulselbar` |
| Bank Sulteng | `id-bank-sulteng` |
| Bank Sultra | `id-bank-sultra` |
| Bank Sulut | `id-bank-sulut` |
| Bank Sumsel Babel | `id-bank-sumsel-babel` |
| Bank Sumut | `id-bank-sumut` |
| Bank Syariah Bukopin | `id-bukopin-syariah` |
| Bank Syariah Indonesia | `id-bsi` |
| Bank Syariah Mandiri | `id-mandiri-syariah` |
| Bank Tabungan Negara (BTN) | `id-btn` |
| Bank UOB Indonesia | `id-uob` |
| Bank Victoria Internasional | `id-bank-victoria` |
| Bank Victoria Syariah | `id-bank-victoria-syariah` |
| Bank Windu (China Construction Bank Indonesia) | `id-ccb` |
| Bank Woori Saudara | `id-woori-saudara` |
| Bank Yudha Bhakti | `id-bank-yudha-bhakti` |
| Centratama Nasional Bank (CNB) | `id-cnb` |
| Citibank N.a. | `id-citibank` |
| KEB Hana Bank | `id-keb-hana` |
| Maybank Indonesia | `id-maybank` |
| PT Bank SeaBank Indonesia (formerly Bank Kesejahteraan Ekonomi) | `id-seabank` |
| Standard Chartered Bank | `id-standard-chartered` |
| Superbank | `id-superbank` |

## Nigeria

Banks for `bank-account-ng`.

| Bank | `institutionId` |
| - | - |
| Access Bank PLC | `ng-access-bank` |
| CITI Bank | `ng-citi-bank` |
| Ecobank Nigeria PLC | `ng-ecobank-nigeria` |
| Fidelity Bank PLC | `ng-fidelity-bank` |
| First Bank Of Nigeria PLC | `ng-first-bank-of-nigeria` |
| First City Monument Bank PLC | `ng-first-city-monument-bank` |
| GT Bank | `ng-gt-bank` |
| Jaiz Bank | `ng-jaiz-bank` |
| Keystone Bank PLC | `ng-keystone-bank` |
| Polaris Bank PLC | `ng-polaris-bank` |
| Providus Bank | `ng-providus-bank` |
| Stanbic IBTC Bank PLC | `ng-stanbic-ibtc-bank` |
| Standard Chartered Bank PLC | `ng-standard-chartered-bank` |
| Sterling Bank PLC | `ng-sterling-bank` |
| Suntrust Bank | `ng-suntrust-bank` |
| Union Bank Of Nigeria PLC | `ng-union-bank-of-nigeria` |
| United Bank For Africa PLC | `ng-united-bank-for-africa` |
| Unity Bank PLC | `ng-unity-bank` |
| Wema Bank PLC | `ng-wema-bank` |
| Zenith International Bank PLC | `ng-zenith-international-bank` |

## Philippines

Banks for `bank-account-ph`.

| Bank | `institutionId` |
| - | - |
| AL AMANAH ISLAMIC INVESTMENT BANK | `ph-al-amanah-islamic-bank` |
| ALLBANK | `ph-allbank` |
| Anz Bank | `ph-anz` |
| Asia united Bank | `ph-aub` |
| Banco De Oro | `ph-bdo` |
| Bangko Kabayan Inc | `ph-bangko-kabayan` |
| Bangko Mabuhay, Inc. | `ph-bangko-mabuhay` |
| Bangko Nuestra Senora Del Pilar Inc | `ph-bangko-nuestra-senora` |
| Bangkok Bank | `ph-bangkok-bank` |
| Bank Of America | `ph-bank-of-america` |
| Bank Of China | `ph-bank-of-china` |
| Bank Of Commerce | `ph-bank-of-commerce` |
| Bank Of Philippines Islands | `ph-bpi` |
| BDO NETWORK BANK | `ph-bdo-network-bank` |
| BDO PRIVATE BANK | `ph-bdo-private-bank` |
| Binan Rural Bank, Inc | `ph-binan-rural-bank` |
| Binangonan Rural Bank (Brbdigital) | `ph-brbdigital` |
| BOF, INC (A Rural Bank) - Bank of Florida | `ph-bank-of-florida` |
| BPI Direct Banko, Inc. | `ph-bpi-banko` |
| BPI Family Savings Bank | `ph-bpi-family-savings` |
| CAMALIG BANK, INC (A Rural Bank) | `ph-camalig-bank` |
| Cantilan Bank, Inc. (A Rural Bank) | `ph-cantilan-bank` |
| Card Bank Inc | `ph-card-bank` |
| Cathay United Bank | `ph-cathay-united-bank` |
| CEBUANA LHUILLIER RURAL BANK INC | `ph-cebuana-lhuillier-bank` |
| China Bank | `ph-china-bank` |
| China Bank Saving | `ph-china-bank-savings` |
| CIMB BANK PHILIPPINES INC | `ph-cimb` |
| Citibank N.a. | `ph-citibank` |
| Cooperative Bank Of Quezon Province | `ph-coop-bank-of-quezon` |
| COUNTRY BUILDERS BANK INC (A Rural Bank) | `ph-country-builders-bank` |
| CTBC Bank (Philippines) Corporation | `ph-ctbc` |
| Deutsche Bank | `ph-deutsche-bank` |
| Development Bank Of Philippines | `ph-dbp` |
| Dungganon Bank, Inc. | `ph-dungganon-bank` |
| East-West Bank | `ph-eastwest-bank` |
| EastWest Rural Bank | `ph-eastwest-rural-bank` |
| Entrepreneur Bank | `ph-entrepreneur-bank` |
| Equicom Saving Bank, Inc. | `ph-equicom-savings-bank` |
| FIRST CONSOLIDATED BANK | `ph-first-consolidated-bank` |
| Gotyme Bank Corporation | `ph-gotyme` |
| Guagua Rural Bank, Inc. (Grbank) | `ph-guagua-rural-bank` |
| HSBC | `ph-hsbc` |
| Industrial And Commercial Bank Of China | `ph-icbc` |
| INDUSTRIAL BANK OF KOREA | `ph-ibk` |
| INNOVATIVE BANK INC | `ph-innovative-bank` |
| Isla Bank, Inc. | `ph-isla-bank` |
| JP Morgan Chase | `ph-jp-morgan` |
| KEB HANA | `ph-keb-hana` |
| Laguna Prestige Bank | `ph-laguna-prestige-bank` |
| Land Bank | `ph-landbank` |
| Luzon Development Bank | `ph-luzon-development-bank` |
| Malarayat Rural Bank, Inc. | `ph-malarayat-rural-bank` |
| Malayan Bank Saving and Mortgage Bank, Inc. | `ph-malayan-bank` |
| Maya Bank, Inc. | `ph-maya` |
| Maybank | `ph-maybank` |
| MEGA INTL COMML BANK CO LTD (ICBC) | `ph-mega-bank` |
| Metrobank | `ph-metrobank` |
| Mindanao Consolidated Cooperative Bank | `ph-mindanao-coop-bank` |
| MIZUHO BANK LTD (Fuji Bank) | `ph-mizuho` |
| Money Mall Rural Bank, Inc | `ph-money-mall-rural-bank` |
| MUFG BANK LTD (Bank Of Tokyo) | `ph-mufg` |
| Mvsm (A Rural Bank Since 1953),inc | `ph-mvsm-bank` |
| Netbank (A Rural Bank), Inc. | `ph-netbank` |
| OmniPay, Inc. | `ph-omnipay` |
| Pacific Ace Savings Bank | `ph-pacific-ace-savings-bank` |
| Partner Rural Bank, Inc. | `ph-partner-rural-bank` |
| Philippine Bank of Communications | `ph-pbcom` |
| Philippine National Bank | `ph-pnb` |
| Philippine Trust Company | `ph-philtrust` |
| Philippine Veterans Bank | `ph-veterans-bank` |
| Philippines Business Bank | `ph-pbb` |
| Philippines Saving Bank | `ph-psbank` |
| PNB Savings Bank | `ph-pnb-savings-bank` |
| PRODUCERS SAVINGS BANK CORP | `ph-producers-bank` |
| QCRB | `ph-qcrb` |
| Queen City Development Bank (Queen Bank) | `ph-queenbank` |
| RANG-AY BANK, INC. (A Rural Bank) | `ph-rang-ay-bank` |
| Rbt Bank, Inc (A Rural Bank), And | `ph-rbt-bank` |
| RCBC | `ph-rcbc` |
| RCBC Saving Bank | `ph-rcbc-savings-bank` |
| Robinson Bank | `ph-robinsons-bank` |
| Rural Bank Of Bacolod City, Inc | `ph-rural-bank-of-bacolod-city` |
| Rural Bank Of Bauang, Inc | `ph-rural-bank-of-bauang` |
| Rural Bank Of Digos Inc (Rbdi) | `ph-rural-bank-of-digos` |
| RURAL BANK OF GUINOBATAN INC (RBGI) | `ph-rural-bank-of-guinobatan` |
| Rural Bank Of La Paz Inc | `ph-rural-bank-of-la-paz` |
| Rural Bank Of Lebak (Sultan Kudarat), Inc. | `ph-rural-bank-of-lebak` |
| Rural Bank Of Montalban Inc | `ph-rural-bank-of-montalban` |
| Rural Bank Of Porac (Pampanga), Inc. | `ph-rural-bank-of-porac` |
| Rural Bank Of Rosario Inc | `ph-rural-bank-of-rosario` |
| Rural Bank Of Sagay, Inc. | `ph-rural-bank-of-sagay` |
| Rural Bank Of San Leonardo | `ph-rural-bank-of-san-leonardo` |
| Rural Bank Of Sta. Ignacia Inc | `ph-rural-bank-of-sta-ignacia` |
| Seabank Philippines , Inc. | `ph-seabank` |
| Security Bank | `ph-security-bank` |
| SHINHAN BANK | `ph-shinhan` |
| SOUTHEAST COUNTRY BANK, INC. (A RURAL, BANK) | `ph-southeast-country-bank` |
| Standard Chartered | `ph-standard-chartered` |
| Sterling Bank of Asia | `ph-sterling-bank-of-asia` |
| SUMITOMO MITSUI BANKING CORP | `ph-smbc` |
| Sun Savings Bank, Inc. | `ph-sun-savings-bank` |
| Tonik Digital Bank, Inc. | `ph-tonik` |
| Union Bank | `ph-unionbank` |
| Union Digital Bank Inc | `ph-union-digital-bank` |
| United Overseas Bank | `ph-uob` |
| Unobank Inc | `ph-unobank` |
| WealthBank | `ph-wealthbank` |
| Yuanta Savings Bank Philippines, Inc. | `ph-yuanta-savings-bank` |

## Thailand

Banks for `bank-account-th`.

| Bank | `institutionId` |
| - | - |
| Bangkok Bank Public Company Limited | `th-bangkok-bank` |
| Bank for Agriculture and Agricultural Cooperatives | `th-baac` |
| Bank of Ayudhya Public Company Limited | `th-bank-of-ayudhya` |
| CIMB Thai Bank Public Company Limited | `th-cimb-thai` |
| Citibank N.A. | `th-citibank` |
| Government Saving Bank | `th-government-savings-bank` |
| Kasikorn Bank Public Company Limited | `th-kasikorn-bank` |
| Kiatnakin Bank Public Company Limited | `th-kiatnakin-bank` |
| Krung Thai Bank Public Company Limited | `th-krung-thai-bank` |
| Siam Commercial Bank Public Company Limited | `th-siam-commercial-bank` |

## Vietnam

Banks for `bank-account-vn`.

| Bank | `institutionId` |
| - | - |
| An Binh Commercial Joint Stock Bank (AnBinh Bank) | `vn-abbank` |
| Asia Commercial Bank (ACB) | `vn-acb` |
| Bank for Investment and Development of Vietnam Joint Stock Commercial Bank (BIDV) | `vn-bidv` |
| BaoViet Commercial Joint Stock Bank (BaoViet Bank) | `vn-baoviet-bank` |
| Cimb Bank (Vietnam) Limited | `vn-cimb` |
| Global Petro Sole Member Limited Commercial Bank (GPBank) | `vn-gpbank` |
| Ho Chi Minh City Development Joint Stock Commercial Bank (HDBank) | `vn-hdbank` |
| Hong Leong Bank Vietnam | `vn-hong-leong-bank` |
| IM BANK | `vn-im-bank` |
| Indovina Bank | `vn-indovina-bank` |
| Industrial Bank Of Korea Ha Noi Branch | `vn-ibk-hanoi` |
| Joint Stock Commercial Bank for Foreign Trade of Vietnam (Vietcombank) | `vn-vietcombank` |
| Kien Long Commercial Joint Stock Bank (KienLong Bank) | `vn-kienlongbank` |
| Lien Viet Post Joint Stock Commercial Bank (LienViet Bank) | `vn-lienviet-bank` |
| Military Commercial Joint Stock bank (MB) | `vn-mb-bank` |
| Modern Bank of Vietnam (MBV) | `vn-mbv` |
| Nam A Commercial Joint Stock Bank (NamA Bank) | `vn-nam-a-bank` |
| National Citizen Commercial Joint Stock Bank (NCB) | `vn-ncb` |
| Orient Commercial Bank (OCB) | `vn-ocb` |
| Petrolimex Group Commercial Joint Stock Bank (PG Bank) | `vn-pgbank` |
| Public Bank Vietnam Limited (Public Bank) | `vn-public-bank` |
| Saigon - Hanoi Commercial Joint Stock Bank (SHB) | `vn-shb` |
| Saigon Bank for Industry and Trade (SaigonBank) | `vn-saigonbank` |
| Saigon Commercial Bank (SGCB) | `vn-scb` |
| Saigon Thuong Tin Commercial Joint Stock Bank (SacomBank) | `vn-sacombank` |
| Shinhan Bank Vietnam (SHBVN) | `vn-shinhan` |
| Southeast Asia Commercial Joint Stock Bank (SeaBank) | `vn-seabank` |
| TAIPEI FUBON BANK HANOI Branch | `vn-taipei-fubon-hanoi` |
| TAIPEI FUBON BANK HCM Branch | `vn-taipei-fubon-hcm` |
| Tienphong commercial Joint Stock Bank (TienPhong Bank) | `vn-tpbank` |
| United Overseas Bank (Vietnam) Limited | `vn-uob` |
| Viet A Joint Stock Commercial Bank (Viet A Bank) | `vn-viet-a-bank` |
| Viet Capital Joint Stock Commercial Bank (Viet Capital Bank) | `vn-viet-capital-bank` |
| Vietnam Bank for Agriculture and Rural Development (AgriBank) | `vn-agribank` |
| Vietnam Export Import Commercial Joint Stock Bank (EximBank) | `vn-eximbank` |
| Vietnam International Commercial Joint Stock Bank (VIB) | `vn-vib` |
| Vietnam Joint Stock Commercial Bank for Intrustry and Trade (VietinBank) | `vn-vietinbank` |
| Vietnam Maritime Commercial Joint Stock Bank (Maritime Bank) | `vn-maritime-bank` |
| Vietnam Prosperity Joint Stock Commercial Bank (VPBank) | `vn-vpbank` |
| Vietnam Public Joint Stock Commercial Bank (PVcomBank) | `vn-pvcombank` |
| Vietnam Russia Joint Venture Bank (VR Bank) | `vn-vrb` |
| Vietnam Technological and commercial Joint Stock Bank (Techcom Bank) | `vn-techcombank` |
| Vietnam Thuong Tin Commercial Joint Stock Bank (Vietbank) | `vn-vietbank` |
| Vikki Digital Bank (Changed from Dong A) | `vn-vikki-bank` |
| Woori Bank | `vn-woori-bank` |

## Next Steps

<CardGroup>
  <Card title="Quickstart" icon="bolt" href="/offramp/quickstarts/rest-api">
    Use a saved payment method in an offramp order
  </Card>

  <Card title="Create Payment Method" icon="code" href="/offramp/api-reference/payment-methods/create-payment-method">
    Full request and response schema in the API reference
  </Card>
</CardGroup>


# Manage Orders
Source: https://docs.crossmint.com/offramp/guides/manage-orders

Track offramp order status through every phase, handle webhooks, and troubleshoot common issues

After you create an offramp order, you track it from the stablecoin deposit through to the fiat payout arriving in your user's bank account. This guide shows you how to monitor that journey, react to each status correctly, and handle every outcome along the way.

In this guide, you will learn how to:

* Check an order's status and know which fields to watch
* Follow an order through each phase of its lifecycle
* Map each status to the right UI state and next action
* Receive order updates through webhooks instead of polling
* Troubleshoot expired quotes and rejected payouts

## Check Order Status

Fetch an order any time with its `orderId` (see the [Get Order API reference](/offramp/api-reference/get-order) for the complete response schema):

```bash theme={null}
curl -X GET \
  'https://staging.crossmint.com/api/2022-06-09/orders/<ORDER_ID>' \
  -H 'X-API-KEY: <YOUR_SERVER_API_KEY>'
```

The response includes the full order object (see the [Quickstart](/offramp/quickstarts/rest-api) for the full end-to-end flow). The key fields to watch are:

* **`phase`**: the high-level stage of the order
* **`payment.status`**: whether the stablecoin deposit has been received
* **`lineItems[0].delivery.status`**: whether the fiat payout is pending, in transit, completed, or failed
* **`lineItems[0].delivery.rail`**: the payout rail the order routed through, snapshotted once resolved and never changed afterward (see [Payment Schemes](/offramp/payment-methods))
* **`lineItems[0].delivery.completedAt`**: the ISO 8601 timestamp when the payout reached its terminal success signal at the rail; on instant rails (RTP, SEPA Instant, SPEI) this is the real credit-confirmation time, while on delayed rails (ACH, standard SEPA) it reflects settlement and is approximate

If you poll instead of using webhooks, use the [status-handling reference](#status-handling-reference) below to decide when to stop and what to show next.

Below is a full completed-order response with the key fields highlighted:

```json {3,22,27,28,46} theme={null}
{
  "orderId": "d3d1e4d8-1aae-45f1-804a-4ca674215bae",
  "phase": "completed",
  "locale": "en-US",
  "lineItems": [
    {
      "metadata": {
        "name": "USD",
        "description": "United States Dollar",
        "imageUrl": "https://www.crossmint.com/assets/ui/flags/us.svg"
      },
      "quote": {
        "status": "expired",
        "charges": {
          "unit": { "amount": "1", "currency": "usdc" },
          "fees": { "type": "exact", "amount": "0.002", "currency": "usdc" }
        },
        "totalPrice": { "amount": "1", "currency": "usdc" },
        "quantityRange": { "lowerBound": "1", "upperBound": "1" }
      },
      "delivery": {
        "status": "completed",
        "recipient": {
          "locator": "paymentMethodId:fb04b8bb-2bba-47ba-a105-66a93f61d468",
          "paymentMethodId": "fb04b8bb-2bba-47ba-a105-66a93f61d468"
        },
        "rail": "ach-us",
        "completedAt": "2026-06-18T16:07:42.000Z"
      },
      "executionMode": "exact-in",
      "callData": {
        "mode": "exact-in",
        "amount": "1",
        "outFiatCurrency": "usd",
        "effectiveAmount": "0.998"
      },
      "quantity": 1
    }
  ],
  "quote": {
    "status": "expired",
    "quotedAt": "2026-06-18T15:47:51.931Z",
    "expiresAt": "2026-06-18T15:57:51.931Z"
  },
  "payment": {
    "status": "completed",
    "method": "base",
    "currency": "usdc",
    "preparation": {
      "chain": "base",
      "payerAddress": "0x64EC529c6525CeD1Bd565a954a725787E31a89b9"
    },
    "received": {
      "chain": "base",
      "txId": "0xc40255de1c9028d1c6401249f5f4a2815749b284f2325d94d231808c2633b3d8",
      "amount": "1",
      "currency": "usdc"
    },
    "receiptEmail": "user@example.com"
  },
  "legal": {
    "shownBy": "crossmint",
    "requirements": [
      {
        "display": "show-checkbox",
        "type": "crossmint-terms-of-service",
        "url": "https://www.crossmint.com/legal/crossmint-terms-of-service/TRGUSAALLALLALL"
      },
      {
        "display": "show-text",
        "type": "crossmint-privacy-policy",
        "url": "https://www.crossmint.com/legal/crossmint-privacy-policy/ALLALLALLALLALL"
      }
    ]
  }
}
```

<Note>
  A completed order can still show `quote.status: "expired"` because the quote time window closes independently of payment and delivery. By itself, this does not indicate a problem. Rely on `phase`, `payment.status`, and `lineItems[].delivery.status` to determine the order outcome.
</Note>

## Order Lifecycle

The full status model has four phases. Offramp orders start in `payment`, with the quote included inside the order, then move through `delivery` to `completed` when the payout reaches a terminal outcome. The `quote` phase appears if the quote expires before the deposit arrives.

<Frame type="simple">
  <img alt="Offramp order lifecycle showing the happy path (Order created, Deposit received, Payout in progress, Payout completed) and failure paths (quote expired before deposit, payout failed)" />
</Frame>

<Steps>
  <Step title="Payment: waiting for the deposit">
    After the order is created and the quote is locked, the order sits in the `payment` phase until the stablecoin deposit arrives on-chain and is matched by memo.

    ```json theme={null}
    {
      "phase": "payment",
      "payment": { "status": "awaiting-payment" },
      "lineItems": [{ "delivery": { "status": "awaiting-payment" } }]
    }
    ```

    If no deposit arrives before the quote expires, the order returns to the `quote` phase with `payment.status: "requires-quote"`. See [Quote expired](#troubleshooting) below.
  </Step>

  <Step title="Delivery: fiat payout in progress">
    Once the deposit lands, Crossmint converts the stablecoin and initiates the fiat payout. The order moves to the `delivery` phase.

    ```json theme={null}
    {
      "phase": "delivery",
      "payment": {
        "status": "completed",
        "received": {
          "chain": "base-sepolia",
          "txId": "0xc953...a338e85",
          "amount": "1",
          "currency": "usdc"
        }
      },
      "lineItems": [{ "delivery": { "status": "in-progress" } }]
    }
    ```

    <Note>
      Offramp settlement has two asynchronous parts: receiving the stablecoin deposit and completing the fiat payout. After `payment.status` becomes `completed`, the order may remain in `delivery` while the payout is being prepared, processed by the rail, or delayed by weekends and bank holidays. For rail-specific timing, see [Payment Schemes](/offramp/payment-methods).
    </Note>
  </Step>

  <Step title="Completed: terminal state">
    Once the bank transfer completes, the order moves to `completed` with a successful delivery status.

    ```json theme={null}
    {
      "phase": "completed",
      "payment": {
        "status": "completed",
        "received": {
          "chain": "base-sepolia",
          "txId": "0xc953...a338e85",
          "amount": "1",
          "currency": "usdc"
        }
      },
      "lineItems": [{ "delivery": { "status": "completed", "completedAt": "2026-06-18T16:07:42.000Z" } }]
    }
    ```

    `delivery.completedAt` records when the payout reached its terminal success signal at the rail. On instant rails (RTP, SEPA Instant, SPEI) it is the real credit-confirmation time; on delayed rails (ACH, standard SEPA) it reflects settlement and is approximate, not the exact instant the funds were credited.
  </Step>
</Steps>

<Warning>
  `phase: "completed"` means the order is **terminal**, not necessarily successful. Always check `lineItems[0].delivery.status` to determine the outcome: `"completed"` (success) or `"failed"` (see [Bank rejection](#troubleshooting)).
</Warning>

## Order Status Reference

Each field below returns one of a fixed set of values. Expand a field for the full list.

<AccordionGroup>
  <Accordion title="phase">
    | Value | Meaning |
    | :- | :- |
    | `quote` | Quote pending or expired; no deposit has been taken yet |
    | `payment` | Quote locked; waiting for or processing the on-chain stablecoin deposit |
    | `delivery` | Stablecoin deposit received; fiat payout is pending or in progress |
    | `completed` | Terminal. Check `delivery.status` for the outcome |
  </Accordion>

  <Accordion title="payment.status">
    In the standard offramp flow, `payment.status` typically moves through `awaiting-payment`, `in-progress`, and `completed`. The other statuses listed below represent missing setup steps, verification requirements, or payer-wallet conditions.

    | Value | Meaning |
    | :- | :- |
    | `draft` | The order was created with `state: "draft"`. It is a quote preview only and cannot be polled or paid (see [Get an Offramp Quote](/offramp/guides/preview-a-quote)) |
    | `requires-quote` | A new or refreshed quote is needed (for example, the previous quote expired) |
    | `requires-crypto-payer-address` | The payer wallet address has not been set yet |
    | `requires-email` | A receipt email is required before payment can proceed |
    | `requires-kyc` | Identity verification (KYC) is required before payment can proceed |
    | `pending-kyc-review` | KYC submission is under review |
    | `manual-kyc` | KYC requires manual review |
    | `failed-kyc` | KYC verification was rejected |
    | `requires-recipient-verification` | The recipient must complete wallet ownership verification |
    | `awaiting-deposit-instructions` | Deposit instructions are being prepared; wait until the order returns `awaiting-payment` before asking the user to send the deposit |
    | `awaiting-payment` | Quote accepted; waiting for the user to send the stablecoin deposit |
    | `crypto-payer-insufficient-funds` | The payer wallet does not have enough funds for the deposit |
    | `crypto-payer-insufficient-funds-for-gas` | The payer wallet does not have enough native token to pay network gas |
    | `in-progress` | Stablecoin deposit detected; waiting for on-chain confirmations |
    | `completed` | Stablecoin deposit received and matched to the order |
  </Accordion>

  <Accordion title="lineItems[0].delivery.status">
    | Value | Meaning |
    | :- | :- |
    | `draft` | The order is a draft. No payout will run until the order is created for real |
    | `awaiting-payment` | Fiat payout not yet initiated |
    | `in-progress` | Fiat payout initiated; awaiting rail completion |
    | `completed` | Fiat payout completed |
    | `failed` | Payout could not be completed (for example, bank rejected the transfer) |
  </Accordion>

  <Accordion title="Failure reasons">
    When a deposit cannot be processed or a payout fails, the order response may include a structured failure reason:

    * **`payment.failureReason`**: may be present when the deposit cannot be processed. Shape: `{ code, message?, developerMessage? }`.
    * **`lineItems[].delivery.failureReason`**: may be present when the fiat payout fails. Shape: `{ code, message? }`. Possible codes: `transfer-failed`, `insufficient-funds`, `invalid-account`, `payout-unauthorized`, `slippage-tolerance-exceeded`, `payment-refunded`. Branch on `code` — `message` is human-readable copy and not a stable contract.

    <Note>
      Payment failure reasons are returned on the order object. If you need to detect deposit-processing issues before a delivery event fires, refetch the order with the [Get Order API](/offramp/api-reference/get-order) and inspect `payment.status` and `payment.failureReason`.
    </Note>
  </Accordion>
</AccordionGroup>

## Status-Handling Reference

Use this table to decide what to show the user and what action to take:

| `phase` | `payment.status` | `delivery.status` | Meaning | Developer action |
| :- | :- | :- | :- | :- |
| `payment` | `awaiting-payment` | `awaiting-payment` | Waiting for stablecoin deposit | Show deposit instructions |
| `payment` | `in-progress` | `awaiting-payment` | Stablecoin deposit detected; waiting for on-chain confirmations | Show "Payment confirming"; do not ask the user to resend funds |
| `delivery` | `completed` | `awaiting-payment` | Stablecoin deposit received; fiat payout not yet initiated | Show "Payout pending"; do not ask the user to resend funds |
| `delivery` | `completed` | `in-progress` | Stablecoin deposit received; fiat payout awaiting rail completion | Show "Payout on the way"; do not ask the user to resend funds |
| `completed` | `completed` | `completed` | Payout completed successfully | Show "Funds sent" confirmation |
| `completed` | `completed` | `failed` | Payout failed | Check `payment.refunded` for refund details; prompt user to retry with corrected bank details |
| `quote` | `requires-quote` | `awaiting-payment` | Quote expired before deposit | Create a new order with a fresh quote |

<Accordion title="Less common payment statuses">
  These statuses may appear during order setup or when the payer wallet has issues. Use `payment.status` as the key to decide what to show:

  | `payment.status` | Meaning | Developer action |
  | :- | :- | :- |
  | `requires-crypto-payer-address` | Payer wallet address is missing | Provide the payer wallet address, then refetch the order |
  | `requires-email` | Receipt email is required | Collect the email, then refetch the order |
  | `requires-kyc` | Identity verification is required | Send the user through verification before showing deposit instructions |
  | `pending-kyc-review`, `manual-kyc` | Identity verification is under review | Show verification pending and wait for the status to update |
  | `failed-kyc` | Identity verification was rejected | Do not ask the user to send funds; show the verification failure state |
  | `requires-recipient-verification` | Wallet ownership verification is required | Complete recipient verification, then refetch the order |
  | `awaiting-deposit-instructions` | Deposit instructions are being prepared | Wait until the order returns `awaiting-payment` before showing deposit instructions |
  | `crypto-payer-insufficient-funds` | Payer wallet does not have enough stablecoin for the deposit | Ask the user to fund the wallet or use another wallet |
  | `crypto-payer-insufficient-funds-for-gas` | Payer wallet does not have enough native token for gas | Ask the user to add gas or use a wallet with gas sponsorship |

  The two insufficient-funds statuses come from Crossmint's balance check when it prepares the deposit transaction, before anything is signed. Errors raised by the wallet while signing or broadcasting are not reflected on the order, which stays in `awaiting-payment`; handle them in your app, then refetch the order.
</Accordion>

## Webhooks

Instead of polling, subscribe to order events so Crossmint notifies your backend as the order progresses. Configure an endpoint in the <a href="https://www.crossmint.com/console">Crossmint console</a> and subscribe to events using the [Webhooks guide](/payments/advanced/webhooks).

The events relevant to the standard offramp progression are:

| Event | Fires when |
| :- | :- |
| `orders.payment.succeeded` | The on-chain stablecoin deposit is matched to the order |
| `orders.delivery.initiated` | The fiat payout has been initiated |
| `orders.delivery.completed` | The fiat payout has completed |
| `orders.delivery.failed` | The payout could not be completed |

Use these events to drive your UI updates. For example, show the user "payout on the way" when you receive `orders.delivery.initiated` and "funds sent" when you receive `orders.delivery.completed`.

## Troubleshooting

An offramp order spans two independent systems: an on-chain stablecoin deposit and a fiat payout over banking rails. Most orders complete on their own, but a few situations can interrupt the standard flow, most often a quote that expires before the deposit arrives or a payout the bank declines. Both are expected and recoverable. Expand a case below to see how to detect and resolve it.

<AccordionGroup>
  <Accordion title="Quote expired">
    `quote.expiresAt` is the deadline for the deposit to be confirmed on-chain and matched to the order, not merely broadcast. If no deposit has been matched by then, the order returns to the `quote` phase.

    ```json theme={null}
    {
      "phase": "quote",
      "quote": { "status": "expired" },
      "payment": { "status": "requires-quote" },
      "lineItems": [{ "delivery": { "status": "awaiting-payment" } }]
    }
    ```

    The exchange rate is stale. Create a new order to get a fresh quote. Expiry alone does not prove that nothing was sent: if your app already broadcast a transaction, track it by transaction ID rather than asking the user to resend.

    If a deposit is detected before expiry (`payment.status: "in-progress"`) but only confirms afterwards, Crossmint refunds it to the payer wallet instead of paying out at the stale rate. The order completes with `payment.refunded` set, `lineItems[].delivery.status: "failed"`, `failureReason.code: "payment-refunded"`, and an `orders.delivery.failed` webhook. Create a new order to retry.
  </Accordion>

  <Accordion title="Bank rejection">
    If the bank rejects the payout after the stablecoin deposit has been received (for example, invalid account details), the order moves to `completed` with a failed delivery. The buyer deposit is automatically refunded.

    ```json theme={null}
    {
      "phase": "completed",
      "payment": {
        "status": "completed",
        "refunded": { "amount": "1", "currency": "usdc" }
      },
      "lineItems": [
        {
          "delivery": {
            "status": "failed",
            "failureReason": {
              "code": "invalid-account",
              "message": "The payout couldn't be delivered because the destination bank account is invalid or closed. Please check your bank details and try again."
            }
          }
        }
      ]
    }
    ```

    Check `payment.refunded` to confirm the refund details. Listen for `orders.delivery.failed` so you can surface the issue in your app and prompt the user to try again with corrected bank details.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Quickstart" icon="bolt" href="/offramp/quickstarts/rest-api">
    Build the full flow
  </Card>

  <Card title="Launch in Production" icon="rocket" href="/offramp/guides/going-to-production">
    Move from staging to live payouts
  </Card>
</CardGroup>


# Get an Offramp Quote
Source: https://docs.crossmint.com/offramp/guides/preview-a-quote

Estimate the fiat payout and fees before placing an offramp order

Use a draft quote to show users what to expect before converting stablecoins to fiat. You can start from either side of the conversion. For example, enter 300 USDC to see the estimated payout in Mexican pesos, or enter 4,500 MXN to see how much USDC the user would need to send. The quote also includes the applicable fees.

Crossmint does not store a draft, and a draft cannot be paid or turned into an order. Display the quote, then discard the response. When the user proceeds, create a new order.

## Request a Quote

Call [Create Order](/offramp/api-reference/create-order) with `state: "draft"`. The rest of the body is the same as a real order. Use `exact-in` to fix the stablecoin the user sends, or `exact-out` to fix the fiat they receive (see [Send or Receive an Exact Amount](/offramp/guides/send-or-receive-an-exact-amount)). Both code samples pay out in MXN.

<Tabs>
  <Tab title="exact-in">
    The user sends exactly 300 USDC and the quote estimates how many MXN they receive after fees.

    ```bash cURL {5,18-19} theme={null}
    curl -X POST 'https://staging.crossmint.com/api/2022-06-09/orders' \
      -H 'X-API-KEY: <YOUR_SERVER_API_KEY>' \
      -H 'Content-Type: application/json' \
      -d '{
        "state": "draft",
        "recipient": {
          "paymentMethodId": "<PAYMENT_METHOD_ID>"
        },
        "payment": {
          "method": "base-sepolia",
          "currency": "usdc",
          "payerAddress": "<USER_WALLET_ADDRESS>",
          "receiptEmail": "alice@example.com"
        },
        "lineItems": {
          "currencyLocator": "fiat:mxn",
          "executionParameters": {
            "mode": "exact-in",
            "amount": "300"
          }
        }
      }'
    ```
  </Tab>

  <Tab title="exact-out">
    The user wants to receive exactly 4,500 MXN and the quote calculates how much USDC they must send, fees included.

    ```bash cURL {5,18-19} theme={null}
    curl -X POST 'https://staging.crossmint.com/api/2022-06-09/orders' \
      -H 'X-API-KEY: <YOUR_SERVER_API_KEY>' \
      -H 'Content-Type: application/json' \
      -d '{
        "state": "draft",
        "recipient": {
          "paymentMethodId": "<PAYMENT_METHOD_ID>"
        },
        "payment": {
          "method": "base-sepolia",
          "currency": "usdc",
          "payerAddress": "<USER_WALLET_ADDRESS>",
          "receiptEmail": "alice@example.com"
        },
        "lineItems": {
          "currencyLocator": "fiat:mxn",
          "executionParameters": {
            "mode": "exact-out",
            "amount": "4500"
          }
        }
      }'
    ```
  </Tab>
</Tabs>

## Read the Quote

Response excerpts for each mode. The amounts are illustrative.

<Tabs>
  <Tab title="exact-in">
    The user sends 300 USDC, pays 0.24 USDC in fees, and the remaining 299.76 USDC converts into an estimated 5,137.89 MXN (`quantity`).

    ```json Draft response (excerpt) {17,26,39,48} theme={null}
    {
      "order": {
        "orderId": "<ORDER_ID>",
        "phase": "payment",
        "lineItems": [
          {
            "metadata": {
              "name": "MXN",
              "description": "Mexican Peso",
              "imageUrl": "https://www.crossmint.com/assets/ui/flags/mx.svg"
            },
            "quote": {
              "status": "valid",
              "charges": {
                "fees": {
                  "type": "exact",
                  "amount": "0.24",
                  "currency": "usdc"
                }
              },
              "totalPrice": {
                "amount": "300",
                "currency": "usdc"
              }
            },
            "quantity": 5137.89,
            "delivery": {
              "status": "awaiting-payment",
              "recipient": {
                "locator": "paymentMethodId:<PAYMENT_METHOD_ID>",
                "paymentMethodId": "<PAYMENT_METHOD_ID>"
              }
            },
            "executionMode": "exact-in",
            "callData": {
              "mode": "exact-in",
              "amount": "300",
              "outFiatCurrency": "mxn",
              "effectiveAmount": "299.76"
            }
          }
        ],
        "quote": {
          "status": "valid",
          "quotedAt": "2026-09-15T19:16:57.608Z",
          "expiresAt": "2026-09-15T19:26:57.608Z",
          "totalPrice": {
            "amount": "300",
            "currency": "usdc"
          }
        },
        "payment": {
          "status": "requires-crypto-payer-address",
          "method": "base-sepolia",
          "currency": "usdc"
        }
      }
    }
    ```
  </Tab>

  <Tab title="exact-out">
    The user receives exactly 4,500 MXN, which costs 262.54 USDC to convert; 0.21 USDC in fees is added on top, so they send 262.75 USDC (`totalPrice`). Amounts are rounded here; the response keeps full precision.

    ```json Draft response (excerpt) {17,26,39,48} theme={null}
    {
      "order": {
        "orderId": "<ORDER_ID>",
        "phase": "payment",
        "lineItems": [
          {
            "metadata": {
              "name": "MXN",
              "description": "Mexican Peso",
              "imageUrl": "https://www.crossmint.com/assets/ui/flags/mx.svg"
            },
            "quote": {
              "status": "valid",
              "charges": {
                "fees": {
                  "type": "exact",
                  "amount": "0.210035",
                  "currency": "usdc"
                }
              },
              "totalPrice": {
                "amount": "262.753792",
                "currency": "usdc"
              }
            },
            "quantity": 4500,
            "delivery": {
              "status": "awaiting-payment",
              "recipient": {
                "locator": "paymentMethodId:<PAYMENT_METHOD_ID>",
                "paymentMethodId": "<PAYMENT_METHOD_ID>"
              }
            },
            "executionMode": "exact-out",
            "callData": {
              "mode": "exact-out",
              "amount": "4500",
              "outFiatCurrency": "mxn",
              "effectiveAmount": "262.543757"
            }
          }
        ],
        "quote": {
          "status": "valid",
          "quotedAt": "2026-09-15T21:13:28.476Z",
          "expiresAt": "2026-09-15T21:23:28.476Z",
          "totalPrice": {
            "amount": "262.753792",
            "currency": "usdc"
          }
        },
        "payment": {
          "status": "requires-crypto-payer-address",
          "method": "base-sepolia",
          "currency": "usdc"
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Display the Quote

Use these fields to build the quote summary:

| Field | Show the user |
| - | - |
| `quote.totalPrice.amount` | Stablecoin to send, including Crossmint fees |
| `lineItems[0].quote.charges.fees.amount` | Crossmint fees, included in the total |
| `lineItems[0].callData.effectiveAmount` | Stablecoin actually converted, after fees |
| `lineItems[0].quantity` | Estimated fiat payout, expected in the destination account |

## Place the Order

Once the user is ready to continue, discard the draft and send the request again without `state: "draft"`. The draft was only a preview and cannot be reused.

The new order includes a fresh quote and instructions for sending the funds. If the amounts have changed, show the updated quote to the user before continuing.

## Next Steps

<CardGroup>
  <Card title="Manage Orders" icon="list-check" href="/offramp/guides/manage-orders">
    Status, webhooks, and failures
  </Card>

  <Card title="Create Order API" icon="code" href="/offramp/api-reference/create-order">
    Every request and response field
  </Card>
</CardGroup>


# Send or Receive an Exact Amount
Source: https://docs.crossmint.com/offramp/guides/send-or-receive-an-exact-amount

Choose an exact stablecoin amount to send or an exact fiat amount to receive

Use `exact-in` when you know how much stablecoin you want to send. Use `exact-out` when you know how much fiat should reach the bank account. Crossmint calculates the other amount and includes both in the quote.

<Columns>
  <div>
    **Exact-in**

    <Frame type="simple">
      <img alt="Withdraw screen in exact-in mode: the You send card is highlighted with 300 USDC entered, and the You receive card shows the computed 5,061.29 MXN payout" />
    </Frame>
  </div>

  <div>
    **Exact-out**

    <Frame type="simple">
      <img alt="Withdraw screen in exact-out mode: the You receive card is highlighted with 4,500 MXN entered, and the You send card shows the computed 266.73 USDC deposit" />
    </Frame>
  </div>
</Columns>

## Before You Start

Both modes use [Create Order](/offramp/api-reference/create-order). Set `payment.currency` to the stablecoin being sent, such as `"usdc"`, and `lineItems.currencyLocator` to the payout currency, such as `"fiat:mxn"`.

Choose the mode with `lineItems.executionParameters.mode`. Pass `executionParameters.amount` as a decimal string, such as `"300"` or `"4500.50"`. The mode determines its currency and allowed precision:

* `exact-in`: the stablecoin amount to send. Use up to the token's supported decimal places, which is 6 for USDC.
* `exact-out`: the fiat amount to receive. Use up to the currency's minor unit, which is 2 decimal places for MXN, USD, EUR, and COP. For MXN, `"4500.50"` is accepted; `"4500.505"` returns a 400 error.

## Exact-in: Send an Exact Amount

To cash out 300 USDC into MXN, use `exact-in` with an amount of `"300"`:

```json {11,12} theme={null}
{
  "recipient": { "paymentMethodId": "<paymentMethodId>" },
  "payment": {
    "method": "solana",
    "currency": "usdc",
    "payerAddress": "<payerAddress>"
  },
  "lineItems": {
    "currencyLocator": "fiat:mxn",
    "executionParameters": {
      "mode": "exact-in",
      "amount": "300"
    }
  }
}
```

In this example, the quote returns:

```json Quote excerpt {6,9,13} theme={null}
{
  "lineItems": [
    {
      "quote": {
        "charges": {
          "fees": { "amount": "0.24", "currency": "usdc" }
        }
      },
      "quantity": 5061
    }
  ],
  "quote": {
    "totalPrice": { "amount": "300", "currency": "usdc" }
  }
}
```

The payer sends 300 USDC. After the 0.24 USDC fee, 299.76 USDC is converted into 5,061 MXN for the bank account. Fiat payouts are rounded to the currency's minor unit, which is two decimal places for MXN.

## Exact-out: Receive an Exact Amount

To have the bank account receive exactly 4,500 MXN, use `exact-out` with an amount of `"4500"`:

```json {11,12} theme={null}
{
  "recipient": { "paymentMethodId": "<paymentMethodId>" },
  "payment": {
    "method": "solana",
    "currency": "usdc",
    "payerAddress": "<payerAddress>"
  },
  "lineItems": {
    "currencyLocator": "fiat:mxn",
    "executionParameters": {
      "mode": "exact-out",
      "amount": "4500"
    }
  }
}
```

The quote tells you how much USDC to deposit:

```json Quote excerpt {6,9,13} theme={null}
{
  "lineItems": [
    {
      "quote": {
        "charges": {
          "fees": { "amount": "0.2128", "currency": "usdc" }
        }
      },
      "quantity": 4500
    }
  ],
  "quote": {
    "totalPrice": { "amount": "266.2128", "currency": "usdc" }
  }
}
```

The payout requires 266 USDC, plus a 0.2128 USDC fee. The payer deposits 266.2128 USDC, and the bank account receives 4,500 MXN.

Use `quote.totalPrice.amount` to fund the order. In this mode, the `amount` in your request is the fiat payout.

## Reading the Quote

Use these three fields to show the user how much they will send, how much they will receive, and the fee. Paths start inside the `order` object returned by Create Order and [Get Order](/offramp/api-reference/get-order).

* `quote.totalPrice.amount`: stablecoin to send, including the Crossmint fee.
* `lineItems[].quantity`: fiat the bank account will receive, in the payout currency.
* `lineItems[].quote.charges.fees.amount`: the Crossmint fee, in the stablecoin.

`quantity` is a JSON number; the other amounts are strings. Use `quote.totalPrice.amount` for the deposit. The per-unit price in `charges.unit.amount` is rounded, so multiplying it by `quantity` may give a different total.

The prepared transaction represents the deposit in token base units. See the [REST API quickstart](/offramp/quickstarts/rest-api) for how to send it, and the [Create Order reference](/offramp/api-reference/create-order) for the full schema.

## Fees

With `exact-in`, the fee comes out of the deposit. With `exact-out`, it is added to the stablecoin needed for the payout. In both cases, the total deposit already includes the Crossmint fee.

Network gas is separate from the quoted deposit. The payer wallet pays it in the chain's native token unless the transaction is sponsored.

## Rate Lock

The quote locks the exchange rate for about 10 minutes. To keep the quoted amounts, the deposit must be confirmed on-chain before `quote.expiresAt`. If no deposit arrives in time, the order expires and you create a new order to get a fresh quote. If your flow can take longer, such as waiting for user authorization or KYC, create the order only when the payer is ready to deposit.

See [Manage Orders](/offramp/guides/manage-orders#troubleshooting) for expired quotes, including cases where a deposit is already in flight.

## See Also

<CardGroup>
  <Card title="Create Order" icon="code" href="/offramp/api-reference/create-order">
    Request and response fields for creating an offramp order.
  </Card>

  <Card title="Manage Orders" icon="list-check" href="/offramp/guides/manage-orders">
    Track payouts and handle expired quotes or payment issues.
  </Card>
</CardGroup>


# Offramp Orders on Solana
Source: https://docs.crossmint.com/offramp/guides/sign-deposit-solana

Sign and broadcast the deposit transaction for an existing Solana offramp order.

Every offramp order returns a prepared deposit transaction that the payer must sign and broadcast before the order leaves the payment phase. On Solana, that transaction has its own format and a blockhash that can expire, so it can't be sent with the EVM steps in the quickstart. This guide shows how to sign and broadcast it — from a Crossmint wallet or your own Solana keypair — so Crossmint matches the deposit to the order and the payout can proceed.

For the complete offramp lifecycle, see the [REST API Quickstart](/offramp/quickstarts/rest-api).

## Prerequisites

You need:

* **Offramp order:** created with `payment.method: "solana"` via [Create Order](/offramp/api-reference/create-order).
* **Payer wallet:** a Crossmint wallet on `chain: "solana"` with a configured signer, or an external Solana wallet whose public key matches the order's `payment.payerAddress`.
* **Funds:** enough USDC to pay the order and enough SOL to cover the network fee.

## Pay the Order

<Tabs>
  <Tab title="Crossmint wallet">
    The prepared blockhash may expire before the user approves the transaction. To avoid signing an expired transaction, fetch a current blockhash from your server and rebuild the transaction before sending it to the wallet.

    ```tsx theme={null} theme={null}
    import { useWallet, SolanaWallet } from "@crossmint/client-sdk-react-ui";
    import { Transaction } from "@solana/web3.js";
    import bs58 from "bs58";

    type OfframpOrder = {
        orderId: string;
        payment: {
            preparation: {
                serializedTransaction: string;
            };
        };
    };

    export function PayOfframpOrder({ order }: { order: OfframpOrder }) {
        const { wallet } = useWallet();

        async function pay() {
            if (wallet == null) {
                throw new Error("Wallet not ready");
            }

            const prepared = Transaction.from(
                bs58.decode(order.payment.preparation.serializedTransaction),
            );

            const blockhash = await fetch("/api/solana-blockhash").then(
                (response) => response.text(),
            );

            const transaction = new Transaction({
                feePayer: prepared.feePayer,
                recentBlockhash: blockhash,
            });

            transaction.add(...prepared.instructions);

            const { hash } = await SolanaWallet.from(wallet).sendTransaction({
                serializedTransaction: bs58.encode(
                    transaction.serialize({
                        requireAllSignatures: false,
                        verifySignatures: false,
                    }),
                ),
            });

            console.log(`https://explorer.solana.com/tx/${hash}`, order.orderId);
        }

        return <button onClick={pay}>Cash out</button>;
    }
    ```

    This copies every instruction from the prepared transaction while replacing only its blockhash.

    See [Custom Solana Transactions](/wallets/guides/send-transaction-solana) for wallet and signer setup.
  </Tab>

  <Tab title="External wallet">
    Use this flow when you control the payer wallet's keypair. The example verifies the payer, replaces the expiring blockhash, signs the transaction, and broadcasts it through your Solana RPC endpoint. `order` is the response from [Create Order](/offramp/api-reference/create-order) or [Get Order](/offramp/api-reference/get-order).

    ```typescript theme={null} theme={null}
    import {
        Connection,
        Keypair,
        SendTransactionError,
        Transaction,
    } from "@solana/web3.js";
    import bs58 from "bs58";

    const connection = new Connection(
        process.env.SOLANA_RPC_URL!,
        "confirmed",
    );

    const payer = Keypair.fromSecretKey(
        bs58.decode(process.env.SOLANA_PRIVATE_KEY!),
    );

    type OfframpOrder = {
        orderId: string;
        payment: {
            preparation: {
                serializedTransaction: string;
            };
        };
    };

    export async function payOfframpOrder(order: OfframpOrder) {
        const prepared = Transaction.from(
            bs58.decode(order.payment.preparation.serializedTransaction),
        );

        if (prepared.feePayer?.equals(payer.publicKey) !== true) {
            throw new Error(
                `Order expects payer ${prepared.feePayer?.toBase58()}`,
            );
        }

        const { blockhash, lastValidBlockHeight } =
            await connection.getLatestBlockhash("confirmed");

        const transaction = new Transaction({
            feePayer: prepared.feePayer,
            recentBlockhash: blockhash,
        });

        transaction.add(...prepared.instructions);
        transaction.partialSign(payer);

        let signature: string;

        try {
            signature = await connection.sendRawTransaction(
                transaction.serialize(),
            );
        } catch (error) {
            if (error instanceof SendTransactionError) {
                console.error(await error.getLogs(connection));
            }

            throw error;
        }

        await connection.confirmTransaction(
            { signature, blockhash, lastValidBlockHeight },
            "confirmed",
        );

        console.log(
            `https://explorer.solana.com/tx/${signature}`,
            order.orderId,
        );
    }
    ```

    `serializedTransaction` is base58-encoded. If the transaction fails to send, `SendTransactionError.getLogs()` returns the Solana program logs.
  </Tab>
</Tabs>

## Why the Blockhash Must Be Replaced

Solana rejects transactions after their blockhash expires. The prepared transaction's blockhash expires roughly a minute after Crossmint builds it, well before the order's `quote.expiresAt`.

For this reason, do not treat `quote.expiresAt` as the transaction-signing deadline. Fetch a current blockhash immediately before signing.

Replacing the blockhash does not require a new order or quote. Copy the original transaction's fee payer and instructions into a new transaction, then sign it against the current blockhash.

## Confirm the Payout

A confirmed Solana transaction proves that the USDC left the payer's wallet. It does not prove that the fiat payout reached the recipient.

Use [Get Order](/offramp/api-reference/get-order) or subscribe to the webhooks described in [Manage Orders](/offramp/guides/manage-orders).

## Next Steps

<CardGroup>
  <Card title="Manage Orders" icon="list-check" href="/offramp/guides/manage-orders">
    Track order phases, delivery statuses, and webhooks.
  </Card>

  <Card title="Custom Solana Transactions" icon="wallet" href="/wallets/guides/send-transaction-solana">
    Wallet and signer setup per platform.
  </Card>
</CardGroup>


# Overview
Source: https://docs.crossmint.com/offramp/overview

Allow your users to convert stablecoins to fiat currency

Crossmint Offramp lets your users convert stablecoins into fiat and withdraw funds directly to their bank account through a fully white-labeled, native experience inside your app.

The product is delivered through a single API that handles compliance, liquidity, and bank payouts, so you can add cash-out without managing banking relationships or regulatory infrastructure. Embedded widget and SDK support is coming soon.

<Note>**Offramping from a corporate treasury wallet?** See the [Treasury offramps guide](/stablecoin-orchestration/guides/on-off-ramps/withdrawing-from-company-wallets).</Note>

## See It in Action

Try it yourself using the following <a href="https://ramps.demos-crossmint.com/">link</a>.

<video />

## Key Features

<CardGroup>
  <Card title="Native UX" icon="window">
    Seamless in-app experiences
  </Card>

  <Card title="One API, many rails" icon="globe">
    Same API for global access
  </Card>

  <Card title="Bring Your KYC" icon="share-nodes">
    Import user data (optional)
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="Quickstart" icon="bolt" href="/offramp/quickstarts/rest-api" />

  <Card title="Launch in Production" icon="rocket" href="/offramp/guides/going-to-production" />
</CardGroup>

## Guides

<CardGroup>
  <Card title="Import user KYC data" icon="id-card" href="/offramp/guides/import-user-kyc-data">
    KYC Data Imports
  </Card>

  <Card title="Save payment data" icon="building-columns" href="/offramp/guides/collect-bank-accounts">
    Manage Payment Methods
  </Card>

  <Card title="Track order status" icon="list-check" href="/offramp/guides/manage-orders">
    Track order status
  </Card>
</CardGroup>

## FAQs

<AccordionGroup>
  <Accordion title="How do I move to production?">
    Integrating the product on staging is fully self-serve, simply get an API key on the <a href="https://staging.crossmint.com/signin?callbackUrl=/console">staging console</a> and follow the docs.

    Production access requires a signed Order Form and completed KYB verification. <a href="https://www.crossmint.com/contact/sales">Contact sales</a> to get started. See the [account verification documentation](/introduction/platform/account-verification) for details.
  </Accordion>

  <Accordion title="How can I track sales?">
    You can monitor purchases onchain or using webhooks. Sales dashboards, logs, and advanced analytics are also
    available in the console.
  </Accordion>
</AccordionGroup>


# Payment Schemes
Source: https://docs.crossmint.com/offramp/payment-methods

Supported payout rails and geographies for Crossmint Offramp

Crossmint Offramp lets your users convert USDC into fiat and withdraw it to bank accounts across the US, Europe, and Latin America. Here is where each payout rail stands today, how fast funds arrive, and any limits to keep in mind.

<Note>
  Availability in this table describes the bank account, not the payer. At order time, Crossmint can refuse SEPA and SEPA Instant for a payer whose verified country of residence is outside the SEPA area, even when the payment method lists them as supported.
</Note>

| Rail/Scheme | Availability | Settlement | Processing Window (Working Days) | Transaction Limits |
| :- | :- | :- | :- | :- |
| 🇺🇸 **ACH** (USD) | Available | 1 business day | GMT 01:45pm to 08:00pm | \$50,000 per transaction |
| 🇺🇸 **Same-day ACH** (USD) | Available | Same day | GMT 01:45pm to 08:00pm | \$50,000 per transaction |
| 🇺🇸 **RTP** (USD) | Available | Instant | 24/7 | \$1,000,000 per transaction |
| 🇺🇸 **Wire** (USD) | Available | Same day | GMT 01:45pm to 08:00pm | No limit |
| 🇪🇺 **SEPA Instant** (EUR) | Available | Instant | 24/7 | €500,000 per transaction |
| 🇪🇺 **SEPA** (EUR) | Available | 1 to 2 business days | GMT 07:00am to 02:00pm | No limit |
| 🇲🇽 **SPEI** (MXN) | Available | Instant | | |
| 🇨🇴 **Bre-B** (COP) | Available | Instant | 24/7 | COP 12,110,000 (about USD 3,600) per transaction |
| 🇨🇴 **Bank Transfer** (COP) | Available | Minutes to 36 hours (up to 72 hours on weekends and holidays) | Depends on the receiving bank ([see below](#colombia-bank-transfer)) | No limit |
| 🇪🇺 **SWIFT** (EUR) | Q4 | 1 to 5 business days | GMT 07:00am to 02:00pm | No limit |
| 🇬🇧 **Faster Payments** (GBP) | Q4 | Minutes to hours | 24/7 | £1,000,000 per transaction |
| 🇧🇷 **Pix** (BRL) | Q4 | Instant | | |
| Additional rails available upon request | <a href="https://www.crossmint.com/contact/sales">Contact sales</a> | | | |

## Processing Windows by Timezone

The settlement times above apply only when you submit the order within the processing window.

### US (ACH, Same-day ACH, Wire)

| Timezone | Winter (Standard) | Summer (Daylight) |
| :- | :- | :- |
| PT | 05:45am to 12:00pm PST | 06:45am to 01:00pm PDT |
| ET | 08:45am to 03:00pm EST | 09:45am to 04:00pm EDT |

### Europe and UK (SEPA, SWIFT)

| Timezone | Winter (Standard) | Summer (Daylight) |
| :- | :- | :- |
| PT | 11:00pm to 06:00am PST | 12:00am to 07:00am PDT |
| ET | 02:00am to 09:00am EST | 03:00am to 10:00am EDT |

### Colombia (Bank Transfer)

Settlement time depends on the receiving bank. All times are Colombia time (COT), which is GMT-5 all year. COT matches ET in winter and is 1 hour behind ET in summer.

| Receiving bank | Receiving window | Typical settlement |
| :- | :- | :- |
| Bancolombia | 24/7 | Most payouts within 30 minutes |
| Nequi | 24/7 | Most payouts within 5 minutes |
| Coltefinanciera | 24/7 | Most payouts within 5 minutes |
| Banco de Bogotá | Monday to Friday, 06:00 to 20:30 (payouts submitted 20:30 to 03:45 are processed at 04:00) | Most payouts within 45 minutes |
| Coopcentral | Monday to Friday, 08:00 to 17:30 | Most payouts within 30 minutes |
| BBVA | Monday to Friday, 06:00 to 19:00 | Most payouts within 60 minutes |
| Banco de Occidente | Monday to Friday, 08:00 to 21:00 | Most payouts within 60 minutes |
| Banco Popular, Banco AV Villas | Monday to Friday, 08:00 to 17:30 | Most payouts within 2 hours |
| Other banks | Business days, 08:30 to 17:00 | Up to 36 hours (72 hours on weekends and holidays) |

If you submit an order outside the receiving bank's window, the bank processes the payout when that window next opens. The typical settlement time above counts from then.

## Next Steps

<CardGroup>
  <Card title="Quickstart" icon="bolt" href="/offramp/quickstarts/rest-api">
    Build your first offramp end to end
  </Card>

  <Card title="KYC & Compliance" icon="id-card" href="/offramp/concepts/kyc-and-compliance">
    How verification works for offramp
  </Card>
</CardGroup>


# REST API Quickstart
Source: https://docs.crossmint.com/offramp/quickstarts/rest-api

Allow users to offramp stablecoins to fiat

In this guide, you will run a full USDC to USD offramp in the Staging environment. You will:

* Confirm Offramp eligibility
* Save the user's payout method
* Set up the wallet the user pays from
* Create an Offramp order and read its deposit instructions
* Broadcast the deposit and track the order to completion

## Prerequisites

* A **server-side API key** with the `orders` and `payment-methods` scopes (<a href="https://staging.crossmint.com/console">Crossmint console</a>).
* A user **KYC-verified for Offramp**. To verify a user, follow [Import User KYC Data](/offramp/guides/import-user-kyc-data) or the [Identity quickstart](/identity/quickstart). This quickstart uses `userId:<USER_ID>` in examples, but the API accepts any supported `userLocator`.
* **USDC** to cash out. On staging, get testnet USDC from the <a href="https://faucet.circle.com/">Circle faucet</a>.
* **Native gas tokens** in the sender wallet to broadcast the deposit transaction (e.g., ETH on Base, SOL on Solana). This does not apply if the wallet sponsors gas.

<Note>
  Offramp uses Crossmint's user KYC API. <a href="https://www.crossmint.com/contact/sales">Contact sales</a> to enable it for your project.
</Note>

<Frame type="simple">
  <img alt="Offramp quickstart flow: confirm eligibility, save payout method, choose payer wallet, create order, broadcast deposit, track order to completion" />
</Frame>

<Steps>
  <Step title="Confirm Offramp eligibility">
    Before creating an order, confirm that the user is verified for Offramp. Verification is asynchronous. Poll the user's status with the <a href="https://docs.crossmint.com/api-reference/users/get-identity-verification">Get Identity Verification</a> endpoint until the `offramp` eligibility reads `verified`:

    ```bash theme={null}
    curl -X GET 'https://staging.crossmint.com/api/2025-06-09/users/<USER_LOCATOR>/identity-verification' \
      -H 'X-API-KEY: <YOUR_SERVER_API_KEY>'
    ```

    `<USER_LOCATOR>` is the Crossmint user locator for the verified user, for example `userId:<USER_ID>` or `email:<EMAIL>`. See the <a href="https://docs.crossmint.com/api-reference/users/get-identity-verification">Get Identity Verification</a> API reference for all supported locator formats.

    <Accordion title="Example response">
      ```json theme={null}
      {
        "eligibility": [
          { "type": "onramp", "status": "verified" },
          { "type": "onramp-light", "status": "verified" },
          { "type": "offramp", "status": "verified" },
          { "type": "offramp-light", "status": "verified" },
          { "type": "regulated-transfer", "status": "verified" }
        ]
      }
      ```
    </Accordion>
  </Step>

  <Step title="Save the user's payout method">
    Save the user's payout destination as a reusable payment method. The example below saves a US bank account. Sensitive fields are saved securely.

    See the <a href="https://docs.crossmint.com/offramp/api-reference/payment-methods/create-payment-method">Create Payment Method</a> API reference for the full request schema and supported payment method types.

    <Note>Use a bank account number that is unique to your integration. A sample account number shared across integrations can be disabled upstream, after which this request fails for everyone using it.</Note>

    ```bash theme={null}
    curl -X POST 'https://vault.staging.crossmint.com/api/unstable/payment-methods' \
      -H 'X-API-KEY: <YOUR_SERVER_API_KEY>' \
      -H 'Content-Type: application/json' \
      -d '{
        "type": "bank-account-us",
        "userLocator": "<USER_LOCATOR>",
        "bankAccount": {
          "accountNumber": "<ACCOUNT_NUMBER>",
          "routingNumber": "071000013",
          "accountType": "checking",
          "bankName": "Chase",
          "bankAddress": {
            "line1": "420 Montgomery St",
            "city": "San Francisco",
            "stateOrRegion": "CA",
            "postalCode": "94104",
            "country": "US"
          },
          "currency": "usd",
          "country": "US",
          "entityType": "individual",
          "billing": {
            "name": "Alice Smith",
            "phone": "+13055551234",
            "address": {
              "line1": "701 S Miami Ave",
              "city": "Miami",
              "stateOrRegion": "FL",
              "postalCode": "33156",
              "country": "US"
            }
          }
        }
      }'
    ```

    The response returns the saved payment method. Banks expose a masked `accountSuffix` (not `last4`). Save the `paymentMethodId` for the order step.

    <Accordion title="Example response">
      ```json theme={null}
      {
        "paymentMethodId": "d5e5c48a-7dec-44b1-8cf4-4615bf00c8fc",
        "createdAt": "2026-06-17T21:25:56.542Z",
        "updatedAt": "2026-06-17T21:25:56.542Z",
        "type": "bank-account-us",
        "bankAccount": {
          "billing": {
            "name": "Alice Smith",
            "phone": "+13055551234",
            "address": {
              "line1": "701 S Miami Ave",
              "city": "Miami",
              "stateOrRegion": "FL",
              "postalCode": "33156",
              "country": "US"
            }
          },
          "bankName": "Chase",
          "accountSuffix": "<LAST_4_DIGITS>",
          "currency": "usd",
          "country": "US",
          "entityType": "individual",
          "bankAddress": {
            "line1": "420 Montgomery St",
            "city": "San Francisco",
            "stateOrRegion": "CA",
            "postalCode": "94104",
            "country": "US"
          },
          "routingNumber": "071000013",
          "accountType": "checking"
        }
      }
      ```
    </Accordion>

    For listing, updating, and removing saved accounts, see [Manage Payment Methods](/offramp/guides/collect-bank-accounts).
  </Step>

  <Step title="Set up the payer wallet">
    Choose the wallet the user will send USDC from. The payer wallet must belong to the same verified user who owns the payout method.

    <Tabs>
      <Tab title="Crossmint wallet">
        Create a wallet owned by the verified user, with a `server` signer so your backend can sign. Ownership links the wallet to the user, so there is no separate linking step, and deposits are gasless.

        ```typescript theme={null}
        import { createCrossmint, CrossmintWallets } from "@crossmint/wallets-sdk";

        const wallets = CrossmintWallets.from(
          createCrossmint({ apiKey: process.env.CROSSMINT_SERVER_API_KEY })
        );

        const wallet = await wallets.createWallet({
          chain: "base-sepolia",
          owner: "userId:<USER_ID>",                                       // the user you verified
          recoveryMethods: [{ type: "server", secret: process.env.CROSSMINT_SIGNER_SECRET }], // server recovery method
          alias: "offramp-<USER_ID>",                                      // idempotent per (owner, alias)
        });
        ```

        * **`owner`** ties the wallet to the verified user via their locator (e.g., `userId:<USER_ID>`). This ownership means no separate linking step is needed.
        * **`recoveryMethods`** sets a `server` signer as the recovery method, derived from your `CROSSMINT_SIGNER_SECRET` — a secret you generate and keep on your server (the SDK derives the signing key from it locally). See [Server Signer](/wallets/guides/signers/server-signer) to create one.
        * **`alias`** is an optional label that makes the call idempotent, so re-running it with the same owner and alias returns the same wallet.

        For all wallet options, see [Create a Wallet](/wallets/guides/create-wallet). Then fund `wallet.address` with USDC and use it as the payer. No native gas is needed.
      </Tab>

      <Tab title="External wallet">
        Link the user's own wallet to the verified user. Make sure it holds USDC plus a little native gas for the deposit.

        ```bash theme={null}
        curl -X PUT 'https://staging.crossmint.com/api/2025-06-09/users/<USER_LOCATOR>/linked-wallets/<USER_WALLET_ADDRESS>' \
          -H 'X-API-KEY: <YOUR_SERVER_API_KEY>' \
          -H 'Content-Type: application/json' \
          -d '{ "chain": "base-sepolia" }'
        ```

        <Accordion title="Example response">
          ```json theme={null}
          {
            "address": "0xAa266270cf90FEEA9760617d9c7B5083e9f08984",
            "chain": "base-sepolia",
            "type": "external-wallet",
            "ownership": {
              "verified": false,
              "verificationChallenge": "crossmint.com wants you to sign in with your blockchain account..."
            }
          }
          ```
        </Accordion>

        Each wallet links to one user, so use a separate wallet per user. The response returns an ownership challenge; on staging you do not need to sign it to proceed.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Create an offramp order">
    Create the order with the amount of USDC to cash out (`exact-in`), the chain you will pay from, and the saved bank account as the recipient. Use the payer wallet from the previous step as `payerAddress`.

    ```bash theme={null}
    curl -X POST 'https://staging.crossmint.com/api/2022-06-09/orders' \
      -H 'X-API-KEY: <YOUR_SERVER_API_KEY>' \
      -H 'Content-Type: application/json' \
      -d '{
        "recipient": {
          "paymentMethodId": "<PAYMENT_METHOD_ID>"
        },
        "payment": {
          "method": "base-sepolia",
          "currency": "usdc",
          "payerAddress": "<USER_WALLET_ADDRESS>",
          "receiptEmail": "alice@example.com"
        },
        "lineItems": {
          "currencyLocator": "fiat:usd",
          "executionParameters": {
            "mode": "exact-in",
            "amount": "1"
          }
        }
      }'
    ```

    The order comes back in the `payment` phase. Its **deposit instructions** live under `order.payment.preparation`: a ready to broadcast `serializedTransaction` (a USDC transfer that already carries the matching memo in its calldata) and the same memo in `transactionParameters.memo`. Keep the `order.orderId`.

    <Note>
      To pin a specific payout rail, pass `recipient.rail` (for example, `"rail": "rtp"`) alongside `paymentMethodId`. The value must be one of the payment method's `bankAccount.rails.supported` entries, or the order fails with a `rail-not-supported` error whose message includes the current status and supported list. Omit it to use the account's default rail. Once the order routes, it snapshots the chosen rail on `lineItems[].delivery.rail`, which never changes afterward. See [Payment Schemes](/offramp/payment-methods) for the current rail catalog.
    </Note>

    <Accordion title="Example response (201)">
      ```json theme={null}
      {
        "clientSecret": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvcmRlcklkZW50aWZpZXIiOiI0MGY0OTgxMi0xMjNiLTRkMTAtYmRhZS01NjFlNGVkMmI5OTAiLCJjb2xsZWN0aW9uSWQiOiJjMjI0MGQ2Yy00NGM0LTQ1OTMtOGM4Yy1jZDRkYzJiZjE4MzUiLCJpYXQiOjE3ODE3MzI5MzQsImV4cCI6MTc4MTgxOTMzNH0.Na-AHOlge6-pYhpMszvITqe3ry49fk-o66i3gfz9a3I",
        "order": {
          "orderId": "40f49812-123b-4d10-bdae-561e4ed2b990",
          "phase": "payment",
          "locale": "en-US",
          "lineItems": [
            {
              "metadata": {
                "name": "USD",
                "description": "United States Dollar",
                "imageUrl": "https://www.crossmint.com/assets/ui/flags/us.svg"
              },
              "quote": {
                "status": "valid",
                "charges": {
                  "unit": { "amount": "1", "currency": "usdc" },
                  "fees": { "type": "exact", "amount": "0.002", "currency": "usdc" }
                },
                "totalPrice": { "amount": "1", "currency": "usdc" },
                "quantityRange": { "lowerBound": "1", "upperBound": "1" }
              },
              "delivery": {
                "status": "awaiting-payment",
                "recipient": {
                  "locator": "paymentMethodId:d5e5c48a-7dec-44b1-8cf4-4615bf00c8fc",
                  "paymentMethodId": "d5e5c48a-7dec-44b1-8cf4-4615bf00c8fc"
                }
              },
              "executionMode": "exact-in",
              "callData": {
                "mode": "exact-in",
                "amount": "1",
                "outFiatCurrency": "usd",
                "effectiveAmount": "0.998"
              },
              "quantity": 1
            }
          ],
          "quote": {
            "status": "valid",
            "quotedAt": "2026-06-17T21:48:49.059Z",
            "expiresAt": "2026-06-17T21:58:49.059Z",
            "totalPrice": { "amount": "1", "currency": "usdc" }
          },
          "payment": {
            "status": "awaiting-payment",
            "method": "base-sepolia",
            "currency": "usdc",
            "preparation": {
              "chain": "base-sepolia",
              "payerAddress": "0xAa266270cf90FEEA9760617d9c7B5083e9f08984",
              "serializedTransaction": "0x02f9018e83014a348083171dd9837ec1d582c3be94036cbd53842c5426634e7929541ec2318f3dcf7e80b90164a9059cbb000000000000000000000000bd1af733aed9d9f472a15a4ce13f42097bbc9eaa00000000000000000000000000000000000000000000000000000000000f42400a0a2d2d2d2d2d2d424547494e204d454d4f2d2d2d2d2d2d65794a68624763694f694a49557a49314e694973496e523563434936496b705856434a392e65794a756232356a5a534936496a4d774d57566d5a5467344c5755324d6a49744e444d30595330344e4459324c5467774e57517a4e5751345a54466a59694973496d39795a4756795357526c626e52705a6d6c6c63694936496a51775a6a51354f4445794c5445794d3249744e4751784d4331695a47466c4c5455324d5755305a575179596a6b354d434973496d6c68644349364d5463344d54637a4d6a6b794f58302e5a6f6b68766e30626e796a4c734f70754a797a5131666e73465a486b4d36456d3965724c7a6678576443492d2d2d2d2d2d454e44204d454d4f2d2d2d2d2d2dc0",
              "transactionParameters": {
                "amount": "1000000",
                "memo": "------BEGIN MEMO------eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJub25jZSI6IjMwMWVmZTg4LWU2MjItNDM0YS04NDY2LTgwNWQzNWQ4ZTFjYiIsIm9yZGVySWRlbnRpZmllciI6IjQwZjQ5ODEyLTEyM2ItNGQxMC1iZGFlLTU2MWU0ZWQyYjk5MCIsImlhdCI6MTc4MTczMjkyOX0.Zokhvn0bnyjLsOpuJyzQ1fnsFZHkM6Em9erLzfxWdCI------END MEMO------"
              }
            },
            "receiptEmail": "alice@example.com"
          },
          "legal": {
            "shownBy": "crossmint",
            "requirements": [
              { "display": "show-checkbox", "type": "crossmint-terms-of-service", "url": "https://staging.crossmint.com/legal/crossmint-terms-of-service/TRGUSAALLALLALL" },
              { "display": "show-text", "type": "crossmint-privacy-policy", "url": "https://staging.crossmint.com/legal/crossmint-privacy-policy/ALLALLALLALLALL" }
            ]
          }
        }
      }
      ```
    </Accordion>
  </Step>

  <Step title="Broadcast the deposit">
    The order's `payment.preparation.serializedTransaction` is a prepared USDC transfer that already carries the order's memo in its calldata. Sign and broadcast it from the payer wallet. Crossmint matches the deposit to the order by that memo automatically, so no further call is needed. The transfer moves `quote.totalPrice.amount` expressed in token base units, which is what `transactionParameters.amount` shows (`1` USDC is `1000000` at 6 decimals); the payer wallet also needs native token for gas unless the transaction is sponsored.

    <Tabs>
      <Tab title="Crossmint wallet">
        Sign and send it from the wallet you created, using its `server` signer (a gasless transaction):

        ```typescript theme={null}
        import { EVMWallet } from "@crossmint/wallets-sdk";
        import { parseTransaction } from "viem";

        // `wallet` from the setup step, `order` from the create-order step
        await wallet.useSigner({ type: "server", secret: process.env.CROSSMINT_SIGNER_SECRET });

        const { to, data } = parseTransaction(order.payment.preparation.serializedTransaction);
        await EVMWallet.from(wallet).sendTransaction({ to, value: 0n, data });
        ```

        See [Send a Transaction](/wallets/guides/send-transaction-evm) for signer setup and other platforms. To pay from a Solana wallet instead, see [Offramp Orders on Solana](/offramp/guides/sign-deposit-solana); the `parseTransaction` pattern above does not port to Solana.
      </Tab>

      <Tab title="External wallet">
        Sign and broadcast it with the payer's key using <a href="https://viem.sh">viem</a>:

        ```typescript theme={null}
        import { createWalletClient, http, parseTransaction } from "viem";
        import { privateKeyToAccount } from "viem/accounts";
        import { baseSepolia } from "viem/chains";

        const account = privateKeyToAccount(process.env.PAYER_PRIVATE_KEY);
        const walletClient = createWalletClient({ account, chain: baseSepolia, transport: http() });

        // `order` from the create-order step
        const { to, data } = parseTransaction(order.payment.preparation.serializedTransaction);
        const hash = await walletClient.sendTransaction({ to, value: 0n, data });
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Track the order">
    Poll the order until the payout completes, or subscribe to webhooks (see [Manage Orders](/offramp/guides/manage-orders)).

    ```bash theme={null}
    curl -X GET 'https://staging.crossmint.com/api/2022-06-09/orders/<ORDER_ID>' \
      -H 'X-API-KEY: <YOUR_SERVER_API_KEY>'
    ```

    `GET` returns the order flat at the top level (no `order` wrapper and no `clientSecret`, unlike the create response). Watch `phase`, which moves from `payment` to `completed`, along with `payment.status` and `lineItems[0].delivery.status`. When it completes, `payment.received` is populated with the matched on-chain transaction.

    <Accordion title="Example response (completed)">
      ```json theme={null}
      {
        "orderId": "40f49812-123b-4d10-bdae-561e4ed2b990",
        "phase": "completed",
        "locale": "en-US",
        "lineItems": [
          {
            "metadata": {
              "name": "USD",
              "description": "United States Dollar",
              "imageUrl": "https://www.crossmint.com/assets/ui/flags/us.svg"
            },
            "quote": {
              "status": "valid",
              "charges": {
                "unit": { "amount": "1", "currency": "usdc" },
                "fees": { "type": "exact", "amount": "0.002", "currency": "usdc" }
              },
              "totalPrice": { "amount": "1", "currency": "usdc" },
              "quantityRange": { "lowerBound": "1", "upperBound": "1" }
            },
            "delivery": {
              "status": "completed",
              "rail": "ach-same-day",
              "recipient": {
                "locator": "paymentMethodId:d5e5c48a-7dec-44b1-8cf4-4615bf00c8fc",
                "paymentMethodId": "d5e5c48a-7dec-44b1-8cf4-4615bf00c8fc"
              }
            },
            "executionMode": "exact-in",
            "callData": {
              "mode": "exact-in",
              "amount": "1",
              "outFiatCurrency": "usd",
              "effectiveAmount": "0.998"
            },
            "quantity": 1
          }
        ],
        "quote": {
          "status": "valid",
          "quotedAt": "2026-06-17T21:48:49.059Z",
          "expiresAt": "2026-06-17T21:58:49.059Z",
          "totalPrice": { "amount": "1", "currency": "usdc" }
        },
        "payment": {
          "status": "completed",
          "method": "base-sepolia",
          "currency": "usdc",
          "preparation": {
            "chain": "base-sepolia",
            "payerAddress": "0xAa266270cf90FEEA9760617d9c7B5083e9f08984",
            "serializedTransaction": "0x02f9018e83014a348083171dd9837ec1d582c3be94036cbd53842c5426634e7929541ec2318f3dcf7e80b90164a9059cbb000000000000000000000000bd1af733aed9d9f472a15a4ce13f42097bbc9eaa00000000000000000000000000000000000000000000000000000000000f42400a0a2d2d2d2d2d2d424547494e204d454d4f2d2d2d2d2d2d65794a68624763694f694a49557a49314e694973496e523563434936496b705856434a392e65794a756232356a5a534936496a4d774d57566d5a5467344c5755324d6a49744e444d30595330344e4459324c5467774e57517a4e5751345a54466a59694973496d39795a4756795357526c626e52705a6d6c6c63694936496a51775a6a51354f4445794c5445794d3249744e4751784d4331695a47466c4c5455324d5755305a575179596a6b354d434973496d6c68644349364d5463344d54637a4d6a6b794f58302e5a6f6b68766e30626e796a4c734f70754a797a5131666e73465a486b4d36456d3965724c7a6678576443492d2d2d2d2d2d454e44204d454d4f2d2d2d2d2d2dc0",
            "transactionParameters": {
              "amount": "1000000",
              "memo": "------BEGIN MEMO------eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJub25jZSI6IjMwMWVmZTg4LWU2MjItNDM0YS04NDY2LTgwNWQzNWQ4ZTFjYiIsIm9yZGVySWRlbnRpZmllciI6IjQwZjQ5ODEyLTEyM2ItNGQxMC1iZGFlLTU2MWU0ZWQyYjk5MCIsImlhdCI6MTc4MTczMjkyOX0.Zokhvn0bnyjLsOpuJyzQ1fnsFZHkM6Em9erLzfxWdCI------END MEMO------"
            }
          },
          "received": {
            "chain": "base-sepolia",
            "txId": "0xc9537a0e4ee4794101514d30418bd20f09cf66c3ce86b82b0be916489a338e85",
            "amount": "1",
            "currency": "usdc"
          },
          "receiptEmail": "alice@example.com"
        }
      }
      ```
    </Accordion>

    On staging the payout is simulated. To pay out to a bank in production, see [Launch in Production](/offramp/guides/going-to-production).
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Enable KYC for your project">
    Offramp's KYC endpoints are turned on per project. <a href="https://www.crossmint.com/contact/sales">Contact sales</a> to enable KYC for yours. The response `project not configured to support the users KYC endpoints` is the signal to reach out.
  </Accordion>

  <Accordion title="Use a userId locator">
    The user and KYC endpoints expect a `userId:` locator, for example `userId:alice-123`. The `email:` and other locator formats apply to Crossmint auth wallets, so use `userId:` for these endpoints.
  </Accordion>

  <Accordion title="Wait for verification before ordering">
    Verification is asynchronous. Poll `GET /users/{userId}/identity-verification` until the `offramp` eligibility reads `verified`, then create the order.
  </Accordion>

  <Accordion title="Set the Crossmint wallet owner to the verified user">
    Create the payer wallet with `owner: "userId:<the verified user>"`. With no owner it is company-owned, which the order does not accept. A wallet's owner is set once at creation.
  </Accordion>

  <Accordion title="The deposit matches automatically">
    After you broadcast the prepared transaction, Crossmint matches it to the order by its memo, so the deposit is already assigned. You do not need to call `POST /orders/{orderId}/payment`.
  </Accordion>

  <Accordion title="Rail Not Supported">
    If `recipient.rail` is not one of the payment method's `bankAccount.rails.supported` values, order creation fails with a `rail-not-supported` error. The error message text includes the account's current rail status and supported list; refetch the payment method to read those values as structured fields.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Manage Orders" icon="list-check" href="/offramp/guides/manage-orders">
    Status, webhooks, and failures
  </Card>

  <Card title="How It Works" icon="diagram-project" href="/offramp/concepts/how-it-works">
    The end-to-end offramp flow
  </Card>
</CardGroup>


# Create Order
Source: https://docs.crossmint.com/onramp/api-reference/create-order

api-reference/_open-api/OnrampAPIs.json POST /2022-06-09/orders
Creates an onramp order to buy tokens with a card. The order returns a payment intent that the buyer completes to receive tokens in the specified wallet.



# Payment Error Codes
Source: https://docs.crossmint.com/onramp/api-reference/error-codes

Reference of the normalized error categories and codes returned in an Onramp order's payment.failureReason

<Snippet />

## See Also

<CardGroup>
  <Card title="Get Order" icon="brackets-curly" href="/onramp/api-reference/get-order">
    REST endpoint that returns an Onramp order, including `payment.failureReason`
  </Card>

  <Card title="Payment Methods" icon="credit-card" href="/onramp/guides/payment-methods">
    Payment methods available in Onramp and how buyers use them
  </Card>

  <Card title="Supporting Your Customers" icon="headset" href="/payments/headless/guides/supporting-your-customers">
    What to collect from a buyer before escalating a checkout issue to Crossmint
  </Card>

  <Card title="Webhooks" icon="webhook" href="/payments/advanced/webhooks">
    Receive order updates, including declines, server-side
  </Card>
</CardGroup>


# Get Order
Source: https://docs.crossmint.com/onramp/api-reference/get-order

api-reference/_open-api/OnrampAPIs.json GET /2022-06-09/orders/{orderId}
Retrieves an onramp order by its ID to track its progress through KYC, recipient verification, payment, and delivery.



# List Orders
Source: https://docs.crossmint.com/onramp/api-reference/list-orders

api-reference/_open-api/OnrampAPIs.json GET /2022-06-09/orders
Retrieve a paginated list of onramp orders for your project to track purchases through quote, payment, KYC, and delivery.



# Payment Methods
Source: https://docs.crossmint.com/onramp/concepts/payment-methods

Understanding the payment methods available for onramp

Crossmint Onramp lets users buy stablecoins with the payment methods they already have: debit and credit cards, Apple Pay, and Google Pay. This page explains how each method works, where it is available, and why an onramp transaction is different from a token checkout.

## Supported Payment Methods

| Method | Description | Availability |
| :- | :- | :- |
| **Card** | Debit and credit cards (Visa, Mastercard) | All platforms |
| **Apple Pay** | One-click payment with cards stored in Apple Wallet | Safari on macOS and iOS (web), native iOS apps |
| **Google Pay** | One-click payment with cards stored in Google Wallet | Web browsers, Android apps (React Native, Flutter, Kotlin) |

All three methods are selected by the user inside the same embedded checkout component. You control which methods are offered through a single configuration option (`allowedMethods`), and the component only displays the methods that the user's device and browser actually support. For example, Apple Pay is never shown on an Android device, even when it is enabled.

## How Each Method Works

### Card

The user enters their card details directly in the embedded checkout. Card data is captured in a PCI-compliant environment and never touches your servers. Cards are the baseline method: they work on every platform without additional configuration.

### Apple Pay

Apple Pay wraps the user's stored cards behind Face ID, Touch ID, or a device passcode. Instead of typing card details, the user confirms the payment through the native Apple Pay sheet.

Apple requires every web domain that displays the Apple Pay button to be verified with Apple. Crossmint manages the Apple merchant relationship, so you only need to verify your domain once through the Crossmint Console. Native iOS apps do not require domain verification; the Swift SDK supports Apple Pay automatically.

### Google Pay

Google Pay works the same way for cards stored in Google Wallet: the user confirms the payment through the native Google Pay sheet instead of typing card details.

On the web, Google Pay works without additional configuration. Mobile apps require native configuration (permissions and intent declarations) because the payment sheet is rendered by the operating system, and production Android apps must be approved by Google before Google Pay is shown to real users.

## Why Onramp Is Not a Standard Checkout

A standard card payment in a checkout pays for a good or service; the cardholder receives a product, and the transaction ends there. An onramp transaction is different: the user's fiat is converted into stablecoins that are delivered to a wallet. This is a **regulated transfer** — a money movement that must run on licensed infrastructure.

Because of this, every onramp transaction is routed through Crossmint's regulated infrastructure, which handles:

* **Licensing** — Crossmint operates the required licenses, so you do not need your own.
* **Identity verification** — users complete a lightweight KYC once, valid for up to \$1,000 per day. See [User Onboarding](/onramp/introduction/user-onboarding).
* **AML screening and sanctions checks** — every transaction is screened before the stablecoins are delivered.
* **Chargeback liability** — Crossmint assumes liability for fraudulent disputes.

The payment method only changes how the user funds the transaction. Whether they pay with a card, Apple Pay, or Google Pay, the compliance flow and the on-chain delivery are identical.

<Info>
  The user experience differs mainly in friction: Apple Pay and Google Pay skip manual card entry and typically convert better on mobile devices, while cards remain the universal fallback.
</Info>

## Choosing Which Methods to Offer

Offering every method is usually the right default: the checkout only shows what the device supports, so enabling all three costs nothing. Restricting methods makes sense when:

* Your app is native-only on one platform and you want to hide methods that will never appear.
* You have a business reason to route users through a specific method.

## See Also

<CardGroup>
  <Card title="Add Payment Methods" icon="credit-card" href="/onramp/guides/payment-methods">
    Enable Apple Pay, Google Pay, and cards in your integration
  </Card>

  <Card title="User Onboarding" icon="id-card" href="/onramp/introduction/user-onboarding">
    How identity verification works for onramp
  </Card>
</CardGroup>


# Embed the KYC Step in Your App
Source: https://docs.crossmint.com/onramp/guides/decouple-identity-verification

Render the identity verification step in your own view instead of inside the embedded checkout, for more control over when and where verification happens

By default, when an onramp order requires identity verification (KYC), Crossmint collects it inside the embedded checkout component. If you would like more control over when and where the verification step shows up, you can decouple it: create the order via API, read the verification credentials that Crossmint already returns on the order, and render the step yourself with Crossmint's `CrossmintIdentityVerification` component.

This mostly affects where the verification step lives in your UI. You can surface it as its own screen, a modal, or a step in your flow, rather than having it appear inside the checkout iframe. The underlying flow stays Crossmint's, and the credentials on the order are enough to render it.

<Note>
  Crossmint runs the underlying identity verification provider on your behalf, and your application only ever integrates with Crossmint's component.

  If you instead want to run verification with your own UI **and** your own identity verification provider, see the [Identity quickstart](/identity/quickstart) for sharing the resulting KYC data with Crossmint.
</Note>

## How It Works

<Steps>
  <Step title="Create the order and check the payment status">
    Create an onramp order via API. If the buyer needs to verify their identity, it comes back with `payment.status: "requires-kyc"`.
  </Step>

  <Step title="Read the verification credentials from the order">
    The `requires-kyc` response includes `payment.preparation.kyc`, the verification session Crossmint has prepared for this buyer. Pass it through as it comes; its shape depends on the verification flow of the order.
  </Step>

  <Step title="Render the verification step in your own view">
    Pass those credentials to `CrossmintIdentityVerification` and render it wherever you want in your app.
  </Step>

  <Step title="Poll the order until verification resolves">
    Once the buyer finishes verifying, poll the order until the status moves off `requires-kyc`, then continue with payment as usual.
  </Step>
</Steps>

## Prerequisites

Install the Crossmint React SDK, along with the base package that exports the shared types. No provider SDK is needed, since the verification UI is rendered by Crossmint:

<CodeGroup>
  ```bash npm theme={null}
  npm install @crossmint/client-sdk-react-ui @crossmint/client-sdk-base
  ```

  ```bash pnpm theme={null}
  pnpm add @crossmint/client-sdk-react-ui @crossmint/client-sdk-base
  ```

  ```bash yarn theme={null}
  yarn add @crossmint/client-sdk-react-ui @crossmint/client-sdk-base
  ```

  ```bash bun theme={null}
  bun add @crossmint/client-sdk-react-ui @crossmint/client-sdk-base
  ```
</CodeGroup>

<Note>
  The `appearance` prop needs `@crossmint/client-sdk-react-ui` 4.10.0 or later.
</Note>

## Create the Order and Detect the Verification Requirement

Create the order server-side as you normally would (see the [onramp quickstart](/onramp/quickstarts/react)). When the response comes back, inspect `payment.status`. If it is `requires-kyc`, read the credentials from `payment.preparation.kyc`:

```json Example order response theme={null}
{
    "orderIdentifier": "123",
    // ...
    "payment": {
        "method": "card",
        "currency": "usd",
        "status": "requires-kyc",
        "preparation": {
            "kyc": {
                "verificationId": "68e6a9c4f1b2a3d4e5f60718",
                "clientSecret": "YOUR_VERIFICATION_CLIENT_SECRET"
            }
        }
    }
}
```

Pass the `payment.preparation.kyc` object straight to the component as it comes, not the whole order.

<Note>
  If you only want to preview what an order would look like, you can pass `state: "draft"` on creation. A draft order is not persisted and starts no identity verification, so its `payment.status` is `draft` and it cannot be polled or paid: create the order for real (omit `state`, or pass `state: "create"`) and use that order's credentials and `orderId` for the verification step and the polling below.
</Note>

## Render the Verification Step in Your Own View

Instead of letting the checkout collect the verification, render `CrossmintIdentityVerification` yourself with those credentials. You can place it wherever suits your app, such as a dedicated route, a modal, or a step in your onboarding. The component must be rendered inside `CrossmintProvider`:

```tsx components/VerificationStep.tsx theme={null}
"use client";

import { CrossmintIdentityVerification } from "@crossmint/client-sdk-react-ui";
import type { IdentityVerificationAppearance, IdentityVerificationCredentials } from "@crossmint/client-sdk-base";

// The same object you pass to the embedded checkout. See /identity/ui-customization.
const appearance: IdentityVerificationAppearance = {
    variables: {
        colors: { backgroundPrimary: "#FFFFFF", textPrimary: "#00150D", accent: "#0074D9" },
    },
    rules: {
        PrimaryButton: { colors: { background: "#0074D9", text: "#FFFFFF" } },
    },
};

interface VerificationStepProps {
    credentials: IdentityVerificationCredentials;
    onComplete: () => void;
    onCancel: () => void;
}

export function VerificationStep({ credentials, onComplete, onCancel }: VerificationStepProps) {
    return (
        <div className="my-custom-verification-container" style={{ padding: 24, background: "#FFFFFF" }}>
            {/* Your own heading, copy, progress indicator, etc. */}
            <CrossmintIdentityVerification
                credentials={credentials}
                appearance={appearance}
                locale="en-US"
                onReady={() => console.log("Verification UI loaded")}
                onComplete={() => onComplete()}
                onCancel={() => onCancel()}
                onError={({ retriable, reason, message }) => {
                    console.error("Verification error", reason, message);
                    if (!retriable) {
                        // The buyer cannot finish this attempt. Show a terminal state.
                    }
                }}
            />
        </div>
    );
}
```

Since you own the surrounding view, the verification tends to feel more like a native step in your product than something embedded inside the checkout. The component renders a Crossmint-hosted iframe that resizes itself to its content, so your container controls the width and placement, and the height follows the current verification screen. A few rules keep it working:

* **Keep it mounted until `onComplete` or `onCancel`.** The order leaves `requires-kyc` before the flow shows its result screen, so do not unmount the component when the credentials go away.
* **Handle `onCancel`.** The Done button on a blocked screen, and closing the document capture, send it. Without a handler, Done does nothing.
* **Leave 24px around the iframe and no fixed height.** The screens have no outer padding of their own, and a fixed height cuts off the Continue button. See [placing the screens on your page](/identity/ui-customization#place-the-screens-on-your-page).
* **Allow the camera.** The ID document and selfie step uses it. The component already sets `allow="camera"` on the iframe; the browser still asks the user for permission.

### Match Your Theme

`appearance` takes the same object as the embedded checkout's `appearance` prop, so one theme covers both. The KYC screens read light or dark from `variables.colors.backgroundPrimary`. The [identity verification UI customization guide](/identity/ui-customization) lists the settings that apply and the defaults.

### Verification Outcomes

`onComplete` reports one of `verified`, `pending-review`, `pending-manual-review`, `declined`, `expired`, `failed`, or `unknown`. Treat `unknown` as an unresolved outcome rather than a success, and fall back to the order status.

### If you also use the embedded checkout for payment

If the buyer pays through the embedded checkout rather than a fully headless integration, tell the checkout that your application owns the verification step by passing `identityVerificationHandling="external"`. The checkout then renders nothing for verification and keeps polling the order in the background, so it picks the flow back up at the payment step on its own:

```tsx components/OnrampCheckout.tsx theme={null}
"use client";

import { useEffect, useState } from "react";
import {
    CrossmintProvider,
    CrossmintCheckoutProvider,
    CrossmintEmbeddedCheckout,
    useIdentityVerificationCredentials,
} from "@crossmint/client-sdk-react-ui";
import type { IdentityVerificationCredentials } from "@crossmint/client-sdk-base";
import { VerificationStep } from "./VerificationStep";

export function OnrampCheckout({ orderId, clientSecret }: { orderId: string; clientSecret: string }) {
    return (
        <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
            <CrossmintCheckoutProvider>
                <CrossmintEmbeddedCheckout
                    orderId={orderId}
                    clientSecret={clientSecret}
                    identityVerificationHandling="external"
                    payment={{
                        receiptEmail: "YOUR_USER_EMAIL",
                        crypto: { enabled: false },
                        fiat: { enabled: true },
                        defaultMethod: "fiat",
                    }}
                />
                <DecoupledVerification />
            </CrossmintCheckoutProvider>
        </CrossmintProvider>
    );
}

function DecoupledVerification() {
    // The checkout emits order updates to this hook, so the credentials arrive
    // without a second API call. Undefined until verification is required, and
    // undefined again once the order moves on, before the flow shows its result.
    const credentials = useIdentityVerificationCredentials();
    const [activeCredentials, setActiveCredentials] = useState<IdentityVerificationCredentials>();

    useEffect(() => {
        if (credentials != null) {
            setActiveCredentials(credentials);
        }
    }, [credentials]);

    if (activeCredentials == null) {
        return null;
    }

    return (
        <VerificationStep
            credentials={activeCredentials}
            onComplete={() => setActiveCredentials(undefined)}
            onCancel={() => setActiveCredentials(undefined)}
        />
    );
}
```

For an order that does not come from the checkout context, the plain `getIdentityVerificationCredentials(order)` function is also exported from `@crossmint/client-sdk-react-ui`.

<Warning>
  Passing `identityVerificationHandling="external"` without rendering `CrossmintIdentityVerification` leaves the buyer with no way to finish the order. The checkout suppresses the verification step and all of its outcome screens, on the assumption that your application shows them instead.
</Warning>

## Poll the Order Until Verification Resolves

The component callbacks fire when the buyer finishes, but the order status is the source of truth. After `onComplete`, poll the order until `payment.status` moves off `requires-kyc`:

```typescript theme={null}
async function waitForVerification(orderId: string, maxAttempts: number = 60): Promise<string> {
    for (let attempt = 0; attempt < maxAttempts; attempt++) {
        const order = await getOrder(orderId); // GET /2022-06-09/orders/{orderId}
        const status = order.payment?.status;

        if (status !== "requires-kyc") {
            return status; // "awaiting-payment", "manual-kyc", "failed-kyc", ...
        }

        await new Promise((r) => setTimeout(r, 2000));
    }

    throw new Error("Verification did not resolve within the expected time");
}
```

Verification usually resolves within 15 seconds, so the loop above is generous on purpose: it allows for about two minutes before giving up. Adjust `maxAttempts` or add your own deadline to fit your UX. If you use the embedded checkout with `identityVerificationHandling="external"`, the checkout already polls for you, and `useCrossmintCheckout` returns a fresh order instead.

The resulting status tells you what to do next:

| Status | Meaning | What to do |
| :- | :- | :- |
| `awaiting-payment` | Verification passed and the order is ready to be paid | Continue to the payment step (embedded component or headless API). |
| `pending-kyc-review` | The submission is being reviewed | Show a pending state and keep polling. |
| `manual-kyc` | Verification needs manual review | Show a "Crossmint is reviewing your identity" state. The buyer is notified of the outcome. |
| `failed-kyc` | Verification failed | The buyer cannot proceed with this order. Show a terminal state. |

Because the checkout suppresses its own verification screens when your application owns the step, the pending, review, and rejected states are yours to render as well.

<Note>
  See the [Status Codes](/payments/headless/guides/status-codes) page for the authoritative list of order statuses.
</Note>

## Continue with Payment

Once the order reaches `awaiting-payment`, continue as you would in the standard flow, rendering the embedded checkout for payment or driving it yourself if you are fully headless. Decoupling verification only affects that step; the rest of the order lifecycle stays the same.

## Next Steps

<CardGroup>
  <Card title="User Onboarding and KYC" icon="id-card" href="/onramp/introduction/user-onboarding" />

  <Card title="Identity Verification UI Customization" icon="palette" href="/identity/ui-customization" />
</CardGroup>


# Get an Onramp Quote
Source: https://docs.crossmint.com/onramp/guides/get-a-quote

Estimate the stablecoin amount and fees before placing an onramp order

Use a draft quote to show users what to expect before they buy stablecoins with a card. For example, enter 100 USD to see roughly how much USDC the user receives after fees.

Crossmint does not store a draft, and a draft cannot be paid or turned into an order. A draft also starts no identity verification. Display the quote, then discard the response. When the user proceeds, create a new order.

## Request a Quote

Call [Create Order](/onramp/api-reference/create-order) with `state: "draft"`. The rest of the body is the same as a real order. The code sample buys USDC on Base Sepolia with exactly 100 USD.

```bash cURL {5} theme={null}
curl -X POST 'https://staging.crossmint.com/api/2022-06-09/orders' \
  -H 'X-API-KEY: <YOUR_SERVER_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "state": "draft",
    "recipient": {
      "walletAddress": "<USER_WALLET_ADDRESS>"
    },
    "payment": {
      "method": "card",
      "receiptEmail": "alice@example.com"
    },
    "lineItems": [
      {
        "tokenLocator": "base-sepolia:0x036CbD53842c5426634e7929541eC2318f3dCF7e",
        "executionParameters": {
          "mode": "exact-in",
          "amount": "100"
        }
      }
    ]
  }'
```

## Read the Quote

The user is charged 100 USD in total and receives between 96.50 and 97.50 USDC (`quantityRange`). Part of the fee depends on the card the user pays with, so a draft returns a range rather than an exact amount and does not break fees down. The amounts are illustrative.

```json Draft response (excerpt) {21,24-27,46} theme={null}
{
  "order": {
    "orderId": "<ORDER_ID>",
    "phase": "payment",
    "lineItems": [
      {
        "chain": "base-sepolia",
        "metadata": {
          "name": "USDC",
          "description": "USDC Token"
        },
        "quote": {
          "status": "valid",
          "charges": {
            "unit": {
              "amount": "1",
              "currency": "usd"
            }
          },
          "totalPrice": {
            "amount": "100",
            "currency": "usd"
          },
          "quantityRange": {
            "lowerBound": "96.500000",
            "upperBound": "97.500000"
          }
        },
        "delivery": {
          "status": "awaiting-payment",
          "recipient": {
            "locator": "base-sepolia:<USER_WALLET_ADDRESS>",
            "walletAddress": "<USER_WALLET_ADDRESS>"
          }
        },
        "executionMode": "exact-in",
        "executionParams": {
          "mode": "exact-in",
          "amount": "100"
        }
      }
    ],
    "quote": {
      "status": "valid",
      "quotedAt": "2026-09-22T12:55:01.803Z",
      "expiresAt": "2026-09-22T13:25:01.803Z",
      "totalPrice": {
        "amount": "100",
        "currency": "usd"
      }
    }
  }
}
```

## Display the Quote

Use these fields to build the quote summary:

| Field | Show the user |
| - | - |
| `quote.totalPrice.amount` | Fiat charged to the card, all fees included |
| `lineItems[0].quote.quantityRange` | Lowest and highest stablecoin amount the user can expect to receive |
| `lineItems[0].quote.charges.unit.amount` | Fiat price of one unit of the stablecoin |
| `lineItems[0].quote.charges.gas.amount` | Gas paid on the destination chain, when applicable |
| `lineItems[0].quote.charges.networkFee.amount` | Network fee such as Solana account creation, when applicable |
| `quote.expiresAt` | When the quoted price stops being valid |

`gas` and `networkFee` only appear when they are not zero. Once the user enters card details on the real order, the quote resolves to an exact amount: `quantityRange` collapses to a single value and `charges.crossmintFees` lists the Crossmint fee included in the total.

## Place the Order

Once the user is ready to continue, discard the draft and send the request again without `state: "draft"`. The draft was only a preview and cannot be reused.

The new order includes a fresh quote and a `clientSecret` for the embedded checkout. If the amounts have changed, show the updated quote to the user before continuing.

## Next Steps

<CardGroup>
  <Card title="React Quickstart" icon="bolt" href="/onramp/quickstarts/react">
    Create the order and render the checkout
  </Card>

  <Card title="Create Order API" icon="code" href="/onramp/api-reference/create-order">
    Every request and response field
  </Card>
</CardGroup>


# Import User KYC Data
Source: https://docs.crossmint.com/onramp/guides/import-user-kyc-data

Use existing KYC data for faster onboarding

If you already verify users with an identity verification (IDV) provider like Sumsub or Persona, you can send that data to Crossmint before creating an onramp order. When the data is complete, users can skip in-checkout identity verification.

If you prefer to have individual users provide their KYC data client-side, Crossmint supports that as well. See the [React Quickstart](/onramp/quickstarts/react) for that approach.

## How It Works

1. Verify the user with your IDV provider
2. Have the user accept Crossmint's <a href="https://www.crossmint.com/legal/privacy-policy">Privacy Policy</a>
3. [Register the user's identity data](/identity/quickstart) with Crossmint and trigger verification
4. Create an onramp order to the wallet linked to that user
5. Crossmint runs sanctions, Politically Exposed Persons (PEP), and compliance checks
6. The user completes payment

## Register and Verify the User

User registration, KYC data, document uploads, and identity verification are managed by the identity APIs. Follow the [Identity Quickstart](/identity/quickstart) to:

* Record the user's privacy-policy acceptance (consent must be collected following the requirements in [Register User Data](/identity/register-user-data))
* Register the user's details and KYC data
* Upload any required documents
* Trigger identity verification and poll until the `onramp` eligibility reads `verified`

The exact fields required vary by region and KYC tier. See [Data Requirements](/identity/data-requirements) for the full list, and [User Onboarding and KYC](/onramp/introduction/user-onboarding) for how the onramp KYC tiers work.

## Create an Onramp Order

Once the user is registered with their KYC data, you can create an onramp order. The order will use the registered KYC data for compliance checks.

<Warning>
  **Important**: Crossmint links pre-registered KYC data to an order using the user's email address. The `payment.receiptEmail` value must match the email used in `kycData.email` when registering the user's KYC data with the [Create User API](/api-reference/users/upsert-user).
</Warning>

<CodeGroup>
  ```js Node.js theme={null}
  const options = {
      method: 'POST',
      headers: {
          'X-API-KEY': 'YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      body: JSON.stringify({
          recipient: {
              walletAddress: "YOUR_WALLET_ADDRESS"
          },
          payment: {
              method: "card",
              receiptEmail: "YOUR_USER_EMAIL"
          },
          lineItems: [
              {
                  tokenLocator: "base-sepolia:0x036CbD53842c5426634e7929541eC2318f3dCF7e",
                  executionParameters: {
                      mode: "exact-in",
                      amount: "1"
                  }
              }
          ]
      })
  };

  fetch('https://staging.crossmint.com/api/2022-06-09/orders', options)
      .then(response => response.json())
      .then(response => console.log(response))
      .catch(err => console.error(err));
  ```

  ```bash cURL theme={null}
  curl --request POST \
      --url https://staging.crossmint.com/api/2022-06-09/orders \
      --header 'X-API-KEY: YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
          "recipient": {
              "walletAddress": "YOUR_WALLET_ADDRESS"
          },
          "payment": {
              "method": "card",
              "receiptEmail": "YOUR_USER_EMAIL"
          },
          "lineItems": [
              {
                  "tokenLocator": "base-sepolia:0x036CbD53842c5426634e7929541eC2318f3dCF7e",
                  "executionParameters": {
                      "mode": "exact-in",
                      "amount": "1"
                  }
              }
          ]
      }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://staging.crossmint.com/api/2022-06-09/orders"

  payload = {
      "recipient": {
          "walletAddress": "YOUR_WALLET_ADDRESS"
      },
      "payment": {
          "method": "card",
          "receiptEmail": "YOUR_USER_EMAIL"
      },
      "lineItems": [
          {
              "tokenLocator": "base-sepolia:0x036CbD53842c5426634e7929541eC2318f3dCF7e",
              "executionParameters": {
                  "mode": "exact-in",
                  "amount": "1"
              }
          }
      ]
  }
  headers = {
      "X-API-KEY": "YOUR_API_KEY",
      "Content-Type": "application/json"
  }

  response = requests.post(url, json=payload, headers=headers)

  print(response.json())
  ```
</CodeGroup>

<Info>
  The `lineItems` field accepts either a single object or an array. The examples above use an array for consistency, but you can also pass a single line item object directly.
</Info>

## Order Responses

<AccordionGroup>
  <Accordion title="Success: Full KYC Data Present">
    When all required KYC data has been provided and validated, the order moves to the payment phase:

    ```json theme={null}
    {
      "clientSecret": "...",
      "order": {
        "orderId": "987e81ab-8c8f-464e-95e9-11ceda80d559",
        "phase": "payment",
        "locale": "en-US",
        "lineItems": [...],
        "quote": {...},
        "payment": {
          "method": "card",
          "currency": "usd",
          "status": "awaiting-payment"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Success: Additional KYC Inquiry">
    When full KYC data is present but Crossmint needs to run additional compliance checks, the order enters a processing state. This typically resolves within a few seconds as Crossmint runs the appropriate checks:

    ```json theme={null}
    {
      "clientSecret": "...",
      "order": {
        "orderId": "987e81ab-8c8f-464e-95e9-11ceda80d559",
        "phase": "payment",
        "locale": "en-US",
        "lineItems": [...],
        "quote": {...},
        "payment": {
          "method": "card",
          "currency": "usd",
          "status": "pending-kyc-review"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Error: Missing KYC Data">
    If no user personal data is provided, or if the data is insufficient, the order will fail:

    ```json theme={null}
    {
      "error": true,
      "message": "Required full KYC user data is missing to complete the order"
    }
    ```
  </Accordion>
</AccordionGroup>

## Guides

<CardGroup>
  <Card title="Identity Quickstart" icon="bolt" href="/identity/quickstart" />

  <Card title="Data Requirements" icon="list-check" href="/identity/data-requirements" />
</CardGroup>


# Local Currencies
Source: https://docs.crossmint.com/onramp/guides/local-currencies

Charge users in their local currency by creating the onramp order in USD or EUR

This guide covers how to charge your users in their local currency. When you create an order with a local currency, the quote, the checkout, and the card charge are all denominated in the selected currency.

## Available Currencies

| Currency | Code | Availability |
| :- | :- | :-: |
| USD | `usd` | ✅ |
| EUR | `eur` | ✅ |
| GBP | `gbp` | ✱ |
| AUD | `aud` | ✱ |
| COP | `cop` | ✱ |

<p><em>\*EUR, GBP, AUD, and COP are not available for US residents.</em></p>

**Legend:**

* `✅` Supported
* `✱` Available, but not self-serve. <a href="https://www.crossmint.com/contact/sales">Contact us</a> to request it for your project.

<Note>
  If you are interested in a local currency that is not listed, <a href="https://www.crossmint.com/contact/sales">contact Crossmint</a> to confirm support.
</Note>

## Create the Order in the Selected Currency

From your server, pass the selected currency in `payment.currency`. With `exact-in`, `amount` is expressed in the payment currency, so `"100"` with `"currency": "eur"` means 100 EUR.

<Tip>
  **Recommended:** pre-select the default currency from the user's country of residence if your app already knows it, or from their IP address otherwise, and add a currency selector to your UI so the user can change it.
</Tip>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
      --url https://staging.crossmint.com/api/2022-06-09/orders \
      --header 'Content-Type: application/json' \
      --header 'X-API-KEY: YOUR_SERVER_API_KEY' \
      --data '{
          "recipient": { "walletAddress": "USER_WALLET_ADDRESS" },
          "lineItems": [{
              "tokenLocator": "base-sepolia:0x036CbD53842c5426634e7929541eC2318f3dCF7e",
              "executionParameters": { "mode": "exact-in", "amount": "100" }
          }],
          "payment": {
              "method": "card",
              "currency": "eur",
              "receiptEmail": "user@example.com"
          }
      }'
  ```

  ```js Node.js theme={null}
  const response = await fetch("https://staging.crossmint.com/api/2022-06-09/orders", {
      method: "POST",
      headers: {
          "X-API-KEY": "YOUR_SERVER_API_KEY",
          "Content-Type": "application/json",
      },
      body: JSON.stringify({
          recipient: { walletAddress: "USER_WALLET_ADDRESS" },
          lineItems: [
              {
                  tokenLocator: "base-sepolia:0x036CbD53842c5426634e7929541eC2318f3dCF7e",
                  executionParameters: { mode: "exact-in", amount: "100" },
              },
          ],
          payment: {
              method: "card",
              currency: "eur",
              receiptEmail: "user@example.com",
          },
      }),
  });
  const { order, clientSecret } = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://staging.crossmint.com/api/2022-06-09/orders",
      headers={"X-API-KEY": "YOUR_SERVER_API_KEY", "Content-Type": "application/json"},
      json={
          "recipient": {"walletAddress": "USER_WALLET_ADDRESS"},
          "lineItems": [
              {
                  "tokenLocator": "base-sepolia:0x036CbD53842c5426634e7929541eC2318f3dCF7e",
                  "executionParameters": {"mode": "exact-in", "amount": "100"},
              }
          ],
          "payment": {"method": "card", "currency": "eur", "receiptEmail": "user@example.com"},
      },
  )
  print(response.json())
  ```
</CodeGroup>

The response contains `order.payment.currency: "eur"` and a quote priced in EUR, for example `order.quote.totalPrice: { "amount": "100", "currency": "eur" }`. The amount of stablecoin the user receives is in `order.lineItems[0].quote.quantityRange`.

If the user changes the currency after the order exists, update it from your server with a `PATCH` to `/api/2022-06-09/orders/{orderId}` and the new `payment.currency`, authenticated with your server-side API key. See [Edit Order](/api-reference/headless/edit-order).

<Note>
  Onramp orders cannot be updated from the client side. Update requests authenticated with the order `clientSecret` are rejected. Use your server-side API key.
</Note>

## Render the Checkout in the Same Currency

Set `payment.fiat.defaultCurrency` on the checkout component to the currency you used to create the order. The checkout compares this value with the order currency and, if they differ, tries to update the order to match `defaultCurrency`. Because onramp orders cannot be updated from the client side, that request fails and the checkout shows an error to the user. The SDK default is `usd`, so always set it explicitly on a EUR order.

<Tabs>
  <Tab title="React">
    ```tsx theme={null}
    <CrossmintEmbeddedCheckout
        orderId={order.orderId}
        clientSecret={clientSecret}
        payment={{
            crypto: { enabled: false },
            fiat: {
                enabled: true,
                defaultCurrency: "eur",
                allowedMethods: { card: true, applePay: true, googlePay: true },
            },
        }}
    />
    ```
  </Tab>

  <Tab title="React Native">
    ```tsx theme={null}
    <CrossmintEmbeddedCheckout
        orderId={order.orderId}
        clientSecret={clientSecret}
        payment={{
            crypto: { enabled: false },
            fiat: {
                enabled: true,
                defaultCurrency: "eur",
                allowedMethods: { card: true, applePay: true, googlePay: true },
            },
        }}
    />
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    CheckoutPayment(
        crypto: CheckoutCryptoPayment(enabled: false),
        fiat: CheckoutFiatPayment(
            enabled: true,
            defaultCurrency: "eur",
            allowedMethods: CheckoutAllowedMethods(card: true, applePay: true)
        )
    )
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    CheckoutPayment(
        crypto = CheckoutCryptoPayment(enabled = false),
        fiat = CheckoutFiatPayment(
            enabled = true,
            defaultCurrency = "eur",
            allowedMethods = CheckoutAllowedMethods(card = true, googlePay = true)
        )
    )
    ```
  </Tab>
</Tabs>

## Verify the Currency

Fetch the order with [Get Order](/onramp/api-reference/get-order) and confirm that `payment.currency` and `quote.totalPrice.currency` are both `"eur"`. In the checkout, the price and the card charge are shown in EUR.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The checkout shows an error right after loading">
    `payment.fiat.defaultCurrency` on the checkout component does not match the currency of the order. The checkout tries to update the order from the client side, which is not allowed for onramp orders. Pass the same value you used in `payment.currency` when creating the order.
  </Accordion>

  <Accordion title="Order update fails with 'cannot be updated from client side auth'">
    You are updating an onramp order with the order `clientSecret`. Send the `PATCH` from your server with your server-side API key.
  </Accordion>

  <Accordion title="Order creation fails with payments:payment-currency.not-supported">
    The currency is not enabled for your project. The error response lists the currencies you can use in `parameters.supportedCurrencies`. To enable a non-self-serve currency (`gbp`, `aud`, `cop`), <a href="https://www.crossmint.com/contact/sales">contact Crossmint</a>.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Add Payment Methods" icon="credit-card" href="/onramp/guides/payment-methods">
    Enable cards, Apple Pay, and Google Pay for onramp
  </Card>

  <Card title="Import User KYC Data" icon="id-card" href="/onramp/guides/import-user-kyc-data">
    Reuse the country of residence you already collected
  </Card>

  <Card title="Create Order" icon="code" href="/onramp/api-reference/create-order">
    Full reference for the onramp order payload
  </Card>
</CardGroup>


# Onramp to Non-Crossmint Wallets
Source: https://docs.crossmint.com/onramp/guides/onramp-to-external-wallets

Enable onramp orders to wallets not powered by Crossmint

This guide walks you through how to enable onramp orders to external wallets.

<Note>
  **Internal vs. external wallets:** When you create a Crossmint wallet for a user, set the [`owner`](/wallets/guides/create-wallet) to that user's locator so the wallet is recognized as theirs — onramps to those wallets do not require ownership verification. A wallet created without an `owner`, or any wallet not created through Crossmint, is treated as **external**: you must link it to the user and verify ownership, as shown below.
</Note>

## When Is Proof of Ownership Required?

Proof of ownership confirms that an onramp user controls the wallet receiving their assets. It helps Crossmint meet anti-money laundering (AML) and counter-terrorism financing (CTF) requirements by linking the user's verified identity to the recipient wallet.

Proof of ownership is triggered based on transaction volume thresholds:

| Condition | Verification Required? |
| :- | :- |
| Transaction below **\$1,000** AND 30-day volume below **\$1,000** | No |
| Transaction above **\$1,000** OR 30-day volume above **\$1,000** | Yes |

<Note>
  These thresholds apply to users verified outside the United States who onramp to external wallets.
</Note>

To link the user's identity to an external wallet, Crossmint asks the user to sign a challenge with the recipient wallet and submit the signature in the `proof` field. This flow works the same across chains and for all wallet types, including externally owned accounts (EOAs) and smart contract wallets.

## Integration Steps

<Steps>
  <Step title="Link External Wallet to Crossmint User">
    Before creating an onramp order to an external wallet, you must link the wallet to a Crossmint user (Crossmint creates the user automatically if the locator does not exist yet), using the Link External Wallet API:

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request PUT \
          --url https://staging.crossmint.com/api/2025-06-09/users/{userLocator}/linked-wallets/{address} \
          --header 'X-API-KEY: <x-api-key>' \
          --header 'Content-Type: application/json' \
          --data '{
              "chain": "base-sepolia",
              "proof": "<signature>"
          }'
      ```

      ```js Node.js theme={null}
      const options = {
          method: 'PUT',
          headers: {
              'X-API-KEY': '<x-api-key>',
              'Content-Type': 'application/json'
          },
          body: JSON.stringify({
              chain: "base-sepolia",
              proof: "<signature>"
          })
      };

      const userLocator = "email:user@example.com";
      const walletAddress = "0x1234567890abcdef1234567890abcdef12345678";

      fetch(`https://staging.crossmint.com/api/2025-06-09/users/${userLocator}/linked-wallets/${walletAddress}`, options)
          .then(response => response.json())
          .then(response => console.log(response))
          .catch(err => console.error(err));
      ```
    </CodeGroup>

    The `proof` field is optional:

    * If you omit it, you are simply linking the external wallet to the user without proving ownership yet.
    * If you pass it, you prove ownership of the wallet in the same request.

    When linking without proof, the API responds with a verification challenge:

    ```json theme={null}
    {
        "address": "0x1234567890abcdef1234567890abcdef12345678",
        "chain": "base-sepolia",
        "type": "external-wallet",
        "ownership": {
            "verified": false,
            "verificationChallenge": "crossmint.com wants you to sign in with your blockchain account:\n0x1234...5678\n\nI am signing this message to prove ownership of my wallet address 0x1234...5678 for Crossmint verification.\n\nURI: https://..."
        }
    }
    ```

    The `verificationChallenge` is a message in the <a href="https://chainagnostic.org/CAIPs/caip-122">CAIP-122</a> format for the recipient wallet to sign. CAIP-122 defines only the message format; all wallets, including externally owned accounts (EOAs) and smart contract wallets, use the same verification flow.
  </Step>

  <Step title="Create Onramp Order">
    Create an onramp order using the [Create Order API](/api-reference/headless/create-order) with the linked external wallet address as the recipient.

    <Note>
      Depending on the transaction value and the user's past activity, the order may require wallet ownership verification (steps 3 and 4). If verification is not required, the order proceeds directly to the KYC/payment phase and you can skip to step 5.
    </Note>

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request POST \
          --url https://staging.crossmint.com/api/2022-06-09/orders \
          --header 'X-API-KEY: <x-api-key>' \
          --header 'Content-Type: application/json' \
          --data '{
              "recipient": {
                  "walletAddress": "0x1234567890abcdef1234567890abcdef12345678"
              },
              "payment": {
                  "method": "card",
                  "receiptEmail": "user@example.com"
              },
              "lineItems": [
                  {
                      "tokenLocator": "base-sepolia:0x036CbD53842c5426634e7929541eC2318f3dCF7e",
                      "executionParameters": {
                          "mode": "exact-in",
                          "amount": "10"
                      }
                  }
              ]
          }'
      ```

      ```js Node.js theme={null}
      const options = {
          method: 'POST',
          headers: {
              'X-API-KEY': '<x-api-key>',
              'Content-Type': 'application/json'
          },
          body: JSON.stringify({
              recipient: {
                  walletAddress: "0x1234567890abcdef1234567890abcdef12345678"
              },
              payment: {
                  method: "card",
                  receiptEmail: "user@example.com"
              },
              lineItems: [
                  {
                      tokenLocator: "base-sepolia:0x036CbD53842c5426634e7929541eC2318f3dCF7e",
                      executionParameters: {
                          mode: "exact-in",
                          amount: "10"
                      }
                  }
              ]
          })
      };

      fetch('https://staging.crossmint.com/api/2022-06-09/orders', options)
          .then(response => response.json())
          .then(response => console.log(response))
          .catch(err => console.error(err));
      ```
    </CodeGroup>

    The order may or may not require wallet ownership verification:

    * **Below threshold**: If the transaction value is below **\$1,000** **and** the user's past 30-day onramp transaction volume is below **\$1,000**, ownership verification is not required. The order proceeds directly to the KYC/payment phase.
    * **Above threshold**: If either threshold is surpassed, the order status will be `requires-recipient-verification` and the user must sign a message to prove wallet ownership (steps 3 and 4).

    When ownership verification is required, the order response will look like this:

    ```json theme={null}
    {
        "clientSecret": "...",
        "order": {
            "orderId": "987e81ab-8c8f-464e-95e9-11ceda80d559",
            "phase": "payment",
            "lineItems": [...],
            "quote": {...},
            "payment": {
                "status": "requires-recipient-verification",
                "method": "card",
                "currency": "usd",
                "preparation": {
                    "message": "crossmint.com wants you to sign in with your blockchain account:\n0x1234...5678\n\nI am signing this message to prove ownership of my wallet address 0x1234...5678 for Crossmint verification.\n\nURI: https://...\nVersion: 1\nNonce: ...\nIssued At: ...\nExpiration Time: ...\nRequest ID: ...\nChain ID: base-sepolia"
                }
            }
        }
    }
    ```
  </Step>

  <Step title="Sign Message (conditional)">
    <Info>
      This step is only required if the order status is `requires-recipient-verification`.
    </Info>

    Have the user sign the `preparation.message` with the recipient wallet. All wallets, including EOAs and smart contract wallets, use the same verification flow.

    <CodeGroup>
      ```js EVM (ethers.js) theme={null}
      import { Wallet } from "ethers";

      const PRIVATE_KEY = "YOUR_WALLET_PRIVATE_KEY"; // Replace with your wallet's private key
      const wallet = new Wallet(PRIVATE_KEY);
      const message = order.payment.preparation.message;
      const signature = await wallet.signMessage(message);
      ```

      ```js Solana (tweetnacl) theme={null}
      import nacl from "tweetnacl";
      import { decodeUTF8 } from "tweetnacl-util";
      import { encode as base64Encode } from "@stablelib/base64";

      const message = order.payment.preparation.message;
      const messageBytes = decodeUTF8(message);
      const signatureBytes = nacl.sign.detached(messageBytes, keypair.secretKey);
      const signature = base64Encode(signatureBytes);
      ```
    </CodeGroup>
  </Step>

  <Step title="Submit Signature (conditional)">
    <Info>
      This step is only required if the order status is `requires-recipient-verification`.
    </Info>

    Use the same Link External Wallet API to submit the signature as proof of ownership. Pass the signature in the `proof` field:

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request PUT \
          --url https://staging.crossmint.com/api/2025-06-09/users/{userLocator}/linked-wallets/{address} \
          --header 'X-API-KEY: <x-api-key>' \
          --header 'Content-Type: application/json' \
          --data '{
              "chain": "base-sepolia",
              "proof": "<signature>"
          }'
      ```

      ```js Node.js theme={null}
      const options = {
          method: 'PUT',
          headers: {
              'X-API-KEY': '<x-api-key>',
              'Content-Type': 'application/json'
          },
          body: JSON.stringify({
              chain: "base-sepolia",
              proof: "<signature>"
          })
      };

      const userLocator = "email:user@example.com";
      const walletAddress = "0x1234567890abcdef1234567890abcdef12345678";

      fetch(`https://staging.crossmint.com/api/2025-06-09/users/${userLocator}/linked-wallets/${walletAddress}`, options)
          .then(response => response.json())
          .then(response => console.log(response))
          .catch(err => console.error(err));
      ```
    </CodeGroup>

    Once ownership is verified, the response will confirm verification:

    ```json theme={null}
    {
        "address": "0x1234567890abcdef1234567890abcdef12345678",
        "chain": "base-sepolia",
        "type": "external-wallet",
        "ownership": {
            "verified": true
        }
    }
    ```
  </Step>

  <Step title="Complete Order">
    Once ownership is verified (or if verification was not required), fetch the order using the [Get Order API](/api-reference/headless/get-order). The order status should now have proceeded to the next phase:

    * **`requires-kyc`**: The user hasn't completed KYC yet and will be guided through the KYC flow first.
    * **`awaiting-payment`**: The user has completed KYC and can proceed to complete payment.

    The user will be guided through Crossmint's embedded components to complete their order, handling payment and any remaining compliance steps automatically.
  </Step>
</Steps>

## Pre-Verifying Ownership

You can verify wallet ownership at the time of linking (before any order is created) by including the `proof` field in the initial Link External Wallet call, as shown in step 1. This avoids requiring verification during the checkout flow.

## Related Resources

* [React Quickstart (External Wallets tab)](/onramp/quickstarts/react) — quickstart with external wallet support
* [Import User KYC Data](/onramp/guides/import-user-kyc-data) — pre-register KYC data so users skip in-checkout verification


# Add Payment Methods
Source: https://docs.crossmint.com/onramp/guides/payment-methods

Enable cards, Apple Pay, and Google Pay for onramp

This guide covers how to enable each supported payment method — cards, Apple Pay, and Google Pay — in your onramp integration, including the platform-specific configuration each one requires.

All payment methods are controlled through the payment configuration of the checkout component. The checkout only displays methods that the user's device supports, so enabling a method is safe even on platforms where it cannot appear. For an explanation of how each method works, see [Payment Methods](/onramp/concepts/payment-methods).

## Prerequisites

* A working onramp integration — complete a [quickstart](/onramp/quickstarts/react) first.

## Configure Allowed Methods

Set the methods you want to offer in the fiat payment configuration:

<Tabs>
  <Tab title="React">
    ```tsx theme={null}
    <CrossmintEmbeddedCheckout
        orderId={order.orderId}
        clientSecret={order.clientSecret}
        payment={{
            crypto: { enabled: false },
            fiat: {
                enabled: true,
                allowedMethods: {
                    card: true,
                    applePay: true,
                    googlePay: true,
                },
            },
        }}
    />
    ```
  </Tab>

  <Tab title="React Native">
    ```tsx theme={null}
    <CrossmintEmbeddedCheckout
        orderId={order.orderId}
        clientSecret={order.clientSecret}
        payment={{
            crypto: { enabled: false },
            fiat: {
                enabled: true,
                allowedMethods: {
                    card: true,
                    applePay: true,
                    googlePay: true,
                },
            },
        }}
    />
    ```
  </Tab>

  <Tab title="Flutter">
    ```dart theme={null}
    CrossmintEmbeddedCheckout(
      apiKey: clientApiKey,
      config: CrossmintCheckoutConfig(
        order: CrossmintCheckoutExistingOrder(
          orderId: order.orderId,
          clientSecret: order.clientSecret,
        ),
        payment: CrossmintCheckoutPayment(
          crypto: CrossmintCheckoutCryptoPayment(enabled: false),
          fiat: CrossmintCheckoutFiatPayment(
            enabled: true,
            allowCard: true,
            allowApplePay: true,
            allowGooglePay: true,
          ),
        ),
      ),
    )
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    CrossmintEmbeddedCheckout(
        orderId = "YOUR_ORDER_ID",
        clientSecret = "YOUR_CLIENT_SECRET",
        payment = CheckoutPayment(
            crypto = CheckoutCryptoPayment(enabled = false),
            fiat = CheckoutFiatPayment(
                enabled = true,
                allowedMethods = CheckoutAllowedMethods(
                    card = true,
                    applePay = true,
                    googlePay = true
                )
            )
        ),
        environment = CheckoutEnvironment.STAGING
    )
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    CrossmintEmbeddedCheckout(
        orderId: "YOUR_ORDER_ID",
        clientSecret: "YOUR_CLIENT_SECRET",
        payment: CheckoutPayment(
            crypto: CheckoutCryptoPayment(enabled: false),
            fiat: CheckoutFiatPayment(
                enabled: true,
                allowedMethods: CheckoutAllowedMethods(
                    googlePay: false,
                    applePay: true,
                    card: true
                )
            )
        )
    )
    ```
  </Tab>
</Tabs>

Cards work on every platform with no additional setup. Apple Pay and Google Pay require the platform-specific configuration below.

## Apple Pay

<Tabs>
  <Tab title="Web (React)">
    To display Apple Pay on your website (Safari on macOS and iOS), you must verify your domain with Apple through the Crossmint Console. This is a one-time setup per domain.

    ### Prerequisites

    1. **HTTPS hosting** — your site must be served over HTTPS.
    2. **Crossmint account** — you need an active Crossmint developer account.

    <Steps>
      <Step title="Download the Verification File">
        Go to the <a href="https://www.crossmint.com/console/apple-pay-domains">Apple Pay Domains</a> page in the Crossmint Console and click **Download file** to get the Apple Developer Merchant ID Domain Association file.
      </Step>

      <Step title="Host the Verification File">
        Host the downloaded file on your server at the following path:

        ```text theme={null}
        https://YOUR_DOMAIN/.well-known/apple-developer-merchantid-domain-association
        ```

        <Accordion title="Example: Next.js App Router">
          **Option 1: Using the Public Folder**

          1. Create the `.well-known` folder inside your `public` directory.
          2. Place the downloaded file in `public/.well-known/` with the filename `apple-developer-merchantid-domain-association` (no extension).

          **Option 2: Using a Route**

          1. Create a folder at `app/.well-known/apple-developer-merchantid-domain-association/`
          2. Add a `route.ts` file with the following content:

          ```typescript route.ts theme={null}
          import { NextResponse } from "next/server";

          export async function GET() {
              return new NextResponse("PASTE_FILE_CONTENT_HERE", {
                  headers: {
                      "Content-Type": "text/plain",
                  },
              });
          }
          ```

          Replace `PASTE_FILE_CONTENT_HERE` with the content of the downloaded verification file.
        </Accordion>

        <Accordion title="Example: Next.js Page Router">
          1. Create the `.well-known` folder inside your `public` directory.
          2. Place the downloaded file in `public/.well-known/` with the filename `apple-developer-merchantid-domain-association` (no extension).
        </Accordion>

        <Accordion title="Example: Vite">
          1. Create the `.well-known` folder inside your `public` directory.
          2. Place the downloaded file in `public/.well-known/` with the filename `apple-developer-merchantid-domain-association` (no extension).
        </Accordion>
      </Step>

      <Step title="Verify Your Domain">
        1. Return to the <a href="https://www.crossmint.com/console/apple-pay-domains">Apple Pay Domains</a> page in the Crossmint Console.
        2. Enter your domain (e.g., `example.com` or `checkout.example.com`) in the input field.
        3. Click **Verify domain**.

        If verification succeeds, your domain will appear in the list of registered domains and Apple Pay will be available as a payment method in the onramp checkout.

        <Note>
          If verification fails, ensure the file is publicly accessible at the correct path. You can test by visiting `https://YOUR_DOMAIN/.well-known/apple-developer-merchantid-domain-association` in your browser.
        </Note>
      </Step>
    </Steps>

    ### Local Testing

    Using <a href="https://ngrok.com/">ngrok</a> is recommended for local testing:

    1. Start ngrok with a fixed domain if possible for consistent testing.
    2. Host the verification file on your local server.
    3. Register the ngrok domain in the Crossmint Console.
    4. Test Apple Pay on Safari (macOS) or any iOS device.
  </Tab>

  <Tab title="React Native">
    In React Native, `CrossmintEmbeddedCheckout` renders the checkout page in a WebView, and Apple Pay runs inside that page rather than through a native Apple Pay integration in your app. This changes the setup compared with the web:

    * **No domain verification.** The checkout page is served from `crossmint.com`, which is already enabled for Apple Pay, so the domain steps in the Web tab do not apply.
    * **No Apple Pay native configuration.** Your app does not need an Apple merchant ID or the Apple Pay capability. The `@crossmint/client-sdk-react-native-ui` Expo plugin has no Apple Pay option; its `enableGooglePay` setting only affects Android.
    * **iOS 16 or higher.** Apple Pay is available inside a WebView on iOS 16 and later, including when the SDK injects its bridge scripts into the page. Do not set the `enableApplePay` prop of <a href="https://github.com/react-native-webview/react-native-webview/blob/master/docs/Reference.md#enableapplepay">react-native-webview</a>: it exists for iOS 13 to 15, where injected scripts disabled Apple Pay, and it breaks the communication between the SDK and the checkout page.
    * **Test on a physical iPhone.** Use a device running iOS 17 or higher with a card added to Apple Wallet. The iOS Simulator does not render Apple Pay. A development build installed on the device is enough; a TestFlight build is not required.

    Enable Apple Pay with `applePay: true` in `allowedMethods` as shown in [Configure Allowed Methods](#configure-allowed-methods). To render the checkout in your own WebView instead of the SDK component, see the [Mobile WebView Integration guide](/payments/embedded/guides/webview-integration).
  </Tab>

  <Tab title="iOS (Swift)">
    Apple Pay is supported automatically in native iOS apps via the Swift SDK — no domain verification is required. The checkout renders inside a WebView, so Apple Pay is available on iOS 16 and later; test on a physical iPhone, as the iOS Simulator does not render Apple Pay. Enable it through `allowedMethods` as shown in [Configure Allowed Methods](#configure-allowed-methods), and see the [Swift Quickstart](/onramp/quickstarts/swift) for the full integration.
  </Tab>
</Tabs>

## Google Pay

On the web, Google Pay works out of the box — enabling it via `allowedMethods` is all that is needed. Mobile apps require additional native configuration because the payment sheet is rendered by the operating system.

<Tabs>
  <Tab title="React Native">
    ### Prerequisites

    * React Native project with Expo or bare workflow
    * Android device or emulator with Google Play Services

    <Steps>
      <Step title="Install Dependencies">
        ```bash theme={null}
        pnpm add @crossmint/client-sdk-react-native-ui
        ```

        The SDK includes `react-native-webview` as a dependency. If you need to install it separately, ensure version **13.15.0 or higher**:

        ```bash theme={null}
        pnpm add react-native-webview@^13.15.0
        ```
      </Step>

      <Step title="Configure the Expo Plugin">
        Update your `app.json` to enable Google Pay:

        ```json theme={null}
        {
          "expo": {
            "plugins": [
              [
                "@crossmint/client-sdk-react-native-ui",
                {
                  "enableGooglePay": true
                }
              ]
            ]
          }
        }
        ```

        <Warning>
          This plugin modifies native Android permissions required for Google Pay. The app must be rebuilt after adding this configuration.
        </Warning>
      </Step>

      <Step title="Rebuild Your App">
        Hot reload cannot apply the permission changes. You must rebuild:

        ```bash theme={null}
        npx expo run:android
        ```

        Or for bare React Native:

        ```bash theme={null}
        npx react-native run-android
        ```
      </Step>

      <Step title="Enable Google Pay in the Checkout Component">
        Set `googlePay: true` in `allowedMethods` as shown in [Configure Allowed Methods](#configure-allowed-methods).
      </Step>
    </Steps>
  </Tab>

  <Tab title="Android Native (Kotlin)">
    ### Prerequisites

    * Minimum Android SDK version 24 (Android 7.0)
    * Jetpack Compose

    <Steps>
      <Step title="Add the SDK Dependency">
        In your app-level `build.gradle.kts`:

        ```kotlin theme={null}
        dependencies {
            implementation("com.crossmint:crossmint-sdk-android:0.0.9")
        }
        ```
      </Step>

      <Step title="Configure AndroidManifest.xml">
        Add the required query intents to enable Google Pay functionality:

        ```xml theme={null}
        <manifest xmlns:android="http://schemas.android.com/apk/res/android">
            <queries>
                <intent>
                    <action android:name="org.chromium.intent.action.PAY"/>
                </intent>
                <intent>
                    <action android:name="org.chromium.intent.action.IS_READY_TO_PAY"/>
                </intent>
                <intent>
                    <action android:name="org.chromium.intent.action.UPDATE_PAYMENT_DETAILS"/>
                </intent>
            </queries>
        </manifest>
        ```
      </Step>

      <Step title="Enable Google Pay in the Checkout Component">
        Set `googlePay = true` in `allowedMethods` as shown in [Configure Allowed Methods](#configure-allowed-methods).
      </Step>
    </Steps>
  </Tab>
</Tabs>

### Google Pay Production Approval

Google Pay works immediately in **staging** environments. For **production**, Google requires explicit approval of your Android app.

<AccordionGroup>
  <Accordion title="Step 1: Create Your Business Profile">
    1. Navigate to the <a href="https://pay.google.com/business/console">Google Pay & Wallet Console</a>
    2. Select "Merchant" as your business type
    3. Complete all business profile information
    4. Navigate to **Google Pay API** and click "Get Started"
    5. Accept the Google Pay API Terms of Service
    6. Note your **Merchant ID** (top-right corner after completion)
  </Accordion>

  <Accordion title="Step 2: Submit Your Android App for Approval">
    In the Google Pay & Wallet Console:

    1. Navigate to **Google Pay API** then **Integrations** then **Integrate with your Android app**
    2. Locate your Android application and click "Manage"
    3. Select your integration type (typically "Gateway")
    4. Upload screenshots of your TEST Google Pay integration
    5. Click "Save" then "Submit for approval"

    **Required Screenshots:**

    * Product/item selection showing Google Pay option
    * Cart or checkout view with payment options
    * Google Pay payment sheet with card selection
    * Confirmation or receipt screen
  </Accordion>

  <Accordion title="Step 3: Go Live">
    After Google approval (typically \~1 business day):

    1. Sign your APK with a **release key** (debug keys do not work in production)
    2. Update environment settings:
       * Kotlin: `environment = CheckoutEnvironment.PRODUCTION`
       * React Native: Use production API key
    3. Publish your app to Google Play Store
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Apple Pay button does not appear">
    1. **Domain not verified (web):** Verify your domain on the <a href="https://www.crossmint.com/console/apple-pay-domains">Apple Pay Domains</a> page
    2. **Unsupported browser:** Apple Pay on web only appears in Safari on macOS and iOS
    3. **iOS Simulator (mobile apps):** Apple Pay does not render in the Simulator; test on a physical iPhone running iOS 17 or higher with a card in Apple Wallet
    4. **iOS version (mobile apps):** Apple Pay inside a WebView requires iOS 16 or higher
    5. **Payment method disabled:** Check `applePay: true` in `allowedMethods`
  </Accordion>

  <Accordion title="Google Pay button does not appear">
    1. **Plugin not configured:** Verify `enableGooglePay: true` in `app.json` plugins
    2. **App not rebuilt:** Run `npx expo run:android` after adding the plugin
    3. **Environment mismatch:** Staging works without approval; production requires it
    4. **Payment method disabled:** Check `googlePay: true` in `allowedMethods`
  </Accordion>

  <Accordion title="PaymentRequest API is not supported error">
    1. **AndroidManifest missing queries:** Add all three Chromium intent queries
    2. **Native rebuild required:** Hot reload cannot apply permission changes
    3. **Device requirements:** User needs Google Play Services 25.18.30+ and WebView 137+
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Payment Methods" icon="book-open" href="/onramp/concepts/payment-methods">
    Understand how each payment method works and why onramp is a regulated transfer
  </Card>

  <Card title="UI Customization" icon="palette" href="/onramp/guides/ui-customization">
    Customize the onramp checkout UI to match your brand identity
  </Card>

  <Card title="User Onboarding" icon="id-card" href="/onramp/introduction/user-onboarding">
    Register users and handle KYC before their first onramp transaction
  </Card>

  <Card title="React Quickstart" icon="rocket" href="/onramp/quickstarts/react">
    Build a complete onramp integration from scratch
  </Card>
</CardGroup>


# UI Customization
Source: https://docs.crossmint.com/onramp/guides/ui-customization

Customize the onramp checkout UI to match your brand identity and design system

The onramp embedded checkout component supports extensive customization through the `appearance` prop, allowing you to match the look and feel of your application.

## Quick Start

```jsx theme={null}
<CrossmintEmbeddedCheckout
    orderId={order.orderId}
    clientSecret={order.clientSecret}
    appearance={{
        fonts: [{ cssSrc: "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap" }],
        variables: {
            fontFamily: "Inter, system-ui, sans-serif",
            colors: {
                backgroundPrimary: "#ffffff",
                textPrimary: "#000000",
                accent: "#0074D9",
            },
        },
    }}
/>
```

## Identity Verification Screens

<Snippet />

## Customization Options

### Background

The embedded checkout component has a **transparent background** by default. The `backgroundPrimary` color only affects internal components (inputs, cards, etc.) within the iframe, not the iframe body itself.

To customize the overall background, wrap the component:

```jsx theme={null}
<div style={{ backgroundColor: "#1a1a1a" }}>
    <CrossmintEmbeddedCheckout {...props} />
</div>
```

### Custom Fonts

Load custom fonts using the `fonts` array:

```jsx theme={null}
appearance={{
    fonts: [
        { cssSrc: "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap" }
    ]
}}
```

### Global Variables

Control the overall look and feel:

```jsx theme={null}
appearance={{
    variables: {
        fontFamily: "Inter, system-ui, sans-serif",
        fontSizeUnit: "16px",
        spacingUnit: "1rem",
        borderRadius: "8px",
        colors: {
            borderPrimary: "#E0E0E0",
            backgroundPrimary: "#FFFFFF",
            textPrimary: "#000000",
            textSecondary: "#666666",
            danger: "#FF0000",
            warning: "#FFA500",
            accent: "#0074D9"
        }
    }
}}
```

### Component Rules

<AccordionGroup>
  <Accordion title="Input Visibility">
    Control the visibility of specific inputs:

    ```jsx theme={null}
    appearance={{
        rules: {
            DestinationInput: {
                display: "hidden"
            },
            ReceiptEmailInput: {
                display: "hidden"
            }
        }
    }}
    ```

    <Note>
      When hiding inputs, make sure to provide the corresponding values via props:

      * For hidden `DestinationInput`, provide `recipient.walletAddress`
      * For hidden `ReceiptEmailInput`, provide `payment.receiptEmail`
    </Note>
  </Accordion>

  <Accordion title="Labels">
    Customize label styling:

    ```jsx theme={null}
    appearance={{
        rules: {
            Label: {
                font: {
                    family: "Inter",
                    size: "14px",
                    weight: "500",
                },
                colors: {
                    text: "#333333",
                },
            },
        },
    }}
    ```
  </Accordion>

  <Accordion title="Input Fields">
    Style input fields:

    ```jsx theme={null}
    appearance={{
        rules: {
            Input: {
                borderRadius: "8px",
                font: {
                    family: "Inter",
                    size: "16px",
                    weight: "400",
                },
                colors: {
                    text: "#000000",
                    background: "#FFFFFF",
                    border: "#E0E0E0",
                    boxShadow: "none",
                    placeholder: "#999999",
                },
                hover: {
                    colors: {
                        border: "#0074D9",
                    },
                },
                focus: {
                    colors: {
                        border: "#0074D9",
                        boxShadow: "0 0 0 2px rgba(0,116,217,0.2)",
                    },
                },
            },
        },
    }}
    ```
  </Accordion>

  <Accordion title="Tabs">
    Customize tab appearance:

    ```jsx theme={null}
    appearance={{
        rules: {
            Tab: {
                borderRadius: "4px",
                font: {
                    family: "Inter",
                    size: "14px",
                    weight: "500",
                },
                colors: {
                    text: "#666666",
                    background: "transparent",
                },
                selected: {
                    colors: {
                        text: "#000000",
                        background: "#F5F5F5",
                    },
                },
                hover: {
                    colors: {
                        background: "#F0F0F0",
                    },
                },
            },
        },
    }}
    ```
  </Accordion>

  <Accordion title="Primary Buttons">
    Style primary buttons:

    ```jsx theme={null}
    appearance={{
        rules: {
            PrimaryButton: {
                borderRadius: "8px",
                font: {
                    family: "Inter",
                    size: "16px",
                    weight: "600"
                },
                colors: {
                    text: "#FFFFFF",
                    background: "#0074D9"
                },
                hover: {
                    colors: {
                        background: "#0063B8"
                    }
                },
                disabled: {
                    colors: {
                        text: "#FFFFFF",
                        background: "#CCCCCC"
                    }
                }
            }
        }
    }}
    ```
  </Accordion>
</AccordionGroup>

## Common Examples

### Modern Dark Theme

```jsx theme={null}
appearance={{
    variables: {
        fontFamily: "Inter, system-ui, sans-serif",
        colors: {
            backgroundPrimary: "#1A1A1A",
            textPrimary: "#FFFFFF",
            textSecondary: "#A0A0A0",
            borderPrimary: "#333333",
            accent: "#7928CA"
        }
    },
    rules: {
        Input: {
            colors: {
                background: "#2D2D2D",
                border: "#404040",
                text: "#FFFFFF",
                placeholder: "#666666"
            }
        },
        PrimaryButton: {
            colors: {
                background: "#7928CA",
                text: "#FFFFFF"
            },
            hover: {
                colors: {
                    background: "#6B24B2"
                }
            }
        }
    }
}}
```

### Minimal Light Theme

```jsx theme={null}
appearance={{
    variables: {
        fontFamily: "system-ui, sans-serif",
        borderRadius: "4px",
        colors: {
            backgroundPrimary: "#FFFFFF",
            textPrimary: "#000000",
            borderPrimary: "#E0E0E0",
            accent: "#000000"
        }
    },
    rules: {
        Input: {
            borderRadius: "4px",
            colors: {
                background: "#F5F5F5",
                border: "transparent"
            },
            focus: {
                colors: {
                    border: "#000000",
                    boxShadow: "none"
                }
            }
        },
        PrimaryButton: {
            borderRadius: "4px",
            colors: {
                background: "#000000",
                text: "#FFFFFF"
            }
        }
    }
}}
```

## Related Resources

* [React Quickstart](/onramp/quickstarts/react)
* [React Native Quickstart](/onramp/quickstarts/react-native)
* [User Onboarding](/onramp/introduction/user-onboarding)
* [Identity Verification UI Customization](/identity/ui-customization)


# User Onboarding and KYC
Source: https://docs.crossmint.com/onramp/introduction/user-onboarding

Register users for the Onramp

Every end user must complete KYC before buying stablecoins through the Onramp. This page explains the two decisions you need to make: who collects KYC data, and which KYC tier applies.

## Who Collects KYC Data?

This is independent of the integration mode you choose (embedded component or headless API). In either case, you decide whether Crossmint collects KYC directly from the user, or you supply data you have already collected.

| Approach | Best For | How It Works |
| :- | :- | :- |
| **Crossmint-Hosted** | Teams that want the fastest integration | The user completes KYC inside Crossmint's secure embedded components. You do not need to handle any KYC data yourself. |
| **You supply KYC data** | Platforms that already verify users through their own identity verification (IDV) provider | You pass verified user data to Crossmint via API before creating an order. |

## KYC Tiers

Crossmint applies two KYC tiers based on cumulative transaction volume, transaction frequency, and risk profile:

| Tier | Applies When | Data Required |
| :- | :- | :- |
| **Progressive KYC** | Up to \$1,000 in total volume in the last 12 months | Name, date of birth, nationality, country, address, email, and phone number (phone required for US residents). An ID number or SSN is required for US (SSN) and EU/EEA residents; optional elsewhere. |
| **Full KYC** | Over \$1,000 in total volume in the last 12 months, or a high number of transactions | Progressive KYC data plus `dueDiligence`, `verificationHistory`, identity document, and selfie. See the [data requirements](/identity/data-requirements) page. |

<Note>Independently of the tier, Crossmint's compliance team may request a specific document from a user at any time — proof of address, source of wealth, or an identity document. See [additional document requests](/identity/quickstart#additional-document-requests).</Note>

### How It Works

<Tabs>
  <Tab title="Crossmint-Hosted">
    Crossmint handles all KYC data collection and tier transitions. You create the order via API and render the embedded component in your app.

    <Steps>
      <Step title="Create an Onramp Order and Render the Embedded Component">
        Create an order via API and render the Crossmint embedded checkout component in your app. The [onramp quickstart](/onramp/quickstarts/react) walks through both steps.
      </Step>

      <Step title="Crossmint Collects KYC Inside the Embedded Component">
        The embedded checkout component prompts the user for the required identity data. You do not collect or handle any KYC data yourself. The KYC screens follow the checkout `appearance` you already pass; see [UI Customization](/identity/ui-customization).
      </Step>

      <Step title="Crossmint Manages Tier Transitions Automatically">
        When a user crosses the \$1,000 threshold or reaches a high number of transactions, the component automatically prompts them for the additional Full KYC data. If Crossmint's compliance team requests additional documents from the user, the component collects those as well. You do not need to build or manage any tier logic.
      </Step>
    </Steps>
  </Tab>

  <Tab title="KYC Data Sharing">
    You verify users through your own identity verification (IDV) provider and pass the data to Crossmint via API. You are responsible for supplying the correct tier of data.

    <Steps>
      <Step title="Record User Acceptance of Legal Terms">
        Before submitting any user data, you must record the user's acceptance of Crossmint's <a href="https://www.crossmint.com/legal/crossmint-terms-of-service/TRGUSAALLALLALL">Terms of Service</a> and <a href="https://www.crossmint.com/legal/privacy-policy">Privacy Policy</a>. The [Identity quickstart](/identity/quickstart) walks through this step.
      </Step>

      <Step title="Register Progressive KYC Data">
        Register the user's basic identity data via the [Create User API](/api-reference/users/upsert-user).
      </Step>

      <Step title="Trigger Identity Verification">
        Call the [Trigger Identity Verification API](/api-reference/users/trigger-identity-verification) to run Crossmint's compliance checks. Verification runs asynchronously.
      </Step>

      <Step title="Check Verification Status">
        Poll the [Get Identity Verification Status API](/api-reference/users/get-identity-verification) until the `onramp` eligibility reads `verified`. If the status is `requires-data`, the response includes `missingData` and `missingDocuments` arrays that tell you exactly what additional information is needed. Supply it via the [Create User API](/api-reference/users/upsert-user) and/or [Upload Document API](/api-reference/users/upload-document), then re-trigger verification.

        If the status is `rejected`, check the entry's `failureReasons` array for a machine-readable cause before assuming the case needs manual escalation. See [Failure Reasons](/identity/failure-reasons) for the full list of codes.
      </Step>

      <Step title="Create an Onramp Order and Render the Embedded Component">
        Create an order via API and render the Crossmint embedded checkout component in your app. The [onramp quickstart](/onramp/quickstarts/react) walks through both steps.
      </Step>

      <Step title="Supply Additional Data When Needed">
        On order creation, if the user has exceeded the progressive KYC threshold and full KYC data has not been provided, the order returns an error: `"Insufficient KYC data provided for this user to perform onramp"`. Supply the required data via the [Upsert User API](/api-reference/users/upsert-user) and/or [Upload Document API](/api-reference/users/upload-document), then retry order creation. See the [data requirements](/identity/data-requirements) page for the full list of fields.

        Separately, Crossmint's compliance team may request a specific document from a user at any time: the verification status reads `requires-data` with the document listed in `missingDocuments`. Upload it via the [Upload Document API](/api-reference/users/upload-document) and re-trigger verification — see [additional document requests](/identity/quickstart#additional-document-requests).
      </Step>
    </Steps>

    <Note>
      Tier transitions are not automatic. You must detect when additional data is needed and provide it. The verification status response tells you exactly what is missing.
    </Note>
  </Tab>
</Tabs>

## Onboarding for AI Agents

For AI agent use cases where a human operator has already completed KYC through your platform, you can pre-register the agent operator's identity data via the API. The agent can then execute onramp transactions without being prompted for KYC in the checkout flow.

See the [Agent Wallets Onramp](/solutions/ai-agents/agent-wallets/onramp) guide for agent-specific integration details.

## Guides

<CardGroup>
  <Card title="Import KYC Data" icon="file-import" href="/onramp/guides/import-user-kyc-data" />

  <Card title="Identity Quickstart" icon="bolt" href="/identity/quickstart" />

  <Card title="Data Requirements" icon="list-check" href="/identity/data-requirements" />

  <Card title="Onramp to Non-Crossmint Wallets" icon="fingerprint" href="/onramp/guides/onramp-to-external-wallets" />

  <Card title="Identity Verification UI Customization" icon="palette" href="/identity/ui-customization" />
</CardGroup>


# Overview
Source: https://docs.crossmint.com/onramp/overview

Allow your users to buy stablecoins with any payment method

Crossmint Onramp lets your customers buy stablecoins directly inside your app through a white-labeled, native experience.

With plug-and-play SDKs, your team can focus on building great products instead of building checkout, compliance, and chargeback operations in-house.

The product is available in 160+ countries, with lightweight KYC up to \$1,000. Supported payments include debit and credit cards, Apple Pay, and Google Pay, with bank transfers coming soon.

<Note>
  **Need stablecoin payouts only?** If you already have your own checkout and only need stablecoin payouts or
  licensing support, see the [Payouts guide](/stablecoin-orchestration/regulated-transfers/overview). For treasury
  onramps, check the [treasury funding guide](/stablecoin-orchestration/guides/on-off-ramps/funding-company-wallets).
</Note>

## See It in Action

Try it yourself using the following <a href="https://ramps.demos-crossmint.com/">link</a>.

<video />

## Key Features

<CardGroup>
  <Card title="Native UX" icon="window">
    Seamless in-app experience
  </Card>

  <Card title="Light KYC up to $1,000" icon="id-card">
    Faster onboarding, higher conversion
  </Card>

  <Card title="Apple & Google Pay" icon="apple">
    One-click stablecoin onramps
  </Card>

  <Card title="160+ countries" icon="globe">
    Global coverage out of the box
  </Card>

  <Card title="Chargeback protection" icon="shield">
    Crossmint assumes liability
  </Card>

  <Card title="Bring your KYC" icon="share-nodes">
    Import user data (optional)
  </Card>
</CardGroup>

## Get Started

### Embedded

Select your framework to embed pre-built Crossmint components for onramp. Testing in staging is self-serve. <a href="https://www.crossmint.com/contact/sales">Contact sales</a> for production.

<CardGroup>
  <Card title="React" icon="react" href="/onramp/quickstarts/react" />

  <Card title="React Native" icon="react" href="/onramp/quickstarts/react-native" />

  <Card title="Flutter" icon="mobile" href="/onramp/quickstarts/flutter" />

  <Card title="Swift" icon="swift" href="/onramp/quickstarts/swift" />

  <Card title="Kotlin" icon="android" href="/onramp/quickstarts/kotlin" />
</CardGroup>

### Headless

Use your own custom components with Crossmint APIs for onramp. <a href="https://www.crossmint.com/contact/sales">Contact sales</a> for more details.

## Learn More

* <a href="https://ramps.demos-crossmint.com/">Try It Yourself</a>
* [User Onboarding](/onramp/introduction/user-onboarding)
* [Data Requirements](/identity/data-requirements)

## Advanced Guides

<CardGroup>
  <Card title="KYC Data Imports" icon="id-card-clip" href="/onramp/guides/import-user-kyc-data">
    Import user KYC data
  </Card>

  <Card title="External Wallets" icon="wallet" href="/onramp/guides/onramp-to-external-wallets">
    Onramp to any wallet
  </Card>

  <Card title="UI Customization" icon="palette" href="/onramp/guides/ui-customization">
    Match your brand
  </Card>

  <Card title="Payment Methods" icon="credit-card" href="/onramp/guides/payment-methods">
    Enable Apple Pay & Google Pay
  </Card>
</CardGroup>

## FAQs

<AccordionGroup>
  <Accordion title="How can I test the product? And how do I move to production?">
    You can try out the user journey <a href="https://ramps.demos-crossmint.com/">here</a>.

    Integrating the product on staging is fully self-serve - simply get an API key on the <a href="https://staging.crossmint.com/signin?callbackUrl=/console">staging console</a> and follow the docs.

    Production access requires a signed Order Form and completed KYB verification. <a href="https://www.crossmint.com/contact/sales">Contact sales</a> to get started. See the [account verification documentation](/introduction/platform/account-verification) for details.
  </Accordion>

  <Accordion title="How can I track sales?">
    You can monitor purchases onchain or using webhooks. Sales dashboards, logs, and advanced analytics are also
    available in the console.
  </Accordion>

  <Accordion title="What are the transaction limits?">
    The standard transaction limits are **\$2,000 per user and day**. Limits reset daily at midnight US Eastern Time (05:00 UTC during standard time, 04:00 UTC during daylight saving time). If you need higher limits, <a href="https://www.crossmint.com/contact/sales">contact the sales team</a>.
  </Accordion>

  <Accordion title="Which geographies are supported?">
    Crossmint Onramp is available in 160+ countries. <a href="https://www.crossmint.com/contact/sales">Contact sales</a> for the latest country list and coverage details.
  </Accordion>
</AccordionGroup>


# Flutter
Source: https://docs.crossmint.com/onramp/quickstarts/flutter

Allow your mobile users to buy stablecoins with cards

<Frame type="simple">
  <img alt="Crossmint Onramp Embedded Checkout Demo" />
</Frame>

<CardGroup>
  <Snippet />

  <Card title="Onramp Embedded Quickstart" icon="github" href="https://github.com/Paella-Labs/crossmint-flutter-sdk">
    See the Flutter SDK checkout playground.
  </Card>
</CardGroup>

<Snippet />

Crossmint Checkout lets you build a seamless onramp for Flutter users to buy stablecoins with a credit card, Apple Pay, or Google Pay.

In this guide, you will learn how to:

* Create a Crossmint order via an API endpoint
* Use Crossmint's embedded checkout widget to handle KYC, payment, and delivery automatically

## Prerequisites

* Flutter 3.x+
* Dart SDK ^3.11.4
* iOS 13.0+ / Android 5.0+

<Snippet />

You also need the `http` package for making API requests to your backend:

```bash theme={null}
flutter pub add http
```

* Create a [server-side API key](/introduction/platform/api-keys/server-side) with the
  `orders.create` and `orders.read` scopes enabled.
  <br />
  Create a [client-side API key](/introduction/platform/api-keys/client-side) for the
  embedded checkout component.
* Pass your API key and backend URL via Dart defines when running the app:

  ```bash theme={null}
  flutter run \
    --dart-define=CROSSMINT_CLIENT_API_KEY=YOUR_CLIENT_API_KEY \
    --dart-define=API_URL=http://10.0.2.2:3000
  ```

  <Note>
    `localhost` on a mobile device or emulator does not resolve to your development machine.
    Use `10.0.2.2` for Android emulators, `127.0.0.1` for iOS simulators, or your machine's
    LAN IP / an ngrok tunnel for physical devices.
  </Note>

## Add Onramp to Your App

<Steps>
  <Step title="Create the API endpoint">
    <Note>
      If you want to enable onramp orders to external wallets (EOAs or third-party smart wallets) instead of Crossmint wallets, see the [Onramp to External Wallets](/onramp/guides/onramp-to-external-wallets) guide before proceeding.
    </Note>

    To initiate an onramp, you must first create a purchase order on your backend. This example uses Express, but you can use any backend framework:

    ```typescript server/createOrder.ts theme={null}
    import express from "express";

    const app = express();
    app.use(express.json());

    const USDC_TOKEN_LOCATORS = {
        solanaDevnet: "solana:4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
        baseSepolia: "base-sepolia:0x036CbD53842c5426634e7929541eC2318f3dCF7e",
        stellarTestnet: "stellar:CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA",
    };

    app.post("/api/create-order", async (req, res) => {
        const { walletAddress, receiptEmail, amount, chain } = req.body;
        const serverApiKey = process.env.CROSSMINT_SERVER_SIDE_API_KEY;

        if (serverApiKey == null) {
            return res.status(500).json({ error: "Server API key not configured" });
        }

        // Use `https://www.crossmint.com` in production.
        const baseUrl = process.env.CROSSMINT_BASE_URL ?? "https://staging.crossmint.com";
        const response = await fetch(`${baseUrl}/api/2022-06-09/orders`, {
            method: "POST",
            headers: {
                "Content-Type": "application/json",
                "x-api-key": serverApiKey,
            },
            body: JSON.stringify({
                lineItems: [
                    {
                        tokenLocator: USDC_TOKEN_LOCATORS[chain],
                        executionParameters: {
                            mode: "exact-in",
                            amount,
                        },
                    },
                ],
                payment: {
                    method: "card",
                    receiptEmail,
                },
                recipient: {
                    walletAddress,
                },
            }),
        });

        if (!response.ok) {
            const error = await response.json();
            return res.status(response.status).json(error);
        }

        const data = await response.json();
        res.json(data);
    });

    app.listen(3000);
    ```
  </Step>

  <Step title="Build the onramp checkout UI in your app">
    Create a Flutter screen that handles order creation and displays a checkout:

    ```dart lib/screens/onramp_screen.dart theme={null}
    import 'dart:convert';
    import 'package:flutter/material.dart';
    import 'package:http/http.dart' as http;
    import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

    const clientApiKey = String.fromEnvironment('CROSSMINT_CLIENT_API_KEY');
    // Replace with your backend URL.
    // On Android emulator use 10.0.2.2 instead of localhost.
    // On a physical device use your machine's LAN IP or an ngrok tunnel.
    const apiUrl = String.fromEnvironment('API_URL', defaultValue: 'http://10.0.2.2:3000');

    class OnrampScreen extends StatefulWidget {
      const OnrampScreen({super.key});

      @override
      State<OnrampScreen> createState() => _OnrampScreenState();
    }

    class _OnrampScreenState extends State<OnrampScreen> {
      final _emailController = TextEditingController(text: 'user@example.com');
      final _walletController = TextEditingController();
      final _amountController = TextEditingController(text: '5');
      String _chain = 'solanaDevnet';
      bool _isLoading = false;
      Map<String, dynamic>? _order;

      Future<void> _createOrder() async {
        setState(() => _isLoading = true);
        try {
          final response = await http.post(
            Uri.parse('$apiUrl/api/create-order'),
            headers: {'Content-Type': 'application/json'},
            body: jsonEncode({
              'walletAddress': _walletController.text,
              'receiptEmail': _emailController.text,
              'amount': _amountController.text,
              'chain': _chain,
            }),
          );
          if (response.statusCode != 200) {
            throw Exception('Failed to create order');
          }
          final data = jsonDecode(response.body);
          setState(() {
            _order = {
              'orderId': data['order']['orderId'],
              'clientSecret': data['clientSecret'],
            };
          });
        } catch (e) {
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(content: Text('Failed to create order: $e')),
          );
        } finally {
          setState(() => _isLoading = false);
        }
      }

      @override
      Widget build(BuildContext context) {
        if (_order != null) {
          return Scaffold(
            body: CrossmintEmbeddedCheckout(
              apiKey: clientApiKey,
              config: CrossmintCheckoutConfig(
                order: CrossmintCheckoutExistingOrder(
                  orderId: _order!['orderId']!,
                  clientSecret: _order!['clientSecret'],
                ),
                payment: CrossmintCheckoutPayment(
                  fiat: CrossmintCheckoutFiatPayment(enabled: true),
                  crypto: CrossmintCheckoutCryptoPayment(enabled: false),
                ),
              ),
              onOrderUpdated: (order) => debugPrint('Order: $order'),
            ),
          );
        }

        return Scaffold(
          body: Padding(
            padding: const EdgeInsets.all(24),
            child: Column(
              crossAxisAlignment: CrossAxisAlignment.start,
              children: [
                const Text('Buy USDC',
                    style: TextStyle(fontSize: 24, fontWeight: FontWeight.w600)),
                const SizedBox(height: 24),
                const Text('Network', style: TextStyle(fontWeight: FontWeight.w500)),
                const SizedBox(height: 8),
                SegmentedButton<String>(
                  segments: const [
                    ButtonSegment(value: 'solanaDevnet', label: Text('Solana')),
                    ButtonSegment(value: 'baseSepolia', label: Text('Base')),
                    ButtonSegment(value: 'stellarTestnet', label: Text('Stellar')),
                  ],
                  selected: {_chain},
                  onSelectionChanged: (v) => setState(() => _chain = v.first),
                ),
                const SizedBox(height: 20),
                TextField(
                  controller: _emailController,
                  decoration: const InputDecoration(
                    labelText: 'Email',
                    border: OutlineInputBorder(),
                  ),
                ),
                const SizedBox(height: 12),
                TextField(
                  controller: _walletController,
                  decoration: const InputDecoration(
                    labelText: 'Recipient Wallet',
                    border: OutlineInputBorder(),
                  ),
                ),
                const SizedBox(height: 12),
                TextField(
                  controller: _amountController,
                  decoration: const InputDecoration(
                    labelText: 'Amount (USD)',
                    border: OutlineInputBorder(),
                  ),
                  keyboardType: TextInputType.number,
                ),
                const SizedBox(height: 16),
                SizedBox(
                  width: double.infinity,
                  child: ElevatedButton(
                    onPressed: _isLoading ? null : _createOrder,
                    style: ElevatedButton.styleFrom(
                      backgroundColor: Colors.black,
                      padding: const EdgeInsets.all(16),
                    ),
                    child: _isLoading
                        ? const CircularProgressIndicator(color: Colors.white)
                        : const Text('Continue to Checkout',
                            style: TextStyle(color: Colors.white, fontSize: 16)),
                  ),
                ),
              ],
            ),
          ),
        );
      }

      @override
      void dispose() {
        _emailController.dispose();
        _walletController.dispose();
        _amountController.dispose();
        super.dispose();
      }
    }
    ```
  </Step>

  <Step title="Add the screen to your app">
    Import and render the `OnrampScreen` in your app:

    ```dart lib/main.dart theme={null}
    import 'package:flutter/material.dart';
    import 'screens/onramp_screen.dart';

    void main() {
      runApp(const MaterialApp(home: OnrampScreen()));
    }
    ```

    The integration is complete. When users fill in their details and tap "Continue to Checkout", the API creates an order and the embedded checkout widget handles KYC, payment, and delivery automatically.

    <Tip>
      **Testing:** Use the test credit card number `4242 4242 4242 4242` with any future expiration date and any 3-digit CVC.
    </Tip>
  </Step>
</Steps>

## Transaction Completion

<Snippet />

## Next Steps

<Snippet />


# Kotlin
Source: https://docs.crossmint.com/onramp/quickstarts/kotlin

Allow your Android users to buy stablecoins with credit cards and Google Pay

In this guide, you'll learn how to:

* Install the Kotlin SDK
* Create an Onramp order for your authenticated users
* Use the embedded checkout component to handle KYC, payment, and delivery

<Frame type="simple">
  <img alt="Crossmint Onramp Embedded Checkout Demo" />
</Frame>

<CardGroup>
  <Snippet />

  <Card title="Kotlin SDK on GitHub" icon="github" href="https://github.com/Crossmint/crossmint-kotlin-checkout">
    View the Kotlin checkout example repository.
  </Card>
</CardGroup>

<Snippet />

## Prerequisites

* **Android SDK 24+**
* **Jetpack Compose**
* Android Studio Arctic Fox or later

Install the Crossmint Kotlin SDK using Maven Central.

Add the following dependency to your app's `build.gradle.kts` file:

```kotlin theme={null}
dependencies {
    implementation("com.crossmint:crossmint-sdk-android:0.0.9")
}
```

* Create a [server-side API key](https://docs.crossmint.com/introduction/platform/api-keys/server-side) with the
  `orders.create` and `orders.read` scopes enabled. In staging, all scopes are included in your API key.

## Add Onramp to Your App

<Steps>
  <Step title="Create the order">
    <Note>
      If you want to enable onramp orders to external wallets (EOAs or third-party smart wallets) instead of Crossmint wallets, see the [Onramp to External Wallets](/onramp/guides/onramp-to-external-wallets) guide before proceeding.
    </Note>

    Use the [Create Order API](/api-reference/headless/create-order) to initiate the purchase process from your backend.

    <Snippet />
  </Step>

  <Step title="Use the checkout component">
    Once you have the order response with `orderId` and `clientSecret`, use Crossmint's embedded checkout component in your Jetpack Compose view.

    The component supports **native Google Pay** for a seamless Android payment experience.

    ```kotlin theme={null}
    import com.crossmint.kotlin.checkout.CheckoutEnvironment
    import com.crossmint.kotlin.checkout.CrossmintEmbeddedCheckout
    import com.crossmint.kotlin.checkout.models.*

    CrossmintEmbeddedCheckout(
        orderId = "<your_order_id>",
        clientSecret = "<your_client_secret>",
        payment = CheckoutPayment(
            crypto = CheckoutCryptoPayment(enabled = false),
            fiat = CheckoutFiatPayment(
                enabled = true,
                allowedMethods = CheckoutAllowedMethods(
                    googlePay = true,  // Native Google Pay support
                    applePay = false,
                    card = true
                )
            )
        ),
        appearance = CheckoutAppearance(
            rules = CheckoutAppearanceRules(
                destinationInput = CheckoutDestinationInputRule(display = "hidden"),
                receiptEmailInput = CheckoutReceiptEmailInputRule(display = "hidden")
            )
        ),
        environment = CheckoutEnvironment.STAGING
    )
    ```

    **Key features:**

    * **Native Google Pay**: Seamless integration with Android payment system
    * **Jetpack Compose Components**: Modern declarative UI framework
    * **Automatic KYC**: Handles verification flow automatically
    * **Customizable Appearance**: Control visibility of UI elements
  </Step>

  <Step title="Track the order">
    <Snippet />
  </Step>
</Steps>

## Transaction Completion

<Snippet />

## Next Steps

<Snippet />

* View the <a href="https://github.com/Crossmint/crossmint-kotlin-checkout">Kotlin checkout example repo</a> on GitHub


# React
Source: https://docs.crossmint.com/onramp/quickstarts/react

Allow your users to buy stablecoins with cards

In this guide, you will learn how to:

* Install the React SDK
* Create an Onramp order for your authenticated users
* Use the embedded checkout component to handle KYC, payment, and delivery

<Frame type="simple">
  <img alt="Crossmint Onramp Embedded Checkout Demo" />
</Frame>

<CardGroup>
  <Snippet />

  <Card title="Onramp Embedded Quickstart" icon="github" href="https://github.com/Crossmint/onramp-embedded-quickstart">
    See a full working example.
  </Card>
</CardGroup>

<Note>
  You can test the Onramp self-serve in staging. To enable it in production, <a href="https://www.crossmint.com/contact/sales">contact sales</a>.
</Note>

## Prerequisites

Install the Crossmint client SDK:

<Snippet />

* Create a [server-side API key](https://docs.crossmint.com/introduction/platform/api-keys/server-side) with the
  `orders.create` and `orders.read` scopes enabled, and a [client-side API key](https://docs.crossmint.com/introduction/platform/api-keys/client-side)
  for the embedded checkout component.
* Add environment variables to your `.env.local`:

  ```bash .env.local theme={null}
  NEXT_PUBLIC_CROSSMINT_CLIENT_SIDE_API_KEY="_YOUR_CLIENT_API_KEY_"
  CROSSMINT_SERVER_SIDE_API_KEY="_YOUR_SERVER_API_KEY_"
  ```

## Onramp to Crossmint Wallets

Use this flow to onramp funds into wallets created with Crossmint.

<Steps>
  <Step title="Create the server action">
    Create a server action that will create orders via the Crossmint API:

    ```typescript app/actions/createOrder.ts theme={null}
    "use server";

    const USDC_TOKEN_LOCATORS = {
        solanaDevnet: "solana:4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
        baseSepolia: "base-sepolia:0x036CbD53842c5426634e7929541eC2318f3dCF7e",
        stellarTestnet: "stellar:CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA",
    };

    interface CreateOrderParams {
        walletAddress: string;
        receiptEmail: string;
        amount: string;
        chain: "solanaDevnet" | "baseSepolia" | "stellarTestnet";
    }

    export async function createOrder({ walletAddress, receiptEmail, amount, chain }: CreateOrderParams) {
        const serverApiKey = process.env.CROSSMINT_SERVER_SIDE_API_KEY;
        if (serverApiKey == null) {
            throw new Error("CROSSMINT_SERVER_SIDE_API_KEY is not set");
        }

        const response = await fetch("https://staging.crossmint.com/api/2022-06-09/orders", {
            method: "POST",
            headers: {
                "Content-Type": "application/json",
                "x-api-key": serverApiKey,
            },
            body: JSON.stringify({
                lineItems: [
                    {
                        tokenLocator: USDC_TOKEN_LOCATORS[chain],
                        executionParameters: {
                            mode: "exact-in",
                            amount,
                        },
                    },
                ],
                payment: {
                    method: "card",
                    receiptEmail,
                },
                recipient: {
                    walletAddress,
                },
            }),
        });

        if (!response.ok) {
            const error = await response.json();
            throw new Error(error.message || "Failed to create order");
        }

        return response.json();
    }
    ```
  </Step>

  <Step title="Build the onramp component">
    Create a client component that handles the order creation and displays the embedded checkout:

    ```tsx app/components/OnrampCheckout.tsx theme={null}
    "use client";

    import { useState } from "react";
    import { CrossmintProvider, CrossmintEmbeddedCheckout } from "@crossmint/client-sdk-react-ui";
    import { createOrder } from "../actions/createOrder";

    const CLIENT_API_KEY = process.env.NEXT_PUBLIC_CROSSMINT_CLIENT_SIDE_API_KEY || "";

    // Destination wallets for testing transfers on each network
    const TEST_WALLETS = {
        solanaDevnet: "<destination_wallet_address>",
        baseSepolia: "<destination_wallet_address>",
        stellarTestnet: "<destination_wallet_address>",
    };

    export default function OnrampCheckout() {
        const [order, setOrder] = useState<{ orderId: string; clientSecret: string } | null>(null);
        const [chain, setChain] = useState<"solanaDevnet" | "baseSepolia" | "stellarTestnet">("solanaDevnet");
        const [email, setEmail] = useState("user@example.com");
        const [wallet, setWallet] = useState(TEST_WALLETS.solanaDevnet);
        const [amount, setAmount] = useState("5");
        const [isLoading, setIsLoading] = useState(false);

        function handleChainChange(newChain: "solanaDevnet" | "baseSepolia" | "stellarTestnet") {
            setChain(newChain);
            setWallet(TEST_WALLETS[newChain]);
        }

        async function handleSubmit() {
            setIsLoading(true);
            try {
                const result = await createOrder({ walletAddress: wallet, receiptEmail: email, amount, chain });
                setOrder({ orderId: result.order.orderId, clientSecret: result.clientSecret });
            } catch (error) {
                console.error("Failed to create order:", error);
            } finally {
                setIsLoading(false);
            }
        }

        if (order != null) {
            return (
                <CrossmintProvider apiKey={CLIENT_API_KEY}>
                    <div className="max-w-[450px] w-full mx-auto p-6 rounded-xl bg-white">
                        <CrossmintEmbeddedCheckout
                            orderId={order.orderId}
                            clientSecret={order.clientSecret}
                            payment={{
                                receiptEmail: email,
                                crypto: { enabled: false },
                                fiat: { enabled: true },
                                defaultMethod: "fiat",
                            }}
                        />
                    </div>
                </CrossmintProvider>
            );
        }

        return (
            <div className="max-w-md mx-auto p-8 rounded-xl border border-gray-300 bg-white shadow-sm space-y-6">
                <h2 className="text-2xl font-semibold text-gray-900">Buy USDC</h2>

                <div className="space-y-2">
                    <label className="text-sm font-medium text-gray-900">Network</label>
                    <div className="grid grid-cols-3 gap-2">
                        <button
                            type="button"
                            onClick={() => handleChainChange("solanaDevnet")}
                            className={`p-3 rounded-lg border text-sm font-medium transition-colors ${
                                chain === "solanaDevnet"
                                    ? "bg-green-600 text-white border-green-600"
                                    : "bg-white text-gray-900 border-gray-300 hover:bg-gray-100"
                            }`}
                        >
                            Solana Devnet
                        </button>
                        <button
                            type="button"
                            onClick={() => handleChainChange("baseSepolia")}
                            className={`p-3 rounded-lg border text-sm font-medium transition-colors ${
                                chain === "baseSepolia"
                                    ? "bg-blue-600 text-white border-blue-600"
                                    : "bg-white text-gray-900 border-gray-300 hover:bg-gray-100"
                            }`}
                        >
                            Base Sepolia
                        </button>
                        <button
                            type="button"
                            onClick={() => handleChainChange("stellarTestnet")}
                            className={`p-3 rounded-lg border text-sm font-medium transition-colors ${
                                chain === "stellarTestnet"
                                    ? "bg-purple-600 text-white border-purple-600"
                                    : "bg-white text-gray-900 border-gray-300 hover:bg-gray-100"
                            }`}
                        >
                            Stellar Testnet
                        </button>
                    </div>
                </div>

                <div className="space-y-2">
                    <label className="text-sm font-medium text-gray-900">Email</label>
                    <input
                        type="email"
                        value={email}
                        onChange={(e) => setEmail(e.target.value)}
                        className="w-full px-3 py-2 rounded-lg border border-gray-300 bg-white text-gray-900 text-sm"
                    />
                </div>

                <div className="space-y-2">
                    <label className="text-sm font-medium text-gray-900">Recipient Wallet</label>
                    <input
                        type="text"
                        value={wallet}
                        onChange={(e) => setWallet(e.target.value)}
                        className="w-full px-3 py-2 rounded-lg border border-gray-300 bg-white text-gray-900 text-sm font-mono"
                    />
                </div>

                <div className="space-y-2">
                    <label className="text-sm font-medium text-gray-900">Amount (USD)</label>
                    <input
                        type="number"
                        value={amount}
                        onChange={(e) => setAmount(e.target.value)}
                        className="w-full px-3 py-2 rounded-lg border border-gray-300 bg-white text-gray-900 text-sm"
                    />
                </div>

                <button
                    onClick={handleSubmit}
                    disabled={isLoading || !email || !wallet}
                    className="w-full py-3 rounded-lg bg-black text-white font-medium hover:bg-gray-800 disabled:opacity-50 transition-colors"
                >
                    {isLoading ? "Creating Order..." : "Continue to Checkout"}
                </button>
            </div>
        );
    }
    ```
  </Step>

  <Step title="Add the component to your page">
    Import and render the `OnrampCheckout` component in your page:

    ```tsx app/page.tsx theme={null}
    import OnrampCheckout from "./components/OnrampCheckout";

    export default function Home() {
        return (
            <main className="min-h-screen flex items-center justify-center">
                <OnrampCheckout />
            </main>
        );
    }
    ```

    That is it! When users fill in their details and click "Continue to Checkout", the server action creates an order and the embedded checkout component handles KYC, payment, and delivery automatically.
  </Step>
</Steps>

## Onramp to External Wallets

Use this flow to onramp to external wallets — externally owned accounts (EOAs) or smart wallets not created by Crossmint.

External wallet onramp requires two additional steps compared to Crossmint wallets: linking the wallet to a Crossmint user, and handling ownership verification when transaction thresholds are exceeded.

<Steps>
  <Step title="Link the external wallet">
    Before creating an onramp order to an external wallet, you must link the wallet to a Crossmint user using the Link External Wallet API.

    Create a server action to handle the wallet linking:

    ```typescript app/actions/linkWallet.ts theme={null}
    "use server";

    interface LinkWalletParams {
        userEmail: string;
        walletAddress: string;
        chain: string;
        proof?: string;
    }

    export async function linkWallet({ userEmail, walletAddress, chain, proof }: LinkWalletParams) {
        const serverApiKey = process.env.CROSSMINT_SERVER_SIDE_API_KEY;
        if (serverApiKey == null) {
            throw new Error("CROSSMINT_SERVER_SIDE_API_KEY is not set");
        }

        const userLocator = `email:${userEmail}`;

        const body: Record<string, string> = { chain };
        if (proof) {
            body.proof = proof;
        }

        const response = await fetch(
            `https://staging.crossmint.com/api/2025-06-09/users/${userLocator}/linked-wallets/${walletAddress}`,
            {
                method: "PUT",
                headers: {
                    "Content-Type": "application/json",
                    "x-api-key": serverApiKey,
                },
                body: JSON.stringify(body),
            }
        );

        if (!response.ok) {
            const error = await response.json();
            throw new Error(error.message || "Failed to link wallet");
        }

        return response.json();
    }
    ```

    The `proof` field is optional:

    * If you omit it, the wallet is linked without proving ownership yet. The API responds with a `verificationChallenge` that you can use later to verify ownership.
    * If you pass it, you prove ownership of the wallet in the same request.
  </Step>

  <Step title="Create the server action">
    Create a server action that will create orders via the Crossmint API:

    ```typescript app/actions/createOrder.ts theme={null}
    "use server";

    const USDC_TOKEN_LOCATORS = {
        solanaDevnet: "solana:4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
        baseSepolia: "base-sepolia:0x036CbD53842c5426634e7929541eC2318f3dCF7e",
        stellarTestnet: "stellar:CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA",
    };

    interface CreateOrderParams {
        walletAddress: string;
        receiptEmail: string;
        amount: string;
        chain: "solanaDevnet" | "baseSepolia" | "stellarTestnet";
    }

    export async function createOrder({ walletAddress, receiptEmail, amount, chain }: CreateOrderParams) {
        const serverApiKey = process.env.CROSSMINT_SERVER_SIDE_API_KEY;
        if (serverApiKey == null) {
            throw new Error("CROSSMINT_SERVER_SIDE_API_KEY is not set");
        }

        const response = await fetch("https://staging.crossmint.com/api/2022-06-09/orders", {
            method: "POST",
            headers: {
                "Content-Type": "application/json",
                "x-api-key": serverApiKey,
            },
            body: JSON.stringify({
                lineItems: [
                    {
                        tokenLocator: USDC_TOKEN_LOCATORS[chain],
                        executionParameters: {
                            mode: "exact-in",
                            amount,
                        },
                    },
                ],
                payment: {
                    method: "card",
                    receiptEmail,
                },
                recipient: {
                    walletAddress,
                },
            }),
        });

        if (!response.ok) {
            const error = await response.json();
            throw new Error(error.message || "Failed to create order");
        }

        return response.json();
    }
    ```

    **Ownership verification**

    Depending on the transaction value and the user's past activity, the order may or may not require wallet ownership verification:

    * **Below threshold**: If the transaction value is below **\$1,000** **and** the user's past 30-day onramp transaction volume is below **\$1,000**, ownership verification is not required. The order proceeds directly to the KYC/payment phase.
    * **Above threshold**: If either threshold is surpassed, the order status will be `requires-recipient-verification` and the user must sign a message to prove wallet ownership.

    When ownership verification is required, the order response includes a `preparation.message` field that the user must sign:

    ```json theme={null}
    {
        "payment": {
            "status": "requires-recipient-verification",
            "preparation": {
                "message": "crossmint.com wants you to sign in with your blockchain account:\n0x1234...5678\n\n..."
            }
        }
    }
    ```
  </Step>

  <Step title="Handle wallet verification">
    If the order requires ownership verification, have the user sign the `preparation.message` with the recipient wallet. See [Onramp to Non-Crossmint Wallets](/onramp/guides/onramp-to-external-wallets) for how all wallets, including EOAs and smart contract wallets, use the same verification flow.

    <CodeGroup>
      ```js EVM (ethers.js) theme={null}
      import { Wallet } from "ethers";

      const wallet = new Wallet("YOUR_PRIVATE_KEY");
      const message = order.payment.preparation.message;
      const signature = await wallet.signMessage(message);
      ```

      ```js Solana (tweetnacl) theme={null}
      import nacl from "tweetnacl";
      import { decodeUTF8 } from "tweetnacl-util";
      import { encode as base64Encode } from "@stablelib/base64";

      const message = order.payment.preparation.message;
      const messageBytes = decodeUTF8(message);
      const signatureBytes = nacl.sign.detached(messageBytes, keypair.secretKey);
      const signature = base64Encode(signatureBytes);
      ```
    </CodeGroup>

    Once signed, submit the signature using the same Link External Wallet API by calling the `linkWallet` server action with the `proof` parameter set to the signature. Once ownership is verified, the order proceeds to the next phase (`requires-kyc` or `awaiting-payment`).
  </Step>

  <Step title="Build the onramp component">
    Create a client component that handles wallet linking, order creation, and displays the embedded checkout:

    ```tsx app/components/OnrampCheckout.tsx theme={null}
    "use client";

    import { useState } from "react";
    import { CrossmintProvider, CrossmintEmbeddedCheckout } from "@crossmint/client-sdk-react-ui";
    import { createOrder } from "../actions/createOrder";
    import { linkWallet } from "../actions/linkWallet";

    const CLIENT_API_KEY = process.env.NEXT_PUBLIC_CROSSMINT_CLIENT_SIDE_API_KEY || "";

    // Destination wallets for testing transfers on each network
    const TEST_WALLETS = {
        solanaDevnet: "YOUR_DESTINATION_WALLET_ADDRESS",
        baseSepolia: "YOUR_DESTINATION_WALLET_ADDRESS",
        stellarTestnet: "YOUR_DESTINATION_WALLET_ADDRESS",
    };

    const CHAIN_MAP = {
        solanaDevnet: "solana",
        baseSepolia: "base-sepolia",
        stellarTestnet: "stellar",
    };

    export default function OnrampCheckout() {
        const [order, setOrder] = useState<{ orderId: string; clientSecret: string } | null>(null);
        const [chain, setChain] = useState<"solanaDevnet" | "baseSepolia" | "stellarTestnet">("solanaDevnet");
        const [email, setEmail] = useState("user@example.com");
        const [wallet, setWallet] = useState(TEST_WALLETS.solanaDevnet);
        const [amount, setAmount] = useState("5");
        const [isLoading, setIsLoading] = useState(false);

        function handleChainChange(newChain: "solanaDevnet" | "baseSepolia" | "stellarTestnet") {
            setChain(newChain);
            setWallet(TEST_WALLETS[newChain]);
        }

        async function handleSubmit() {
            setIsLoading(true);
            try {
                // Step 1: Link the external wallet to the Crossmint user
                await linkWallet({
                    userEmail: email,
                    walletAddress: wallet,
                    chain: CHAIN_MAP[chain],
                });

                // Step 2: Create the onramp order
                const result = await createOrder({ walletAddress: wallet, receiptEmail: email, amount, chain });
                setOrder({ orderId: result.order.orderId, clientSecret: result.clientSecret });
            } catch (error) {
                console.error("Failed to create order:", error);
            } finally {
                setIsLoading(false);
            }
        }

        if (order != null) {
            return (
                <CrossmintProvider apiKey={CLIENT_API_KEY}>
                    <div className="max-w-[450px] w-full mx-auto p-6 rounded-xl bg-white">
                        <CrossmintEmbeddedCheckout
                            orderId={order.orderId}
                            clientSecret={order.clientSecret}
                            payment={{
                                receiptEmail: email,
                                crypto: { enabled: false },
                                fiat: { enabled: true },
                                defaultMethod: "fiat",
                            }}
                        />
                    </div>
                </CrossmintProvider>
            );
        }

        return (
            <div className="max-w-md mx-auto p-8 rounded-xl border border-gray-300 bg-white shadow-sm space-y-6">
                <h2 className="text-2xl font-semibold text-gray-900">Buy USDC</h2>

                <div className="space-y-2">
                    <label className="text-sm font-medium text-gray-900">Network</label>
                    <div className="grid grid-cols-3 gap-2">
                        <button
                            type="button"
                            onClick={() => handleChainChange("solanaDevnet")}
                            className={`p-3 rounded-lg border text-sm font-medium transition-colors ${
                                chain === "solanaDevnet"
                                    ? "bg-green-600 text-white border-green-600"
                                    : "bg-white text-gray-900 border-gray-300 hover:bg-gray-100"
                            }`}
                        >
                            Solana Devnet
                        </button>
                        <button
                            type="button"
                            onClick={() => handleChainChange("baseSepolia")}
                            className={`p-3 rounded-lg border text-sm font-medium transition-colors ${
                                chain === "baseSepolia"
                                    ? "bg-blue-600 text-white border-blue-600"
                                    : "bg-white text-gray-900 border-gray-300 hover:bg-gray-100"
                            }`}
                        >
                            Base Sepolia
                        </button>
                        <button
                            type="button"
                            onClick={() => handleChainChange("stellarTestnet")}
                            className={`p-3 rounded-lg border text-sm font-medium transition-colors ${
                                chain === "stellarTestnet"
                                    ? "bg-purple-600 text-white border-purple-600"
                                    : "bg-white text-gray-900 border-gray-300 hover:bg-gray-100"
                            }`}
                        >
                            Stellar Testnet
                        </button>
                    </div>
                </div>

                <div className="space-y-2">
                    <label className="text-sm font-medium text-gray-900">Email</label>
                    <input
                        type="email"
                        value={email}
                        onChange={(e) => setEmail(e.target.value)}
                        className="w-full px-3 py-2 rounded-lg border border-gray-300 bg-white text-gray-900 text-sm"
                    />
                </div>

                <div className="space-y-2">
                    <label className="text-sm font-medium text-gray-900">Recipient Wallet</label>
                    <input
                        type="text"
                        value={wallet}
                        onChange={(e) => setWallet(e.target.value)}
                        className="w-full px-3 py-2 rounded-lg border border-gray-300 bg-white text-gray-900 text-sm font-mono"
                    />
                </div>

                <div className="space-y-2">
                    <label className="text-sm font-medium text-gray-900">Amount (USD)</label>
                    <input
                        type="number"
                        value={amount}
                        onChange={(e) => setAmount(e.target.value)}
                        className="w-full px-3 py-2 rounded-lg border border-gray-300 bg-white text-gray-900 text-sm"
                    />
                </div>

                <button
                    onClick={handleSubmit}
                    disabled={isLoading || !email || !wallet}
                    className="w-full py-3 rounded-lg bg-black text-white font-medium hover:bg-gray-800 disabled:opacity-50 transition-colors"
                >
                    {isLoading ? "Creating Order..." : "Continue to Checkout"}
                </button>
            </div>
        );
    }
    ```
  </Step>

  <Step title="Add the component to your page">
    Import and render the `OnrampCheckout` component in your page:

    ```tsx app/page.tsx theme={null}
    import OnrampCheckout from "./components/OnrampCheckout";

    export default function Home() {
        return (
            <main className="min-h-screen flex items-center justify-center">
                <OnrampCheckout />
            </main>
        );
    }
    ```

    That is it! When users fill in their details and click "Continue to Checkout", the app links the external wallet, creates an order, and the embedded checkout component handles KYC, payment, and delivery automatically.
  </Step>
</Steps>

<Tip>
  **Testing:** Use the test credit card number `4242 4242 4242 4242` with any future expiration date and any 3-digit CVC.
</Tip>

## Transaction Completion

<Snippet />

## Next Steps

<Snippet />


# React Native
Source: https://docs.crossmint.com/onramp/quickstarts/react-native

Allow your mobile users to buy stablecoins with cards

In this guide, you will learn how to:

* Install the React Native SDK
* Create an Onramp order for your authenticated users
* Use the embedded checkout component to handle KYC, payment, and delivery

<Frame type="simple">
  <img alt="Crossmint Onramp Embedded Checkout Demo" />
</Frame>

<CardGroup>
  <Snippet />

  <Card title="Onramp Embedded Quickstart" icon="github" href="https://github.com/Crossmint/onramp-embedded-quickstart">
    See a full working example.
  </Card>
</CardGroup>

<Note>
  You can test the Onramp self-serve in staging. To enable it in production, <a href="https://www.crossmint.com/contact/sales">contact sales</a>.
</Note>

## Prerequisites

* React Native 0.60+
* Expo (recommended) or bare React Native CLI
* iOS 13.0+ / Android 5.0+

<Snippet />

* Create a [server-side API key](https://docs.crossmint.com/introduction/platform/api-keys/server-side) with the
  `orders.create` and `orders.read` scopes enabled.
  <br />
  Create a [client-side API key](https://docs.crossmint.com/introduction/platform/api-keys/client-side) for the
  embedded checkout component.
* Add environment variables to your `.env.local`:

  ```bash .env.local theme={null}
  EXPO_PUBLIC_CROSSMINT_CLIENT_SIDE_API_KEY="_YOUR_CLIENT_API_KEY_"
  ```

  <Note>For Expo projects, use the `EXPO_PUBLIC_` prefix. For bare React Native, configure environment variables according to your setup.</Note>

## Add Onramp to Your App

<Steps>
  <Step title="Create the API endpoint">
    <Note>
      If you want to enable onramp orders to external wallets (EOAs or third-party smart wallets) instead of Crossmint wallets, see the [Onramp to External Wallets](/onramp/guides/onramp-to-external-wallets) guide before proceeding.
    </Note>

    To initiate an onramp, you must first create a purchase order on your backend. This example uses Express, but you can use any backend framework:

    ```typescript server/createOrder.ts theme={null}
    import express from "express";

    const app = express();
    app.use(express.json());

    const USDC_TOKEN_LOCATORS = {
        solanaDevnet: "solana:4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
        baseSepolia: "base-sepolia:0x036CbD53842c5426634e7929541eC2318f3dCF7e",
        stellarTestnet: "stellar:CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA",
    };

    app.post("/api/create-order", async (req, res) => {
        const { walletAddress, receiptEmail, amount, chain } = req.body;
        const serverApiKey = process.env.CROSSMINT_SERVER_SIDE_API_KEY;

        if (serverApiKey == null) {
            return res.status(500).json({ error: "Server API key not configured" });
        }

        const response = await fetch("https://staging.crossmint.com/api/2022-06-09/orders", {
            method: "POST",
            headers: {
                "Content-Type": "application/json",
                "x-api-key": serverApiKey,
            },
            body: JSON.stringify({
                lineItems: [
                    {
                        tokenLocator: USDC_TOKEN_LOCATORS[chain],
                        executionParameters: {
                            mode: "exact-in",
                            amount,
                        },
                    },
                ],
                payment: {
                    method: "card",
                    receiptEmail,
                },
                recipient: {
                    walletAddress,
                },
            }),
        });

        if (!response.ok) {
            const error = await response.json();
            return res.status(response.status).json(error);
        }

        const data = await response.json();
        res.json(data);
    });

    app.listen(3000);
    ```
  </Step>

  <Step title="Build the onramp checkout UI in your app">
    Now let's go to your app. Create a React Native screen that handles order creation and displays a checkout:

    ```tsx screens/OnrampScreen.tsx theme={null}
    import { useState } from "react";
    import { View, Text, TextInput, TouchableOpacity, StyleSheet, ActivityIndicator } from "react-native";
    import { CrossmintProvider, CrossmintEmbeddedCheckout } from "@crossmint/client-sdk-react-native-ui";

    const CLIENT_API_KEY = process.env.EXPO_PUBLIC_CROSSMINT_CLIENT_SIDE_API_KEY || "";
    const API_URL = "http://localhost:3000"; // Replace with your backend URL

    // Destination wallets for testing transfers on each network
    const TEST_WALLETS = {
        solanaDevnet: "<destination_wallet_address>",
        baseSepolia: "<destination_wallet_address>",
        stellarTestnet: "<destination_wallet_address>",
    };

    type Chain = "solanaDevnet" | "baseSepolia" | "stellarTestnet";

    export default function OnrampScreen() {
        const [order, setOrder] = useState<{ orderId: string; clientSecret: string } | null>(null);
        const [chain, setChain] = useState<Chain>("solanaDevnet");
        const [email, setEmail] = useState("user@example.com");
        const [wallet, setWallet] = useState(TEST_WALLETS.solanaDevnet);
        const [amount, setAmount] = useState("5");
        const [isLoading, setIsLoading] = useState(false);

        function handleChainChange(newChain: Chain) {
            setChain(newChain);
            setWallet(TEST_WALLETS[newChain]);
        }

        async function handleSubmit() {
            setIsLoading(true);
            try {
                const response = await fetch(`${API_URL}/api/create-order`, {
                    method: "POST",
                    headers: { "Content-Type": "application/json" },
                    body: JSON.stringify({ walletAddress: wallet, receiptEmail: email, amount, chain }),
                });
                if (!response.ok) {
                    throw new Error("Failed to create order");
                }
                const result = await response.json();
                setOrder({ orderId: result.order.orderId, clientSecret: result.clientSecret });
            } catch (error) {
                console.error("Failed to create order:", error);
            } finally {
                setIsLoading(false);
            }
        }

        if (order != null) {
            return (
                <CrossmintProvider apiKey={CLIENT_API_KEY}>
                    <View style={styles.checkoutContainer}>
                        <CrossmintEmbeddedCheckout
                            orderId={order.orderId}
                            clientSecret={order.clientSecret}
                            payment={{
                                receiptEmail: email,
                                crypto: { enabled: false },
                                fiat: { enabled: true },
                                defaultMethod: "fiat",
                            }}
                        />
                    </View>
                </CrossmintProvider>
            );
        }

        return (
            <View style={styles.container}>
                <Text style={styles.title}>Buy USDC</Text>

                <View style={styles.fieldGroup}>
                    <Text style={styles.label}>Network</Text>
                    <View style={styles.toggleRow}>
                        <TouchableOpacity
                            style={[styles.toggleButton, chain === "solanaDevnet" && styles.toggleButtonActiveSolana]}
                            onPress={() => handleChainChange("solanaDevnet")}
                        >
                            <Text style={[styles.toggleText, chain === "solanaDevnet" && styles.toggleTextActive]}>
                                Solana Devnet
                            </Text>
                        </TouchableOpacity>
                        <TouchableOpacity
                            style={[styles.toggleButton, chain === "baseSepolia" && styles.toggleButtonActiveBase]}
                            onPress={() => handleChainChange("baseSepolia")}
                        >
                            <Text style={[styles.toggleText, chain === "baseSepolia" && styles.toggleTextActive]}>
                                Base Sepolia
                            </Text>
                        </TouchableOpacity>
                        <TouchableOpacity
                            style={[styles.toggleButton, chain === "stellarTestnet" && styles.toggleButtonActiveStellar]}
                            onPress={() => handleChainChange("stellarTestnet")}
                        >
                            <Text style={[styles.toggleText, chain === "stellarTestnet" && styles.toggleTextActive]}>
                                Stellar Testnet
                            </Text>
                        </TouchableOpacity>
                    </View>
                </View>

                <View style={styles.fieldGroup}>
                    <Text style={styles.label}>Email</Text>
                    <TextInput
                        style={styles.input}
                        value={email}
                        onChangeText={setEmail}
                        keyboardType="email-address"
                        autoCapitalize="none"
                    />
                </View>

                <View style={styles.fieldGroup}>
                    <Text style={styles.label}>Recipient Wallet</Text>
                    <TextInput
                        style={[styles.input, styles.monoInput]}
                        value={wallet}
                        onChangeText={setWallet}
                        autoCapitalize="none"
                    />
                </View>

                <View style={styles.fieldGroup}>
                    <Text style={styles.label}>Amount (USD)</Text>
                    <TextInput
                        style={styles.input}
                        value={amount}
                        onChangeText={setAmount}
                        keyboardType="numeric"
                    />
                </View>

                <TouchableOpacity
                    style={[styles.submitButton, (isLoading || !email || !wallet) && styles.submitButtonDisabled]}
                    onPress={handleSubmit}
                    disabled={isLoading || !email || !wallet}
                >
                    {isLoading ? (
                        <ActivityIndicator color="#fff" />
                    ) : (
                        <Text style={styles.submitButtonText}>Continue to Checkout</Text>
                    )}
                </TouchableOpacity>
            </View>
        );
    }

    const styles = StyleSheet.create({
        container: {
            flex: 1,
            padding: 24,
            backgroundColor: "#fff",
        },
        checkoutContainer: {
            flex: 1,
            backgroundColor: "#fff",
        },
        title: {
            fontSize: 24,
            fontWeight: "600",
            color: "#111",
            marginBottom: 24,
        },
        fieldGroup: {
            marginBottom: 20,
        },
        label: {
            fontSize: 14,
            fontWeight: "500",
            color: "#111",
            marginBottom: 8,
        },
        toggleRow: {
            flexDirection: "row",
            gap: 8,
        },
        toggleButton: {
            flex: 1,
            padding: 12,
            borderRadius: 8,
            borderWidth: 1,
            borderColor: "#d1d5db",
            backgroundColor: "#fff",
            alignItems: "center",
        },
        toggleButtonActiveSolana: {
            backgroundColor: "#16a34a",
            borderColor: "#16a34a",
        },
        toggleButtonActiveBase: {
            backgroundColor: "#2563eb",
            borderColor: "#2563eb",
        },
        toggleButtonActiveStellar: {
            backgroundColor: "#9333ea",
            borderColor: "#9333ea",
        },
        toggleText: {
            fontSize: 14,
            fontWeight: "500",
            color: "#111",
        },
        toggleTextActive: {
            color: "#fff",
        },
        input: {
            borderWidth: 1,
            borderColor: "#d1d5db",
            borderRadius: 8,
            padding: 12,
            fontSize: 14,
            color: "#111",
            backgroundColor: "#fff",
        },
        monoInput: {
            fontFamily: "monospace",
        },
        submitButton: {
            backgroundColor: "#000",
            padding: 16,
            borderRadius: 8,
            alignItems: "center",
            marginTop: 8,
        },
        submitButtonDisabled: {
            opacity: 0.5,
        },
        submitButtonText: {
            color: "#fff",
            fontSize: 16,
            fontWeight: "500",
        },
    });
    ```
  </Step>

  <Step title="Add the screen to your app">
    Import and render the `OnrampScreen` in your app:

    ```tsx App.tsx theme={null}
    import { SafeAreaView, StyleSheet } from "react-native";
    import OnrampScreen from "./screens/OnrampScreen";

    export default function App() {
        return (
            <SafeAreaView style={styles.container}>
                <OnrampScreen />
            </SafeAreaView>
        );
    }

    const styles = StyleSheet.create({
        container: {
            flex: 1,
            backgroundColor: "#fff",
        },
    });
    ```

    That is it! When users fill in their details and tap "Continue to Checkout", the API creates an order and the embedded checkout component handles KYC, payment, and delivery automatically.

    <Tip>
      **Testing:** Use the test credit card number `4242 4242 4242 4242` with any future expiration date and any 3-digit CVC.
    </Tip>
  </Step>
</Steps>

## Transaction Completion

<Snippet />

## Next Steps

<Snippet />


# Swift
Source: https://docs.crossmint.com/onramp/quickstarts/swift

Allow your iOS users to buy stablecoins with credit cards and Apple Pay

In this guide, you'll learn how to:

* Install the Swift SDK
* Create an Onramp order for your authenticated users
* Use the embedded checkout component to handle KYC, payment, and delivery

<Frame type="simple">
  <img alt="Crossmint Onramp Embedded Checkout Demo" />
</Frame>

<CardGroup>
  <Snippet />

  <Card title="Swift SDK on GitHub" icon="github" href="https://github.com/Crossmint/crossmint-checkout-swift">
    View the open source Swift Checkout SDK repository.
  </Card>
</CardGroup>

<Snippet />

## Prerequisites

* **iOS 14.0+**
* **SwiftUI** framework
* Xcode 13.0 or later

Install the Crossmint Swift SDK using Swift Package Manager.

In Xcode, go to **File > Add Package Dependencies** and add:

```text theme={null}
https://github.com/Crossmint/crossmint-checkout-swift
```

Select the `CrossmintCheckout` product for your target.

* Create a [server-side API key](https://docs.crossmint.com/introduction/platform/api-keys/server-side) with the
  `orders.create` and `orders.read` scopes enabled. In staging, all scopes are included in your API key.

## Add Onramp to Your App

<Steps>
  <Step title="Create the order">
    <Note>
      If you want to enable onramp orders to external wallets (EOAs or third-party smart wallets) instead of Crossmint wallets, see the [Onramp to External Wallets](/onramp/guides/onramp-to-external-wallets) guide before proceeding.
    </Note>

    Use the [Create Order API](/api-reference/headless/create-order) to initiate the purchase process from your backend.

    <Snippet />
  </Step>

  <Step title="Use the checkout component">
    Once you have the order response with `orderId` and `clientSecret`, use Crossmint's embedded checkout component in your SwiftUI view.

    The component supports **native Apple Pay** for a seamless iOS payment experience.

    ```swift theme={null}
    import SwiftUI
    import CrossmintCheckout

    struct ContentView: View {
        var body: some View {
            CrossmintEmbeddedCheckout(
                orderId: <your_order_id>,
                clientSecret: <your_client_secret>,
                payment: CheckoutPayment(
                    crypto: CheckoutCryptoPayment(enabled: false),
                    fiat: CheckoutFiatPayment(
                        enabled: true,
                        allowedMethods: CheckoutAllowedMethods(
                            googlePay: false,
                            applePay: true,  // Native Apple Pay support
                            card: true
                        )
                    )
                ),
                appearance: CheckoutAppearance(
                    rules: CheckoutAppearanceRules(
                        destinationInput: CheckoutDestinationInputRule(display: "hidden"),
                        receiptEmailInput: CheckoutReceiptEmailInputRule(display: "hidden")
                    )
                )
            )
        }
    }
    ```

    **Key features:**

    * **Native Apple Pay**: Smooth integration with iOS payment system
    * **SwiftUI Components**: Modern declarative UI framework
    * **Automatic KYC**: Handles verification flow automatically
    * **Customizable Appearance**: Control visibility of UI elements
  </Step>

  <Step title="Track the order">
    <Snippet />
  </Step>
</Steps>

## Transaction Completion

<Snippet />

## Next Steps

<Snippet />

* View the <a href="https://github.com/Crossmint/crossmint-checkout-swift">Swift Checkout SDK source code</a> on GitHub


# NFT Drops Gated by Accesslists
Source: https://docs.crossmint.com/payments/advanced/accesslists

Allow purchasing in accesslist-protected NFT drops

## Access Lists

<Note>
  Accesslist support is a premium feature. To get started, [contact sales](https://www.crossmint.com/contact/sales)
</Note>

Crossmint allows you to whitelist both wallet and email addresses. Once the team
has approved your request, you will need to provide the following information:

1. Your Crossmint `clientId` or `collectionId` for the collection.

2. The list of wallet and email addresses to be included in the accesslist.

<Tip>
  If you whitelist users' email addresses, Crossmint will create wallets associated with those email addresses and
  provide them to you for inclusion in the accesslist. Users will then be able to authenticate during the purchase and
  execute the transaction.
</Tip>

<Tabs>
  <Tab title="EVM">
    You can set up accesslists using Merkle Trees or inserting the list of whitelisted addresses directly on the smart contract:

    ### A. Merkle Tree Accesslists

    While using Merkle Trees is more gas-efficient, it involves a slightly more complex setup.
    Here is an example accesslist mint function:

    <Accordion title="See Example">
      ```solidity Solidity theme={null}
      //SPDX-License-Identifier: Unlicense
      pragma solidity ^0.8.0;

      import "@openzeppelin/contracts/utils/cryptography/MerkleProof.sol";
      import "@openzeppelin/contracts/token/ERC721/ERC721.sol";
      import "@openzeppelin/contracts/access/Ownable.sol";

      contract Accesslist is ERC721, Ownable {
          bytes32 public merkleRoot;
          uint256 public nextTokenId;
          mapping(address => bool) public claimed;

          constructor() ERC721("ExampleNFT", "NFT") {
              merkleRoot = 0x0;
          }

          function isWhiteListed(bytes32[] memory proof, bytes32 leaf) public view returns(bool) {
              return MerkleProof.verify(proof, merkleRoot, leaf);
          }

          function setMerkleRoot(bytes32 merkleRoot_) external onlyOwner {
              merkleRoot = merkleRoot_;
          }

          function mint(address to, bytes32[] calldata merkleProof) public payable {
              require(claimed[to] == false, "already claimed");
              claimed[to] = true;
              require(
                  isWhiteListed(
                      merkleProof,
                      keccak256(abi.encodePacked(to))
                  ),
                  "invalid merkle proof"
              );
              nextTokenId++;
              _mint(to, nextTokenId);
          }
      }
      ```
    </Accordion>

    ### B. Mapping-Based Accesslists

    The most straightforward method of whitelisting involves maintaining
    a mapping of the whitelisted addresses within your smart contract.
    This approach is faster but consumes more gas and savvy developers
    may be able to determine the addresses of the accesslist.

    <Accordion title="See Example">
      ```solidity Solidity theme={null}
      mapping(address => uint256) public whitelistMapping;
      ```

      ```solidity Solidity theme={null}
      function presale(address _to, uint256 _count) external payable {
          // ensure _to address has tokens left to mint
          require(whitelistMapping[_to] > 0, "no whitelist tokens for user");

          // decrement mapping for user
          whitelistMapping[_to] -= _count;

          // presale minting logic here
      }
      ```
    </Accordion>
  </Tab>

  <Tab title="Solana">
    You can set up accesslists on your Candy Machine using Merkle Trees or SPL Tokens

    ### A. Merkle Tree Accesslists

    Simply send the user IDs to Crossmint. Once you have the Merkle proof, you can pass it into the Crossmint Hosted Checkout `lineItems.callData` as a string, as in the example below:

    <Accordion title="See Example">
      ```jsx React theme={null}
      <CrossmintProvider apiKey="_YOUR_CLIENT_API_KEY_">
          <CrossmintHostedCheckout
              lineItems={{
                  collectionId: "crossmint:_YOUR_COLLECTION_ID_",
                  callData: {
                      type: "candy-machine",
                      quantity: 1,
                      mintingGroup: "pre",
                      merkleProof: "62, 43, 204, 46, 222, 219, 236, 32, 60, 4, 235, [...]",
                  }
              }}
          />
      </CrossmintProvider>
      ```
    </Accordion>

    ### B. SPL Token-based Accesslists

    You can whitelist wallets by airdropping them SPL tokens.
  </Tab>
</Tabs>

## Geofencing

<Note>
  Geofencing support is a premium feature only available to customers on a paid plan. To get started, [contact
  sales](https://www.crossmint.com/contact/sales)
</Note>

Crossmint supports geofencing capabilities through our Customer Success Engineering (CSE) team. Our CSE team can work with you to block transactions from specific countries or geographic regions via Stripe rules.

To set up geofencing for your project, please contact our sales team to discuss your specific requirements and implementation details.


# NFT Drops with Dynamic Price or Quantity
Source: https://docs.crossmint.com/payments/advanced/dynamic-quantity-and-price

Details about implementing dynamic functionality into the Checkout

See the below examples to understand how to implement dynamic pricing or quantity into your dApp.

<Check>
  The examples below use the [Hosted Checkout](/payments/pay-button/overview), but the same approach is compatible
  with the [Embedded Checkout](/payments/embedded/overview) as well.
</Check>

<CodeGroup>
  ```jsx React theme={null}
  import { useState } from 'react';
  import { CrossmintProvider, CrossmintHostedCheckout } from "@crossmint/client-sdk-react-ui";

  function App() {
      const [mintAmount, setMintAmount] = useState(1);
      const nftCost = 0.001;
      const apiClientId = '_YOUR_API_CLIENT_ID_';
      const collectionId = '_YOUR_COLLECTION_ID_';

      const handleDecrement = () => {
          if (mintAmount <= 1) return;
          setMintAmount(mintAmount - 1);
      }

      const handleIncrement = () => {
          if (mintAmount >= 3) return;
          setMintAmount(mintAmount + 1);
      }

      return (
          <CrossmintProvider apiKey={apiClientId}>
              <>
                  <button onClick={handleDecrement}> - </button>
                  <input
                      readOnly
                      type="number"
                      value={mintAmount}
                  />
                  <button onClick={handleIncrement}> + </button>
                  <CrossmintHostedCheckout
                      lineItems={
                          {
                              collectionId: collectionId,
                              callData: {
                                  totalPrice: (nftCost * mintAmount).toString(),
                                  _quantity: mintAmount // the `_quantity` property should match what is in your mint function
                                  // your custom minting arguments...
                              }
                          }
                      }
                  />
              </>
          </CrossmintProvider>
      );
  }

  export default App;
  ```
</CodeGroup>


# Improving Conversion
Source: https://docs.crossmint.com/payments/advanced/improving-conversion

Best practices to maximize checkout conversion

Here are a selection of best practices you can follow to optimize conversion on your checkout flow.

## 1. Ensure your checkout has the right locale

Improper locales can significantly reduce conversion. Double check that your checkout is configured to work in the locales you have customers.

You can manage the locale in your [integrated checkout components](/sdk-reference/checkout/react/components), or your [payment order objects.](/payments/headless/guides/order-lifecycle/quote-phase#update-the-locale)

## 2. Choose the best payment methods

You may have data that shows your customers convert better with one payment method over another one. Customizing your checkout to feature these preferred payment methods by default is a good way to improve your conversion.

**Embedded Checkout** - Set the default payment method as your customers most preferred one (i.e. Apple Pay, Sol, etc.)

**Headless Checkout** - you have full control over your UI. Put the payment method your customers prefer as default option, and pre-fill as much information as you can.

## 3. Further customize your checkout flow

You may know your customer very well, and what exactly increases conversion for them: large images, progress bars, loyalty point reward offers.

Building these bespoke checkout experiences can increase your conversion. [Embedded](/payments/embedded/overview) or [headless checkout](/payments/headless/overview) are more customizable checkout tools.


# NFT Marketplaces & Launchpads
Source: https://docs.crossmint.com/payments/advanced/marketplaces-and-launchpads

Add fiat and cross-chain crypto payments to your platform

<Accordion title="Additional services offered to marketplaces and launchpads">
  Crossmint offers additional services to marketplaces and launchpads,
  including:

  * Custom branding and email receipts

  * Dedicated Slack channel with Crossmint's support team

  * Custom SLAs

  * APIs to register new collections programmatically

  * Increased purchase limits

  * Cart mode and ability to sweep the floor

  ...and more
</Accordion>

<Tabs>
  <Tab title="Marketplaces">
    ### Integrating Crossmint into a marketplace

    Integrating Crossmint into a marketplace can be as simple as
    adding five lines of code, depending on the level of customization required.

    The following snippet would be sufficient to render a button that enables
    the purchase of one of your listings with credit card.

    <CodeGroup>
      ```jsx EVM theme={null}
      <CrossmintProvider apiKey="_YOUR_CLIENT_API_KEY_">
        <CrossmintHostedCheckout
          lineItems={{
              tokenLocator: "ethereum:0xbC…307e:7777",
              callData: {
                totalPrice: "0.1"
              }
            }}
        />
      </CrossmintProvider>
      ```

      ```jsx Solana theme={null}
      <CrossmintProvider apiKey="_YOUR_CLIENT_API_KEY_">
        <CrossmintHostedCheckout
          lineItems={{
              tokenLocator: "solana:4oDd…x6NC",
              callData: {
                totalPrice: "0.1",
                buyerCreatorRoyaltyPercent: 100
              }
            }}
        />
      </CrossmintProvider>
      ```
    </CodeGroup>

    <br />

    <Note>[Contact sales](https://www.crossmint.com/contact/sales) to get started.</Note>
    <Tip>If you are building a new marketplace, use one of the supported contracts for a faster integration. If you are looking for help building a marketplace, [contact us](https://www.crossmint.com/contact/sales) and the Crossmint team will introduce you to the right partner.</Tip>

    ### FAQs

    <AccordionGroup>
      <Accordion title="What marketplaces are supported">
        <Snippet />
      </Accordion>

      <Accordion title="Supported contracts">
        Crossmint supports a wide range of contracts across chains, including:

        | Blockchain | Contract |
        | :- | :- |
        | EVM | Rarible, Seaport, OpenSea, Zora, LooksRare, 0x, Foundation, CoinbaseNFT, Sudoswap, Manifold |
        | Solana | Auction House, Magic Eden API, Exchange.art |

        <Note>Custom integrations available only for enterprise clients.</Note>
      </Accordion>

      <Accordion title="Where can I test it?">
        You can see a live implementation of the payment button on [Tensor](https://tensor.trade/).
      </Accordion>

      <Accordion title="What is the maximum transaction limit?">
        The default transaction limit is 7,000 USD. If you need a higher limit, [contact us](https://www.crossmint.com/contact/sales)
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Launchpads">
    ### Integrating Crossmint into a launchpad

    The integration is identical to that of the standard digital asset checkout. However, Crossmint offers additional services to improve the creator experience, including the ability to register collections via API.

    <br />

    <Note>[Contact sales](https://www.crossmint.com/contact/sales) to get started.</Note>

    ### FAQs

    <Accordion title="Where can I test it?">
      Crossmint powers most major launchpads across chains. You can see in action on [Manifold](https://app.manifold.xyz/c/sleeping-potato) and [Highlight](https://highlight.xyz/mint/6525a4b606bc6fa5b8acdcfa).
    </Accordion>

    <Accordion title="How does creator and collection verification work?">
      For primary sales, Crossmint requires creators to do <Tooltip>light KYC</Tooltip> and confirm their project meets Crossmint's [content policy](https://drive.google.com/file/d/1kXv5gX7C8xHJFDAnCQTNUmXrDP05YYk1/view). There are multiple options to achieve this:

      * You can conduct project verification yourself.
      * You can send creators to register their collection at Crossmint.com and share their collectionID with you, so you can pass it to the digital asset checkout.
      * (Coming soon) You can use Crossmint's collection verification SDK to verify creators directly on your site.
    </Accordion>
  </Tab>
</Tabs>


# Mint to Specific Template
Source: https://docs.crossmint.com/payments/advanced/mint-to-specific-template

Specify which NFT template to mint from during checkout (for Managed collections only)

## Overview

When minting NFTs from a collection with multiple templates, you can specify which template to mint to using your Crossmint integration. This feature must be explicitly enabled in the Crossmint Console.

This gives you control over exactly which template gets minted when processing a purchase, rather than relying on random template selection.

## Supported Collection Types

Selecting a specific token template for purchase is supported on:

* EVM ERC-721 and ERC-1155 collections
* Solana collections

In the following chains, tokens will always be selected randomly:

* Aptos collections

## Enabling Template Minting

Follow these steps in the Crossmint Console to enable template-specific minting:

1. Go to your collection in the Crossmint Console
2. Navigate to the "Checkout" section
3. Under "NFT Template Settings", enable "Mint to specific NFT Template"

<img alt="" />

## Using Template IDs

<Warning>
  If template-specific minting is disabled for your collection and you pass a template ID in the collection locator,
  the request will select a template randomly. Make sure to enable this feature in the Console before using template IDs.
</Warning>

<Note>
  To see all your available templates, navigate to the "NFTs" section in the Console for your managed collection.

  You can also get all your available templates for a collection using the [NFT Template API](/api-reference/minting/template/get-all-templates).
</Note>

Once enabled, specify which template to mint by adding the template ID to your collection locator. The collection locator format without templateId is:

```
crossmint:<collectionId>
```

and with templateId is:

```
crossmint:<collectionId>:<templateId>
```

The `templateId` portion is optional with mint to specific template enabled. If omitted, the system will use your collection's default minting behavior.

Here's how to implement template minting in your integration:

<Tabs>
  <Tab title="Embedded Checkout v3">
    Add the template ID to your collection locator string:

    ```jsx theme={null}
    <CrossmintProvider apiKey={clientApiKey}>
      <CrossmintEmbeddedCheckout
        lineItems={{
          // For a specific template:
          collectionLocator: `crossmint:${collectionId}:${templateId}`,
          // Or for random template selection:
          // collectionLocator: `crossmint:${collectionId}`,
          callData: {
            totalPrice: "0.001",
            quantity: 1,
          },
        }}
      />
    </CrossmintProvider>
    ```
  </Tab>

  <Tab title="Headless Checkout">
    Add the template ID to your collection locator string when creating an order:

    ```json theme={null}
    {
      "payment": {
        "method": "card"  // or your preferred payment method
      },
      "lineItems": [
        {
          // For a specific template:
          "collectionLocator": "crossmint:<collectionId>:<templateId>",
          // Or for random template selection:
          // "collectionLocator": "crossmint:<collectionId>",
          "callData": {
            "totalPrice": "0.001"
          }
        }
      ]
    }
    ```
  </Tab>
</Tabs>

## Error Handling

When implementing template minting, handle these potential error cases:

1. **Invalid Template ID**

   * Error message: Transaction fails with template validation error
   * Occurs when: The specified template ID doesn't exist in the collection
   * Resolution: Verify the template ID exists in your collection

Here's how to handle these errors in your code:

<Tabs>
  <Tab title="Embedded Checkout v3">
    ```jsx theme={null}
    try {
      <CrossmintProvider apiKey={clientApiKey}>
        <CrossmintEmbeddedCheckout
          lineItems={{
            collectionLocator: `crossmint:${collectionId}:${templateId}`,
            callData: {
              totalPrice: "0.001",
              quantity: 1,
            },
          }}
          onError={(error) => {
            if (error.message.includes(`Template ${templateId} was not found in collection`)) {
              // Invalid template ID
              throw new Error("Invalid template ID provided");
            }
            throw error
          }}
        />
      </CrossmintProvider>
    } catch (error) {
      // Handle other errors
      console.error("Minting failed:", error);
    }
    ```
  </Tab>

  <Tab title="Headless Checkout">
    ```typescript theme={null}
    try {
      const response = await fetch("/api/create-order", {
        method: "POST",
        body: JSON.stringify({
          lineItems: [
            {
              collectionLocator: `crossmint:${collectionId}:${templateId}`,
              callData: {
                totalPrice: "0.001"
              }
            }
          ]
        })
      });

      if (!response.ok) {
        const error = await response.json();
        if (error.message.includes(`Template ${templateId} was not found in collection`)) {
          // Invalid template ID
          throw new Error("Invalid template ID provided");
        }
        throw error;
      }
    } catch (error) {
      // Handle the error appropriately
      console.error("Order creation failed:", error);
    }
    ```
  </Tab>
</Tabs>


# Receipt Customization
Source: https://docs.crossmint.com/payments/advanced/receipt-customization

Customize your users' order receipt

Customizing the order receipt that gets sent to your users' email addresses is possible under our Enterprise plan.

## Elements that can be customized

* **Subject**: the subject of the email.
* **Header**: the header of the email.
* **Body**: the body of the receipt within the email.
* **Company logo**: you can add your company logo.
* **Remove Crossmint's links**: you can also remove Crossmint's social links and buttons (included in the default receipt sent).
* **Remove transaction hash**: you can also remove the transaction hash (included in the default receipt sent).

## Elements that cannot be customized

* You cannot include the user's name in the receipt as this information is not always available.
* You cannot remove the "Payment powered by Crossmint" message on the footer for compliance.

<Note>Please contact your Crossmint customer success engineer and provide them with the above information.</Note>

<AccordionGroup>
  <Accordion title="What does the default purchase receipt look like?">
    Here is an example of the default purchase receipt that is emailed to users:

    <img alt="Crossmint default purchase receipt" />
  </Accordion>

  <Accordion title="What does a customized purchase receipt look like?">
    Here is an example of a customized purchase receipt that is emailed to users:

    <img alt="Crossmint customized purchase receipt" />
  </Accordion>
</AccordionGroup>


# Collection Registration and Verification API
Source: https://docs.crossmint.com/payments/advanced/registration-and-verification-api

Launchpads now use Crossmint's API to register and verify a collection.

Crossmint provides an API to facilitate collection registration and verification. This functionality is for launchpads that want to use Crossmint's checkout and allow their users to go through the KYC and collection verification flow.

## Before you get started:

Contact your Crossmint customer success engineer to request the `collections.write` scope be added to an existing API key. You will need to provide the projectId associated with the API key you will be using.

Your contract also needs to meet certain requirements. Please refer to the [Register External Collection](/payments/guides/register-collection) documentation page for further information.

<Note>Please do not share your API key secret with the Crossmint team or anyone else.</Note>

## Collection Registration and Verification process

Once a user has created a collection on your launchpad, you can optionally choose to register the collection with Crossmint to enable Credit Card payments. This API abstracts away much of the complexity involved from the user when they perform KYC and the collection verification process.

As the launchpad, you will pass information about the collection as parameters to the API. Crossmint will then return a URL where the user can complete the KYC and collection verification. This API call's structure is as follows:

<Tab title="Hosted Checkout">
  Sample code for the collection registration and verification API. Click on "Response" to see what a successful response will look like.

  <CodeGroup>
    ```jsx JavaScript theme={null}
       // Define the API URL
       const apiUrl = "https://staging.crossmint.com/api/v1-alpha1/collections";

       // Set up the request body with actual data instead of placeholders
       const requestBody = {
          chain: "ethereum", // replace with actual chain name
          contractType: "erc-721", // choose between "erc-721" or "erc-1155" or "candy-machine"
          args: {
              contractAddress: "0x123...", // replace with actual contract address
              mintFunctionName: "mintUSDC(address,uint256)", // specify the mint function
              abi: [], // provide the actual contract ABI array
              toParamName: "toAddress", // specify the 'to' parameter name in the mint function
              erc20MintCurrency: "usdc", // the ERC20 currency to be used for minting
          },
          metadata: {
              title: "<collection_title>", // replace '<collection_title>' with the actual collection name
              description: "<description>", // replace `<description>` with the actual collection's description
              imageUrl: "<image_url>", // replace '<image_url>' with actual URL to an image
          },
          ownership: "external", // optional - if you are regestering the collection on behalf of a creator or yourself, choose "external". Else, choose "self".
          category: "art", // specify the verification category - this expedites the collection review
          scopes: ["payments:credit-card"], // required scopes- "payments:cross-chain" or "payments:credit-card", must specify at least one
      };
      // Set up the request options
      const requestOptions = {
          method: "POST",
          headers: {
              'Content-Type': 'application/json',
              'X-API-KEY': '<api-key>', // replace '<api-key>' with the API Key that has the scope `collections.write`
          },
          body: JSON.stringify(requestBody), // Convert the JavaScript object to a JSON string
      };
      // Make the fetch request
      fetch(apiUrl, requestOptions)
      .then((response) => response.json()) // Parsing the JSON response
      .then((data) => console.log("Success:", data))
      .catch((error) => console.error("Error:", error));
    ```

    ```json Response (Successful) theme={null}
       {
          "collectionId": "<your-collection-id-string>"
       }
    ```
  </CodeGroup>
</Tab>

The returned URL must be the URL that your user needs to be directed to. The user can complete the verification with that URL.

## Get Collection status

You can check the status of your user's verification with the get collection status endpoint. Upon a successful request, the verification `status` for the `seller` and `collection` may have either of the following values:

* `verified` - The user has successfully completed the verification.
* `failed` - The verification failed.
* `crossmint-review` - It is being reviewed by the Crossmint team.
* `unverified` - The user has not initiated or completed the verification process.

<CodeGroup>
  ```jsx JavaScript theme={null}
     // Replace '<collectionId>' with the collectionId returned in the successful POST response
     const collectionId = 'your_collection_id'; // Replace 'your_collection_id' with the actual ID
     const apiUrl = `https://staging.crossmint.com/api/v1-alpha1/collections/${collectionId}`;
     
     // Set up the request options
     const requestOptions = {
        method: 'GET',
        headers: {
            'X-API-KEY': '<api-key>', /// replace '<api-key>' with your API Key
            'Content-Type': 'application/json',
        }
    };
    
    // Make the fetch request
    fetch(apiUrl, requestOptions)
    .then(response => {
        if (!response.ok) {
            throw new Error('Network response was not ok: ' + response.statusText);
        }
        return response.json(); // Parse the JSON from the response
    })
    .then(data => console.log('Success:', data)) // Handle the parsed data
    .catch(error => console.error('Error:', error)); // Handle any errors
  ```

  ```json Response (Successful) theme={null}
      {
         "verificationStatus": {
             "seller": {
                 "status": "verified"
             },
             "collection": {
                 "status": "verified"
             }
         }
     }
  ```
</CodeGroup>

***

## FAQs

<AccordionGroup>
  <Accordion title="What are the possible inputs for the category parameter?">
    You can find all the possible inputs below:

    ```json VerificationCategory inputs theme={null}
       VerificationCategory {
        LOYALTY: "loyalty",
        ART: "art",
        MUSIC: "music",
        GAMING: "gaming",
        TICKETING: "ticketing",
        CHARITY: "charity",
        OTHER: "other",
       }
    ```
  </Accordion>

  <Accordion title="Does every collection require seller's KYC and collection verification?">
    The verification requirement varies by the payment type selected for the collection.

    * Credit card: Seller and collection status must be “verified”.
    * Crypto: Only collection status must be “verified”.
  </Accordion>
</AccordionGroup>


# Checking Supported Tokens
Source: https://docs.crossmint.com/payments/advanced/supported-tokens

Learn how to check if a memecoin or token is supported by Crossmint Checkout

<Snippet />

## Introduction

Before integrating a memecoin or token using Crossmint's checkout, it's important to verify that it's supported by Crossmint. This guide will show you how to use the Crossmint API to check if a specific token is supported and what features are available for it.

## Prerequisites

<Steps>
  <Step title="Create a server-side API key">
    Get your API keys from the [Crossmint Console](https://www.crossmint.com/console/projects/apiKeys)

    <Snippet />

    [More info on creating API keys here](/introduction/platform/api-keys#how-to-get-and-use-api-keys)
  </Step>

  <Step title="Enable the orders.create scope">
    Make sure the `orders.create` scope is enabled for your API key.
  </Step>
</Steps>

## Getting Started

The Supported Tokens API allows you to query the status of any token to determine if it's supported by Crossmint and what features are available.

* **Endpoint**: `https://www.crossmint.com/api/v1-alpha2/tokens/:tokenLocator`
* **Method**: GET
* **Authentication**: Requires either a server or client API key

### Token Locator Format

Memecoin checkout supports the **Solana** and **Base** networks.

The token locator follows this format:

```
network:tokenAddress
```

Example:

* **Staging**: Use the XMEME test token: `solana:7EivYFyNfgGj8xbUymR7J4LuxUHLKRzpLaERHLvi7Dgu`
* **Production**: Use any supported token, e.g. TRUMP: `solana:6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN`

<Note>
  Production memecoin tokens **will not work** in the **staging** environment.
</Note>

## Checking Token Support

### Using JavaScript

Here's how to check if a token is supported using JavaScript:

```javascript theme={null}
// Example usage
const apiKey = "your-api-key"; // Replace with your actual API key
const tokenLocator = "solana:6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN"; // Example: TRUMP token

const checkTokenSupport = async (apiKey, tokenLocator) => {
    try {
        const response = await fetch(`https://www.crossmint.com/api/v1-alpha2/tokens/${tokenLocator}`, {
            method: "GET",
            headers: {
                "x-api-key": apiKey,
                "Content-Type": "application/json",
            },
        });

        const data = await response.json();
        return data;
    } catch (error) {
        console.error("Error checking token support:", error);
        throw error;
    }
};

checkTokenSupport(apiKey, tokenLocator)
    .then((result) => {
        console.log("Token support details:", result);

        if (result.available) {
            console.log("This token is supported by Crossmint!");
        } else {
            console.log("This token is not currently supported.");
        }

        console.log("Available features:", result.features);
    })
    .catch((err) => {
        console.error("Failed to check token support:", err);
    });
```

### Sample Response

A successful response will look similar to this:

```json theme={null}
{
    "token": "solana:6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN",
    "available": true,
    "features": {
        "creditCardPayment": true
    }
}
```

## Integrating with Your Checkout Flow

Once you've confirmed that a token is supported, you can use the information from the API response to customize your checkout experience.

### Example: Pre-checkout Validation

Here's an example of how to incorporate token support checking before initiating a checkout:

```javascript theme={null}
const initiateCheckout = async (apiKey, tokenLocator, amount, recipientWallet) => {
    // First, check if the token is supported
    const tokenSupport = await checkTokenSupport(apiKey, tokenLocator);

    if (!tokenSupport.available) {
        throw new Error("This token is not currently supported by Crossmint.");
    }

    if (!tokenSupport.features.creditCardPayment) {
        throw new Error("Credit card payment is not available for this token.");
    }

    // If we get here, the token is supported with credit card checkout
    // Proceed with creating an order
    const orderResponse = await fetch("https://www.crossmint.com/api/2022-06-09/orders", {
        method: "POST",
        headers: {
            "x-api-key": apiKey,
            "Content-Type": "application/json",
        },
        body: JSON.stringify({
            lineItems: [
                {
                    tokenLocator: tokenLocator,
                    executionParameters: {
                        mode: "exact-in",
                        amount: amount,
                        maxSlippageBps: "500",
                    },
                },
            ],
            payment: {
                method: "card",
                receiptEmail: "user@example.com", // Replace with user's email
            },
            recipient: {
                walletAddress: recipientWallet,
            },
        }),
    });

    return await orderResponse.json();
};
```

## Best Practices

1. **Cache Results (with caution)**: Token support status can change, but for frequently accessed tokens, consider caching results for a short period (e.g., 1 hour) to reduce API calls.

2. **Handle Errors Gracefully**: Implement proper error handling to provide clear feedback to users when a token is not supported.

3. **Check Before Displaying Options**: Only display payment methods that are actually available for the token.

## Next Steps

<CardGroup>
  <Card title="Credit Card Memecoin Checkout" icon="credit-card" href="/payments/headless/quickstarts/credit-card-memecoin-cko">
    Now that you can check token support, learn how to implement a credit card checkout for memecoins
  </Card>

  <Card title="Order Lifecycle" icon="rotate" href="/payments/headless/guides/order-lifecycle">
    Understand the lifecycle of orders in Crossmint's checkout flow
  </Card>
</CardGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Can I request support for a specific token?">
    Yes, if you'd like to request support for a token that is currently unsupported, contact our [support team](https://help.crossmint.com).
  </Accordion>

  <Accordion title="What happens if I try to process a transaction for an unsupported token?">
    Transactions for unsupported tokens will fail. This is why it's crucial to check token support before initiating
    a checkout process.
  </Accordion>

  <Accordion title="Are all payment methods available for all supported tokens?">
    No, each token may have different available payment features. The API response includes a `features` object that
    specifies which payment methods are available for each token.
  </Accordion>

  <Accordion title="Is there a limit to how many tokens I can check?">
    The API is rate-limited to 50 requests per second. For most applications, this should be more than sufficient.
  </Accordion>
</AccordionGroup>


# Testing Tips
Source: https://docs.crossmint.com/payments/advanced/testing-tips

This document is intended to share some of the best practices and tips for testing.

## Limits in Staging

<Tip>
  In order to preserve testnet ETH/tokens, Crossmint imposes very low upper bound limits on NFT prices in the staging
  environment. The default limit on production is USD $0.75 - $1,500 per transaction.
</Tip>

To avoid issues, set the `totalPrice` and the onchain NFT price to no more than:

* Ethereum (Sepolia): 0.000005 ETH (this applies for other EVM chains as well)
* Polygon (Amoy): 0.005 MATIC
* Solana (Devnet): 0.001 SOL
* USDC (all chains): \$10
* Other chains: the equivalent of \$0.10 in the native token

<Note>
  The minimum credit card charge amount is \$0.50. Even though the price of the NFT at the above rates will often be
  less the \$0.01, the checkout will still show \$0.50. This will be less of an issue on production when you're
  charging full price.
</Note>

## Test Credit Card Numbers

When testing the Checkout and credit card payments on staging you'll need to use test card numbers. You can use these cards to test the flow end-to-end without actually processing real payments.

You can use the following test credit card numbers:

* `4242424242424242` (Visa)
* `4000056655665556` (Visa Debit)
* `5555555555554444` (Mastercard)
* `5200828282828210` (Mastercard Debit)

For `CVV` or `CVC`, use any 3 digit number

For `Expiry Date` or `MM/YY`, enter any future date

### Advanced Card Testing

If you want to simulate purchases from [different countries](https://stripe.com/docs/testing?testing-method=card-numbers#international-cards), [decline conditions](https://stripe.com/docs/testing?testing-method=card-numbers#declined-payments), or other [brands](https://stripe.com/docs/testing?testing-method=card-numbers#cards) refer to the [Stripe documentation](https://stripe.com/docs/testing?testing-method=card-numbers) for more test card numbers.

## Reviewing Orders in the Developer Console

You can get insights into the purchases being made against your collection by navigating to the Orders tab for your collection in the Developer Console. You can use this to get insights about orders in production, but also to see the status of orders when testing out your integration in the staging environment.

<Frame type="simple">
  <img alt="Orders view in developer console" />
</Frame>

<Note>
  When looking for pre-completion phase orders while testing [Headless Checkout](/payments/headless/overview), you'll
  need to enter the order ID in the search box. This is because the console view purposefully has a reduced list of
  status options for filtering.
</Note>


# NFT Drops Priced in USDC
Source: https://docs.crossmint.com/payments/advanced/usdc-support

How to set up Crossmint if your collection is denominated in USDC

<Tip>
  By denominating your collection in USDC, you can eliminate price volatility, and offer a more accessible experience
  to users.
</Tip>

## Ensure you are using a supported USDC token

First of all, make sure your collection is denominated in one of the USDC token addresses supported by Crossmint.

<div>
  <table>
    <thead>
      <tr>
        <th>Chain</th>
        <th>Network</th>
        <th>USDC Token Address</th>
        <th>USDXM Token Address</th>
      </tr>
    </thead>
  </table>
</div>

<Note>
  USDC.e is only supported on previously registered integrations on Polygon mainnet. Please use the native USDC
  address for new projects.
</Note>

<Check>
  If you need some testnet USDC you can mint it freely from the contract or from this faucet app that uses the same
  testnet token contracts as the Checkout tools.

  [Crossmint Testnet USDXM Faucet](https://usdc-faucet.vercel.app/)
</Check>

## Validate your collection meets the requirements

<Tabs>
  <Tab title="EVM">
    In addition to the standard requirements, keep in mind:

    1. **The mint function should be `nonpayable`.**
    2. **The USDC token has 6 decimals** instead of 18 like ETH, Matic, and most other tokens.
    3. **The `totalPrice` attribute in the `callData` of your `lineItems` should be in units of USDC**. If your intended price is 100 USD, then you will set `totalPrice` to `100` e.g. `totalPrice="100"`.
    4. **Your ERC-20 transfer call must request the funds from `msg.sender`** instead of the address parameter. This allows Crossmint to pay from our fleet of treasury wallets and deliver the NFTs directly to the user's wallet. See an example mint function below.

    ```solidity Solidity theme={null}
    function mintUSDC(address _to) public {
      // pre payment logic here

      // note that you need to transfer from msg.sender, NOT the _to address
      tokenInstance.transferFrom(msg.sender, address(this), priceUSDC );

      // actual minting logic here
    }
    ```

    ```tsx theme={null}
    <CrossmintProvider apiKey="_YOUR_CLIENT_API_KEY_">
        <CrossmintEmbeddedCheckout
            lineItems={{
                collectionLocator: "crossmint:_YOUR_COLLECTION_ID_",
                callData: {
                    totalPrice: "100", // 100 USDC
                    quantity: 1,
                }
            }}
        />
    </CrossmintProvider>
    ```

    <Note>The `totalPrice` attribute in the `callData` of your `lineItems` should be in units of USDC. If your intended price is 100 USD, then you will set `totalPrice` to `100` e.g. `totalPrice="100"`.</Note>
  </Tab>

  <Tab title="Solana">
    Denominate your candy machine on USDC and Crossmint will automatically detect it. You can learn how on this [guide](https://medium.com/crossmint-tech/how-to-create-a-fixed-price-usdc-nft-drop-on-solana-2ab251e61384).
  </Tab>
</Tabs>


# Webhooks
Source: https://docs.crossmint.com/payments/advanced/webhooks

Track order lifecycle events and payment status with webhooks

# Webhooks Overview

Webhooks allow you to track the status of payments and order lifecycle events in your application. They provide real-time notifications for various events like checkout, NFT minting, and order fulfillment.

## Webhook Systems by Checkout Version

Crossmint offers different webhook systems for Checkout V2 and V3:

### Checkout V2 Webhooks (Legacy)

The Checkout V2 webhook system provides basic payment tracking with a single event type:

* `purchase.succeeded` - Triggered when an NFT has been successfully purchased and delivered

### Checkout V3 Webhooks (Current)

The Checkout V3 webhook system offers comprehensive order lifecycle tracking with multiple event types:

**Quote Phase**

* `orders.quote.created` - Triggered when a new order is created
* `orders.quote.updated` - Triggered when order details are modified

**Payment Phase**

* `orders.payment.succeeded` - Triggered when payment is successfully processed
* `orders.payment.failed` - Triggered when payment fails

**Delivery Phase**

* `orders.delivery.initiated` - Triggered when delivery begins
* `orders.delivery.completed` - Triggered when delivery succeeds
* `orders.delivery.failed` - Triggered when delivery fails

## Setting Up Webhooks

### 1. Create an endpoint route

Using a standard nodejs API server, create an endpoint.

<Accordion title="I don't have a webserver or want to test locally">
  You can test locally by installing [ngrok](https://ngrok.com/docs/getting-started/) and creating a routed endpoint
  to a specified port. > **Note**: Use ngrok only for testing. In production, ensure your endpoint is properly secured
  with HTTPS and appropriate access controls.
</Accordion>

### 2. Configure the endpoint

Your endpoint should:

* Handle POST requests only
* Parse webhook events from the request body
* Respond with a `200` status code to acknowledge receipt

<Tip>Your server must return a 2xx HTTP status quickly so the webhook is marked as delivered.</Tip>

Example handler:

```javascript theme={null}
// endpoint.js

export default function handler(req, res) {
    if (req.method === "POST") {
        console.log(`[webhook] Event received:`, req.body);
    }
    res.status(200).json({});
}
```

<Warning>
  Don't be strict with payload validations as Crossmint may add new fields to the webhooks as products evolve.
</Warning>

<Tip>Your server must return a 2xx HTTP status quickly so the webhook is marked as delivered.</Tip>

### 3. Example Webhook Responses

Every Checkout V3 webhook (`orders.*`) is delivered as `{ actionId, type, data }`:

* `actionId` — the order identifier
* `type` — the event name (for example, `orders.delivery.completed`)
* `data` — the complete order object, identical to the [Get Order API](/api-reference/headless/get-order) response

The fields inside `data.lineItems` depend on the order execution mode. `exact-out` orders (for example, NFT purchases) carry `callData` (when present) and `quantity`. `exact-in` orders (for example, token or memecoin purchases) carry `executionParams` and `maxSlippageBps`.

<AccordionGroup>
  <Accordion title="Checkout V2: purchase.succeeded">
    <CodeGroup>
      ```json EVM theme={null}
      {
          "type": "purchase.succeeded",
          "status": "success",
          "walletAddress": "<EVM_ADDRESS>",
          "projectId": "<PROJECT_ID>",
          "collectionId": "<COLLECTION_ID>",
          "clientId": "<CLIENT_ID>",
          "txId": "<TX_ID>",
          "contractAddress": "<CONTRACT_ADDRESS>",
          "tokenIds": [<TOKEN_IDS>], // only present for EVM collections
          "passThroughArgs": "<YOUR_ARGS_JSON>" // only if whPassThroughArgs set
      }
      ```

      ```json Solana theme={null}
      {
          "type": "purchase.succeeded",
          "status": "success", 
          "walletAddress": "<SOL_ADDRESS>",
          "clientId": "<CLIENT_ID>",
          "txId": "<TXID>",
          "mintAddress": "<MINT_HASH>",
          "passThroughArgs": "<YOUR_ARGS_JSON>"
      }
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Checkout V3: orders.quote.created">
    ```json theme={null}
    {
        "actionId": "7723139d-fba3-474d-8e52-0ac7512d5c7b",
        "type": "orders.quote.created",
        "data": {
            "orderId": "7723139d-fba3-474d-8e52-0ac7512d5c7b",
            "phase": "payment",
            "locale": "en-US",
            "lineItems": [
                {
                    "chain": "polygon",
                    "executionMode": "exact-out",
                    "quantity": 1,
                    "callData": { "quantity": 1 },
                    "metadata": {
                        "name": "Collection Name",
                        "description": "Collection Description",
                        "imageUrl": "https://..."
                    },
                    "quote": {
                        "status": "valid",
                        "charges": { "unit": { "amount": "0.50", "currency": "usd" } },
                        "totalPrice": { "amount": "0.50", "currency": "usd" }
                    },
                    "delivery": {
                        "status": "awaiting-payment",
                        "recipient": {
                            "locator": "email:user@example.com:polygon",
                            "email": "user@example.com",
                            "walletAddress": "0x1234..."
                        }
                    }
                }
            ],
            "quote": {
                "status": "valid",
                "quotedAt": "2024-11-20T12:00:00.000Z",
                "expiresAt": "2024-11-20T13:00:00.000Z",
                "totalPrice": { "amount": "0.50", "currency": "usd" }
            },
            "payment": {
                "status": "awaiting-payment",
                "method": "stripe-payment-element",
                "currency": "usd",
                "receiptEmail": "user@example.com"
            }
        }
    }
    ```
  </Accordion>

  <Accordion title="Checkout V3: orders.payment.succeeded">
    ```json theme={null}
    {
        "actionId": "7723139d-fba3-474d-8e52-0ac7512d5c7b",
        "type": "orders.payment.succeeded",
        "data": {
            "orderId": "7723139d-fba3-474d-8e52-0ac7512d5c7b",
            "phase": "delivery",
            "locale": "en-US",
            "lineItems": [
                {
                    "chain": "polygon",
                    "executionMode": "exact-out",
                    "quantity": 1,
                    "callData": { "quantity": 1 },
                    "metadata": { "name": "Collection Name", "imageUrl": "https://..." },
                    "quote": {
                        "status": "valid",
                        "totalPrice": { "amount": "0.50", "currency": "usd" }
                    },
                    "delivery": {
                        "status": "in-progress",
                        "recipient": {
                            "locator": "email:user@example.com:polygon",
                            "email": "user@example.com",
                            "walletAddress": "0x1234..."
                        }
                    }
                }
            ],
            "quote": {
                "status": "valid",
                "totalPrice": { "amount": "0.50", "currency": "usd" }
            },
            "payment": {
                "status": "completed",
                "method": "stripe-payment-element",
                "currency": "usd",
                "receiptEmail": "user@example.com",
                "received": { "amount": "0.50", "currency": "usd" }
            }
        }
    }
    ```
  </Accordion>

  <Accordion title="Checkout V3: orders.delivery.completed (NFT / exact-out)">
    ```json theme={null}
    {
        "actionId": "7723139d-fba3-474d-8e52-0ac7512d5c7b",
        "type": "orders.delivery.completed",
        "data": {
            "orderId": "7723139d-fba3-474d-8e52-0ac7512d5c7b",
            "phase": "completed",
            "locale": "en-US",
            "lineItems": [
                {
                    "chain": "polygon",
                    "executionMode": "exact-out",
                    "quantity": 1,
                    "callData": { "quantity": 1 },
                    "metadata": { "name": "Collection Name", "imageUrl": "https://..." },
                    "quote": {
                        "status": "valid",
                        "totalPrice": { "amount": "0.50", "currency": "usd" }
                    },
                    "delivery": {
                        "status": "completed",
                        "recipient": {
                            "locator": "email:user@example.com:polygon",
                            "email": "user@example.com",
                            "walletAddress": "0x1234..."
                        },
                        "txId": "0x2e69f11dae7869b92e3d5eaf4cadd50c48b5c6803d1232815f979d744521ad4c",
                        "tokens": [
                            {
                                "locator": "polygon:0xE04Cf294985282Ddc088E6433c064cfB85eD9EdA:3",
                                "contractAddress": "0xE04Cf294985282Ddc088E6433c064cfB85eD9EdA",
                                "tokenId": "3"
                            }
                        ]
                    }
                }
            ],
            "quote": {
                "status": "valid",
                "totalPrice": { "amount": "0.50", "currency": "usd" }
            },
            "payment": {
                "status": "completed",
                "method": "stripe-payment-element",
                "currency": "usd",
                "receiptEmail": "user@example.com",
                "received": { "amount": "0.50", "currency": "usd" }
            }
        }
    }
    ```
  </Accordion>

  <Accordion title="Checkout V3: orders.delivery.completed (token / exact-in)">
    ```json theme={null}
    {
        "actionId": "2795199f-f599-44c4-84dc-38d944853a05",
        "type": "orders.delivery.completed",
        "data": {
            "orderId": "2795199f-f599-44c4-84dc-38d944853a05",
            "phase": "completed",
            "locale": "en-US",
            "lineItems": [
                {
                    "chain": "base",
                    "executionMode": "exact-in",
                    "executionParams": {
                        "mode": "exact-in",
                        "amount": "5",
                        "contractAddress": "0x4ed4e862860bed51a9570b96d89af5e1b0efefed",
                        "quantity": 1
                    },
                    "maxSlippageBps": "50",
                    "metadata": {
                        "name": "DEGEN",
                        "description": "DEGEN is a community-driven token..."
                    },
                    "quote": {
                        "status": "valid",
                        "totalPrice": { "amount": "5", "currency": "usd" }
                    },
                    "delivery": {
                        "status": "completed",
                        "recipient": {
                            "locator": "base:0x24573a80ae60c0e75735843f119ab4623a45e523",
                            "walletAddress": "0x24573a80ae60c0e75735843f119ab4623a45e523"
                        },
                        "txId": "0x8e20e4b1edff7375fb5d4fc87f6cdb66aa03573e725d5eacc7053800a4f1c11b",
                        "tokens": [
                            {
                                "locator": "base:0x4ed4e862860bed51a9570b96d89af5e1b0efefed:0",
                                "contractAddress": "0x4ed4e862860bed51a9570b96d89af5e1b0efefed",
                                "tokenId": "0",
                                "quantity": "50000000000000000000",
                                "symbol": "DEGEN",
                                "decimals": 18
                            }
                        ]
                    }
                }
            ],
            "quote": {
                "status": "valid",
                "totalPrice": { "amount": "5", "currency": "usd" }
            },
            "payment": {
                "status": "completed",
                "method": "basis-theory",
                "currency": "usd",
                "received": { "amount": "5", "currency": "usd" }
            }
        }
    }
    ```
  </Accordion>

  <Accordion title="Checkout V3: orders.delivery.failed">
    ```json theme={null}
    {
        "actionId": "2795199f-f599-44c4-84dc-38d944853a05",
        "type": "orders.delivery.failed",
        "data": {
            "orderId": "2795199f-f599-44c4-84dc-38d944853a05",
            "phase": "completed",
            "locale": "en-US",
            "lineItems": [
                {
                    "chain": "base",
                    "executionMode": "exact-in",
                    "executionParams": {
                        "mode": "exact-in",
                        "amount": "5",
                        "contractAddress": "0x4ed4e862860bed51a9570b96d89af5e1b0efefed",
                        "quantity": 1
                    },
                    "maxSlippageBps": "50",
                    "metadata": {
                        "name": "DEGEN",
                        "description": "DEGEN is a community-driven token..."
                    },
                    "quote": {
                        "status": "valid",
                        "totalPrice": { "amount": "5", "currency": "usd" }
                    },
                    "delivery": {
                        "status": "failed",
                        "failureReason": {
                            "code": "slippage-tolerance-exceeded"
                        },
                        "recipient": {
                            "locator": "base:0x24573a80ae60c0e75735843f119ab4623a45e523",
                            "walletAddress": "0x24573a80ae60c0e75735843f119ab4623a45e523"
                        }
                    }
                }
            ],
            "quote": {
                "status": "valid",
                "totalPrice": { "amount": "5", "currency": "usd" }
            },
            "payment": {
                "status": "completed",
                "method": "basis-theory",
                "currency": "usd",
                "received": { "amount": "5", "currency": "usd" },
                "refunded": { "amount": "5", "currency": "usd" }
            }
        }
    }
    ```
  </Accordion>
</AccordionGroup>

### 4. Pass Custom Arguments (Optional)

<Warning>
  Custom arguments (whPassThroughArgs) are only supported in Checkout V2 webhooks. This feature is not available in
  Checkout V3 webhooks (orders.\*).
</Warning>

You can pass custom arguments through Checkout V2 webhooks to track additional information:

* User IDs (If you want additional security, sign this ID with a custom key, or send it as a signed JWT, and verify its integrity later on your server)
* Timestamps
* Product SKUs
* Custom metadata

Example of passing arguments:

```jsx theme={null}
function NFTSalePage() {
    const whArgs = {
        uid: 123424,
        sku: 123123123,
        metadata: { custom: "data" },
    };

    const whArgsSerialized = JSON.stringify(whArgs);

    return (
        <CrossmintPayButton
            projectId="_YOUR_PROJECT_ID_"
            collectionId="_YOUR_COLLECTION_ID_"
            whPassThroughArgs={whArgsSerialized}
        />
    );
}
```

Then, extract them on the server:

```javascript theme={null}
export default function handler(req, res) {
    const { whPassThroughArgs } = req.body;

    if (whPassThroughArgs) {
        const whArgsDeserialized = JSON.parse(whPassThroughArgs);
        console.log(whArgsDeserialized);
    }

    res.status(200).json({});
}
```

### 5. Pre & Post Processing

Add your pre and post processing logic when setting up your webhook listener. For example, you can call back to your database when a certain id has succeeded or even use <a href="https://sendgrid.com/">Sendgrid</a> or <a href="https://www.emailjs.com/">EmailJS</a> to send an email to a recipient when a mint completes.

### 6. Configure in Crossmint Console

1. Navigate to the [Webhooks page](https://www.crossmint.com/console/webhooks) in the console
2. Click **Add Endpoint**
3. Enter your endpoint URL
4. Select the webhook events to receive
5. Click **Create**

<Frame type="simple">
  <img alt="Add webhook endpoint UI" />
</Frame>

### 6. Security

For security, verify webhook signatures using the signing secret from your endpoint details page:

<Frame type="simple">
  <img alt="Screenshot of webhooks status UI" />
</Frame>

See the [Verify Webhooks](/introduction/platform/webhooks/verify-webhooks) guide for implementation details.

## Testing Webhooks

1. Use test card number `4242 4242 4242 4242` for successful payments
2. Use `4000 0000 0000 4954` to test payment failures
3. Monitor webhook deliveries in the [Console](https://www.crossmint.com/console/webhooks)

<Accordion title="Watch a video tutorial">
  <Frame type="simple">
    <iframe />
  </Frame>
</Accordion>


# Payment Error Codes
Source: https://docs.crossmint.com/payments/api-reference/error-codes

Reference of the normalized error categories and codes returned in the order's payment.failureReason

<Snippet />

## See Also

<CardGroup>
  <Card title="Display Payment Error Messages" icon="message-exclamation" href="/payments/embedded/guides/display-payment-errors">
    Surface the decline reason in Embedded Checkout, including after the Apple Pay or Google Pay sheet closes
  </Card>

  <Card title="Supporting Your Customers" icon="headset" href="/payments/headless/guides/supporting-your-customers">
    What to collect from a buyer before escalating a checkout issue to Crossmint
  </Card>

  <Card title="Status Codes" icon="list-check" href="/payments/headless/guides/status-codes">
    Order, quote, payment, and delivery statuses, which are distinct from payment error codes
  </Card>

  <Card title="Pay with Card" icon="credit-card" href="/payments/headless/guides/order-lifecycle/credit-card-payment-phase">
    The payment phase of the Headless Checkout order lifecycle, including handling declined payments
  </Card>

  <Card title="Get Order" icon="brackets-curly" href="/api-reference/headless/get-order">
    REST endpoint that returns the order, including `payment.failureReason`
  </Card>

  <Card title="Webhooks" icon="webhook" href="/payments/advanced/webhooks">
    Receive order updates, including declines, server-side
  </Card>
</CardGroup>


# Localization
Source: https://docs.crossmint.com/payments/embedded/customize/localization

Customize the language and currency displayed on checkout

<Snippet />

## How to Adjust the Currency and Language

To customize the language use the property `locale` and for currency, set `defaultCurrency`. Here's an example:

```tsx {3,16} theme={null}
<CrossmintProvider apiKey="_YOUR_CLIENT_API_KEY_">
    <CrossmintEmbeddedCheckout
        locale="es-ES" // Change locale to Spanish
        lineItems={{
            collectionLocator: "crossmint:_YOUR_COLLECTION_ID_",
            callData: {
                // your callData args
            },
        }}
        payment={{
            crypto: {
                enabled: true,
            },
            fiat: {
                enabled: true,
                defaultCurrency: "eur", // Change default currency to be Euro
            },
        }}
    />
</CrossmintProvider>
```


# Apple Pay Integration Guide
Source: https://docs.crossmint.com/payments/embedded/guides/apple-pay

Learn how to enable Apple Pay on your site for Checkout

To enable Apple Pay on your site, follow these steps using the [Crossmint Developer Console](https://www.crossmint.com/console/apple-pay-domains).

## Prerequisites

1. **HTTPS Hosting**: Your site must be hosted on HTTPS to ensure secure transactions.
2. **Crossmint Account**: You need an active Crossmint developer account.

## Setup Instructions

### Step 1: Download the Verification File

1. Go to the [Apple Pay Domains](https://www.crossmint.com/console/apple-pay-domains) page in the Crossmint Console.
2. Click **Download file** to get the Apple Developer Merchant ID Domain Association file.

### Step 2: Host the Verification File

Host the downloaded file on your server at the following path:

```
https://[your-domain]/.well-known/apple-developer-merchantid-domain-association
```

<Accordion title="Example: Next.js App Router">
  **Option 1: Using the Public Folder**

  1. Create the `.well-known` folder inside your `public` directory.
  2. Place the downloaded file in `public/.well-known/` with the filename `apple-developer-merchantid-domain-association` (no extension).

  **Option 2: Using a Route**

  1. Create a folder at `app/.well-known/apple-developer-merchantid-domain-association/`
  2. Add a `route.ts` file with the following content:

  ```typescript route.ts theme={null}
  import { NextResponse } from "next/server";

  export async function GET() {
      return new NextResponse("PASTE_FILE_CONTENT_HERE", {
          headers: {
              "Content-Type": "text/plain",
          },
      });
  }
  ```

  Replace `PASTE_FILE_CONTENT_HERE` with the content of the downloaded verification file.
</Accordion>

<Accordion title="Example: Next.js Page Router">
  1. Create the `.well-known` folder inside your `public` directory.
  2. Place the downloaded file in `public/.well-known/` with the filename `apple-developer-merchantid-domain-association` (no extension).
</Accordion>

<Accordion title="Example: Vite">
  1. Create the `.well-known` folder inside your `public` directory.
  2. Place the downloaded file in `public/.well-known/` with the filename `apple-developer-merchantid-domain-association` (no extension).
</Accordion>

### Step 3: Verify Your Domain

1. Return to the [Apple Pay Domains](https://www.crossmint.com/console/apple-pay-domains) page in the Crossmint Console.
2. Enter your domain (e.g., `example.com` or `checkout.example.com`) in the input field.
3. Click **Verify domain**.

If verification succeeds, your domain will appear in the list of registered domains and Apple Pay will be enabled for that domain.

<Note>
  If verification fails, ensure the file is publicly accessible at the correct path. You can test by visiting `https://your-domain/.well-known/apple-developer-merchantid-domain-association` in your browser.
</Note>

## Local Testing

Using [ngrok](https://ngrok.com/) is recommended for local testing. Ngrok allows you to expose your local server to the internet securely.

1. Start ngrok with a fixed domain if possible for consistent testing.
2. Host the verification file on your local server.
3. Register the ngrok domain in the Crossmint Console.
4. Test Apple Pay on Safari (macOS) or any iOS device.

## Apple Pay in Mobile Apps

In native iOS and React Native apps, the checkout renders inside a WebView, and Apple Pay works there with two differences from the web setup above:

* **Domain verification is not required.** The steps on this page apply to websites that embed the checkout. Inside a mobile app, the checkout page is served from `crossmint.com`, which is already enabled for Apple Pay.
* **Test on a physical iPhone** running iOS 17 or higher, with a card added to Apple Wallet. The iOS Simulator does not render Apple Pay.

***

For further assistance, please contact our support team.


# Use Connected Wallet as Payer
Source: https://docs.crossmint.com/payments/embedded/guides/custom-payer

Learn how to configure an already connected wallet as the payer wallet

## Overview

By default, Embedded checkout includes wallet connector UI. However, if your customers have already
connected their wallet to your website, you can configure that connected wallet directly as the payer.

This is useful when:

* You're already using a wallet connection solution (like RainbowKit, Solana Wallet Adapter, Web3Modal, or ConnectKit)
* You are using embedded wallets (from Crossmint or other providers)

## Quick Integration

Here's a simple example using [wagmi](https://wagmi.sh/), [viem](https://viem.sh/) and [TanStack Query](https://tanstack.com/query/v5):

<Note>
  Make sure you have this environment variables on `.env.local` or directly replace it in the code `bash
        NEXT_PUBLIC_CLIENT_API_KEY="__YOUR_CLIENT_KEY__" # From API Keys page NEXT_PUBLIC_RECIPIENT_WALLET_ADDRESS="" #
        Address receiving the assets NEXT_PUBLIC_RECEIPT_EMAIL="user@example.com"
        NEXT_PUBLIC_COLLECTION_ID="__YOUR_COLLECTION_ID__" # From Collection details page `
</Note>

<CodeGroup>
  ```tsx Checkout.tsx theme={null}
  import { CrossmintEmbeddedCheckout } from "@crossmint/client-sdk-react-ui";
  import { Hex, parseTransaction } from "viem";
  import { useAccount, useWalletClient } from "wagmi";
  import { baseSepolia, polygonAmoy } from "wagmi/chains";

  export default function Checkout() {
    const { address } = useAccount();
    const { data: walletClient } = useWalletClient();
    const collectionId = process.env.NEXT_PUBLIC_COLLECTION_ID as string;

    const chainIds: Record<string, number> = {
      "base-sepolia": baseSepolia.id,
      "polygon-amoy": polygonAmoy.id,
    } as const;

    // Don't render checkout if wallet is not connected
    if (!address || !walletClient) {
      return (
        <div className="flex flex-col items-center justify-center p-6">
          <h2 className="text-xl text-gray-600 mb-4">Please connect your wallet to continue</h2>
        </div>
      );
    }

    return (
      <CrossmintEmbeddedCheckout
        locale="es-ES"
        recipient={{
          walletAddress: process.env.NEXT_PUBLIC_RECIPIENT_WALLET_ADDRESS ?? "",
        }}
        payment={{
          crypto: {
            // Enable crypto payment, this example only uses Crypto
            enabled: true,
            payer: {
              address,
              initialChain: "base-sepolia",
              supportedChains: ["base-sepolia", "polygon-amoy"],
              handleChainSwitch: async (chain) => {
                await walletClient.switchChain({
                  id: chainIds[chain],
                });
              },
              handleSignAndSendTransaction: async (serializedTx) => {
                try {
                  const tx = parseTransaction(serializedTx as Hex);
                  const hash = await walletClient.sendTransaction({
                    to: tx.to,
                    value: tx.value,
                    data: tx.data ?? "0x",
                    gas: tx.gas,
                    chainId: tx.chainId,
                  });

                  return { success: true, txId: hash };
                } catch (error) {
                  return {
                    success: false,
                    errorMessage: error instanceof Error ? error.message : "Transaction failed",
                  };
                }
              },
            },
          },
          fiat: { enabled: false },
          receiptEmail: process.env.NEXT_PUBLIC_RECEIPT_EMAIL ?? "",
        }}
        lineItems={{
          collectionLocator: `crossmint:${collectionId}`,
          callData: {
            quantity: 1,
          },
        }}
      />
    );
  }

  ```

  ```tsx WalletConnector.tsx theme={null}
  import { useAccount, useConnect, useDisconnect } from "wagmi";

  export default function WalletConnector() {
    const { address, isConnected } = useAccount();
    const { connect, connectors, isPending } = useConnect();
    const { disconnect } = useDisconnect();

    if (!isConnected) {
      return (
        <div className="absolute top-4 right-4">
          <button
            onClick={() => connect({ connector: connectors[0] })}
            disabled={isPending}
            className="px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700 disabled:opacity-50 cursor-pointer"
          >
            {isPending ? 'Connecting...' : 'Connect Wallet'}
          </button>
        </div>
      );
    }

    return (
      <div className="absolute top-4 right-4">
        <div className="flex items-center gap-2">
          <span className="px-4 py-2 bg-green-600 text-white rounded-lg">
            {address?.slice(0, 6)}...{address?.slice(-4)}
          </span>
          <button
            onClick={() => disconnect()}
            className="px-3 py-2 bg-red-600 text-white rounded-lg hover:bg-red-700 cursor-pointer text-sm"
          >
            Disconnect
          </button>
        </div>
      </div>
    );
  }
  ```

  ```tsx Home.tsx theme={null}
  "use client";

  import { CrossmintProvider } from "@crossmint/client-sdk-react-ui";
  import { WagmiProvider, createConfig, http } from "wagmi";
  import { baseSepolia, polygonAmoy } from "wagmi/chains";
  import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
  import { injected } from "wagmi/connectors";
  import Checkout from "@/components/Checkout";
  import WalletConnector from "@/components/WalletConnector";

  export default function Home() {
      const clientApiKey = process.env.NEXT_PUBLIC_CLIENT_API_KEY as string;
      // Create a client
      const queryClient = new QueryClient();

      // Create wagmi config
      const config = createConfig({
          chains: [baseSepolia, polygonAmoy] as any,
          connectors: [injected()] as any,
          transports: {
              [baseSepolia.id]: http(),
              [polygonAmoy.id]: http(),
          },
      } as any);

      return (
          <WagmiProvider config={config}>
              <QueryClientProvider client={queryClient}>
                  <div className="relative flex flex-col items-center justify-start h-screen p-6 bg-white">
                      <WalletConnector />
                      <CrossmintProvider apiKey={clientApiKey}>
                          <div className="max-w-[450px] w-full">
                              <Checkout />
                          </div>
                      </CrossmintProvider>
                  </div>
              </QueryClientProvider>
          </WagmiProvider>
      );
  }
  ```
</CodeGroup>

<Note>
  When the user clicks the hosted checkout button, our SDK will first call `handleChainSwitch` to ensure the correct
  network is set, then `handleSignAndSendTransaction` to complete the purchase.
</Note>

## Payer Configuration

The `payer` prop accepts the following configuration:

| Property | Type | Description |
| - | - | - |
| `address` | `string` | The wallet address of the payer |
| `initialChain` | `PayerSupportedBlockchains` | The initial blockchain (e.g. "polygon", "ethereum", "base-sepolia") |
| `supportedChains` | `PayerSupportedBlockchains[]` | Optional list of supported chains. Defaults to `initialChain` if not specified |
| `handleChainSwitch` | `(chain: PayerSupportedBlockchains) => Promise<void>` | Function to handle chain switching |
| `handleSignAndSendTransaction` | `(serializedTx: string) => Promise<TransactionResponse>` | Function to handle transaction signing and sending, where `TransactionResponse` is either `{ success: true, txId: string }` or `{ success: false, errorMessage: string }` |

## Popular Wallet Solutions

You can integrate Crossmint with popular Web3 solutions:

### RainbowKit

```tsx theme={null}
import { useConnectModal } from "@rainbow-me/rainbowkit";

// Similar implementation as above, but using RainbowKit's hooks
```

### Web3Modal

```tsx theme={null}
import { useWeb3Modal } from "@web3modal/react";

// Similar implementation as above, but using Web3Modal's hooks
```

## Best Practices

1. **Error Handling**: Always return clear error messages in `handleSignAndSendTransaction`
2. **Chain Support**: Be explicit about supported chains to avoid runtime errors
3. **User Experience**: Show loading states during chain switches and transactions
4. **Wallet Connection**: Ensure wallet is connected before showing checkout

## Related Resources

* [Payment Methods](/payments/embedded/guides/payment-methods)
* [React Hooks](/payments/embedded/guides/hooks)
* [Testing Tips](/payments/advanced/testing-tips)


# Display Payment Error Messages
Source: https://docs.crossmint.com/payments/embedded/guides/display-payment-errors

Show buyers why a card was declined after the Apple Pay or Google Pay sheet closes

When a card is declined during an Apple Pay or Google Pay purchase, the wallet sheet closes with only the wallet's generic failure state — for example, Apple Pay shows "Order failed" with no explanation. Without a visible decline reason, buyers tend to retry the same card several times, which lowers their chance of a successful purchase.

Crossmint always delivers a structured decline reason to your page. This guide shows the two ways to surface it, and how to tell a decline apart from a user cancellation.

## Prerequisites

* **Embedded Checkout**: An [Embedded Checkout](/payments/embedded/overview) integration with Apple Pay or Google Pay enabled. See the [payment methods guide](/payments/embedded/guides/payment-methods).
* **React SDK**: The code samples use `@crossmint/client-sdk-react-ui` with `CrossmintCheckoutProvider`. See [React Hooks](/payments/embedded/guides/hooks).

## Option 1: Enable the Built-In Error Banner

The checkout component includes an error banner that displays the decline reason. On the Apple Pay and Google Pay screens this banner is hidden by default. Enable it with one appearance rule — **`appearance.rules.GlobalMessage.display: "visible"`**:

```tsx theme={null}
<CrossmintEmbeddedCheckout
    // ...other props
    appearance={{
        rules: {
            GlobalMessage: { display: "visible" },
        },
    }}
/>
```

With this rule set, the checkout shows the decline reason above the payment button after the wallet sheet closes.

<Note>
  The built-in banner dismisses automatically after 8 seconds. If your page constrains the checkout iframe's height,
  the banner can render outside the visible area. For full control over placement and persistence, use Option 2.
</Note>

## Option 2: Render Your Own Error Message

The checkout reports every order change to your page. After a decline, the updated order contains `payment.failureReason`. Read it with the `useCrossmintCheckout` hook and render the message anywhere on your page:

```tsx theme={null}
import { useCrossmintCheckout } from "@crossmint/client-sdk-react-ui";

function CheckoutErrorBanner() {
    const { order } = useCrossmintCheckout();
    const failureReason = order?.payment?.failureReason;

    if (failureReason == null) {
        return null;
    }
    return (
        <div role="alert" className="checkout-error">
            {failureReason.message ?? "Your payment was declined. Try a different payment method."}
        </div>
    );
}
```

Place the component where the buyer is guaranteed to see it — directly adjacent to the checkout, or in a sticky status region. Do not place it where it can fall outside the visible viewport.

Keep listening after the sheet closes. With Google Pay, the sheet closes as soon as the buyer authorizes, and the decline can arrive afterwards. Some declines also arrive asynchronously while the order is finalized. React to `failureReason` whenever it appears, and clear your error UI when the buyer starts a new attempt.

## Tell a Cancellation Apart from a Decline

The sheet closing is ambiguous on its own: it happens both when the buyer cancels and when the card is declined. Use the order state to distinguish the two:

| Signal | Meaning | What to show |
| - | - | - |
| Sheet closes and `order.payment.failureReason` stays `undefined` | The buyer canceled | Nothing, or a neutral "Payment not completed" message |
| An order update arrives with `order.payment.failureReason` set | The card was declined | The decline explanation (`failureReason.message`) |

A cancellation never produces a `failureReason`, and a decline always does. Gate your error UI strictly on `failureReason` — never on the sheet closing.

## The `failureReason` Object

| Field | Type | Description |
| - | - | - |
| `code` | `string` | Normalized decline code for logic, analytics, and support tooling |
| `category` | `string` (optional) | The broad reason the payment failed, such as `authorization_decline` or `risk_block` |
| `retryPolicy` | `string` (optional) | The recommended next step for the buyer, such as `retry_with_different_payment_method` |
| `message` | `string` (optional) | User-safe explanation. **The only field safe to render to buyers** |

The complete list of categories, codes, and retry policies lives in the [Payment Error Codes](/payments/api-reference/error-codes) reference. Use `retryPolicy` to decide which affordance to show — for example, prompt for a different card on `retry_with_different_payment_method`, and hide the retry button on `do_not_retry`.

A card decline returns the order to the `awaiting-payment` state regardless of the decline code, so the order can still accept a payment. `awaiting-payment` therefore means the order is open, not that retrying is a good idea — `retryPolicy` is the signal for that. With `do_not_retry` (for example `psp_security_block`, where fraud or risk screening blocked the attempt), do not offer a retry even though the order remains `awaiting-payment`. Never retry a declined payment automatically on the buyer's behalf.

<Note>
  `awaiting-payment` together with `retryPolicy: "do_not_retry"` is a valid, expected combination. Crossmint does not enforce `do_not_retry` server-side; it is a hint for your UI.
</Note>

## Common Gotchas

<AccordionGroup>
  <Accordion title="The error message renders but the buyer never sees it">
    The checkout iframe's height is managed dynamically by the SDK. If your page wraps the iframe in a
    fixed-height container with internal scrolling, content near the bottom — including the built-in error banner —
    can land below the fold. Let the SDK manage the iframe height, or render your own error message outside the
    iframe (Option 2).
  </Accordion>

  <Accordion title="The decline arrives after the sheet is already closed">
    This is expected, particularly with Google Pay, where authorization completes before the charge is attempted.
    Keep observing order updates after the sheet closes instead of checking once.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Payment Error Codes" icon="circle-exclamation" href="/payments/api-reference/error-codes" />

  <Card title="React Hooks" icon="react" href="/payments/embedded/guides/hooks" />

  <Card title="UI Customization" icon="palette" href="/payments/embedded/guides/ui-customization" />

  <Card title="Payment Methods" icon="credit-card" href="/payments/embedded/guides/payment-methods" />
</CardGroup>


# Google Pay Mobile
Source: https://docs.crossmint.com/payments/embedded/guides/google-pay

Learn how to enable Google Pay for token checkout and onramp flows using Crossmint's mobile SDKs

<Info>
  **This guide is for mobile apps only.** For web applications, Google Pay works automatically when enabled via the `payment.fiat.allowedMethods.googlePay` prop—no additional setup required. See [Payment Methods](/payments/embedded/guides/payment-methods) for web configuration.
</Info>

This guide covers how to enable Google Pay for token checkout and onramp flows in **React Native** and **Android native (Kotlin)** applications. Mobile apps require additional native configuration that web apps don't need.

## Overview

Crossmint's mobile SDKs provide pre-built checkout components that support Google Pay out of the box. When properly configured, users see the native Android Google Pay sheet, providing seamless access to payment credentials stored in Google Wallet without leaving your app.

### Mobile vs Web

| Platform | Setup Required | Guide |
| - | - | - |
| Web (React, Next.js, etc.) | Enable via props only | [Payment Methods](/payments/embedded/guides/payment-methods) |
| React Native (Expo) | Expo plugin + rebuild | This guide |
| React Native (Bare) | Manual Android config | This guide |
| Android Native (Kotlin) | AndroidManifest config | This guide |
| Your own WebView (no SDK) | WebView + manifest config | [Mobile WebView Integration](/payments/embedded/guides/webview-integration) |

### Supported Use Cases

* Token purchases (buy tokens with fiat)
* Stablecoin onramp (USDC, etc.)
* NFT checkout

## Mobile SDK Integration

<Tabs>
  <Tab title="React Native">
    ### Prerequisites

    Before starting, ensure you have:

    * React Native project with Expo or bare workflow
    * Crossmint account with API keys (staging and/or production)
    * Android device or emulator with Google Play Services

    <Steps>
      <Step title="Install Dependencies">
        ```shell theme={null}
        pnpm add @crossmint/client-sdk-react-native-ui
        ```

        The SDK includes `react-native-webview` as a dependency. If you need to install it separately, ensure version **13.15.0 or higher**:

        ```shell theme={null}
        pnpm add react-native-webview@^13.15.0
        ```
      </Step>

      <Step title="Configure the Expo Plugin">
        Update your `app.json` to enable Google Pay:

        ```json theme={null}
        {
          "expo": {
            "plugins": [
              [
                "@crossmint/client-sdk-react-native-ui",
                {
                  "enableGooglePay": true
                }
              ]
            ]
          }
        }
        ```

        <Warning>
          This plugin modifies native Android permissions required for Google Pay. The app must be rebuilt after adding this configuration.
        </Warning>
      </Step>

      <Step title="Rebuild Your App">
        Hot reload cannot apply the permission changes. You must rebuild:

        ```shell theme={null}
        npx expo run:android
        ```

        Or for bare React Native:

        ```shell theme={null}
        npx react-native run-android
        ```
      </Step>

      <Step title="Implement the Checkout Component">
        Use `CrossmintEmbeddedCheckout` for token purchases:

        ```javascript theme={null}
        import {
          CrossmintEmbeddedCheckout,
          CrossmintProvider,
        } from "@crossmint/client-sdk-react-native-ui";

        export default function CheckoutScreen() {
          return (
            <CrossmintProvider apiKey="your_client_side_api_key">
              <CrossmintEmbeddedCheckout
                recipient={{
                  walletAddress: "YOUR_WALLET_ADDRESS",
                }}
                payment={{
                  crypto: { enabled: false },
                  fiat: {
                    enabled: true,
                    allowedMethods: {
                      card: true,
                      applePay: false,
                      googlePay: true,
                    },
                  },
                }}
                lineItems={{
                  tokenLocator: "solana:TOKEN_ADDRESS",
                  executionParameters: {
                    mode: "exact-in",
                    amount: "1",
                    maxSlippageBps: "500",
                  },
                }}
              />
            </CrossmintProvider>
          );
        }
        ```

        <Note>
          For staging/testing, use the XMEME test token:

          ```javascript theme={null}
          tokenLocator: "solana:7EivYFyNfgGj8xbUymR7J4LuxUHLKRzpLaERHLvi7Dgu"
          ```
        </Note>
      </Step>

      <Step title="Customize Appearance (Optional)">
        Hide destination and email inputs for a cleaner UI:

        ```javascript theme={null}
        <CrossmintEmbeddedCheckout
          // ... other props
          appearance={{
            rules: {
              DestinationInput: { display: "hidden" },
              ReceiptEmailInput: { display: "hidden" },
            },
            variables: {
              colors: {
                backgroundPrimary: "#000000",
                textPrimary: "#ffffff",
              },
            },
          }}
        />
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Android Native (Kotlin)">
    ### Prerequisites

    * Minimum Android SDK version 24 (Android 7.0)
    * Jetpack Compose
    * Crossmint account with API keys

    <Steps>
      <Step title="Add the SDK Dependency">
        In your app-level `build.gradle.kts`:

        ```kotlin theme={null}
        dependencies {
            implementation("com.crossmint:crossmint-sdk-android:0.0.9")
        }
        ```
      </Step>

      <Step title="Configure AndroidManifest.xml">
        Add the required query intents to enable Google Pay functionality:

        ```xml theme={null}
        <manifest xmlns:android="http://schemas.android.com/apk/res/android">
            <queries>
                <intent>
                    <action android:name="org.chromium.intent.action.PAY"/>
                </intent>
                <intent>
                    <action android:name="org.chromium.intent.action.IS_READY_TO_PAY"/>
                </intent>
                <intent>
                    <action android:name="org.chromium.intent.action.UPDATE_PAYMENT_DETAILS"/>
                </intent>
            </queries>
        </manifest>
        ```
      </Step>

      <Step title="Create Orders Server-Side">
        <Warning>
          **Security requirement:** Order creation must happen on your backend to protect your API key.
        </Warning>

        <CodeGroup>
          ```bash cURL theme={null}
          curl --location 'https://staging.crossmint.com/api/2022-06-09/orders' \
          --header 'x-api-key: YOUR_SERVER_API_KEY' \
          --header 'Content-Type: application/json' \
          --data-raw '{
              "recipient": {
                  "walletAddress": "YOUR_WALLET_ADDRESS"
              },
              "payment": {
                  "receiptEmail": "user@example.com",
                  "method": "card"
              },
              "lineItems": {
                  "tokenLocator": "solana:TOKEN_ADDRESS",
                  "executionParameters": {
                      "mode": "exact-in",
                      "amount": "1"
                  }
              }
          }'
          ```

          ```javascript Node.js theme={null}
          const url = 'https://staging.crossmint.com/api/2022-06-09/orders';

          const payload = {
              recipient: {
                  walletAddress: "YOUR_WALLET_ADDRESS"
              },
              payment: {
                  receiptEmail: "user@example.com",
                  method: "card"
              },
              lineItems: {
                  tokenLocator: "solana:TOKEN_ADDRESS",
                  executionParameters: {
                      mode: "exact-in",
                      amount: "1"
                  }
              }
          };

          const options = {
              method: 'POST',
              headers: {
                  'x-api-key': 'YOUR_SERVER_API_KEY',
                  'Content-Type': 'application/json'
              },
              body: JSON.stringify(payload)
          };

          const response = await fetch(url, options);
          const data = await response.json();
          console.log(data);
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2022-06-09/orders"

          payload = {
              "recipient": {
                  "walletAddress": "YOUR_WALLET_ADDRESS"
              },
              "payment": {
                  "receiptEmail": "user@example.com",
                  "method": "card"
              },
              "lineItems": {
                  "tokenLocator": "solana:TOKEN_ADDRESS",
                  "executionParameters": {
                      "mode": "exact-in",
                      "amount": "1"
                  }
              }
          }

          headers = {
              "x-api-key": "YOUR_SERVER_API_KEY",
              "Content-Type": "application/json"
          }

          response = requests.post(url, json=payload, headers=headers)
          print(response.json())
          ```
        </CodeGroup>

        The response includes `orderId` and `clientSecret` needed for the checkout component.
      </Step>

      <Step title="Implement the Checkout Component">
        ```kotlin theme={null}
        import com.crossmint.kotlin.checkout.CheckoutEnvironment
        import com.crossmint.kotlin.checkout.CrossmintEmbeddedCheckout
        import com.crossmint.kotlin.checkout.models.*

        @Composable
        fun CheckoutScreen(orderId: String, clientSecret: String) {
            CrossmintEmbeddedCheckout(
                orderId = orderId,
                clientSecret = clientSecret,
                payment = CheckoutPayment(
                    crypto = CheckoutCryptoPayment(enabled = false),
                    fiat = CheckoutFiatPayment(
                        enabled = true,
                        allowedMethods = CheckoutAllowedMethods(
                            googlePay = true,
                            applePay = false,
                            card = true
                        )
                    )
                ),
                appearance = CheckoutAppearance(
                    rules = CheckoutAppearanceRules(
                        destinationInput = CheckoutDestinationInputRule(display = "hidden"),
                        receiptEmailInput = CheckoutReceiptEmailInputRule(display = "hidden")
                    )
                ),
                environment = CheckoutEnvironment.STAGING,
                modifier = Modifier.fillMaxSize()
            )
        }
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Google Pay Production Approval

Google Pay works immediately in **staging** environments. For **production**, Google requires explicit approval of your app.

<AccordionGroup>
  <Accordion title="Step 1: Create Your Business Profile">
    1. Navigate to the [Google Pay & Wallet Console](https://pay.google.com/business/console)
    2. Select "Merchant" as your business type
    3. Complete all business profile information
    4. Navigate to **Google Pay API** and click "Get Started"
    5. Accept the Google Pay API Terms of Service
    6. Note your **Merchant ID** (top-right corner after completion)
  </Accordion>

  <Accordion title="Step 2: Submit Your Android App for Approval">
    In the Google Pay & Wallet Console:

    1. Navigate to **Google Pay API** then **Integrations** then **Integrate with your Android app**
    2. Locate your Android application and click "Manage"
    3. Select your integration type (typically "Gateway")
    4. Upload screenshots of your TEST Google Pay integration
    5. Click "Save" then "Submit for approval"

    **Required Screenshots:**

    * Product/item selection showing Google Pay option
    * Cart or checkout view with payment options
    * Google Pay payment sheet with card selection
    * Confirmation or receipt screen
  </Accordion>

  <Accordion title="Step 3: Go Live">
    After Google approval (typically \~1 business day):

    1. Sign your APK with a **release key** (debug keys don't work in production)
    2. Update environment settings:
       * Kotlin: `environment = CheckoutEnvironment.PRODUCTION`
       * React Native: Use production API key
    3. Publish your app to Google Play Store
  </Accordion>
</AccordionGroup>

## SDK Version Requirements

| Component | Minimum Version |
| - | - |
| `@crossmint/client-sdk-react-native-ui` | Latest |
| `react-native-webview` (if installed separately) | 13.15.0 |
| `com.crossmint:crossmint-sdk-android` | Latest |
| Google Play Services (user device) | 25.18.30 |

## Troubleshooting

<AccordionGroup>
  <Accordion title="Google Pay button doesn't appear">
    1. **Plugin not configured:** Verify `enableGooglePay: true` in `app.json` plugins
    2. **App not rebuilt:** Run `npx expo run:android` after adding the plugin
    3. **Environment mismatch:** Staging works without approval; production requires it
    4. **Payment method disabled:** Check `googlePay: true` in `allowedMethods`
  </Accordion>

  <Accordion title="PaymentRequest API is not supported error">
    1. **AndroidManifest missing queries:** Add all three Chromium intent queries
    2. **Native rebuild required:** Hot reload cannot apply permission changes
    3. **Device requirements:** User needs Google Play Services 25.18.30+ and WebView 137+
  </Accordion>

  <Accordion title="Order status stuck on undefined">
    1. Check that your API key is valid for the environment (staging vs production)
    2. Verify the `tokenLocator` is correct and available
    3. Ensure the quote hasn't expired (quotes have time limits)
  </Accordion>

  <Accordion title="Token checkout errors">
    **"Token purchase is only available in production":** Some tokens only work in production. Use the XMEME test token for staging: `7EivYFyNfgGj8xbUymR7J4LuxUHLKRzpLaERHLvi7Dgu`
  </Accordion>
</AccordionGroup>

## Testing Guidance

<Tabs>
  <Tab title="Staging Environment">
    * Use staging API keys from your Crossmint console
    * Google Pay functions immediately after proper configuration
    * Use XMEME test token for token testing
    * Test with real Google accounts and saved payment methods
  </Tab>

  <Tab title="Production Environment">
    * Requires completed Google approval process
    * Sign APK with release key
    * Use production API keys
    * Real charges may occur - test with small amounts
  </Tab>
</Tabs>

## Useful Resources

<CardGroup>
  <Card title="React Native Token Quickstart" icon="mobile" href="/payments/embedded/quickstarts/credit-card-memecoin-react-native">
    Get started with token checkout in React Native
  </Card>

  <Card title="Google Pay & Wallet Console" icon="wallet" href="https://pay.google.com/business/console">
    Manage your Google Pay merchant account
  </Card>

  <Card title="Checkout Expo Demo" icon="github" href="https://github.com/Crossmint/checkout-expo-demo">
    Example React Native Expo project with checkout
  </Card>

  <Card title="Kotlin Checkout SDK" icon="github" href="https://github.com/Crossmint/crossmint-kotlin-checkout">
    Example Android Kotlin project with checkout
  </Card>
</CardGroup>


# React Hooks
Source: https://docs.crossmint.com/payments/embedded/guides/hooks

Learn how to use React hooks to control and customize your Embedded Checkout experience

<Snippet />

<Snippet />

## Complete Example

Here's a full example showing how to implement a custom checkout experience:

```tsx theme={null}
import {
    CrossmintProvider,
    CrossmintCheckoutProvider,
    CrossmintEmbeddedCheckout,
    useCrossmintCheckout,
} from "@crossmint/client-sdk-react-ui";

function CheckoutPage() {
    return (
        <CrossmintProvider apiKey="YOUR_API_KEY">
            <CrossmintCheckoutProvider>
                <div className="checkout-container">
                    <CrossmintEmbeddedCheckout
                        lineItems={{
                            collectionLocator: "crossmint:your-collection-id",
                            callData: {
                                totalPrice: "0.001",
                                quantity: 1,
                            },
                        }}
                        payment={{
                            crypto: { enabled: true },
                            fiat: { enabled: true },
                        }}
                    />
                    <CheckoutStatus />
                </div>
            </CrossmintCheckoutProvider>
        </CrossmintProvider>
    );
}

function CheckoutStatus() {
    const { order } = useCrossmintCheckout();

    if (!order) {
        return <div>Loading...</div>;
    }

    switch (order.phase) {
        case "completed":
            return <div>Purchase complete!</div>;
        case "delivery":
            return <div>Delivering your NFTs...</div>;
        case "payment":
            return <div>Processing payment...</div>;
        case "quote":
            return <div>Preparing your order...</div>;
    }
}
```

<Snippet />

## Migration from Previous Version

If you're migrating from the previous version, note these key differences:

* The event system has been replaced with the `useCrossmintCheckout` hook
* Order status is now accessed through the hook instead of event listeners
* Custom UI is built using React components instead of event handlers
* Components must be wrapped with required providers

<Note>
  The new hook-based approach provides a more React-friendly experience and better TypeScript support compared to the
  previous event system.
</Note>

## Related Resources

* [UI Customization](/payments/embedded/guides/ui-customization)
* [Payment Methods](/payments/embedded/guides/payment-methods)
* [Order Lifecycle](/payments/headless/guides/order-lifecycle)
* [Testing Tips](/payments/advanced/testing-tips)


# Item Selection
Source: https://docs.crossmint.com/payments/embedded/guides/item-selection

Specify which items to purchase with Embedded Checkout

The Embedded Checkout allows you to specify which items your users can purchase using the `lineItems` property. This guide explains how to configure item selection for different asset types.

<Snippet />

## Item Selection Examples

<CodeGroup>
  ```tsx collectionLocator theme={null}
  <CrossmintProvider apiKey="_YOUR_CLIENT_API_KEY_">
      <CrossmintEmbeddedCheckout
          lineItems={{
              collectionLocator: "crossmint:_YOUR_COLLECTION_ID_", // Crossmint managed collection
              // collectionLocator: "crossmint:_YOUR_COLLECTION_ID_:_TEMPLATE_ID_", // With specific template
              callData: {
                  totalPrice: "5.00",
                  quantity: 1, // matches your contract's parameter name
              },
          }}
      />
  </CrossmintProvider>
  ```

  ```tsx collectionLocator - imported contract theme={null}
  <CrossmintProvider apiKey="_YOUR_CLIENT_API_KEY_">
      <CrossmintEmbeddedCheckout
          lineItems={{
              collectionLocator: "ethereum:0x71c7656ec7ab88b098defb751b7401b5f6d897", // External collection registered in Crossmint Console
              callData: {
                  totalPrice: "5.00",
                  quantity: 1, // matches your contract's parameter name
                  // For external contracts, you might need additional parameters such as:
                  // _amount: 1, // if your mint function uses _amount instead of quantity
                  // tokenId: "123", // if your contract requires a specific tokenId
                  // metadata: "ipfs://...", // if your contract accepts metadata
              },
          }}
      />
  </CrossmintProvider>
  ```

  ```tsx tokenLocator - EVM theme={null}
  <CrossmintProvider apiKey="_YOUR_CLIENT_API_KEY_">
      <CrossmintEmbeddedCheckout
          lineItems={{
              tokenLocator: "ethereum:0x71c7656ec7ab88b098defb751b7401b5f6d897:1234", // <blockchain>:<contractAddress>:<tokenId>
              callData: {
                  totalPrice: "25.00", // Only totalPrice is required for token purchases
                  // For external EVM contracts, you might need additional parameters:
                  // _amount: 1, // if your contract uses _amount instead of quantity
                  // tokenId: "1234", // if your contract requires explicit tokenId
                  // metadata: "ipfs://...", // if your contract accepts metadata
              },
          }}
      />
  </CrossmintProvider>
  ```

  ```tsx tokenLocator - Solana theme={null}
  <CrossmintProvider apiKey="_YOUR_CLIENT_API_KEY_">
      <CrossmintEmbeddedCheckout
          lineItems={{
              tokenLocator: "solana:7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU", // <blockchain>:<tokenAddress>
              callData: {
                  totalPrice: "25.00",
                  buyerCreatorRoyaltyPercent: 100, // Required for Solana
              },
          }}
      />
  </CrossmintProvider>
  ```
</CodeGroup>

<Snippet />

<Snippet />

<Snippet />

## Accessing Item Data in React Components

When using Embedded Checkout, you can access the current order's item data using the `useCrossmintCheckout` hook:

```tsx theme={null}
import { useCrossmintCheckout } from "@crossmint/client-sdk-react-ui";

function YourComponent() {
    const { order } = useCrossmintCheckout();

    // Access line items data
    const lineItems = order?.lineItems || [];

    return (
        <div>
            {lineItems.map((item, index) => (
                <div key={index}>
                    <h3>{item.metadata?.name}</h3>
                    <p>
                        Price: {item.quote?.totalPrice?.amount} {item.quote?.totalPrice?.currency}
                    </p>
                </div>
            ))}
        </div>
    );
}
```

<Note>
  The `useCrossmintCheckout` hook must be used within components wrapped by both `CrossmintProvider` and
  `CrossmintCheckoutProvider`.
</Note>


# Payment Methods
Source: https://docs.crossmint.com/payments/embedded/guides/payment-methods

Enable a complete payment suite for your digital asset checkout - from traditional credit cards and digital wallets to cross-chain crypto payments, all through a single integration

## Overview

Crossmint's Embedded Checkout makes it easy to accept multiple payment methods. Users can pay:

* With credit/debit cards
* Using Apple Pay or Google Pay
* Using ETH, SOL, USDC, EURC, or other supported tokens
* Using cross-chain crypto on supported chains

## Quick Integration

Enable all payment methods with just a few lines of code:

```jsx theme={null}
<CrossmintEmbeddedCheckout
    lineItems={{
        collectionLocator: `crossmint:${collectionId}`,
        callData: {
            totalPrice: "0.001",
            quantity: 1,
        },
    }}
    payment={{
        crypto: {
            enabled: true, // Enable crypto payments
        },
        fiat: {
            enabled: true, // Enable fiat payments
        },
    }}
/>
```

## Fiat Payments

### Credit Cards & Digital Wallets

Embedded Checkout provides a seamless fiat payment experience supporting:

* All major credit and debit cards
* Apple Pay for iOS/Safari users
* Google Pay for Android/Chrome users

You can configure which fiat payment methods to enable:

```jsx theme={null}
payment={{
  fiat: {
    enabled: true,
    // By default, all payment methods are enabled if you don't specify any.
    allowedMethods: {
      card: true, // Enable/disable credit cards
      applePay: true, // Enable/disable Apple Pay
      googlePay: true, // Enable/disable Google Pay
    },
    defaultCurrency: "usd" // Set default currency
  }
}}
```

## Crypto Payments

### Native Wallet Support

Embedded Checkout works with any Web3 wallet, including:

* MetaMask
* Coinbase Wallet
* WalletConnect
* Phantom

Users can pay with ETH, SOL, stablecoins (USDC, EURC), or other supported tokens on their preferred chain. Enable crypto payments with:

```jsx theme={null}
payment={{
  crypto: {
    enabled: true,
    defaultChain: "ethereum", // Optional: Set default blockchain
    defaultCurrency: "usdc" // Optional: Set default currency (usdc, eurc, eth)
  }
}}
```

## Cross-Chain Support

The checkout supports paying with funds from any supported blockchain, even if the digital asset is on a different chain. For example, a user could pay for a digital asset on Polygon using ETH from their Ethereum wallet. The checkout handles all necessary conversions automatically.

## Customizing the Default Experience

Set a default payment method to guide users:

```jsx theme={null}
payment={{
  defaultMethod: "fiat", // or "crypto"
  crypto: {
    enabled: true
  },
  fiat: {
    enabled: true
  }
}}
```

### Test Price Limits and Test Credit Cards

When building your applications using the staging environment, you can use various test credit cards numbers to see the entire process end-to-end, without actually having to transact using a real credit card. Check out the Testing Tips page for more info on [price limits](/payments/advanced/testing-tips#limits-in-staging) and [test card numbers](/payments/advanced/testing-tips#test-credit-card-numbers).

## Best Practices

* Enable Multiple Payment Methods: Offer both fiat and crypto options to maximize conversion
* Set Default Currency: Choose a default that matches your target market
* Test All Flows: Use test cards and test wallets to verify the complete payment experience
* Handle Events: Use the `useCrossmintCheckout` hook to track payment status and handle completion

## Related Resources

* [Price Limits](/payments/advanced/testing-tips#limits-in-staging)
* [Test Credit Card Numbers](/payments/advanced/testing-tips#test-credit-card-numbers)
* [Order Lifecycle](/payments/headless/guides/order-lifecycle)
* [Customizing Appearance](/payments/embedded/guides/ui-customization)
* [React Hooks](/payments/embedded/guides/hooks)


# Production Launch
Source: https://docs.crossmint.com/payments/embedded/guides/production-launch

Follow this checklist to ensure you are ready for production launch with Embedded Checkout

## From Staging to Production with Embedded Checkout

<Snippet />

***

### Launch Checklist

1. Change your API keys to the production versions. Ensure your production API key has the appropriate scopes enabled, such as `orders.create`.
2. Update your collection ID to the production one.
3. As needed, change your passed-in props to be production ready (e.g. make `email`, `payment`, `lineItems` programmatically filled).

<Accordion title="See Code Example">
  <CodeGroup>
    ```jsx {(1, 4)} Production theme={null}
    <CrossmintProvider apiKey="YOUR_PROD_API_KEY">
        <CrossmintEmbeddedCheckout
            lineItems={{
                collectionLocator: "crossmint:YOUR_PROD_COLLECTION_ID",
                callData: {
                    totalPrice: "0.25",
                    quantity: 1,
                },
            }}
            payment={{
                crypto: { enabled: true },
                fiat: { enabled: true },
            }}
            recipient={{
                email: "steve@gmail.com",
            }}
        />
    </CrossmintProvider>
    ```

    ```jsx {(1, 4)} Staging theme={null}
    <CrossmintProvider apiKey="YOUR_STAGING_API_KEY">
        <CrossmintEmbeddedCheckout
            lineItems={{
                collectionLocator: "crossmint:YOUR_STAGING_COLLECTION_ID",
                callData: {
                    totalPrice: "0.001",
                    quantity: 1,
                },
            }}
            payment={{
                crypto: { enabled: true },
                fiat: { enabled: true },
            }}
            recipient={{
                email: "test@crossmint.com",
            }}
        />
    </CrossmintProvider>
    ```
  </CodeGroup>
</Accordion>


# Specify Recipient
Source: https://docs.crossmint.com/payments/embedded/guides/specify-recipient

Select where purchased items should be delivered in Embedded Checkout

<Snippet />

## Specifying the Recipient

For Embedded Checkout, you specify the recipient by adding a `recipient` object to your checkout component. The recipient can be specified by email or wallet address.

### Recipient by Email

When specifying a recipient by email, Crossmint will automatically create a secure custodial wallet on the fly for that email address:

```jsx React {4} theme={null}
<CrossmintProvider apiKey="YOUR_API_KEY">
    <CrossmintEmbeddedCheckout
        recipient={{
            email: "user@example.com", // Email address of the recipient
        }}
        // other properties removed for brevity
    />
</CrossmintProvider>
```

The recipient will be able to access their purchased items by logging into their Crossmint wallet in [staging](https://staging.crossmint.com/user/collection) or [mainnet](https://www.crossmint.com/user/collection).

### Recipient by Wallet Address

To deliver items directly to a specific blockchain wallet address:

```jsx React {4} theme={null}
<CrossmintProvider apiKey="YOUR_API_KEY">
    <CrossmintEmbeddedCheckout
        recipient={{
            walletAddress: "0x1234567890abcdef1234567890abcdef12345678", // For EVM chains
            // walletAddress: "5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty" // For Solana
        }}
        // other properties removed for brevity
    />
</CrossmintProvider>
```


# UI Customization
Source: https://docs.crossmint.com/payments/embedded/guides/ui-customization

Learn how to customize the Embedded Checkout UI to match your brand identity and design system

## Quick Start

The checkout UI can be customized using the `appearance` prop:

```jsx theme={null}
<CrossmintEmbeddedCheckout
    appearance={{
        fonts: [{ cssSrc: "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap" }],
        variables: {
            fontFamily: "Inter, system-ui, sans-serif",
            colors: {
                backgroundPrimary: "#ffffff",
                textPrimary: "#000000",
                accent: "#0074D9",
            },
        },
    }}
/>
```

## Identity Verification Screens

<Snippet />

## Customization Options

### Background Customization

The embedded checkout component has a **transparent background** by default. The `backgroundPrimary` color in the appearance configuration only affects internal components (inputs, cards, etc.) within the iframe, not the iframe body itself.

To customize the overall background, wrap the component in a div with your desired background styling:

#### Solid Background Colors

```jsx theme={null}
{
    /* Tailwind CSS */
}
<div className="bg-gray-900">
    <CrossmintEmbeddedCheckout {...props} />
</div>;

{
    /* Custom CSS */
}
<div style={{ backgroundColor: "#1a1a1a" }}>
    <CrossmintEmbeddedCheckout {...props} />
</div>;
```

<Note>
  Remember that the `backgroundPrimary` color in your appearance configuration should complement your wrapper
  background for the best visual result.
</Note>

### Custom Fonts

Load custom fonts using the `fonts` array:

```jsx theme={null}
appearance={{
  fonts: [
    { cssSrc: "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap" },
    { cssSrc: "https://fonts.googleapis.com/css2?family=Roboto:wght@400;500;700&display=swap" }
  ]
}}
```

### Global Variables

Control the overall look and feel with these global variables:

```jsx theme={null}
appearance={{
  variables: {
    // Typography
    fontFamily: "Inter, system-ui, sans-serif",
    fontSizeUnit: "16px",

    // Spacing
    spacingUnit: "1rem",
    borderRadius: "8px",

    // Colors
    colors: {
      borderPrimary: "#E0E0E0",
      backgroundPrimary: "#FFFFFF",
      textPrimary: "#000000",
      textSecondary: "#666666",
      danger: "#FF0000",
      warning: "#FFA500",
      accent: "#0074D9"
    }
  }
}}
```

### Component Rules

<AccordionGroup>
  <Accordion title="Input Visibility">
    Control the visibility of specific inputs:

    ```jsx theme={null}
    appearance={{
      rules: {
        DestinationInput: {
          display: "hidden"  // Hides the wallet address input
        },
        ReceiptEmailInput: {
          display: "hidden"  // Hides the email input
        }
      }
    }}
    ```

    <Note>
      When hiding inputs, make sure to provide the corresponding values via props:

      * For hidden `DestinationInput`, provide `recipient.walletAddress`
      * For hidden `ReceiptEmailInput`, provide `payment.receiptEmail`
    </Note>
  </Accordion>

  <Accordion title="Labels">
    Customize label styling:

    ```jsx theme={null}
    appearance={{
        rules: {
            Label: {
                font: {
                    family: "Inter",
                    size: "14px",
                    weight: "500",
                },
                colors: {
                    text: "#333333",
                },
            },
        },
    }}
    ```
  </Accordion>

  <Accordion title="Input Fields">
    Style input fields:

    ```jsx theme={null}
    appearance={{
        rules: {
            Input: {
                borderRadius: "8px",
                font: {
                    family: "Inter",
                    size: "16px",
                    weight: "400",
                },
                colors: {
                    text: "#000000",
                    background: "#FFFFFF",
                    border: "#E0E0E0",
                    boxShadow: "none",
                    placeholder: "#999999",
                },
                hover: {
                    colors: {
                        border: "#0074D9",
                    },
                },
                focus: {
                    colors: {
                        border: "#0074D9",
                        boxShadow: "0 0 0 2px rgba(0,116,217,0.2)",
                    },
                },
            },
        },
    }}
    ```
  </Accordion>

  <Accordion title="Tabs">
    Customize tab appearance:

    ```jsx theme={null}
    appearance={{
        rules: {
            Tab: {
                borderRadius: "4px",
                font: {
                    family: "Inter",
                    size: "14px",
                    weight: "500",
                },
                colors: {
                    text: "#666666",
                    background: "transparent",
                },
                selected: {
                    colors: {
                        text: "#000000",
                        background: "#F5F5F5",
                    },
                },
                hover: {
                    colors: {
                        background: "#F0F0F0",
                    },
                },
            },
        },
    }}
    ```
  </Accordion>

  <Accordion title="Primary Buttons">
    Style primary buttons:

    ```jsx theme={null}
    appearance={{
      rules: {
        PrimaryButton: {
          borderRadius: "8px",
          font: {
            family: "Inter",
            size: "16px",
            weight: "600"
          },
          colors: {
            text: "#FFFFFF",
            background: "#0074D9"
          },
          hover: {
            colors: {
              background: "#0063B8"
            }
          },
          disabled: {
            colors: {
              text: "#FFFFFF",
              background: "#CCCCCC"
            }
          }
        }
      }
    }}
    ```
  </Accordion>
</AccordionGroup>

## Common Examples

### Modern Dark Theme

```jsx theme={null}
appearance={{
  variables: {
    fontFamily: "Inter, system-ui, sans-serif",
    colors: {
      backgroundPrimary: "#1A1A1A",
      textPrimary: "#FFFFFF",
      textSecondary: "#A0A0A0",
      borderPrimary: "#333333",
      accent: "#7928CA"
    }
  },
  rules: {
    Input: {
      colors: {
        background: "#2D2D2D",
        border: "#404040",
        text: "#FFFFFF",
        placeholder: "#666666"
      }
    },
    PrimaryButton: {
      colors: {
        background: "#7928CA",
        text: "#FFFFFF"
      },
      hover: {
        colors: {
          background: "#6B24B2"
        }
      }
    }
  }
}}
```

### Minimal Light Theme

```jsx theme={null}
appearance={{
  variables: {
    fontFamily: "system-ui, sans-serif",
    borderRadius: "4px",
    colors: {
      backgroundPrimary: "#FFFFFF",
      textPrimary: "#000000",
      borderPrimary: "#E0E0E0",
      accent: "#000000"
    }
  },
  rules: {
    Input: {
      borderRadius: "4px",
      colors: {
        background: "#F5F5F5",
        border: "transparent"
      },
      focus: {
        colors: {
          border: "#000000",
          boxShadow: "none"
        }
      }
    },
    PrimaryButton: {
      borderRadius: "4px",
      colors: {
        background: "#000000",
        text: "#FFFFFF"
      }
    }
  }
}}
```

## Related Resources

* [Identity Verification UI Customization](/identity/ui-customization)
* [Payment Methods](/payments/embedded/guides/payment-methods)
* [React Hooks](/payments/embedded/guides/hooks)
* [Order Lifecycle](/payments/headless/guides/order-lifecycle)
* [Testing Tips](/payments/advanced/testing-tips)


# Mobile WebView Integration
Source: https://docs.crossmint.com/payments/embedded/guides/webview-integration

Render the embedded checkout inside your own WebView on iOS, Android, or React Native

The embedded checkout renders from a URL, so any mobile app can display it in a WebView: create an order server-side, build the checkout URL, and load it. This guide covers the direct WebView integration for apps that do not use a Crossmint client SDK, including native iOS (Swift) and Android (Kotlin) apps.

<Note>
  The [React Native](/payments/embedded/quickstarts/credit-card-memecoin-react-native),
  [Flutter](/payments/embedded/quickstarts/credit-card-memecoin-flutter), and
  [Kotlin](/sdk-reference/checkout/kotlin/index) SDKs render and configure this WebView for you. If you build with one
  of those frameworks, start from the SDK instead and return here only if you need full control over the WebView.
</Note>

## Prerequisites

* **API keys**: From the [Crossmint Console](https://staging.crossmint.com/console), under **Integrate → API Keys**, create a **server key** (`sk_staging_...`) with the `orders.create` and `orders.read` scopes, and a **client key** (`ck_staging_...`) with the `orders.read` scope.
* **A recipient wallet**: purchased assets are delivered to a wallet address that you pass at order creation.
* **A backend**: order creation uses the server key, which must never ship inside the app.

## Integration

<Steps>
  <Step title="Create the order server-side">
    Create the order from your backend and return the `orderId` and `clientSecret` to the app. The order carries the item, the recipient, and optionally the receipt email, so the checkout never needs to ask the user for them:

    ```javascript theme={null}
    // server.js
    const CROSSMINT_SERVER_API_KEY = "YOUR_SERVER_API_KEY"; // sk_staging_...

    // sk_staging_ keys pair with staging.crossmint.com,
    // sk_production_ keys with www.crossmint.com
    const BASE_URL = "https://staging.crossmint.com";

    async function createOrder(walletAddress) {
        const res = await fetch(`${BASE_URL}/api/2022-06-09/orders`, {
            method: "POST",
            headers: {
                "Content-Type": "application/json",
                "x-api-key": CROSSMINT_SERVER_API_KEY,
            },
            body: JSON.stringify({
                lineItems: {
                    // XMEME test token on Solana (staging only)
                    tokenLocator: "solana:7EivYFyNfgGj8xbUymR7J4LuxUHLKRzpLaERHLvi7Dgu",
                    executionParameters: {
                        mode: "exact-in",
                        amount: "5",
                        maxSlippageBps: "500",
                    },
                },
                payment: { method: "card" }, // wallet payment methods ride this rail at creation time
                recipient: { walletAddress },
            }),
        });

        const data = await res.json();
        if (!res.ok) {
            throw new Error(data.message ?? "Order creation failed");
        }
        return {
            orderId: data.order.orderId,
            clientSecret: data.clientSecret,
        };
    }
    ```

    The example uses a token line item; NFT collection line items work the same way. See the
    [create order API reference](/api-reference/headless/create-order) for all line item types and options.
  </Step>

  <Step title="Build the checkout URL">
    The checkout page accepts its configuration as URL query parameters:

    | Parameter | Value |
    | - | - |
    | `orderId` | From order creation |
    | `clientSecret` | From order creation |
    | `apiKey` | Your **client** key (`ck_...`) |
    | `payment` | URL-encoded JSON. Same options as the `payment` prop of the React component |
    | `appearance` | URL-encoded JSON. Same options as the `appearance` prop of the React component |

    ```javascript theme={null}
    const BASE_URL = "https://staging.crossmint.com"; // www.crossmint.com in production
    const CLIENT_API_KEY = "YOUR_CLIENT_API_KEY"; // ck_staging_...

    const payment = {
        crypto: { enabled: false },
        fiat: {
            enabled: true,
            allowedMethods: { applePay: true, card: false, googlePay: true },
        },
    };

    const appearance = {
        rules: {
            DestinationInput: { display: "hidden" },
            ReceiptEmailInput: { display: "hidden" },
            GlobalMessage: { display: "visible" },
        },
    };

    function buildCheckoutUrl(orderId, clientSecret) {
        const params = new URLSearchParams({
            orderId,
            clientSecret,
            payment: JSON.stringify(payment),
            appearance: JSON.stringify(appearance),
            apiKey: CLIENT_API_KEY,
        });
        return `${BASE_URL}/sdk/2024-03-05/embedded-checkout?${params.toString()}`;
    }
    ```

    Every configuration option from [payment methods](/payments/embedded/guides/payment-methods) and
    [UI customization](/payments/embedded/guides/ui-customization) works here. The example above renders a
    wallet-button-only checkout; see the
    [one-tap Apple Pay quickstart](/payments/embedded/quickstarts/apple-pay-only) for that experience end to end.
  </Step>

  <Step title="Render the URL in a WebView">
    A few WebView settings make the difference between a checkout that shows Apple Pay and Google Pay and one that silently does not. The tabs below contain the tested configuration per platform:

    <Tabs>
      <Tab title="React Native">
        Requires <a href="https://github.com/react-native-webview/react-native-webview">react-native-webview</a> version 13.15.0 or higher.

        ```tsx theme={null}
        import { Platform } from "react-native";
        import { WebView } from "react-native-webview";

        // A standard mobile browser userAgent. The default WebView userAgent
        // identifies as an app, and the checkout hides wallet buttons for it.
        const userAgent = Platform.select({
            ios: "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1",
            android:
                "Mozilla/5.0 (Linux; Android 14) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Mobile Safari/537.36",
        });

        export function CheckoutWebView({ checkoutUrl }: { checkoutUrl: string }) {
            return (
                <WebView
                    source={{ uri: checkoutUrl }}
                    userAgent={userAgent}
                    paymentRequestEnabled={true} // Google Pay; no effect on iOS
                    allowsInlineMediaPlayback={true}
                    mediaPlaybackRequiresUserAction={false}
                    domStorageEnabled={true}
                />
            );
        }
        ```

        For Google Pay, the app also needs the Android payment intent declaration from the
        [Google Pay guide](/payments/embedded/guides/google-pay).
      </Tab>

      <Tab title="Android (Kotlin)">
        Add the <a href="https://developer.android.com/jetpack/androidx/releases/webkit">androidx.webkit</a> dependency to reach the Payment Request setting, which Google Pay requires and Android WebView ships disabled:

        ```kotlin theme={null}
        import android.webkit.WebChromeClient
        import android.webkit.WebView
        import android.webkit.WebViewClient
        import androidx.webkit.WebSettingsCompat
        import androidx.webkit.WebViewFeature

        fun configureCheckoutWebView(webView: WebView, checkoutUrl: String) {
            webView.settings.apply {
                javaScriptEnabled = true
                domStorageEnabled = true
                userAgentString =
                    "Mozilla/5.0 (Linux; Android 14) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Mobile Safari/537.36"
            }
            if (WebViewFeature.isFeatureSupported(WebViewFeature.PAYMENT_REQUEST)) {
                WebSettingsCompat.setPaymentRequestEnabled(webView.settings, true)
            }
            // Default clients keep every step of the checkout inside the WebView
            webView.webViewClient = WebViewClient()
            webView.webChromeClient = WebChromeClient()
            webView.loadUrl(checkoutUrl)
        }
        ```

        Declare the payment intent in `AndroidManifest.xml` so Google Pay can respond:

        ```xml theme={null}
        <manifest xmlns:android="http://schemas.android.com/apk/res/android">
            <queries>
                <intent>
                    <action android:name="org.chromium.intent.action.PAY" />
                </intent>
            </queries>
        </manifest>
        ```
      </Tab>

      <Tab title="iOS (Swift)">
        `WKWebView` needs inline media playback enabled; its other defaults work with the checkout as-is:

        ```swift theme={null}
        import WebKit

        func makeCheckoutWebView(checkoutUrl: URL) -> WKWebView {
            let configuration = WKWebViewConfiguration()
            configuration.allowsInlineMediaPlayback = true
            configuration.mediaTypesRequiringUserActionForPlayback = []

            let webView = WKWebView(frame: .zero, configuration: configuration)
            webView.load(URLRequest(url: checkoutUrl))
            return webView
        }
        ```

        <Note>
          If your app declares `WKAppBoundDomains` in its `Info.plist`, WebKit restricts every `WKWebView` to those
          domains. Add the domains listed under "Restricting navigation" below to that list, or the checkout cannot
          complete.
        </Note>
      </Tab>
    </Tabs>

    <Warning>
      Keep navigation inside the WebView unrestricted, and keep iframes enabled. To complete an order, the checkout
      navigates to pages from Crossmint's payment method and identity partners, and a WebView that blocks those
      pages interrupts the purchase with no visible error.
    </Warning>

    <Accordion title="Restricting navigation: the domains the checkout uses">
      If your security policy requires a navigation allowlist, include these domains, grouped by what they render
      during checkout:

      | Purpose | Domains |
      | - | - |
      | Checkout and order pages | `crossmint.com` |
      | Card and wallet payment methods | `stripe.com`, `checkout.com`, `pay.google.com`, `applepay.cdn-apple.com` |
      | Identity verification and risk screening | `withpersona.com`, `sardine.ai` |

      Match subdomains as well (for example `*.crossmint.com`), and revisit the list when you update the SDK or
      change payment methods.
    </Accordion>
  </Step>

  <Step title="Track the order">
    The checkout page reports progress with messages. In React Native, listen with `onMessage`:

    ```tsx theme={null}
    <WebView
        // ...configuration from the previous step
        onMessage={(event) => {
            const message = JSON.parse(event.nativeEvent.data);
            // message.event is one of:
            //   order:updated              order phase changes; "delivery" means the purchase succeeded
            //   order:creation-failed     the order could not initialize
            //   ui:height.changed          the checkout has rendered content
            //   ui:express-checkout.ready  the wallet button is interactive
            if (message.event === "order:updated" && message.data?.order?.phase === "delivery") {
                // show your success state
            }
        }}
    />
    ```

    On iOS (Swift) and Android (Kotlin), track the order from your backend instead: subscribe to
    [webhooks](/payments/advanced/webhooks) or poll the
    [get order endpoint](/api-reference/headless/get-order) with the `orderId` you already hold.
  </Step>

  <Step title="Test on a physical device">
    Wallet payment methods render on real hardware: test Apple Pay on an iPhone running iOS 17 or higher with a card added to Apple Wallet, and Google Pay on an Android device with Google Play Services. In staging, wallet payments run against a test environment, so the card behind the wallet is never charged.

    To exercise the full purchase from a simulator or emulator during development, enable the card form
    (`allowedMethods: { card: true, ... }`) and pay with the staging test card `4242 4242 4242 4242`. More options are
    listed in [testing tips](/payments/advanced/testing-tips#test-credit-card-numbers).
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The wallet button does not render">
    * Set a standard mobile browser `userAgent` on the WebView (step 3). The checkout serves wallet buttons to
      mobile browsers, and the default WebView userAgent identifies as an app.
    * For Google Pay, enable the Payment Request setting and declare the payment intent in the manifest (step 3),
      and test on a device with Google Play Services.
    * For Apple Pay, use a physical iPhone on iOS 17 or higher: the iOS Simulator does not render Apple Pay.
    * Confirm the order was created successfully and `payment` in the URL enables the wallet you expect.
  </Accordion>

  <Accordion title="The payment sheet opens but the purchase never completes">
    A navigation restriction is usually interrupting the checkout mid-purchase. Remove custom
    `WebViewClient`/`WKNavigationDelegate` rules that cancel navigations, or extend your allowlist with the
    domains listed under "Restricting navigation" above.
  </Accordion>

  <Accordion title="The checkout page does not load">
    * Enable JavaScript and DOM storage on the WebView (step 3).
    * Match the base URL to the key environment: `ck_staging_`/`sk_staging_` keys pair with
      `staging.crossmint.com`, production keys with `www.crossmint.com`.
    * Confirm the `payment` and `appearance` parameters contain valid JSON after URL encoding.
  </Accordion>

  <Accordion title="A payment fails and nothing appears on screen">
    Pass `GlobalMessage: { display: "visible" }` inside `appearance.rules` (step 2). In layouts that hide the
    checkout inputs, this rule is the surface where payment errors render.
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Can a Crossmint SDK handle this for me?">
    Yes. The [React Native](/payments/embedded/quickstarts/credit-card-memecoin-react-native),
    [Flutter](/payments/embedded/quickstarts/credit-card-memecoin-flutter), and
    [Kotlin](/sdk-reference/checkout/kotlin/index) SDKs apply this WebView configuration automatically and expose
    the checkout as a component. Use this guide when you need your own WebView, or on platforms without an SDK,
    such as native iOS (Swift).
  </Accordion>

  <Accordion title="Do I need to register a domain for Apple Pay?">
    No. [Apple Pay domain registration](/payments/embedded/guides/apple-pay) applies to websites that embed the
    checkout. In this integration the checkout page is served from `crossmint.com`, which is already enabled for
    Apple Pay.
  </Accordion>

  <Accordion title="How do I render only the Apple Pay or Google Pay button?">
    Restrict the payment methods and hide the checkout inputs through the `payment` and `appearance` URL
    parameters. The [one-tap Apple Pay quickstart](/payments/embedded/quickstarts/apple-pay-only) covers the
    complete configuration, and every setting in it maps directly onto the URL parameters from step 2.
  </Accordion>

  <Accordion title="Can I open the checkout in a browser instead of a WebView?">
    Yes. The checkout URL also renders in `SFSafariViewController`, Chrome Custom Tabs, or a regular browser tab.
    A WebView keeps the checkout inside your own screens; a browser surface takes less configuration and suits
    flows where opening a sheet over the app is acceptable.
  </Accordion>

  <Accordion title="Which payment methods can users see?">
    The same ones as the embedded checkout on web: cards, Apple Pay, Google Pay, and crypto, controlled by the
    `payment` URL parameter. See [payment methods](/payments/embedded/guides/payment-methods).
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="One-Tap Apple Pay" icon="apple" href="/payments/embedded/quickstarts/apple-pay-only">
    Render only the wallet button and build the rest of the experience in your own UI
  </Card>

  <Card title="Google Pay Mobile" icon="google" href="/payments/embedded/guides/google-pay">
    Production approval and native Android configuration for Google Pay
  </Card>

  <Card title="UI Customization" icon="paintbrush" href="/payments/embedded/guides/ui-customization">
    Theme the checkout through the appearance parameter
  </Card>
</CardGroup>


# Overview
Source: https://docs.crossmint.com/payments/embedded/overview

Create seamless purchases with a fully customizable checkout experience

For an overview of our checkout solution, please refer to the [introduction](/payments/introduction). This guide specifically covers embedded checkout features.

## See It in Action

The video below showcases Embedded Checkout for memecoins on <a href="https://fomo.family/">fomo</a>, highlighting a seamless mobile onboarding experience with Apple Pay.

<video />

## When is the Embedded Checkout the best fit?

Embedded Checkout is the best choice for most teams. It offers experiences that can feel fully native (see the video above), and is a more complete product than headless. Embedded handles orchestration between multiple PSPs, error and state management, and has better approval rates than headless.

## Integration Methods

Embedded Checkout renders the same checkout experience on every platform. Pick the integration that matches your stack:

| Platform | Integration | Start here |
| - | - | - |
| Web | React SDK | [Quickstart](/payments/embedded/quickstarts/credit-card-nft) |
| React Native | React Native SDK | [Quickstart](/payments/embedded/quickstarts/credit-card-memecoin-react-native) |
| Flutter | Flutter SDK | [Quickstart](/payments/embedded/quickstarts/credit-card-memecoin-flutter) |
| Android (Kotlin) | Kotlin SDK | [SDK reference](/sdk-reference/checkout/kotlin/index) |
| iOS (Swift) or any other stack | Your own WebView | [Mobile WebView Integration](/payments/embedded/guides/webview-integration) |

The SDKs are the fastest path on their platforms. The [WebView integration](/payments/embedded/guides/webview-integration) works anywhere a WebView does and gives you full control over how the checkout is hosted.

## Get Started

<CardGroup>
  <Card title="Quickstart" icon="bolt" href="/payments/embedded/quickstarts/credit-card-nft">
    Start selling digital assets in 5 minutes.
  </Card>

  <Card title="Talk to an expert" icon="message" href="https://www.crossmint.com/contact/sales">
    Contact our sales team for advanced support.
  </Card>
</CardGroup>

## Advanced Topics

<CardGroup>
  <Card title="Marketplaces & Launchpads" icon="cart-shopping" href="/payments/advanced/marketplaces-and-launchpads" />

  <Card title="SDK Reference" icon="gear" href="/sdk-reference/checkout/react/components" />

  <Card title="Purchasing Multiple Assets" icon="rectangle-vertical-history" href="/payments/pay-button/guides/item-selection#multiple-item-orders" />

  <Card title="Bring your own Collection" icon="file-import" href="/payments/guides/register-collection" />

  <Card title="USDC Contracts" icon="circle-dollar" href="/payments/advanced/usdc-support" />

  <Card title="Checkout Localization" icon="globe" href="/payments/embedded/customize/localization" />

  <Card title="Webhooks" icon="bars-progress" href="/payments/advanced/webhooks" />

  <Card title="Accesslists" icon="clipboard" href="/payments/advanced/accesslists" />
</CardGroup>


# One-Tap Pay - Tokens (React)
Source: https://docs.crossmint.com/payments/embedded/quickstarts/apple-pay-only

Render only the Apple Pay or Google Pay button and build the rest of the checkout experience in your own UI

<Snippet />

## Introduction

This guide shows you how to configure Crossmint's Embedded Checkout so it renders **only the Apple Pay or Google Pay button**, and everything else on the screen is yours: your amount selector, your token UI, your success states. Rendering just the wallet button gives users a smooth one-tap purchase experience inside your own UI.

You'll learn how to:

* Restrict the embedded checkout to a single payment method
* Create the order server-side so the pay button is ready when the user sees it
* Hide the checkout's built-in inputs and surface payment errors in your layout
* Detect success and update your own UI

## The five required settings

The whole experience is this configuration. There is no single "Apple Pay only" switch: restricting the payment methods removes the tabs and forms, hiding the two inputs removes the rest, and the error rule gives payment failures a place to render.

```tsx theme={null}
<CrossmintEmbeddedCheckout
  orderId={order.orderId} // created server-side (step 2)
  clientSecret={order.clientSecret}
  payment={{
    receiptEmail: email, // 1. receipt email, so the user is never asked for it
    crypto: { enabled: false }, // 2. restrict methods to Apple Pay only...
    fiat: {
      enabled: true,
      allowedMethods: { applePay: true, card: false, googlePay: false },
    },
  }}
  appearance={{
    rules: {
      DestinationInput: { display: "hidden" }, // 3. hide the wallet input (the order carries the recipient)
      ReceiptEmailInput: { display: "hidden" }, // 4. hide the email input
      GlobalMessage: { display: "visible" }, // 5. surface payment errors
    },
  }}
/>
```

<Warning>
  `GlobalMessage: { display: "visible" }` is essential for pay-button-only integrations. It renders payment failures
  (for example, a payment blocked by risk checks) directly above the button. Without it, this layout has no other
  surface for errors, so a declined order looks like nothing happened.
</Warning>

<Tip>
  To reach buyers on Android and desktop Chrome too, enable Google Pay — but keep exactly **one** wallet enabled per
  visitor, or the checkout shows a method selector in browsers that support both. Detect Apple Pay in your page and
  flip the flags:

  ```tsx theme={null}
  // detect after mount: window only exists in the browser, and frameworks
  // that render on the server (such as Next.js) crash on it during render
  const [applePay, setApplePay] = useState(false);

  useEffect(() => {
    const session = (window as { ApplePaySession?: { canMakePayments(): boolean } })
      .ApplePaySession;
    setApplePay(Boolean(session?.canMakePayments()));
  }, []);

  // in the component props:
  allowedMethods: applePay
    ? { applePay: true, card: false, googlePay: false }
    : { applePay: false, card: false, googlePay: true }
  ```

  This keeps the one-tap, single-button look everywhere: Apple Pay in Safari and on iPhone, Google Pay elsewhere.
</Tip>

## Prerequisites

<Note>
  Create everything below in the **same project**: the server key that creates the order, the client key the widget
  renders with, and the Apple Pay domain registration all work together, and the payment sheet validates against the
  project the order belongs to.
</Note>

<Steps>
  <Step title="Get API keys">
    From the <a href="https://staging.crossmint.com/console">Crossmint Console</a>, under **Integrate → API Keys**, create:

    * A **client key** (`ck_staging_...`) with the `orders.read` scope, plus `users.create`, `users.read`,
      `wallets.read`, `wallets.create`, and `wallets:balance.read` if you also use Crossmint Auth and Wallets as
      the demo app does. Add every origin the app runs on (for example `http://localhost:3000` and your public
      domain) to the key's **origins allowlist**.
    * A **server key** (`sk_staging_...`) with the `orders.create` and `orders.read` scopes.
  </Step>

  <Step title="Get a public HTTPS domain">
    Apple Pay validates the merchant against the domain serving your page, so the domain must be publicly
    reachable over HTTPS — `localhost` cannot be registered. For local development, tunnel your dev server with
    <a href="https://ngrok.com">ngrok</a> (`ngrok http 3000`) and use the resulting domain.
  </Step>

  <Step title="Register the domain for Apple Pay">
    In the console, under **Integrate → Apple Pay Domains**:

    1. Download the verification file and serve it at
       `https://<your-domain>/.well-known/apple-developer-merchantid-domain-association`. In Next.js, place it at
       `public/.well-known/apple-developer-merchantid-domain-association`.
    2. Enter your domain and click **Verify domain**. The status turns to `verified` immediately once the file is
       reachable.

    See the [Apple Pay setup guide](/payments/embedded/guides/apple-pay) for framework-specific hosting details.
  </Step>

  <Step title="Have a recipient wallet">
    The purchased tokens are delivered to a Solana wallet address. Use any address you control, or create wallets
    for your users with [Crossmint Wallets](/wallets/quickstarts/client-side-wallets) as the demo app does.
  </Step>
</Steps>

## Integration

The example buys XMEME, the staging test token, on Solana. Production tokens will not work in the staging environment.

<Steps>
  <Step title="Add environment variables">
    Create `.env.local` in your Next.js project root:

    ```sh theme={null}
    NEXT_PUBLIC_CROSSMINT_CLIENT_API_KEY="_YOUR_CLIENT_API_KEY_"
    SERVER_API_KEY="_YOUR_SERVER_API_KEY_"
    ```
  </Step>

  <Step title="Create the order server-side">
    Create `app/checkout/actions.ts`. The server key never reaches the browser, and the order carries the recipient and the receipt email, so the checkout never needs to ask for them:

    ```ts theme={null}
    "use server";

    const serverApiKey = process.env.SERVER_API_KEY ?? "";

    const baseUrl = serverApiKey.startsWith("sk_production")
      ? "https://www.crossmint.com"
      : "https://staging.crossmint.com";

    // XMEME test token on Solana (staging only)
    const TOKEN_LOCATOR = "solana:7EivYFyNfgGj8xbUymR7J4LuxUHLKRzpLaERHLvi7Dgu";

    export async function createOrder(
      amountUsd: string,
      email: string,
      walletAddress: string,
    ) {
      const res = await fetch(`${baseUrl}/api/2022-06-09/orders`, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "x-api-key": serverApiKey,
        },
        body: JSON.stringify({
          lineItems: {
            tokenLocator: TOKEN_LOCATOR,
            executionParameters: {
              mode: "exact-in", // amount is the exact USD to spend
              amount: amountUsd,
              maxSlippageBps: "500",
            },
          },
          payment: {
            method: "card", // wallet payments ride the card rail at creation time
            receiptEmail: email,
          },
          recipient: {
            walletAddress,
          },
        }),
      });

      const data = await res.json();
      if (!res.ok) {
        throw new Error(data.message ?? "Failed to create order");
      }
      return {
        orderId: data.order.orderId as string,
        clientSecret: data.clientSecret as string,
      };
    }
    ```

    <Note>
      The base URL must match your key's environment: `sk_staging_` keys pair with `staging.crossmint.com` and
      `sk_production_` keys with `www.crossmint.com`.
    </Note>
  </Step>

  <Step title="Render only the Apple Pay button">
    Create `app/checkout/page.tsx`. Three details make the experience feel native:

    * **Create the order as soon as the user picks an amount**, not on a separate confirm button. Order creation takes a moment, so starting early means the Apple Pay button is ready by the time the user looks at it.
    * **Show a loader until the iframe reports content** via the `ui:height.changed` message, then reveal the button.
    * **The Apple Pay button is the CTA.** Do not add your own "Continue" button in front of it; one tap should open the payment sheet.

    ```tsx theme={null}
    "use client";

    import { useEffect, useState } from "react";
    import {
      CrossmintProvider,
      CrossmintCheckoutProvider,
      CrossmintEmbeddedCheckout,
      useCrossmintCheckout,
    } from "@crossmint/client-sdk-react-ui";

    import { createOrder } from "./actions";

    const RECIPIENT_WALLET = "_YOUR_SOLANA_WALLET_ADDRESS_";
    const RECEIPT_EMAIL = "_YOUR_EMAIL_";
    const AMOUNTS = ["1", "5", "10"];

    function Checkout() {
      const [amount, setAmount] = useState("1");
      const [order, setOrder] = useState<{
        orderId: string;
        clientSecret: string;
      } | null>(null);
      const [ready, setReady] = useState(false);
      const { order: checkoutOrder } = useCrossmintCheckout();

      // create the order as soon as the user picks an amount, so the Apple Pay
      // button is already loading by the time they look at it. The cleanup flag
      // discards responses from amounts the user has already moved past.
      useEffect(() => {
        let current = true;
        setOrder(null);
        setReady(false);
        void createOrder(amount, RECEIPT_EMAIL, RECIPIENT_WALLET).then((created) => {
          if (current) {
            setOrder(created);
          }
        });
        return () => {
          current = false;
        };
      }, [amount]);

      // reveal the button once the iframe has content (ui:height.changed)
      useEffect(() => {
        const onMessage = (e: MessageEvent) => {
          if (!e.origin.endsWith(".crossmint.com")) return;
          const event = (e.data as { event?: string } | null)?.event;
          if (event === "ui:height.changed" || event === "ui:express-checkout.ready") {
            setReady(true);
          }
        };
        window.addEventListener("message", onMessage);
        return () => window.removeEventListener("message", onMessage);
      }, []);

      // success = the order reaches the delivery phase
      const succeeded =
        checkoutOrder?.phase === "delivery" || checkoutOrder?.phase === "completed";

      if (succeeded) {
        return <p className="text-xl font-semibold">Payment complete. Tokens on the way!</p>;
      }

      return (
        <div className="w-full max-w-sm">
          <div className="mb-6 flex gap-2">
            {AMOUNTS.map((a) => (
              <button
                key={a}
                onClick={() => setAmount(a)}
                className={`flex-1 rounded-xl border px-4 py-2 font-medium ${
                  amount === a ? "border-black bg-black text-white" : "border-gray-300"
                }`}
              >
                ${a}
              </button>
            ))}
          </div>

          {!ready && <p className="py-4 text-center text-gray-500">Loading…</p>}
          <div className={ready ? "" : "invisible absolute h-0 overflow-hidden"}>
            {order && (
              <CrossmintEmbeddedCheckout
                key={order.orderId}
                orderId={order.orderId}
                clientSecret={order.clientSecret}
                payment={{
                  receiptEmail: RECEIPT_EMAIL,
                  crypto: { enabled: false },
                  fiat: {
                    enabled: true,
                    allowedMethods: { applePay: true, card: false, googlePay: false },
                  },
                }}
                appearance={{
                  rules: {
                    DestinationInput: { display: "hidden" },
                    ReceiptEmailInput: { display: "hidden" },
                    GlobalMessage: { display: "visible" },
                  },
                }}
              />
            )}
          </div>
        </div>
      );
    }

    export default function CheckoutPage() {
      return (
        <CrossmintProvider apiKey={process.env.NEXT_PUBLIC_CROSSMINT_CLIENT_API_KEY!}>
          <CrossmintCheckoutProvider>
            <main className="flex min-h-screen flex-col items-center justify-center bg-white p-6">
              <h1 className="mb-6 text-2xl font-bold">Buy XMEME</h1>
              <Checkout />
            </main>
          </CrossmintCheckoutProvider>
        </CrossmintProvider>
      );
    }
    ```

    Note the `key={order.orderId}`: changing the amount creates a fresh order, and keying the component by order id remounts the widget cleanly instead of navigating the iframe in place.
  </Step>

  <Step title="Run your app">
    <Snippet />
  </Step>

  <Step title="Test with Apple Pay">
    Open your **registered HTTPS domain** (not `localhost`) in Safari 17+ on macOS, or on an iPhone running iOS 17+, with a card added to Apple Wallet. Use a physical device rather than the iOS Simulator, which does not render Apple Pay. In staging the payment is processed in the PSP's sandbox, so the card in your Wallet is never actually charged.

    To exercise the full flow from any browser during development, temporarily flip the allowed methods to the card form and pay with the staging test card `4242 4242 4242 4242` (any future expiry, any CVC):

    ```tsx theme={null}
    allowedMethods: { applePay: false, card: true, googlePay: false }
    ```

    More on testing can be found [here](/payments/advanced/testing-tips#test-credit-card-numbers).
  </Step>
</Steps>

## One-Tap on Mobile

The five settings above are order and URL parameters, so the same configuration renders inside a native app unchanged. The recommended integration paths are the <a href="https://github.com/Crossmint/crossmint-checkout-swift">Swift</a> and [Kotlin](/sdk-reference/checkout/kotlin/index) SDKs, which render and configure the checkout for you. If you prefer full control and do not want to add an SDK, create the order exactly as in step 2 and render the checkout in your own WebView following the [Mobile WebView Integration guide](/payments/embedded/guides/webview-integration):

```tsx theme={null}
// React Native: the same payment and appearance configuration, in a WebView
const checkoutUrl =
    `https://staging.crossmint.com/sdk/2024-03-05/embedded-checkout?` +
    new URLSearchParams({
        orderId: order.orderId,
        clientSecret: order.clientSecret,
        payment: JSON.stringify({
            receiptEmail: RECEIPT_EMAIL, // must also be here, or the email input renders
            crypto: { enabled: false },
            fiat: {
                enabled: true,
                allowedMethods: { applePay: true, card: false, googlePay: false },
            },
        }),
        appearance: JSON.stringify({
            rules: {
                DestinationInput: { display: "hidden" },
                ReceiptEmailInput: { display: "hidden" },
                GlobalMessage: { display: "visible" },
            },
        }),
        apiKey: CLIENT_API_KEY,
    }).toString();

<WebView source={{ uri: checkoutUrl }} /* configuration from the WebView guide */ />;
```

Two things get simpler on mobile:

* **Simpler wallet detection.** The operating system determines the wallet, so replace the `ApplePaySession` check from the tip above with a platform check: enable Apple Pay on iOS and Google Pay on Android (`Platform.OS === "ios"` in React Native), keeping one wallet enabled per device.
* **No Apple Pay domain registration.** The checkout page is served from `crossmint.com`, which is already enabled for Apple Pay, so the domain steps in the prerequisites apply to the web integration only.

The [Mobile WebView Integration guide](/payments/embedded/guides/webview-integration) covers the WebView configuration, order tracking from a native app, and mobile testing.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The payment sheet shows &#x22;Failed to validate merchant. Please try again.&#x22;">
    Apple could not validate the domain serving your page. Check, in order:

    1. **You are on a registered domain.** The page must be served from a domain that shows `verified` under
       **Apple Pay Domains** in the console — `localhost` always fails validation. Use your ngrok or production
       domain instead.
    2. **The domain matches exactly.** The registration is per host: `app.example.com` and `example.com` are
       different domains, and a new ngrok tunnel gets a new domain that needs registering again.
    3. **Everything belongs to one project.** The order (server key), the widget's `apiKey` (client key), and the
       Apple Pay domain registration must all come from the same console project. If the order was created with a
       key from a different project, validation fails even with a verified domain.
  </Accordion>

  <Accordion title="The Apple Pay button does not render, or Safari shows &#x22;Apple Pay is not available&#x22;">
    * Serve the page from your registered HTTPS domain: even in Safari, Apple Pay is unavailable on plain
      `http://localhost`, which surfaces as an "Apple Pay is not available" message. Open the app through your
      ngrok or production domain instead.
    * Apple Pay renders in Safari 17+ on macOS and iOS 17+; other browsers show nothing where the button would
      be (enable `googlePay: true` to cover them). Test in Safari or on an iPhone.
    * Use a physical device: the iOS Simulator does not render Apple Pay.
    * Confirm `payment.fiat.allowedMethods` sets `applePay: true` and the order was created successfully (the
      `ui:height.changed` message only fires once the iframe has content).
  </Accordion>

  <Accordion title="The checkout iframe does not load at all">
    * Add the exact origin the app runs on (scheme + host + port) to the client key's **origins allowlist** in the
      console.
    * Match the base URL to the key environment: `ck_staging_`/`sk_staging_` keys pair with
      `staging.crossmint.com`, production keys with `www.crossmint.com`.
  </Accordion>

  <Accordion title="The console shows &#x22;The API key provided doesn't have the required scopes&#x22;">
    The error names the missing scope. The widget's client key needs `orders.read`; if you also use Crossmint Auth
    and Wallets like the demo app, add `users.create`, `users.read`, `wallets.read`, `wallets.create`, and
    `wallets:balance.read`. Edit the key's scopes in the console under **Integrate → API Keys**.
  </Accordion>

  <Accordion title="A payment fails and nothing appears on screen">
    Pass `GlobalMessage: { display: "visible" }` in `appearance.rules`. In the pay-button-only layout this rule is
    the only surface where payment errors (such as a payment blocked by risk checks) can render.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Take it to mobile" icon="mobile" href="/payments/embedded/guides/webview-integration">
    Render the same experience inside your iOS, Android, or React Native app
  </Card>

  <Card title="Apple Pay domain setup" icon="apple" href="/payments/embedded/guides/apple-pay">
    Host the domain association file and verify your domain
  </Card>

  <Card title="Customize UI" icon="paintbrush" href="/payments/embedded/guides/ui-customization">
    Match the button and messages to your brand
  </Card>

  <Card title="Payment methods" icon="credit-card">
    <a href="/payments/embedded/guides/payment-methods">Enable Google Pay or cards</a> with the same pattern
  </Card>
</CardGroup>

<Snippet />


# Pay with Card - Memecoins (React)
Source: https://docs.crossmint.com/payments/embedded/quickstarts/credit-card-memecoin

Create a fully customized embedded memecoin checkout experience that accepts credit cards

<Snippet />

## Introduction

This guide will show you how to accept credit card payments using Crossmint's Embedded Checkout for memecoin sales. You'll learn how to:

* Set up credit card payments for Solana memecoin purchases in JavaScript
* Implement an embedded checkout UI using Crossmint's React components
* Track order status and delivery

<Snippet />

<Snippet />

<Snippet />

## Embedded Memecoin Checkout

The fastest way to start selling memecoins is to use our embedded checkout solution adapted for fungible tokens.

### Important Parameters

Before implementing the checkout, note these key parameters:

* `receiptEmail`: Optional. If the buyer pays with Apple Pay or Google Pay, Crossmint obtains the email automatically. Providing it improves fraud signal quality.
* `executionParameters.mode`: Set to "exact-in" for memecoin purchases (specifies exact USD amount to spend). "exact-out" is for NFTs, while "exact-in" is for fungible tokens.
* `maxSlippageBps`: Optional slippage tolerance (default is typically 500 BPS or 5% if not specified)

<Note>
  **Testing in Staging?** Use the XMEME test token: `solana:7EivYFyNfgGj8xbUymR7J4LuxUHLKRzpLaERHLvi7Dgu`. Production tokens will not work in the staging environment.
</Note>

<Snippet />

### Memecoin Embedded Integration

Next, we will set up a project file with Crossmint's embedded checkout to accept memecoin purchases.

<Steps>
  <Step title="Add environment variables">
    Create `.env.local` in your project root:

    ```sh theme={null}
    NEXT_PUBLIC_CLIENT_API_KEY="_YOUR_CLIENT_API_KEY_"                    # From API Keys page
    NEXT_PUBLIC_TOKEN_ADDRESS="7EivYFyNfgGj8xbUymR7J4LuxUHLKRzpLaERHLvi7Dgu" # xmeme token for staging testing
    NEXT_PUBLIC_RECIPIENT_WALLET_ADDRESS="YOUR_SOLANA_WALLET_ADDRESS"     # Add desired recipient wallet
    NEXT_PUBLIC_RECEIPT_EMAIL="YOUR_EMAIL"                               # Add desired recipient email
    ```
  </Step>

  <Step title="Create the checkout page">
    Create `/src/app/page.tsx` with:

    ```tsx theme={null}
    "use client";
    import { CrossmintProvider, CrossmintEmbeddedCheckout } from "@crossmint/client-sdk-react-ui";

    export default function Home() {
        const clientApiKey = process.env.NEXT_PUBLIC_CLIENT_API_KEY as string;
        const tokenAddress = process.env.NEXT_PUBLIC_TOKEN_ADDRESS as string;
        const recipientWalletAddress = process.env.NEXT_PUBLIC_RECIPIENT_WALLET_ADDRESS as string;

        return (
            <div className="flex flex-col items-center justify-start h-screen p-6 bg-white">
                <CrossmintProvider apiKey={clientApiKey}>
                    <div className="max-w-[450px] w-full">
                        <CrossmintEmbeddedCheckout
                            recipient={{
                                walletAddress: recipientWalletAddress, // Wallet address to receive the memecoins
                            }}
                            lineItems={{
                                tokenLocator: `solana:${tokenAddress}`, // Token address in format solana:tokenAddress (e.g., solana:7EivYFyNfgGj8xbUymR7J4LuxUHLKRzpLaERHLvi7Dgu for xmeme token)
                                executionParameters: {
                                    mode: "exact-in", // The execution method for the order. It tells Crossmint to operate in buying fungibles mode
                                    amount: "5", // Amount in USD
                                    maxSlippageBps: "500" // Optional - default slippage will be applied if not specified
                                }
                            }}
                            payment={{
                                receiptEmail: process.env.NEXT_PUBLIC_RECEIPT_EMAIL as string, // Email address to receive the receipt
                                crypto: {
                                    enabled: false, // Only fiat is supported for memecoin purchases
                                },
                                fiat: {
                                    enabled: true,
                                },
                                defaultMethod: "fiat",
                            }}
                        />
                    </div>
                </CrossmintProvider>
            </div>
        );
    }
    ```

    For more details on tokenLocator formatting and other item selection options, see our [embedded item selection guide](/payments/embedded/guides/item-selection#item-selection-examples).
  </Step>

  <Step title="Run your app">
    <Snippet />
  </Step>

  <Step title="Test your app">
    Test purchases in staging using test credit cards, like `4242424242424242` (Visa). More information on testing can be found [here](/payments/advanced/testing-tips#test-credit-card-numbers).

    For production launch with live memecoin tokens, <a href="https://www.crossmint.com/contact/sales">contact the Crossmint sales team</a> — production Checkout requires a signed Order Form and successful KYB. See the [production launch guide](/payments/embedded/guides/production-launch) for the full sequence.
  </Step>
</Steps>

Here's how your embedded checkout will look after implementation:

<img alt="Embedded Memecoin Checkout" />

Note the quote expiration timer above the checkout button.

🎉 Congratulations! You've successfully set up your embedded memecoin checkout. Check out the [Next Steps](#next-steps) section below to learn how to customize your integration.

<Snippet />

## Next Steps

<CardGroup>
  <Card title="Customize UI" icon="paintbrush" href="/payments/embedded/guides/ui-customization">
    Learn how to customize the embedded checkout experience
  </Card>

  <Card title="Handle Webhooks" icon="bell" href="/payments/advanced/webhooks">
    Implement webhook handling for order updates
  </Card>
</CardGroup>

<Snippet />

<Note>
  If the quote expires (after 1 minute), the embedded checkout will automatically refresh the quote. You can
  customize this behavior using the checkout hooks.
</Note>

<Snippet />


# Pay with Card - Memecoins (Flutter)
Source: https://docs.crossmint.com/payments/embedded/quickstarts/credit-card-memecoin-flutter

Create a fully customized embedded memecoin checkout experience for Flutter that accepts credit cards

<Snippet />

<Note>
  For this quickstart, you will create a minimal Flutter app. Make sure you have <a href="https://docs.flutter.dev/get-started/install">Flutter installed</a>.
</Note>

## Create a New Flutter Project + Crossmint SDK

<Steps>
  <Step title="Create a new Flutter app">
    ```bash theme={null}
    flutter create crossmint_checkout_quickstart

    cd crossmint_checkout_quickstart
    ```
  </Step>

  <Step title="Install crossmint_flutter">
    <Snippet />
  </Step>

  <Step title="Set your environment variables">
    Pass your API key and configuration via Dart defines:

    ```bash theme={null}
    flutter run \
      --dart-define=CROSSMINT_API_KEY=YOUR_CLIENT_SIDE_API_KEY \
      --dart-define=RECIPIENT_WALLET=YOUR_SOLANA_WALLET_ADDRESS \
      --dart-define=RECEIPT_EMAIL=YOUR_EMAIL@example.com
    ```

    <Note>The `receiptEmail` field is **optional**. If the buyer pays with Apple Pay or Google Pay, Crossmint obtains the email automatically. Providing it improves fraud signal quality.</Note>
  </Step>

  <Step title="Replace lib/main.dart with">
    ```dart theme={null}
    import 'package:flutter/material.dart';
    import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

    const apiKey = String.fromEnvironment('CROSSMINT_API_KEY');
    const recipientWallet = String.fromEnvironment('RECIPIENT_WALLET');
    const receiptEmail = String.fromEnvironment('RECEIPT_EMAIL');

    void main() {
      runApp(const MaterialApp(home: CheckoutScreen()));
    }

    class CheckoutScreen extends StatelessWidget {
      const CheckoutScreen({super.key});

      @override
      Widget build(BuildContext context) {
        final checkoutController = CrossmintCheckoutController();

        return Scaffold(
          body: SafeArea(
            child: CrossmintEmbeddedCheckout(
              apiKey: apiKey,
              config: CrossmintCheckoutConfig(
                order: CrossmintCheckoutNewOrder.typed(
                  lineItems: [
                    CrossmintCheckoutLineItem.tokenWithExecutionParameters(
                      tokenLocator:
                          'solana:7EivYFyNfgGj8xbUymR7J4LuxUHLKRzpLaERHLvi7Dgu', // XMEME token (staging)
                      executionParameters: {
                        'mode': 'exact-in',
                        'amount': '1',
                        'maxSlippageBps': '500',
                      },
                    ),
                  ],
                  recipient: CrossmintCheckoutWalletRecipient(
                    walletAddress: recipientWallet,
                  ),
                ),
                payment: CrossmintCheckoutPayment(
                  fiat: CrossmintCheckoutFiatPayment(enabled: true),
                  crypto: CrossmintCheckoutCryptoPayment(enabled: false),
                  receiptEmail: receiptEmail,
                ),
              ),
              checkoutController: checkoutController,
              onOrderUpdated: (order) =>
                  debugPrint('Order updated: ${order['status']}'),
              onOrderCreationFailed: (error) =>
                  debugPrint('Error: $error'),
            ),
          ),
        );
      }
    }
    ```
  </Step>

  <Step title="Run your project">
    Run with the same `--dart-define` flags from step 3:

    <CodeGroup>
      ```bash iOS theme={null}
      flutter run -d ios \
        --dart-define=CROSSMINT_API_KEY=YOUR_CLIENT_SIDE_API_KEY \
        --dart-define=RECIPIENT_WALLET=YOUR_SOLANA_WALLET_ADDRESS \
        --dart-define=RECEIPT_EMAIL=YOUR_EMAIL@example.com
      ```

      ```bash Android theme={null}
      flutter run -d android \
        --dart-define=CROSSMINT_API_KEY=YOUR_CLIENT_SIDE_API_KEY \
        --dart-define=RECIPIENT_WALLET=YOUR_SOLANA_WALLET_ADDRESS \
        --dart-define=RECEIPT_EMAIL=YOUR_EMAIL@example.com
      ```

      ```bash Chrome theme={null}
      flutter run -d chrome \
        --dart-define=CROSSMINT_API_KEY=YOUR_CLIENT_SIDE_API_KEY \
        --dart-define=RECIPIENT_WALLET=YOUR_SOLANA_WALLET_ADDRESS \
        --dart-define=RECEIPT_EMAIL=YOUR_EMAIL@example.com
      ```
    </CodeGroup>
  </Step>
</Steps>


# Pay with Card - Memecoins (React Native)
Source: https://docs.crossmint.com/payments/embedded/quickstarts/credit-card-memecoin-react-native

Create a fully customized embedded memecoin checkout experience for React Native that accepts credit cards

<Snippet />

# Crossmint Checkout React Native SDK Quickstart

<Note>
  For this quickstart we'll be using Expo. You can follow this [tutorial](https://docs.expo.dev/tutorial/create-your-first-app/) to create an expo app. **Only do steps 1 and 3**, plus the Crossmint-specific steps below.

  **Prerequisites:** Before starting, ensure you have completed the [Expo prerequisites](https://docs.expo.dev/tutorial/create-your-first-app/#prerequisites) including Node.js, Git, and your development environment setup.
</Note>

<Note>
  To integrate without the SDK, or on a platform the SDKs do not cover, render the checkout URL in your own WebView
  following the [Mobile WebView Integration guide](/payments/embedded/guides/webview-integration).
</Note>

## Following Expo Tutorial + Crossmint SDK

<Steps>
  <Step title="Initialize a new Expo app">
    ```bash theme={null}
    npx create-expo-app@latest crossmint-checkout-quickstart

    cd crossmint-checkout-quickstart
    ```
  </Step>

  <Step title="Run reset-project script">
    ```bash theme={null}
    npm run reset-project
    ```
  </Step>

  <Step title="Install @crossmint/client-sdk-react-native-ui">
    <Snippet />
  </Step>

  <Step title="Add your .env.local environment variables">
    ```bash theme={null}
    EXPO_PUBLIC_CLIENT_CROSSMINT_API_KEY="your_client_side_api_key"
    EXPO_PUBLIC_RECIPIENT_WALLET_ADDRESS="your_solana_wallet_address" 
    EXPO_PUBLIC_RECEIPT_EMAIL="your-email@example.com"
    ```

    <Note>The `receiptEmail` field is **optional**. If the buyer pays with Apple Pay or Google Pay, Crossmint obtains the email automatically. Providing it improves fraud signal quality.</Note>
  </Step>

  <Step title="Replace index.tsx with">
    ```jsx theme={null}
    import { CrossmintEmbeddedCheckout, CrossmintProvider } from "@crossmint/client-sdk-react-native-ui";

    export default function Index() {
        return (
            <CrossmintProvider apiKey={process.env.EXPO_PUBLIC_CLIENT_CROSSMINT_API_KEY ?? ""}>
                <CrossmintEmbeddedCheckout
                    recipient={{
                        walletAddress: process.env.EXPO_PUBLIC_RECIPIENT_WALLET_ADDRESS ?? "",
                    }}
                    payment={{
                        crypto: {
                            enabled: false,
                        },
                        fiat: {
                            enabled: true,
                        },
                        receiptEmail: process.env.EXPO_PUBLIC_RECEIPT_EMAIL ?? "",
                    }}
                    lineItems={{
                        tokenLocator: "solana:7EivYFyNfgGj8xbUymR7J4LuxUHLKRzpLaERHLvi7Dgu", // XMEME token (staging)
                        executionParameters: {
                            mode: "exact-in", // Specifies exact USD amount to spend (vs exact-out for NFTs)
                            amount: "1", // USD amount to spend
                            maxSlippageBps: "500", // Maximum slippage tolerance in basis points (500 = 5%, default if not specified)
                        },
                    }}
                />
            </CrossmintProvider>
        );
    }
    ```
  </Step>

  <Step title="Run your project">
    <CodeGroup>
      ```bash npm theme={null}
      npm run ios
      # For Android:
      npm run android
      ```

      ```bash yarn theme={null}
      yarn ios
      # For Android:
      yarn android
      ```

      ```bash pnpm theme={null}
      pnpm ios
      # For Android:
      pnpm android
      ```

      ```bash bun theme={null}
      bun ios
      # For Android:
      bun android
      ```
    </CodeGroup>
  </Step>
</Steps>

### Result

<img alt="React Native Crossmint Checkout Result" />


# Pay with Card - NFTs (React)
Source: https://docs.crossmint.com/payments/embedded/quickstarts/credit-card-nft

Embed a onchain checkout into a web app in under 5 minutes

<Frame type="simple">
  <img alt="Crossmint Embedded Checkout Demo" />
</Frame>

## Introduction

In this guide, you will create a web app with Next.js which allows customers to buy NFTs with credit card and crypto payments, using Crossmint's embedded checkout. Crossmint also supports payments for [crypto onramp](/onramp/quickstarts/react), [memecoins](/payments/headless/quickstarts/credit-card-memecoin-cko), and other onchain assets (ERC20 tokens, ERC721 tokens, and ERC1155 tokens).

If you want to get started immediately, you can clone a repo with a functioning embedded checkout here: [https://github.com/Crossmint/crossmint-embedded-demo](https://github.com/Crossmint/crossmint-embedded-demo). If you want to get started step by step, continue following the guide below.

<Snippet />

<Snippet />

### Basic Integration

Perfect for getting started quickly with a simple checkout flow.

<Steps>
  <Step title="Add environment variables">
    Create `.env.local` in your project root:

    ```sh theme={null}
    NEXT_PUBLIC_CLIENT_API_KEY="_YOUR_CLIENT_API_KEY_"    # From API Keys page
    NEXT_PUBLIC_COLLECTION_ID="_YOUR_COLLECTION_ID_"      # From Collection details page
    ```
  </Step>

  <Step title="Create the checkout page">
    Replace your home page (e.g `{root_dir}/app/page.tsx`) with:

    ```tsx theme={null}
    "use client";

    import { CrossmintProvider, CrossmintEmbeddedCheckout } from "@crossmint/client-sdk-react-ui";

    export default function Home() {
        const clientApiKey = process.env.NEXT_PUBLIC_CLIENT_API_KEY as string;
        const collectionId = process.env.NEXT_PUBLIC_COLLECTION_ID as string;

        return (
            <div className="flex flex-col items-center justify-start h-screen p-6 bg-white">
                <CrossmintProvider apiKey={clientApiKey}>
                    <div className="max-w-[450px] w-full">
                        <CrossmintEmbeddedCheckout
                            lineItems={{
                                collectionLocator: `crossmint:${collectionId}`,
                                callData: {
                                    totalPrice: "0.001",
                                    quantity: 1,
                                },
                            }}
                            payment={{
                                crypto: { enabled: true },
                                fiat: { enabled: true },
                            }}
                        />
                    </div>
                </CrossmintProvider>
            </div>
        );
    }
    ```
  </Step>

  <Step title="Run your app">
    Navigate to the directory your package.json is to run the app

    ```bash theme={null}
    cd embedded-checkout/crossmint-embedded-checkout-demo
    ```

    <Snippet />
  </Step>
</Steps>

### Advanced Integration

Need purchase tracking, multiple NFT purchases at once, or more customization? Here's a complete setup with additional features:

```tsx theme={null}
"use client";

import { useEffect } from "react";
import {
    CrossmintProvider,
    CrossmintCheckoutProvider,
    CrossmintEmbeddedCheckout,
    useCrossmintCheckout,
} from "@crossmint/client-sdk-react-ui";

// Component with purchase tracking
function Checkout() {
    const { order } = useCrossmintCheckout();
    const collectionId = process.env.NEXT_PUBLIC_COLLECTION_ID as string;

    useEffect(() => {
        if (order && order.phase === "completed") {
            console.log("Purchase completed!");
            // Handle successful purchase
        }
    }, [order]);

    return (
        <CrossmintEmbeddedCheckout
            lineItems={[
                {
                    collectionLocator: `crossmint:${collectionId}`,
                    callData: {
                        totalPrice: "0.001",
                        quantity: 1,
                    },
                },
                {
                    collectionLocator: `crossmint:${collectionId}`,
                    callData: {
                        totalPrice: "0.002",
                        quantity: 2,
                    },
                },
            ]}
            payment={{
                crypto: {
                    enabled: true,
                    defaultChain: "polygon", // Set preferred blockchain
                    defaultCurrency: "matic", // Set preferred crypto
                },
                fiat: {
                    enabled: true,
                    defaultCurrency: "usd", // Set preferred fiat currency
                    allowedMethods: {
                        card: true,
                        applePay: true,
                        googlePay: true,
                    },
                },
                receiptEmail: "receipt@example.com", // Optional: Set receipt email
            }}
            recipient={{
                email: "buyer@example.com", // NFTs will be delivered to this email's wallet
                // Or use walletAddress: "0x..." for direct delivery
            }}
            locale="en-US" // Set interface language
        />
    );
}

// Main component with providers
export default function Home() {
    const clientApiKey = process.env.NEXT_PUBLIC_CLIENT_API_KEY as string;

    return (
        <div className="flex flex-col items-center justify-start min-h-screen p-6">
            <CrossmintProvider apiKey={clientApiKey}>
                <CrossmintCheckoutProvider>
                    <Checkout />
                </CrossmintCheckoutProvider>
            </CrossmintProvider>
        </div>
    );
}
```

<Note>
  This advanced example showcases: - Multiple NFTs in one checkout - Purchase status tracking - Preferred payment
  methods and currencies - Email-based NFT delivery - Language settings Learn more in our guides: - [Payment
  Methods](/payments/embedded/guides/payment-methods) - [Multi-purchases](/payments/pay-button/guides/item-selection#multiple-item-orders) -
  [React Hooks](/payments/embedded/guides/hooks)
</Note>

### Testing Your Integration

<Note>
  This demo uses the staging environment: - Use [test credit
  cards](/payments/advanced/testing-tips#test-credit-card-numbers) for payments - Get test USDC from our
  [faucet](/payments/advanced/testing-tips#getting-test-tokens) - Check [price
  limits](/payments/advanced/testing-tips#limits-in-staging) for staging
</Note>

## All Set!

You've successfully integrated card and crypto payments with the Crossmint Embedded Checkout!

<Frame type="simple">
  <img />
</Frame>

<Note>
  Remember this demo is built on staging, so the digital assets will show up on the testnets. To launch on production,
  check the [production launch checklist](/payments/advanced/production-launch). You will need to contact
  [Sales](https://www.crossmint.com/contact/sales) to enable the embedded checkout on production.
</Note>

## Next Steps

### Customize the UI and Behavior Further

<CardGroup>
  <Card title="UI Customization" icon="paintbrush" href="/payments/embedded/guides/ui-customization">
    Learn how to customize the look and feel of your checkout
  </Card>

  <Card title="Payment Methods" icon="credit-card" href="/payments/embedded/guides/payment-methods">
    Configure available payment options for your users
  </Card>

  <Card title="React Hooks" icon="code" href="/payments/embedded/guides/hooks">
    Use React hooks to build custom checkout experiences
  </Card>
</CardGroup>

### Advanced Topics

<CardGroup>
  <Card title="SDK Reference" icon="gear" href="/sdk-reference/checkout/react/components" />

  <Card title="Launch in Production" icon="ship" href="/payments/advanced/production-launch" />

  <Card title="Localization" icon="globe" href="/payments/embedded/customize/localization" />

  <Card title="Multi-purchases" icon="cart-plus" href="/payments/pay-button/guides/item-selection#multiple-item-orders" />
</CardGroup>


# Create/Deploy an NFT Collection
Source: https://docs.crossmint.com/payments/guides/create-collection

Easily deploy a collection in the console and enable payments

The easiest way to get started with selling or airdropping NFTs is to use the developer console to deploy and manage your NFT contracts.

## Create a Crossmint NFT Collection

This guide will deploy an ERC-721 contract on the Polygon Amoy testnet. Currently, you can also deploy to the mainnets and testsnets for Polygon, Base, Optimism, and Solana directly from the console. Additional chains are supported when deploying via the [create-collection API](/api-reference/minting/collection/create-collection).

<Steps>
  <Step title="Navigate to Token collections and click `New collection`">
    <Frame type="simple">
      <img alt="New collections screenshot" />
    </Frame>
  </Step>

  <Step title="Enter Collection Information">
    This information is displayed in the Hosted Checkout. You can edit it later.

    <Frame type="simple">
      <img alt="Collection info screenshot" />
    </Frame>
  </Step>

  <Step title="Select `Create a new contract` option">
    <Frame type="simple">
      <img alt="Create Collection screenshot" />
    </Frame>
  </Step>

  <Step title="Select `Sell NFTs` option">
    If you want to use this collection exclusively with the [Minting Tools](/minting/introduction), select the `Airdrop NFTs` option only.

    <Frame type="simple">
      <img alt="Select sell or airdrop NFTs screenshot" />
    </Frame>
  </Step>

  <Step title="Select preferred Blockchain">
    Crossmint has staging and production [environments](/introduction/platform/staging-vs-production) to facilitate working in testnets or mainnets.

    <Frame type="simple">
      <img alt="Select blockchain screenshot" />
    </Frame>

    <br />

    <Check>When creating a new collection on production you'll need some API credits to cover the gas cost of contract deployment.</Check>
  </Step>

  <Step title="Configure Payment Settings">
    #### NFT Price

    Enter the price you want to charge for your NFT. When using the staging environment, please set very low test prices to help use preserve our testnet currency. Everything works the same in staging and production, so you can test your collection with low prices in staging and then deploy to production with higher prices.
    In production, there is a lower bound limit of USD $0.75, and an upper bound limit of USD $1,500 per transaction. You can find more information if you need to [increase this limit](/payments/advanced/production-launch#default-transaction-limit).

    #### USDC

    Several chains support USDC for the currency. This option is useful for price stability and to receive payouts in a stable token. You can find more info on [configuring USDC here](/payments/advanced/usdc-support).

    <Frame type="simple">
      <img alt="Crossmint collection nft-price configuration" />
    </Frame>

    ### Fee Sponsorship

    This option enables you to control who pays the fees of the NFT purchase including gas and credit card transaction fees. The default option is "Buyer", which means that if you set a price of 10 USDC, the final price the buyer pays will be 10 USDC plus fees.

    If you want to provide a consistent price for your customers, select the "You" option to sponsor the fees. When you sponsor the fees they will be deducted from the amount the buyer pays and the remainder will be paid to the recipient wallet you set in the next step.

    <Frame type="simple">
      <img alt="Crossmint collection fee sponsorship configuration" />
    </Frame>

    #### Recipient Address

    Enter the wallet address where you want to receive payments. This is the address where Crossmint will send the proceeds from NFT sales.

    <Note>
      Want to split payments across multiple addresses? Use a [splits.org](https://splits.org) address as the payout recipient.
    </Note>

    <Frame type="simple">
      <img alt="Crossmint collection payments settings screenshot" />
    </Frame>
  </Step>

  <Step title="Review details and click `Deploy contract` to complete">
    Make sure you review the Content policy. When launching in production you'll need to submit collection verification information to ensure your collection is compliant with our <a href="https://www.crossmint.com/content-policy">Content Policy</a>. You can find more information about everything required for your production launch in the [Production Launch](/payments/advanced/production-launch) section.

    <Frame type="simple">
      <img alt="Crossmint collection complete screenshot" />
    </Frame>
  </Step>
</Steps>

## Adding NFTs

This is **required** before you can sell or airdrop the NFTs. Without this step there is not any actual information to use for creating the NFTs yet. You can create unique NFT metadata per token or an Open Edition style NFT where all tokens share the same metadata.

<Accordion title="Manual Uploading">
  <Steps>
    <Step title="Select `Manual upload` option">
      <Frame type="simple">
        <img alt="manual upload screenshot" />
      </Frame>
    </Step>

    <Step title="Fill out Metadata">
      #### NFT Name

      The name of your NFT (max 32 characters).

      #### Supply

      For unique per NFT, enter 1. You will need to configure the metadata for each NFT. You can do this via the developer console individually. For projects with many unique NFTs you should use the [Create Template API](/api-reference/minting/template/create-template) with a script.

      For an Open Edition NFT, enter the total quantity, or select the Unlimited checkbox. This will be the only metadata you need to configure.

      #### Description

      The description of your NFT (max 64 characters).

      #### Image

      Upload an image for your NFT.

      Recommended image formats are: JPEG, PNG, WEBP, or GIF. In most cases, the medium in which NFTs are displayed don't require extremely high resolution files. Strike a balance and lean towards file sizes that do not require significant bandwidth to download (below 10 MB for example).

      #### Attributes `optional`

      Additional attributes of the NFT. Add as few or as many as you like. You can refer to the [OpenSea metadata standards](https://docs.opensea.io/docs/metadata-standards#attributes) page for detailed explanations of how to use these in your project.

      <Frame type="simple">
        <img alt="Entering metadata screenshot" />
      </Frame>

      Click the `Create NFT` button to complete.
    </Step>
  </Steps>
</Accordion>

<Accordion title="Batch Uploading with CSV">
  <Steps>
    <Step title="Select `Batch upload` option">
      <Frame type="simple">
        <img alt="batch upload screenshot" />
      </Frame>
    </Step>

    <Step title="Prepare Metadata CSV">
      You can download an example of how your file should be structured here: [batch-upload-example.zip](https://www.crossmint.com/assets/examples/batch-upload-example.zip).

      <Frame type="simple">
        <img alt="upload csv screenshot" />
      </Frame>

      <Note>You can upload a maximum of 1000 items at a time. For collections that require more than 1000 tokens, you can repeat the batch upload process multiple times.</Note>

      The CSV should include a header row with the following fields:

      * `name` - The name for the token.
      * `image` - The filename of the image, which will be uploaded in the next step.
      * `description` - A description for the token.
      * `supply ` - How many of the token should be available.
      * `animation_url` - (optional)

      You can add attributes via additional columns in the spreadsheet. For example, to add an attribute named `weapon`, include an additional column with the attribute name for the header row. You can refer to the example file linked above to see this in action.

      Once you have your CSV ready, upload it to move on to the next step for media files.
    </Step>

    <Step title="Prepare Media Files">
      The image file names must match the value(s) in the `image` column of the uploaded CSV file. These files should be in a flat folder structure for upload (no sub-folders).

      Click the "Upload media files" button and then select all of the images referenced in the `metadata.csv` file you uploaded in the previous step.

      <Frame type="simple">
        <img alt="upload media files screenshot" />
      </Frame>
    </Step>

    <Step title="Complete the Batch Upload">
      Click the "Upload" button to upload the CSV and media files. If any media files are missing you'll be notified which ones they are in the UI.

      <Frame type="simple">
        <img alt="batch upload complete screenshot" />
      </Frame>
    </Step>

    <Step title="Done!">
      If you need to upload additional token metadata click the "New batch upload" button. Otherwise select "View my NFTS" to close the modal and view the metadata for your tokens.

      <Frame type="simple">
        <img alt="batch upload finish screenshot" />
      </Frame>
    </Step>
  </Steps>
</Accordion>

<Accordion title="Bulk Uploading via API">
  You can also perform bulk uploading by calling the [create-template](/api-reference/minting/template/create-template) API using a script that loops through your `metadata.csv` file. You'll need to have an [API key](/introduction/platform/api-keys#how-to-get-and-use-api-keys) with the `nfts.create` scope enabled.

  Below is an example script that will keep your request volume below the 120/min [rate limit](/introduction/platform/api-keys#rate-limits).

  <Check>
    This code example is available as a repository on GitHub also:
    [crossmint/bulk-uploader](https://github.com/Crossmint/bulk-uploader)
  </Check>

  <Note>
    Before running this script you'll need to upload your media files to a service that can host the files, such as [Pinata](https://www.pinata.cloud/).

    The `image` column of your `metadata.csv` should include the full URL to the file instead of only a file name like the batch upload option above.
  </Note>

  ```javascript bulkUploader.js theme={null}
  const fs = require("fs");
  const csv = require("csv-parser");
  require("dotenv").config();

  const collectionId = process.env.COLLECTION_ID;
  const apiKey = process.env.API_KEY;
  const apiUrl = `https://staging.crossmint.com/api/2022-06-09/collections/${collectionId}/templates`;

  // Rate limiting setup
  const rateLimit = 100; // requests per minute
  const interval = 60000 / rateLimit; // interval in milliseconds

  async function sendRequest(data) {
      try {
          const response = await fetch(apiUrl, {
              method: "POST",
              headers: {
                  "Content-Type": "application/json",
                  "X-API-KEY": `${apiKey}`,
              },
              body: JSON.stringify(data),
          });
          const responseData = await response.json();
          console.log("Success:", responseData);
      } catch (error) {
          console.error("Error:", error.message);
      }
  }

  // Read and process the CSV file
  function processFile() {
      let promise = Promise.resolve();
      fs.createReadStream("metadata.csv")
          .pipe(csv())
          .on("data", (row) => {
              promise = promise.then(() => {
                  const postData = {
                      metadata: {
                          name: row.name,
                          image: row.image, // this should be a publicly accessible URL
                          description: row.description,
                      },
                      supply: { limit: Number(row.supply) },
                      reuploadLinkedFiles: false, // this is optional
                  };
                  return sendRequest(postData).then(() => new Promise((resolve) => setTimeout(resolve, interval)));
              });
          })
          .on("end", () => {
              promise.then(() => {
                  console.log("Finished processing file.");
              });
          });
  }

  processFile();
  ```

  Run the script to bulk upload your template metadata.

  ```node theme={null}
  node bulkUploader.js
  ```
</Accordion>

## Send a Test NFT

Once you have added metadata you can send a test NFT to yourself or another user. The interface to mint and send from the console supports email and wallet address for the recipient.

<Steps>
  <Step title="Mint and send a test NFT">
    You can mint and send a test NFT to an email address or wallet to make sure everything is working as expected.

    <Frame type="simple">
      <img alt="Mint and Send NFT screenshot" />
    </Frame>
  </Step>

  <Step title="Enter email or wallet">
    If you enter an email address the NFT will be sent to a unique Crossmint custodial wallet associated with that email address. The owner of this email can log in to Crossmint to view their NFT. The wallet option will send directly to the wallet address.

    <Warning>Crossmint does ***not*** send an email to the user when you airdrop NFTs from the console.</Warning>

    <Frame type="simple">
      <img alt="Enter an email and Send NFT screenshot" />
    </Frame>
  </Step>

  <Step title="Done!">
    That's all there is to it. Check below for recommended next steps.
  </Step>
</Steps>

<Snippet />


# Register External Collection
Source: https://docs.crossmint.com/payments/guides/register-collection

Import custom and/or third party contracts

Crossmint has a pre-audited library of [smart contracts](/minting/nfts/integrate/create-collections) that serve most use cases. However, if you have custom needs, you can also bring your own.

<Tip>
  The Checkout has been battle-tested at scale with Crossmint's collections, and may result in a more reliable
  experience than using an untested, imported contract, or at least require less trouble-shooting.
</Tip>

<AccordionGroup>
  <Accordion title="When does it make sense to bring my own contract?">
    * When you require very custom functionality not supported by Crossmint's contracts.
    * If you're developing a marketplace.
    * If you have an accesslist.
  </Accordion>

  <Accordion title="What about secondary sale contracts/marketplaces?">
    Secondary markets are platforms where NFTs are traded after their initial mint/primary sale. These are marketplaces where users can buy and sell NFTs from each other.
    It requires manual support from Crossmint to import secondary contracts. See our [marketplaces and launchpads guide](/payments/advanced/marketplaces-and-launchpads).

    The self-serve option is only available for importing primary contracts for EVM and Solana.

    When importing contracts, Crossmint has support to fetch listings from the following secondary marketplaces:

    * **Auction House**: Solana's native marketplace protocol
    * **Tensor**: High-performance Solana NFT marketplace
    * **Magic Eden API**: Popular multi-chain NFT marketplace

    To add support for a new marketplace, please [contact sales](https://www.crossmint.com/contact/sales?utm_source=devrel\&utm_medium=docs\&utm_campaign=backlinks).
  </Accordion>
</AccordionGroup>

## Quick Navigation

All collection imports start with the same initial steps, then diverge based on your blockchain:

* [Common Steps (All Chains)](#common-steps-all-chains) - Steps 1-4 for all blockchains
* [EVM-Specific Steps](#evm-specific-steps) - Steps for Ethereum, Polygon, etc.
* [Solana-Specific Steps](#solana-specific-steps) - Additional steps for Solana candy machines

## Common Steps (All Chains)

These initial steps are the same whether you're importing an EVM contract or a Solana candy machine:

<Steps>
  <Step title="Navigate to Token collections and click `New collection`">
    <Frame type="simple">
      <img alt="New collections screenshot" />
    </Frame>
  </Step>

  <Step title="Enter Collection Information">
    This information is displayed in the Hosted Checkout. You can edit it later.

    <Frame type="simple">
      <img alt="Collection info screenshot" />
    </Frame>
  </Step>

  <Step title="Select `Import an existing contract` option">
    <Frame type="simple">
      <img alt="Import Collection screenshot" />
    </Frame>
  </Step>

  <Step title="Select the Blockchain your contract is deployed on">
    Remember, Crossmint has staging and production [environments](/introduction/platform/staging-vs-production).
    When working in the staging environment, choose the mainnet name. For example, if your contract is on the
    Polygon Amoy testnet, select Polygon.

    <Frame type="simple">
      <img alt="Select blockchain screenshot" />
    </Frame>
  </Step>
</Steps>

After completing these common steps, continue with the blockchain-specific instructions below.

## EVM-Specific Steps

Complete the [Common Steps](#common-steps-all-chains) above first, then continue with these EVM-specific steps:

### Pre-requisites

* Your contract must be ERC-721, ERC-721A, or ERC-1155 compliant.
* The minting function must allow minting directly to an address that is different from the one that invoked the contract. And it must contain at least one parameter that specifies that recipient address.
* A single address must be able to call the mint function unlimited times but does not need to be able to hold unlimited NFTs.

### Contract Registration

You may register contracts manually from the console or via <Tooltip>API</Tooltip>.

<AccordionGroup>
  <Accordion title="My ABI wasn't automatically imported">
    When you compile your smart contract there will be a corresponding abi file with an `.abi` or `.json` extension.

    Inside this file, you'll see JSON property named abi, which describes the functions in your smart contract. Here's an example of a very simple abi file. Yours will likely have more function descriptions.

    ```json theme={null}
    // Example generated abi file for smart contract
    {
        "abi": [
            {
                "inputs": [],
                "stateMutability": "nonpayable",
                "type": "constructor"
            },
            {
                "inputs": [
                    {
                        "internalType": "address",
                        "name": "_to",
                        "type": "address"
                    }
                ],
                "name": "mintTo",
                "outputs": [],
                "stateMutability": "payable",
                "type": "function"
            }
        ]
    }
    ```

    Copy the JSON array object that comes after the string `abi` and paste it into the `Contract ABI` text box in the developer console. The content you paste in should begin with `[` and end with `]`.
  </Accordion>

  <Accordion title="Specifying the remaining parameters">
    Whether your ABI was retrieved automatically or you pasted it in manually, you need to specify the:

    * Mint function
    * Recipient address parameter name
    * \[Optional] Quantity of NFTs to mint parameter name

    Crossmint will attempt to automatically select these values for you, but it's important to ensure they are set correctly. Especially if you're setting up a USDC mint function as the list of options will be longer.
  </Accordion>

  <Accordion title="Using proxy contracts">
    Proxy contracts are an advanced feature. You should use this only if you are certain that your contracts adhere to this pattern. This is crucial because Crossmint requires the actual NFT contract address when you register a mint/buy/purchase/claim function in a sales contract or revenue splitter.

    If you don't specify the NFT contract address, our system won't be able to extract token URI information or facilitate transfers. Set this up only if it isn't a transparent proxy, which is common for upgradeable contracts.
  </Accordion>
</AccordionGroup>

### EVM Contract Import Steps

<Steps>
  <Step title="Step 5: Select `Import my own contract` option">
    <Frame type="simple">
      <img alt="Select contract provider screenshot" />
    </Frame>
  </Step>

  <Step title="Step 6: Contract Address">
    Enter the address of your contract and the console will determine the contract type automatically.

    <Frame type="simple">
      <img alt="Enter contract address screenshot" />
    </Frame>
  </Step>

  <Step title="Step 7: Proxy or Sales Contract (optional)">
    Notice in the screenshot that the example has the same contract address that was entered in previous step. This indicates a basic setup where the purchase function is within the registered NFT contract. The only reason to change this is if purchases should be sent to a different contract address that is not the same as the NFT contract.

    Most developers do not need to change this. If you are unsure, leave it as is. Transparent upgradeable contracts also do not need to use this setting and should use the beacon address in the previous step.

    <Frame type="simple">
      <img alt="Sales contract option screenshot" />
    </Frame>
  </Step>

  <Step title="Step 8: Contract ABI">
    As long as your contract is verified on the block explorer we can query the ABI automatically. If you have not verified your contract, you must enter the ABI manually.

    <Frame type="simple">
      <img alt="Contract ABI section screenshot" />
    </Frame>
  </Step>

  <Step title="Step 9: Mint Function Currency">
    Unless you specifically deployed a contract that supports USDC you must leave the native currency selected. If you are unsure, leave it as is.

    <Frame type="simple">
      <img alt="Contract mint function currency section screenshot" />
    </Frame>
  </Step>

  <Step title="Step 10: Select Mint Function">
    If you selected the native currency in the previous step, this will be a very short list. If you have multiple mint functions in your contract that you want to accept payments for, you must register each one separately.

    <Note>USDC mint functions typically are NOT `payable`. Change the currency selector to USDC to populate the mint function list with valid options.</Note>

    The mint function must accept an address parameter and mint to that address. If your mint function lacks this you'll need to deploy a new contract or modify your existing contract.

    <Frame type="simple">
      <img alt="Contract mint function section screenshot" />
    </Frame>
  </Step>

  <Step title="Step 11: Parameter for recipient address">
    After the mint function has been selected, this will be a short list built from the function parameters of type `address`. If you have multiple options here, ensure that you select the correct one. Doing this incorrectly will result in the purchased NFTs being sent to the wrong address and they likely will not be recoverable.

    <Frame type="simple">
      <img alt="Contract mint function recipient address section screenshot" />
    </Frame>
  </Step>

  <Step title="Step 12: Parameter for quantity">
    This will be a short list built from the function parameters of type `uint256`. If you have multiple options here, ensure that you select the correct one. Doing this incorrectly will result in the NFT checkout tools not being able to properly mint the correct quantity of NFTs.

    <Frame type="simple">
      <img alt="Contract mint function quantity parameter section screenshot" />
    </Frame>
  </Step>

  <Step title="Step 13: Review details and click `Register collection` to complete">
    <Frame type="simple">
      <img alt="EVM registration complete screenshot" />
    </Frame>
  </Step>
</Steps>

## Solana-Specific Steps

Complete the [Common Steps](#common-steps-all-chains) above first, then continue with these Solana-specific steps:

Instant support for:

* **Primaries**: Candy Machine v3, Metaplex Instant Sales, Magic Eden's Launchpad
* **Secondaries**: Auction House, Tensor, Magic Eden API

<Note>
  Only the integrations listed above are available at the moment. For custom integrations, please [contact
  sales](https://www.crossmint.com/contact/sales?utm_source=devrel\&utm_medium=docs\&utm_campaign=backlinks).
</Note>

### Solana Candy Machine Import

Crossmint supports Candy Machine v3. After completing the common steps above, continue with these Solana-specific steps:

<Steps>
  <Step title="Step 5: Select Solana for the blockchain">
    This step replaces step 4 from the common steps above - select Solana from the blockchain dropdown.

    <Frame type="simple">
      <img alt="Select Solana blockchain screenshot" />
    </Frame>
  </Step>

  <Step title="Step 6: Choose candy machine version and enter candy machine ID">
    Find the ID in the `cache.json` file in the folder where you deployed your Candy Machine.

    <Frame type="simple">
      <img alt="Candy machine registration screenshot" />
    </Frame>
  </Step>

  <Step title="Step 7: Review details and click `Register collection` to complete">
    <Frame type="simple">
      <img alt="Candy machine registration complete screenshot" />
    </Frame>
  </Step>
</Steps>

Congratulations! 🎉 You've successfully registered your external collection in Crossmint.

<Snippet />

## FAQs

<AccordionGroup>
  <Accordion title="What about Xion blockchain contracts?">
    For Xion blockchain contracts, please refer to our [Xion Contract Requirements](/minting/advanced/xion-contracts) documentation.
  </Accordion>

  <Accordion title="What about other blockchains? (Aptos, Sui, etc.)">
    Currently only importing EVM and Solana primary contracts is self-serve. If you wish to import Aptos and Sui contracts, please [contact
    sales](https://www.crossmint.com/contact/sales?utm_source=devrel\&utm_medium=docs\&utm_campaign=backlinks).
  </Accordion>

  <Accordion title="Can I register my collection via API?">
    Yes! You can programmatically register collections using the Collections Registration API.

    **API Endpoint:** `POST https://staging.crossmint.com/api/v1-alpha1/collections`

    **Required Headers:**

    * `Content-Type: application/json`
    * `x-api-key: <your-api-key>` (requires `collections.create` scope)

    <CodeGroup>
      ```bash EVM Contract Example theme={null}
      curl --request POST \
           --url https://staging.crossmint.com/api/v1-alpha1/collections \
           --header 'content-type: application/json' \
           --header 'x-api-key: <X_API_KEY>' \
           --data '{
             "chain": "ethereum",
             "contractType": "erc-721",
             "args": {
               "contractAddress": "0x1234567890123456789012345678901234567890",
               "abi": "[{\"inputs\":[{\"internalType\":\"address\",\"name\":\"_to\",\"type\":\"address\"}],\"name\":\"mintTo\",\"outputs\":[],\"stateMutability\":\"payable\",\"type\":\"function\"}]",
               "mintFunctionName": "mintTo(address)",
               "toParamName": "_to",
               "quantityParamName": "_quantity",
               "contractType": "erc-721"
             },
             "metadata": {
               "title": "My NFT Collection",
               "description": "A custom NFT collection",
               "imageUrl": "https://example.com/collection-image.png",
               "social": {
                 "twitter": "https://twitter.com/mycollection",
                 "discord": "https://discord.gg/mycollection"
               }
             },
             "ownership": "external",
             "category": "art",
             "scopes": ["payments:credit-card", "payments:cross-chain"]
           }'
      ```

      ```bash Solana Candy Machine Example theme={null}
      curl --request POST \
           --url https://staging.crossmint.com/api/v1-alpha1/collections \
           --header 'content-type: application/json' \
           --header 'x-api-key: <X_API_KEY>' \
           --data '{
             "chain": "solana",
             "contractType": "candy-machine",
             "args": {
               "candyMachineId": "your-candy-machine-id-here"
             },
             "metadata": {
               "title": "My Solana Collection",
               "description": "A Solana NFT collection",
               "imageUrl": "https://example.com/collection-image.png"
             },
             "ownership": "external",
             "category": "art",
             "scopes": ["payments:credit-card", "payments:cross-chain"]
           }'
      ```
    </CodeGroup>

    **Key Parameters:**

    * **chain**: `"solana"`, `"ethereum"`, `"polygon"`, `"bsc"`
    * **contractType**: `"candy-machine"`, `"erc-721"`, `"erc-1155"`
    * **args**: Contract-specific arguments (see examples above)
      * For EVM: `contractAddress`, `abi`, `mintFunctionName`, `toParamName`, `contractType` (required); `quantityParamName`, `tokenContractAddress` (optional)
      <Note>
        In EVM, if you use a separate contract for minting than for token metadata, set the minting contract address as `contractAddress`, and the token contract address as `tokenContractAddress`.
      </Note>
      * For Solana: `candyMachineId` (required)
    * **metadata**: Object with `title`, `description`, `imageUrl` (all required), and optional `social` object with `twitter`/`discord` links
    * **ownership**: `["self", "external"]`. Set to `"external"` for imported contracts
    * **category**: `"art"`, `"gaming"`, `"music"`, `"loyalty"`, `"ticketing"`, `"charity"`, `"other"`
    * **scopes**: `["payments:credit-card", "payments:cross-chain"]`. Scopes are required when `ownership` is `"external"`

    **Response (201 Created):**
    The API returns a collection object with identifiers you can use with Crossmint's checkout and payment systems.

    ```json theme={null}
    {
        "collectionId": "abc123-def456-ghi789...",
        "clientId": "abc123-def456-ghi789..."
    }
    ```

    <Note>This API is currently in alpha (v1-alpha1) and subject to change. The returned `collectionId` and `clientId` are typically the same value and can be used interchangeably for checkout integration.</Note>
  </Accordion>
</AccordionGroup>


# Client or Server
Source: https://docs.crossmint.com/payments/headless/guides/client-or-server

Understand the reasons to use client-side or server-side API keys

The headless checkout supports both server-side and client-side API keys. It's important that you select the right key for your implementation.

## When to use a server-side API key

* Testing in the [API Playground](/api-reference/headless/create-order) of the documentation
* Testing with cURL requests or running scripts from your command line
* Building applications that make API calls to your own backend, which then make the actual API call to Crossmint

<Note>The key consideration here is if the API request is coming from a server environment.</Note>

### Server Side Example Code

```typescript route.ts (server-side) theme={null}
import { callCrossmintAPI } from "@/app/utils/crossmint";
import { NextRequest, NextResponse } from "next/server";

const crossmintBaseUrl = process.env.CROSSMINT_API_URL;
const crossmintApiKey = process.env.CROSSMINT_API_KEY;

const crossmintAPIHeaders = {
    accept: "application/json",
    "content-type": "application/json",
    "x-api-key": crossmintApiKey,
};

const callCrossmintAPI = async (endpoint: string, options: { method: string; body?: any; params?: any }) => {
    const url = `${crossmintBaseUrl}/${endpoint}`;
    const { body, method } = options;

    const response = await fetch(url, {
        body: body ? JSON.stringify(body) : null,
        method,
        headers: crossmintAPIHeaders,
    });
    const json = await response.json();
    return json;
};

export async function POST(req: NextRequest, res: NextResponse) {
    try {
        const body = await req.json();
        console.log("create order: ", body);

        const apiResponse = await callCrossmintAPI("/orders", {
            method: "POST",
            body,
        });

        return NextResponse.json(apiResponse, { status: 200 });
    } catch (error) {
        console.log("failed to create order");
        return NextResponse.json({ message: "Error creating order" }, { status: 500 });
    }
}
```

## When to use a client-side API key

* Your application will be making API requests to Crossmint directly from a browser

<Note>
  When you create client-side API keys you must add the authorized origins that can use the key. For example, in
  testing you'll need to indicate `http://localhost:3000` (or similar local dev URLs) as authorized origins, or the
  request will be denied.
</Note>

<img alt="Client Key Domain" />

There is one additional step when using a client-side API key in your application with headless checkout. The first call will be to create the order. The response will include a `clientSecret` property that you must persist in state and then pass as an additional header in subsequent API requests to the [update-order](/api-reference/headless/edit-order) or [get-order](/api-reference/headless/get-order) routes.

### Client Side Example Code

<Note>
  The sample code below shows direct client-side API calls to Crossmint using a client-side API key. The `component.tsx` file is simplified to only show the relevant logic for making requests directly from the browser to Crossmint's API.
</Note>

<CodeGroup>
  ```tsx component.tsx (create-order) theme={null}
  // note the end of try block where the clientSecret is saved to local state
  const { setOrder, setClientSecret } = useLocalState();

  const createOrder = async (orderInput: any) => {
      try {
          const res = await fetch(`https://staging.crossmint.com/api/2022-06-09/orders`, {
              method: "POST",
              headers: {
                  "Content-Type": "application/json",
                  "x-api-key": process.env.NEXT_PUBLIC_CLIENT_SIDE_KEY,
              },
              body: JSON.stringify(orderInput),
          });

          const order = await res.json();

          setOrder(order.order);
          setClientSecret(order.clientSecret);
      } catch (e) {
          console.error(e);
          throw new Error("Failed to create order");
      }
  };
  ```

  ```tsx component.tsx (update-order) theme={null}
  // note the `authorization` header, which contains previously saved clientSecret
  const { order, clientSecret, setOrder } = useLocalState();

  const updateOrder = async (orderInput: any) => {
      try {
          const res = await fetch(`https://staging.crossmint.com/api/2022-06-09/orders/${order.orderId}`, {
              method: "PATCH",
              headers: {
                  "Content-Type": "application/json",
                  "x-api-key": process.env.NEXT_PUBLIC_CLIENT_SIDE_KEY,
                  authorization: clientSecret,
              },
              body: JSON.stringify(orderInput),
          });

          const updatedOrder = await res.json();

          setOrder(updatedOrder);
      } catch (e) {
          console.error(e);
          throw new Error("Failed to update order");
      }
  };
  ```

  ```tsx component.tsx (get-order) theme={null}
  // note the `authorization` header, which contains previously saved clientSecret
  const { order, clientSecret, setOrder } = useLocalState();

  const getOrder = async () => {
      try {
          const res = await fetch(`https://staging.crossmint.com/api/2022-06-09/orders/${order.orderId}`, {
              method: "GET",
              headers: {
                  "Content-Type": "application/json",
                  "x-api-key": process.env.NEXT_PUBLIC_CLIENT_SIDE_KEY,
                  authorization: clientSecret,
              },
          });

          const refreshedOrder = await res.json();

          setOrder(refreshedOrder);

          return refreshedOrder.lineItems[0].delivery.status;
      } catch (e) {
          console.error(e);
          throw new Error("Failed to fetch order");
      }
  };
  ```
</CodeGroup>

### Mobile Applications

When using client-side API keys in mobile applications, you must include an additional `x-app-identifier` header in your requests. This header should contain the bundle identifier (iOS) or package name (Android) that you whitelisted when creating your API key.

<img alt="Client Key Domain Mobile" />

<CodeGroup>
  ```swift iOS (Swift) theme={null}
  let headers = [
      "Content-Type": "application/json",
      "x-api-key": "your-client-side-api-key",
      "x-app-identifier": "com.yourcompany.yourapp", // iOS Bundle ID
      "authorization": clientSecret // When updating/reading orders
  ]
  ```

  ```kotlin Android (Kotlin) theme={null}
  val headers = mapOf(
      "Content-Type" to "application/json",
      "x-api-key" to "your-client-side-api-key",
      "x-app-identifier" to "com.yourcompany.yourapp", // Android Package Name
      "authorization" to clientSecret // When updating/reading orders
  )
  ```

  ```javascript React Native theme={null}
  const headers = {
      "Content-Type": "application/json",
      "x-api-key": "your-client-side-api-key",
      "x-app-identifier": "com.yourcompany.yourapp", // Bundle ID or Package Name
      authorization: clientSecret, // When updating/reading orders
  };
  ```
</CodeGroup>

<Note>
  The `x-app-identifier` must match one of the mobile app identifiers you whitelisted when creating your client-side
  API key. For more information on setting up mobile app identifiers, see the [Client-side API
  Keys](/introduction/platform/api-keys/client-side#mobile-app-identifiers) documentation.
</Note>


# Design Your UI
Source: https://docs.crossmint.com/payments/headless/guides/design-your-ui

How to get started with setting up your UI

This guide will walk you through the basic steps of implementing a user interface integrated with the Headless Checkout. The first step in the process will be to create an Order via API call.

You can create an order on load and add the recipient later, or wait to create the order when you have the recipient info ready. Creating the order immediately helps obtain the price quote for display. Let's proceed with that approach in mind.

## Building Your App

There are four key components you'll need to represent in the UI for your users.

1. Purchase Preview - a visual explanation of what they are buying and the price
2. Wallet Connection - cross-chain payments will require the ability to connect a wallet
3. Payment Status - keeping the user updated about the payment acceptance
4. Delivery Status - progress of delivery and information upon completion/failure

### Purchase Preview

It is common to create an order upon initial render for your user, and then update the details of that order as the adjustments are made by the user. You'll need to create a function in your application that can call the create-order API and save the response.

<Tabs>
  <Tab title="Preview Screenshot">
    After you create the `order` you'll get back metadata related to the `collectionId` you pass in the [create-order](/api-reference/headless/create-order) call. You can use this metadata to build the preview highlighted in the screenshot below.

    <Frame type="simple">
      <img alt="preview purchase screenshot" />
    </Frame>
  </Tab>

  <Tab title="Code Snippet">
    ```jsx theme={null}
    useEffect(() => {
        if (order != null) {
            return;
        }

        createOrder({
            payment: {
                method: "ethereum-sepolia",
                currency: "eth",
            },
            locale: "en-US",
            lineItems: [
                {
                    collectionLocator: "crossmint:YOUR_CROSSMINT_COLLECTION_ID",
                    callData: {
                        totalPrice: "0.001",
                    },
                },
            ],
        });
    }, [order]);
    ```
  </Tab>
</Tabs>

### Wallet Connection

To enable the cross-chain payments feature, you'll need to provide an easy way for users to connect their wallet. This guide will not go into detail about how to add any specific tools, since there are a variety available and the implementation of each is unique to the tool.

However, you will want to set up your app to listen for changes to the primary connected wallet and selected network so that the order is updated automatically.

<Tabs>
  <Tab title="Wallet & Network Screenshot">
    Once the user has connected their wallet they might still change the primary connected account or network. You need to listen for these changes and update the order.

    <Frame type="simple">
      <img alt="preview wallet and network screenshot" />
    </Frame>
  </Tab>

  <Tab title="Code Snippet">
    Note the dependency array at the end of this `useEffect` watches `primaryWallet` and `selectedNetwork`. If any of these change your app needs to refresh the order with the new values.

    ```jsx theme={null}
    useEffect(() => {
        if (order == null || primaryWallet == null) {
            return;
        }

        const currentRecipient = order.lineItems[0].delivery.recipient?.walletAddress;
        const isSameWallet = currentRecipient === primaryWallet.address;
        const isSameNetwork = order.payment.method === selectedNetwork;
        if (isSameWallet && isSameNetwork) {
            return;
        }

        updateOrder({
            recipient: {
                walletAddress: primaryWallet.address,
            },
            payment: {
                method: selectedNetwork,
                currency: "eth",
                payerAddress: primaryWallet.address,
            },
        });
    }, [primaryWallet, selectedNetwork]);
    ```
  </Tab>
</Tabs>


# Item Selection
Source: https://docs.crossmint.com/payments/headless/guides/item-selection

Specify which items to purchase with Headless Checkout API

The Headless Checkout API allows you to specify which items your users can purchase using the `lineItems` property. This guide explains how to configure item selection for different asset types.

<Snippet />

## JSON Item Selection Examples

<CodeGroup>
  ```json collectionLocator theme={null}
  {
    "lineItems": [
      {
        "collectionLocator": "crossmint:_YOUR_COLLECTION_ID_", // Crossmint managed collection
        // "collectionLocator": "crossmint:_YOUR_COLLECTION_ID_:_TEMPLATE_ID_", // With specific template
        "callData": {
          "totalPrice": "5.00",
          "quantity": 1 // matches your contract's parameter name
        }
      }
    ]
  }
  // To use exact-in mode, add executionParameters: { maxSlippageBps: "500" } to the lineItem object. For custom contract params, add executionParameters: { customParam: "value" }.
  ```

  ```json collectionLocator - imported contract theme={null}
  {
    "lineItems": [
      {
        "collectionLocator": "ethereum:0x71c7656ec7ab88b098defb751b7401b5f6d897", // External collection registered in Crossmint Console
        "callData": {
          "totalPrice": "5.00",
          "quantity": 1 // matches your contract's parameter name
          // For external contracts, you might need additional parameters such as:
          // "_amount": 1, // if your mint function uses _amount instead of quantity
          // "tokenId": "123", // if your contract requires a specific tokenId
          // "metadata": "ipfs://...", // if your contract accepts metadata
        }
      }
    ]
  }
  ```

  ```json tokenLocator - EVM theme={null}
  {
    "lineItems": [
      {
        "tokenLocator": "ethereum:0x71c7656ec7ab88b098defb751b7401b5f6d897:1234", // <blockchain>:<contractAddress>:<tokenId>
        "callData": {
          "totalPrice": "25.00" // Only totalPrice is required for token purchases
          // For external EVM contracts, you might need additional parameters:
          // "_amount": 1, // if your contract uses _amount instead of quantity
          // "tokenId": "1234", // if your contract requires explicit tokenId
          // "metadata": "ipfs://...", // if your contract accepts metadata
        }
      }
    ]
  }
  // To use exact-in mode, add executionParameters: { maxSlippageBps: "500" } to the lineItem object. For custom contract params, add executionParameters: { customParam: "value" }.
  ```

  ```json tokenLocator - Solana theme={null}
  {
    "lineItems": [
      {
        "tokenLocator": "solana:7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU", // <blockchain>:<tokenAddress>
        "callData": {
          "totalPrice": "25.00",
          "buyerCreatorRoyaltyPercent": 100 // Required for Solana
        }
      }
    ]
  }
  // To use exact-in mode, add executionParameters: { maxSlippageBps: "500" } to the lineItem object. For custom contract params, add executionParameters: { customParam: "value" }.
  ```
</CodeGroup>

<Snippet />

<Snippet />

## Complete API Request Examples

For those who want a full copy/pastable code example, extended versions of the JSON guides are provided below.

<CodeGroup>
  ```javascript collectionLocator theme={null}
  const options = {
      method: "POST",
      headers: { "x-api-key": "_YOUR_API_KEY_", "Content-Type": "application/json" },
      body: JSON.stringify({
          recipient: {
              email: "buyer@example.com",
          },
          payment: {
              method: "ethereum-sepolia",
              currency: "eth",
          },
          lineItems: [
              {
                  collectionLocator: "crossmint:_YOUR_COLLECTION_ID_", // Crossmint managed collection
                  // collectionLocator: "crossmint:_YOUR_COLLECTION_ID_:_TEMPLATE_ID_", // With specific template
                  callData: {
                      totalPrice: "5.00",
                      quantity: 1, // matches your contract's parameter name
                  },
              }
          ],
      }),
  };

  fetch("https://staging.crossmint.com/api/2022-06-09/orders", options)
      .then((response) => response.json())
      .then((response) => console.log(response))
      .catch((err) => console.error(err));
  ```

  ```javascript tokenLocator - EVM theme={null}
  const options = {
      method: "POST",
      headers: { "x-api-key": "_YOUR_API_KEY_", "Content-Type": "application/json" },
      body: JSON.stringify({
          recipient: {
              email: "buyer@example.com",
          },
          payment: {
              method: "ethereum-sepolia",
              currency: "eth",
          },
          lineItems: [
              {
                  tokenLocator: "ethereum:0x71c7656ec7ab88b098defb751b7401b5f6d897:1234", // <blockchain>:<contractAddress>:<tokenId>
                  callData: {
                      totalPrice: "25.00", // Only totalPrice is required for token purchases
                      // For external EVM contracts, you might need additional parameters:
                      // _amount: 1, // if your contract uses _amount instead of quantity
                      // tokenId: "1234", // if your contract requires explicit tokenId
                      // metadata: "ipfs://...", // if your contract accepts metadata
                  },
              }
          ],
      }),
  };

  fetch("https://staging.crossmint.com/api/2022-06-09/orders", options)
      .then((response) => response.json())
      .then((response) => console.log(response))
      .catch((err) => console.error(err));
  ```

  ```javascript tokenLocator - Solana theme={null}
  const options = {
      method: "POST",
      headers: { "x-api-key": "_YOUR_API_KEY_", "Content-Type": "application/json" },
      body: JSON.stringify({
          recipient: {
              email: "buyer@example.com",
          },
          payment: {
              method: "solana",
              currency: "sol",
          },
          lineItems: [
              {
                  tokenLocator: "solana:7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU", // <blockchain>:<tokenAddress>
                  callData: {
                      totalPrice: "25.00",
                      buyerCreatorRoyaltyPercent: 100, // Required for Solana
                  },
              }
          ],
      }),
  };

  fetch("https://staging.crossmint.com/api/2022-06-09/orders", options)
      .then((response) => response.json())
      .then((response) => console.log(response))
      .catch((err) => console.error(err));
  ```

  ```javascript collectionLocator - imported contract theme={null}
  const options = {
      method: "POST",
      headers: { "x-api-key": "_YOUR_API_KEY_", "Content-Type": "application/json" },
      body: JSON.stringify({
          recipient: {
              email: "buyer@example.com",
          },
          payment: {
              method: "ethereum-sepolia",
              currency: "eth",
          },
          lineItems: [
              {
                  collectionLocator: "ethereum:0x71c7656ec7ab88b098defb751b7401b5f6d897", // External collection registered in Crossmint Console
                  callData: {
                      totalPrice: "5.00",
                      quantity: 1, // matches your contract's parameter name
                      // For external contracts, you might need additional parameters such as:
                      // _amount: 1, // if your mint function uses _amount instead of quantity
                      // tokenId: "123", // if your contract requires a specific tokenId
                      // metadata: "ipfs://...", // if your contract accepts metadata
                  },
              }
          ],
      }),
  };

  fetch("https://staging.crossmint.com/api/2022-06-09/orders", options)
      .then((response) => response.json())
      .then((response) => console.log(response))
      .catch((err) => console.error(err));
  ```
</CodeGroup>

<Snippet />


# Localization
Source: https://docs.crossmint.com/payments/headless/guides/localization

Customize the language of the email receipt for headless checkouts

## Supported Locales

| Variable | Possible Values | Description |
| - | - | - |
| `locale` | `en-US` `de-DE` `es-ES` `fr-FR` `it-IT` `ja-JP` `ko-KR` `pt-PT` `ru-RU` `th-TH` `tr-TR` `uk-UA` `vi-VN` `zh-CN` `zh-TW` `Klingon` | Language selected for the email receipt. |

<Info>
  * Only `usd` is supported for credit and debit card checkouts, so set `payment.currency` to `usd`
  * Localization is not supported for stablecoins. While `payment.crypto.defaultCurrency` can be set to `usdc` or other supported tokens, localized stablecoins like `eurc` are not available.
</Info>

To customize the language use the property `locale`. Here is an example:

```json {2,6} theme={null}
{
    "locale": "es-ES", // Language for the receipt (e.g. Spanish customers)
    "payment": {
        "receiptEmail": "jsmith@example.com",
        "method": "card",
        "currency": "usd" // If collection is priced in another currency, the quote is returned in USD
    },
    "lineItems": [
        {
            "collectionLocator": "crossmint:76ced33d-fec8-4741-a69f-450f1ae09fa6",
            "callData": {
                "totalPrice": "<string>"
            }
        }
    ]
}
```

<Note>
  When implementing a headless checkout, you will need to handle the display of localized content in your own UI based
  on the locale you selected. The locale only affects the email receipt language, not the checkout interface built
  by you.
</Note>


# Multiple Line Items
Source: https://docs.crossmint.com/payments/headless/guides/multiple-line-items

How to handle orders with multiple NFTs at once

The Headless Checkout multiple line items feature is used to build more elaborate purchase experiences, which require multiple NFT purchases at once. Multiple line items is currently only supported for NFTs.

<Note>Currently, there is a maximum limit of 15 NFTs per order.</Note>

Example use cases include:

* A marketplace where a buyer can add multiple NFTs to a cart and make the purchase in a single transaction.
* Enabling the purchase of multiple distinct tokens from an ERC-1155 contract in a single transaction.

## Marketplace Sales

The following example requires that you have a custom `collectionId` that supports secondary sales provisioned for you by your Crossmint Customer Success Engineer. For more information on marketplace and launchpad support, check [this guide](/payments/advanced/marketplaces-and-launchpads).

If you need to contact the team about getting set up with secondary sales support [contact the team](https://www.crossmint.com/contact/sales).

### Multiple `lineItems` for Secondary Sales

To enable a multi item purchase, you simply need to pass an array of `lineItems` instead of a single object when creating an order.

The below examples demonstrate how to create a multiple line item order for secondary sales:

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://staging.crossmint.com/api/2022-06-09/orders \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: _YOUR_API_KEY_' \
    --data '{
      "recipient": {
        "email": "testy@crossmint.com"
      },
      "locale": "en-US",
      "payment": {
        "receiptEmail": "testy@crossmint.com",
        "method": "ethereum-sepolia",
        "currency": "eth"
      },
      "lineItems": [
        {
          "collectionLocator": "crossmint:_YOUR_SECONDARY_SALES_COLLECTION_ID_",
          "callData": {
            "contractAddress": "0x___CONTRACT_ADDRESS_OF_TOKEN",
            "tokenId": "234"
          }
        },
        {
          "collectionLocator": "crossmint:_YOUR_SECONDARY_SALES_COLLECTION_ID_",
          "callData": {
            "contractAddress": "0x___ANOTHER_TOKEN_CONTRACT",
            "tokenId": "567"
          }
        }
      ]
    }'
  ```

  ```javascript Node.js theme={null}
  const options = {
    method: 'POST',
    headers: {'x-api-key': '_YOUR_API_KEY_', 'Content-Type': 'application/json'},
    body: '{
      "recipient": {
        "email": "test@crossmint.com"
      },
      "locale": "en-US",
      "payment": {
        "receiptEmail": "test@crossmint.com",
        "method": "ethereum-sepolia",
        "currency": "eth",
        "payerAddress": "0x1234_payer_address"
      },
      "lineItems": [
        {
          "collectionLocator": "crossmint:_YOUR_SECONDARY_SALES_COLLECTION_ID_",
          "callData": {
            "contractAddress": "0x___CONTRACT_ADDRESS_OF_TOKEN",
            "tokenId": "234"
          }
        },
        {
          "collectionLocator": "crossmint:_YOUR_SECONDARY_SALES_COLLECTION_ID_",
          "callData": {
            "contractAddress": "0x___ANOTHER_TOKEN_CONTRACT",
            "tokenId": "567"
          }
        }
      ]
    }'
  };

  fetch('https://staging.crossmint.com/api/2022-06-09/orders', options)
    .then(response => response.json())
    .then(response => console.log(response))
    .catch(err => console.error(err));
  ```
</CodeGroup>

After this step you will collect payment from the buyer as outlined in the [Order Lifecycle](/payments/headless/guides/order-lifecycle/) section.

## Primary Sales of Multiple Items

<Note>
  If you have a custom ERC-721 contract that supports the minter being able to specify which token they want to mint
  you could use the example(s) below to enable them to purchase multiple and specific tokens in the same transaction.
  This is an uncommon pattern for ERC-721 contracts though.
</Note>

In the following example, the use case is purchasing two unique tokens from an ERC-1155 contract. You can see that the `_id` passed in the `callData` of each `lineItem` is unique (1 and 2).

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://staging.crossmint.com/api/2022-06-09/orders \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: _YOUR_API_KEY_' \
    --data '{
    "recipient": {
      "email": "testy@crossmint.com"
    },
    "locale": "en-US",
    "payment": {
      "receiptEmail": "testy@crossmint.com",
      "method": "ethereum-sepolia",
      "currency": "eth"
    },
    "lineItems": [
      {
        "collectionLocator": "crossmint:_YOUR_COLLECTION_ID_",
        "callData": {
          "_id_": "1",
          "quantity": "1"
        }
      },
      {
        "collectionLocator": "crossmint:_YOUR_COLLECTION_ID_",
        "callData": {
          "_id_": "2",
          "quantity": "1"
        }
      },
    ]
  }'
  ```

  ```javascript Node.js theme={null}
  const options = {
    method: 'POST',
    headers: {'x-api-key': '_YOUR_API_KEY_', 'Content-Type': 'application/json'},
    body: '{
        "recipient":
        {
            "email": "testy@crossmint.com"
        },
        "locale": "en-US",
        "payment":
        {
            "receiptEmail": "testy@crossmint.com",
            "method": "ethereum-sepolia",
            "currency": "eth",
            "payerAddress": "0x1234_payer_address"
        },
        "lineItems": [
          {
            "collectionLocator": "crossmint:_YOUR_COLLECTION_ID_",
            "callData": {
              "_id_": "1",
              "quantity": "1"
            }
          },
          {
            "collectionLocator": "crossmint:_YOUR_COLLECTION_ID_",
            "callData": {
              "_id_": "2",
              "quantity": "1"
            }
          },
        ]
      }'
    };

  fetch('https://staging.crossmint.com/api/2022-06-09/orders', options)
    .then(response => response.json())
    .then(response => console.log(response))
    .catch(err => console.error(err));
  ```
</CodeGroup>

As in the secondary sales example above, you'll need to handle the remaining steps of the order lifecycle in your UI - payment, delivery, etc.

## Error Handling

As outlined in the [Delivery Phase](/payments/headless/guides/order-lifecycle/delivery-phase#error-handling) of the order lifecycle guides, it is important to keep track of the delivery for each item passed when you created the order and report back to the user on the status of the order.

Each line item is attempted and processed independently. If one line item fails, others will still go through and be fulfilled. If any items are undeliverable, the buyer will be automatically refunded for that specific portion of their order.
For definitions of delivery and line item statuses, see the <a href="/payments/headless/guides/status-codes">Status Codes</a> page.


# Order Complete Phase
Source: https://docs.crossmint.com/payments/headless/guides/order-lifecycle/completed-phase

Completion phase of the order lifecycle

The final phase in the order lifecycle is order completion. This occurs once payment has been successful and the delivery phase is finished.

The `order.phase` property will be set to `completed` once all line items have reached a final state — whether each item individually succeeded or failed.

For reference on all statuses (quote, payment, delivery), see the [Status Codes](/payments/headless/guides/status-codes) page.

<Warning>
  `order.phase === "completed"` does **not** mean every line item succeeded. The phase reaches `completed` once all
  line items have reached a final state — whether `completed` or `failed`. This applies to **both** single-item and multi-item orders.
  You must always check each line item's `delivery.status` individually.
</Warning>

### Checking Line Item Delivery Status

Once `order.phase` reaches `completed`, fetch the order via the GET order API and loop through the `lineItems` array to determine the outcome of each item. Each line item's `delivery.status` can be one of: `awaiting-payment`, `in-progress`, `completed`, or `failed`.

```tsx theme={null}
const apiUrl = "https://staging.crossmint.com/api/2022-06-09";
const res = await fetch(`${apiUrl}/orders/${orderId}`, {
    method: "GET",
    headers: {
        "Content-Type": "application/json",
        "x-api-key": process.env.NEXT_PUBLIC_CROSSMINT_API_KEY,
        authorization: clientSecret,
    },
});

const order = await res.json();

if (order.phase === "completed") {
    for (const item of order.lineItems) {
        if (item.delivery.status === "failed") {
            // Handle item failure
        } else if (item.delivery.status === "completed") {
            // Handle successful delivery
        }
    }
}
```

### Recommendations

Think through and implement the call to action that makes sense for your buyers.

#### Where can they access the purchased item?

If the token was minted to their Crossmint wallet you can provide a direct link and/or render a representation of it.

Even if they minted directly to an existing wallet you can provide a link to display the token in Crossmint. Use the following URL format to display NFTs within Crossmint:

`https://www.crossmint.com/user/collection/<chain>:<contractAddress>:<tokenId>`

For info on the values to use for `<chain>` refer to the [supported chains](/introduction/supported-chains) page.

#### What are the next steps?

Can they stake, trade, or utilize the purchase in some way? Tell them how!

#### Handling Order Failure

If there were any issues with delivery explain what happened and ensure they know that refunds are automatic. Anyone who purchases through Crossmint and has an issue with delivery can contact our support team for assistance.


# Pay with Card
Source: https://docs.crossmint.com/payments/headless/guides/order-lifecycle/credit-card-payment-phase

Payment acceptance phase of the order lifecycle for credit cards.

The order lifecycle can be summarized as follows:

<Steps>
  <Step title="Order Creation or Update">
    Your application determines recipient info for the buyer. It can be an email wallet or wallet address. Create or
    update an order with this info to proceed to next step.
  </Step>

  <Step title="API Response">
    The API response returned from create/update order call(s) will include a `clientSecret` and `order` object that your
    application uses to render the Crossmint Embedded Component.
  </Step>

  <Step title="Render Crossmint Embedded Component">
    Use the `clientSecret` and `order.orderId` returned in the API response to render the Crossmint Embedded Component
    for credit card checkout.
  </Step>

  <Step title="User Completes Payment">The buyer completes checkout via credit card.</Step>

  <Step title="Poll for Status">
    Your application will poll the GET order status and update the UI as the order progresses to the next phase.
  </Step>
</Steps>

<Note>During the initial `quote` phase of the order the payment status will be `requires-quote`.</Note>

Once the quote phase is completed, the order enters the payment phase and will have the status `awaiting-payment`, which indicates that the order is ready to be paid.

For the complete, authoritative list of payment statuses and their meanings, see the [Status Codes](/payments/headless/guides/status-codes) page. |

### Render the Crossmint Embedded Component

When the order is ready to accept payment, the API response will include a `clientSecret` and `order` object. You can use these with the Crossmint Embedded Component to collect the user's credit card payment.

<Accordion title="Example response">
  ```json theme={null}
  {
    "clientSecret": "_YOUR_CLIENT_SECRET_",
    "order": {
      "orderId": "5ddc0090-7f63-4f6a-b68d-a91f8253b02e",
      "phase": "payment",
      "locale": "en-US",
      "lineItems": [], // removed for brevity
      "quote": {
        "status": "valid",
        "quotedAt": "_timestamp_",
        "expiresAt": "_timestamp_",
        "totalPrice": {
          "amount": "0.5",
          "currency": "usd"
        }
      },
      "payment": {
        "status": "awaiting-payment",
        "method": "basis-theory",
        "currency": "usd",
        "preparation": {},
        "receiptEmail": "test@example.com"
      }
    }
  }
  ```
</Accordion>

After creating an order, you'll need to render the Crossmint Embedded Component to collect payment information. This secure, embeddable UI component lets you accept payment methods, validates input, and handles errors:

```tsx theme={null}
import { CrossmintEmbeddedCheckout, CrossmintProvider } from "@crossmint/client-sdk-react-ui";

export function MyCheckoutPage({ clientSecret, order, recipientWalletAddress, receiptEmail }) {
  return (
    <div className="w-full">
      <CrossmintProvider apiKey="<YOUR_CLIENT_SIDE_KEY>">
        <CrossmintEmbeddedCheckout 
          recipient={{ walletAddress: recipientWalletAddress}}
          clientSecret={clientSecret}
          orderId={order.orderId}
          payment={{
            crypto: {
                enabled: false,
            },
            fiat: {
                enabled: true,
                allowedMethods: {
                    card: true,
                    applePay: false,
                    googlePay: false,
                },
            },
            defaultMethod: "fiat",
            receiptEmail: receiptEmail,
          }}
          appearance={{
              rules: {
                  DestinationInput: {
                      display: "hidden",
                  },
                  ReceiptEmailInput: {
                      display: "hidden",
                  },
              },
          }} />
      </CrossmintProvider>
    </div>
  );
}
```

<Tip>
  The `CrossmintEmbeddedCheckout` component is highly customizable. You can adjust colors, styling, layout, and behavior to match your brand. Learn more in our [UI customization guide](/payments/embedded/guides/ui-customization).
</Tip>

### Poll for Status Updates

<Snippet />

### Handling Declined Payments

When a card payment is declined, the order returns to `awaiting-payment` in most cases and includes a `payment.failureReason` object with a normalized `code`, `category`, `retryPolicy`, and user-safe `message`. Render the `message` to the buyer and use `retryPolicy` to decide whether to offer a retry, prompt for a different card, or stop. See the [Payment Error Codes](/payments/api-reference/error-codes) reference for the full catalog.

### Handling Refunded Payments

When polling for order status, you may encounter a situation where `payment.status` is `completed` but the order also contains a `payment.refunded` property. This indicates that the payment was initially successful but has since been refunded.

```json theme={null}
{
    "order": {
        "payment": {
            "status": "completed",
            "refunded": {
                "amount": "1.00",
                "currency": "usd"
            }
        }
    }
}
```

The `payment.refunded` object includes the following fields:

* `amount`: The amount that was refunded
* `currency`: The currency of the refund

When you encounter this state, your application should:

1. Display an appropriate message to the user indicating that their payment was refunded
2. Prevent any further actions related to the order (such as delivery expectations)
3. Provide options for the user to place a new order if desired

This state typically occurs when there was an issue with processing the order after payment was received, such as insufficient liquidity for memecoin purchases or compliance issues.


# Pay with Crypto
Source: https://docs.crossmint.com/payments/headless/guides/order-lifecycle/crypto-payment-phase

Payment acceptance phase of the order lifecycle for pay with crypto

An overview of the process works as follows:

<Steps>
  <Step title="Order Creation or Update">
    Your user selects the chain, token, and wallet they want to pay from via your application and you create or
    update an existing order with this information.
  </Step>

  <Step title="API Response">
    The API response returned from create or update order will include a `serializedTransaction` that your
    application uses to request payment from the user's wallet.
  </Step>

  <Step title="User Confirms Transaction">
    After your application initiates the payment request the user must confirm the transaction.
  </Step>

  <Step title="Poll for Status">
    Your application will poll the GET order status and update the UI as the order progresses to the next phase.
  </Step>
</Steps>

<Note>During the initial `quote` phase of the order the payment status will be `requires-quote`.</Note>

Once the quote phase is completed, the order enters the payment phase.

For most orders the payment phase will begin with the status `awaiting-payment`, which indicates that the order is ready to be paid. It can also begin with `requires-crypto-payer-address` if the payer address is missing.

For the complete, authoritative list of payment statuses and their meanings, see the [Status Codes](/payments/headless/guides/status-codes) page. |

### Setting the Payer Address

The order must know the address that will be sending the crypto payment. This enables Crossmint's payment listeners to associate incoming transactions with the correct order. To update the order with the payer address, call the update API as demonstrated below:

`PATCH` `/api/2022-06-09/orders/<orderId>`

```json theme={null}
{
    "payment": {
        "currency": "eth",
        "method": "base-sepolia",
        "payerAddress": "0x1234abcd…"
    }
}
```

The `payerAddress` is the wallet the user will be sending the payment from. Note that you must send the entire payment object even if the currency and/or method values are not changing.

### Submitting the Payment

When you've fully prepared the order such that the payment status is `awaiting-payment` you'll have everything necessary to request the crypto payment from your user. The details will be returned in the `order.payment.preparation` property.

<Accordion title="Example response">
  ```json theme={null}
  {
    "orderId": "c167db0f-0cb9-4c59-80d3-aface6bcb338",
    "phase": "payment",
    "locale": "en-US",
    "lineItems": [], // removed for brevity
    "quote": // removed for brevity
    "payment": {
      "status": "awaiting-payment",
      "method": "base-sepolia",
      "currency": "eth",
      "preparation": {
        "chain": "base-sepolia",
        "payerAddress": "0x6C3b3225759Cbda68F96378A9F0277B4374f9F06",
        "serializedTransaction": "0x02f9015083014a34238489173700848917387582653d94a105c311fa72b8fb78c992ecbdb8b02ea5bd394d868644e0f88d81b9011e2d2d2d2d2d2d424547494e204d454d4f2d2d2d2d2d2d65794a68624763694f694a49557a49314e694973496e523563434936496b705856434a392e65794a756232356a5a534936496a4e6b5954673159324a6b4c546c6a4e4459744e4459774f4331694d44686a4c5746694e6d557a595746684e4468694d794973496d39795a4756795357526c626e52705a6d6c6c63694936496d4d784e6a646b596a426d4c54426a596a6b744e474d314f5330344d47517a4c57466d59574e6c4e6d4a6a596a4d7a4f434973496d6c68644349364d5463784f446b784d7a63774f48302e75574365534961563642504b6f6935724d7939394c2d4b56303256644d4d343442343934724c4352656f632d2d2d2d2d2d454e44204d454d4f2d2d2d2d2d2dc0"
      }
    }
  }
  ```
</Accordion>

The `order.payment.preparation` property contains details about the chain that Crossmint is expecting the payment to be received on, the payer address, and a `serializedTransaction` that you can use to open a payment request in the user's wallet. See examples of how to parse the response and request transaction confirmation from the user below:

<Tabs>
  <Tab title="EVM">
    ```jsx theme={null}
    import { parseTransaction } from "viem";
    import { useSendTransaction } from "wagmi";

    const { sendTransactionAsync } = useSendTransaction();

    const signAndSendTransaction = async (serializedTransaction) => {
        const txn = parseTransaction(serializedTransaction)

        try {
          const txId = await sendTransactionAsync(txn);
          console.log("Transaction ID:", txId);
        } catch (error) {
          console.error("Error sending transaction:", error);
        }
    };
    ```
  </Tab>

  <Tab title="Solana">
    ```jsx theme={null}
    import bs58 from "bs58";
    import { useConnection, useWallet } from "@solana/wallet-adapter-react";

    const { connection } = useConnection();
    const { sendTransaction } = useWallet();

    const signAndSendTransaction = async (serializedTransaction) => {
        const transaction = Transaction.from(bs58.decode(serializedTransaction));

        try {
           const txId = await sendTransaction(transaction, connection);
           console.log("Transaction ID:", txId);
        } catch (error) {
          console.error("Error sending transaction:", error);
        }
    }
    ```
  </Tab>
</Tabs>

<Warning>
  You should **never** alter the values in the parsed transaction object. Simply parse the transaction object as shown
  in the example above. Changing any of these values may result in Crossmint not being able to validate the payment.
</Warning>

Calling the `signAndSendTransaction` function in the code snippet(s) above will open the user's wallet and enable them to confirm the crypto payment.

### Awaiting Payment Confirmation

<Check>We recommend a polling interval of about 2500ms and never below 500ms.</Check>

<Note>
  You can use client-side or server-side API keys to implement headless checkout. Check the code samples for the type
  of API key you're using in your application.
</Note>

<Tabs>
  <Tab title="Client Side">
    ```tsx theme={null}
    const getOrderPaymentStatus = async () => {
        const apiUrl = "https://staging.crossmint.com/api/2022-06-09";
        try {
            const res = await fetch(`${apiUrl}/orders/${order.orderId}`, {
                method: "GET",
                headers: {
                    "Content-Type": "application/json",
                    "x-api-key": process.env.NEXT_PUBLIC_CROSSMINT_API_KEY,
                    authorization: clientSecret, // saved from response of create order call
                },
            });

            const refreshedOrder = await res.json();

            setOrder(refreshedOrder);

            return refreshedOrder.payment.status;
        } catch (e) {
            console.error(e);
            throw new Error("Failed to fetch order");
        }
    };

    const pollPaymentStatus = async () => {
        const intervalId = setInterval(async () => {
            const status = await getOrderPaymentStatus();
            console.log("payment status: ", status);
            if (status === "completed") {
                clearInterval(intervalId);
            }
        }, 2500);

        // Set a timeout to stop polling after 60 seconds
        setTimeout(() => {
            clearInterval(intervalId);
            console.log("Taking longer than expected...");
        }, 60000);
    };
    ```
  </Tab>

  <Tab title="Server Side">
    <Note>
      The sample code below is from a NextJS application. The `component.tsx` file is simplified to only show the relevant
      logic. The client-side component sends an API request to the application's backend, which then proxies the request
      to Crossmint. This is because the example is using a server-side API key, which requires making requests from a server environment.
    </Note>

    <CodeGroup>
      ```tsx component.tsx (client-side) theme={null}
      const getOrderPaymentStatus = async () => {
          try {
              const res = await fetch(`/orders/${order.orderId}`, {
                  method: "GET",
                  headers: {
                      "Content-Type": "application/json",
                  },
              });

              const refreshedOrder = await res.json();

              setOrder(refreshedOrder);

              return refreshedOrder.payment.status;
          } catch (e) {
              console.error(e);
              throw new Error("Failed to fetch order");
          }
      };

      const pollPaymentStatus = async () => {
          const intervalId = setInterval(async () => {
              try {
                  const status = await getOrderPaymentStatus();
                  console.log("payment status: ", status);
                  if (status === "completed") {
                      clearInterval(intervalId);
                  }
              } catch (e) {
                  clearInterval(intervalId);
                  console.error("Error polling payment status: ", e);
              }
          }, 2500);

          // Set a timeout to stop polling after 60 seconds
          setTimeout(() => {
              clearInterval(intervalId);
              console.log("Taking longer than expected...");
          }, 60000);
      };
      ```

      ```typescript route.ts (server-side) theme={null}
      import { callCrossmintAPI } from "@/app/utils/crossmint";
      import { NextRequest, NextResponse } from "next/server";

      export async function GET(req: NextRequest, { params }: { params: { orderId: string } }) {
          if (params.orderId) {
              const order = await callCrossmintAPI(`/orders/${params.orderId}`, {
                  method: "GET",
              });

              return NextResponse.json(order, { status: 200 });
          } else {
              return NextResponse.json({ error: true, message: "Missing orderId" }, { status: 400 });
          }
      }
      ```

      ```typescript crossmint.ts theme={null}
      const crossmintBaseUrl = process.env.CROSSMINT_API_URL;

      const crossmintAPIHeaders = {
          accept: "application/json",
          "content-type": "application/json",
          "x-api-key": process.env.CROSSMINT_API_KEY!,
      };

      const callCrossmintAPI = async (endpoint: string, options: { method: string; body?: any; params?: any }) => {
          const url = `${crossmintBaseUrl}/${endpoint}`;
          const { body, method } = options;

          const response = await fetch(url, {
              body: body ? JSON.stringify(body) : null,
              method,
              headers: crossmintAPIHeaders,
          });
          const json = await response.json();
          return json;
      };

      export { callCrossmintAPI };
      ```
    </CodeGroup>
  </Tab>
</Tabs>

Once the payment is confirmed, you can move on to the delivery phase of the order lifecycle.

### Handling Refunded Payments

When polling for order status, you may encounter a situation where `payment.status` is `completed` but the order also contains a `payment.refunded` property. This indicates that the payment was initially successful but has since been refunded.

```json theme={null}
{
    "order": {
        "payment": {
            "status": "completed",
            "refunded": {
                "amount": "1.23",
                "currency": "eth"
            }
        }
    }
}
```

The `payment.refunded` object includes the following fields:

* `amount`: The amount that was refunded
* `currency`: The currency of the refund

When you encounter this state, your application should:

1. Display an appropriate message to the user indicating that their payment was refunded
2. Prevent any further actions related to the order (such as delivery expectations)
3. Provide options for the user to place a new order if desired

This state typically occurs when there was an issue with processing the order after payment was received, such as insufficient liquidity for memecoin purchases or compliance issues.


# Delivery Phase
Source: https://docs.crossmint.com/payments/headless/guides/order-lifecycle/delivery-phase

Token delivery phase of the order lifecycle

When the payment phase is completed, the user is guaranteed to receive the items ordered or an automatic refund for any unfulfilled items. Upon payment completion you'll want to display an animation in the UI indicating that the delivery is in-progress. Then poll the GET order API to check on delivery status and update your application UI when delivery status is updated.

<Note>
  You can use client-side or server-side API keys to implement headless checkout. Check the code samples for the type
  of API key you're using in your application.
</Note>

<Check>We recommend a polling interval of about 2500ms and never below 500ms.</Check>

<Tabs>
  <Tab title="Client Side">
    ```tsx theme={null}
    const getOrderDeliveryStatus = async () => {
        const apiUrl = "https://staging.crossmint.com/api/2022-06-09";
        try {
            const res = await fetch(`${apiUrl}/orders/${order.orderId}`, {
                method: "GET",
                headers: {
                    "Content-Type": "application/json",
                    "x-api-key": process.env.NEXT_PUBLIC_CROSSMINT_API_KEY,
                    authorization: clientSecret, // saved from response of create order call
                },
            });

            const refreshedOrder = await res.json();

            setOrder(refreshedOrder);

            return refreshedOrder.lineItems[0].delivery.status;
        } catch (e) {
            console.error(e);
            throw new Error("Failed to fetch order");
        }
    };

    const pollDeliveryStatus = async () => {
        const intervalId = setInterval(async () => {
            try {
                const status = await getOrderDeliveryStatus();
                console.log("delivery status: ", status);
                if (status === "completed") {
                    clearInterval(intervalId);
                }
            } catch (e) {
                clearInterval(intervalId);
                console.error("Error polling delivery status: ", e);
            }
        }, 2500);

        // Set a timeout to stop polling after 60 seconds
        setTimeout(() => {
            clearInterval(intervalId);
            console.log("Taking longer than expected...");
        }, 60000);
    };
    ```
  </Tab>

  <Tab title="Server Side">
    <Note>
      The sample code below is from a NextJS application. The `component.tsx` file is simplified to only show the relevant
      logic. The client-side component sends an API request to the application's backend, which then proxies the request
      to Crossmint. This is because the example is using a server-side API key, which requires making requests from a
      server environment.
    </Note>

    <CodeGroup>
      ```tsx component.tsx (client-side) theme={null}
      const getOrderDeliveryStatus = async () => {
          try {
              const res = await fetch(`/orders/${order.orderId}`, {
                  method: "GET",
                  headers: {
                      "Content-Type": "application/json",
                  },
              });

              const refreshedOrder = await res.json();

              setOrder(refreshedOrder);

              return refreshedOrder.lineItems[0].delivery.status;
          } catch (e) {
              console.error(e);
              throw new Error("Failed to fetch order");
          }
      };

      const pollDeliveryStatus = async () => {
          const intervalId = setInterval(async () => {
              const status = await getOrderDeliveryStatus();
              console.log("delivery status: ", status);
              if (status === "completed") {
                  clearInterval(intervalId);
              }
          }, 2500);

          // Set a timeout to stop polling after 60 seconds
          setTimeout(() => {
              clearInterval(intervalId);
              console.log("Taking longer than expected...");
          }, 60000);
      };
      ```

      ```typescript route.ts (server-side) theme={null}
      import { callCrossmintAPI } from "@/app/utils/crossmint";
      import { NextRequest, NextResponse } from "next/server";

      export async function GET(req: NextRequest, { params }: { params: { orderId: string } }) {
          if (params.orderId) {
              const order = await callCrossmintAPI(`/orders/${params.orderId}`, {
                  method: "GET",
              });

              return NextResponse.json(order, { status: 200 });
          } else {
              return NextResponse.json({ error: true, message: "Missing orderId" }, { status: 400 });
          }
      }
      ```

      ```typescript crossmint.ts theme={null}
      const crossmintBaseUrl = process.env.CROSSMINT_API_URL;

      const crossmintAPIHeaders = {
          accept: "application/json",
          "content-type": "application/json",
          "x-api-key": process.env.CROSSMINT_API_KEY!,
      };

      const callCrossmintAPI = async (endpoint: string, options: { method: string; body?: any; params?: any }) => {
          const url = `${crossmintBaseUrl}/${endpoint}`;
          const { body, method } = options;

          const response = await fetch(url, {
              body: body ? JSON.stringify(body) : null,
              method,
              headers: crossmintAPIHeaders,
          });
          const json = await response.json();
          return json;
      };

      export { callCrossmintAPI };
      ```
    </CodeGroup>
  </Tab>
</Tabs>

### Error Handling

Once the payment has been confirmed, delivery is likely to complete successfully. Before accepting the payment Crossmint simulates the expected transaction, which means that most delivery issues will be prevented before payment is even accepted. Given a successful payment the delivery process will be retried until it completes successfully or determines that delivery is impossible.

The most common cause for a delivery failure is that the item is no longer available. In the case of primary sales this could mean that the collection is sold out. For secondary sales the reason could be that someone else bought the item first.

Your application should be aware of the potential for delivery to fail and provide information to the buyer on what to expect. In the case of multiple items purchased and partial delivery failure you'll need to indicate which items were successfully delivered and which items failed.

<Note>
  Be sure to let your buyer know that in the case of a failed delivery they will be refunded automatically. If they
  have any questions or issues they can reach out to Crossmint support directly for assistance.
</Note>

A receipt will be sent to the buyer as long as their email was included in the order. There are two ways to pass this information. If the recipient is set to an email address, it will be used to send the receipt. In the case that the recipient is set to a `walletAddress` you can include an optional `receiptEmail` property within the payment object.

<CodeGroup>
  ```json Crypto Payment theme={null}
  {
      "payment": {
          "method": "base-sepolia",
          "currency": "eth",
          "payerAddress": "0xabcd1234...",
          "receiptEmail": "user@example.com"
      },
      "recipient": {
          "walletAddress": "0xabcd1234..."
      }
  }
  ```

  ```json Credit Card Payment theme={null}
  {
      "payment": {
          "method": "card",
          "receiptEmail": "user@example.com"
      },
      "recipient": {
          "email": "user@example.com"
      }
  }
  ```
</CodeGroup>


# Quote Phase
Source: https://docs.crossmint.com/payments/headless/guides/order-lifecycle/quote-phase

Initial phase of the order lifecycle

The first phase of the headless checkout process is the quote phase. During this phase, you construct an order that consists of the items being purchased, payment method, locale, and recipient. This will ultimately yield a quote to purchase it.

<Note>It's possible for an order to go from the payment phase back to the quote phase if the quote expires.</Note>

You can initialize an order such that the quote phase is completed in a single API call. Alternatively, you can create a basic order and iteratively update it with locale, recipient, and payment method information. The only information you cannot edit on a quote is the `lineItems` array, which indicate the details of what is being purchased.

<Check>If you need to alter the `lineItems` in an order you must create a new order.</Check>

## Quote status overview

During the quote phase, statuses indicate whether the order has enough information to proceed (like a recipient), and whether the quote is still valid. For the full, authoritative list of quote statuses, see the Status Codes page.

See the full list: [Status Codes](/payments/headless/guides/status-codes).

## Creating the Order

You will create the order via API call. The headless checkout offers support for both client-side or server-side API keys to enable you to build in a way that makes sense for your application.

<Note>
  Orders can be created using a client-side API key, but any subsequent fetches or updates will require passing the
  `clientSecret` returned in the create-order API response as an `authorization` header. This guide is written with
  the expectation of using a server-side API key.
</Note>

<Note>
  For more information on using Crossmint APIs refer to [API keys](/introduction/platform/api-keys) documentation
  page.
</Note>

To create a minimal order, make a `POST` request to the `/api/2022-06-09/orders` endpoint (view [API reference](/api-reference/headless/create-order)). The required properties to create an order are: `payment` and `lineItems`.

<CodeGroup>
  ```json Crypto Payment theme={null}
  {
      "payment": {
          "method": "base-sepolia",
          "currency": "eth",
          "payerAddress": "0x1234abcd..." // optional to create order, but required to proceed to payment phase
      },
      "lineItems": [
          {
              "collectionLocator": "crossmint:_YOUR_COLLECTION_ID_",
              "callData": {
                  "totalPrice": "0.0001"
              }
          }
      ]
  }
  ```

  ```json Credit Card Payment theme={null}
  {
      "payment": {
          "method": "card",
          "receiptEmail": "your-email@example.com"
      },
      "lineItems": [
          {
              "collectionLocator": "crossmint:_YOUR_COLLECTION_ID_",
              "callData": {
                  "totalPrice": "0.0001"
              }
          }
      ]
  }
  ```
</CodeGroup>

The `payment` object indicates the method and currency you intend to make the payment with. For crypto payments, this can be the same chain of the NFT or another chain that the buyer has liquidity on.

For example, buying an NFT on `BASE` chain with `BASE` `ETH`, buying an NFT on Solana with `SOL`, or any cross-chain combination of a [supported chain](/introduction/supported-chains) and currency.

The `payment.method` value for credit card checkouts should be `card` and the `payment.currency` must be `usd` (see [Supported Locales](/payments/headless/guides/localization#supported-locales)).

The `lineItems` array describes the NFTs being purchased.

#### Collection Locator

The `collectionLocator` within `lineItems` is how you specify the collection within Crossmint.
For primary sales where the NFTs are being minted for the first time, the contract will need to be registered in the Crossmint console.
You can find your `collectionId` within the Token collections tab in the developer console.

#### Token Locator

Alternatively, if this is a secondary sale, and your token is already minted and available on a supported marketplace, you can use a `tokenLocator`, instead of a `collectionLocator`.
***Using a token locator means you do not need to register the collection in the Crossmint console.***

The `tokenLocator` for EVM Chains follows the format `blockchain:contractAddress:tokenId` and for Solana follows the format `blockchain:tokenAddress`.

More information on the `tokenLocator` format can be found in the [marketplaces and launchpads guide](/payments/advanced/marketplaces-and-launchpads).

<Check>
  Remember, you can [view orders within the Developer
  Console](/payments/advanced/testing-tips#reviewing-orders-in-the-developer-console) to help get insight into the
  order process during testing and even after launch.
</Check>

## Updating the Order

All orders require a recipient to progress to the payment phase. You can also optionally add a specific locale, which is used to indicate the language for the email receipt sent to the buyer.

The primary reason you'll update an existing order is when the buyer changes the payment method or currency they'd like to pay with in the UI that you build. To update the order, make a `PATCH` request to the `/api/2022-06-09/orders/<orderId>` endpoint to make these changes and receive a response with updated payment details. View [API reference here](/api-reference/headless/edit-order).

You can update all of these fields at the same time or individually depending on what makes the most sense for your use case.

### Update the Recipient

First, take a look at how to add the recipient to an existing order. The `requires-recipient` state occurs when you initialize a minimal order and do not include a recipient value. Valid options for the recipient property are `email` or `walletAddress`.

When you set an email recipient, the token will be minted to a Crossmint custodial wallet that can be accessed via [www.crossmint.com](https://www.crossmint.com/) (or [staging.crossmint.com](https://staging.crossmint.com) during testing).

You can update the recipient for an existing order as follows:

`PATCH` `/api/2022-06-09/orders/<orderId>`

```json theme={null}
{
    "recipient": {
        "email": "buyer@example.com"
    }
}
```

OR

```json theme={null}
{
    "recipient": {
        "walletAddress": "0x1234abcd…"
    }
}
```

<Warning>
  The wallet address **must** be compatible with the chain the NFT is on. For example, a Solana NFT requires a Solana
  wallet address and an NFT on an EVM chain requires a compatible EVM wallet address.
</Warning>

### Update Chain and/or Currency

To change details about how the buyer will pay for the NFTs you use the same API route as above and pass a new payment object.

<CodeGroup>
  ```json Crypto Payment theme={null}
  {
      "payment": {
          "method": "ethereum-sepolia",
          "currency": "usdc",
          "payerAddress": "0x1234abcd..."
      }
  }
  ```

  ```json Credit Card Payment theme={null}
  {
      "payment": {
          "method": "card",
          "receiptEmail": "your-email@example.com"
      }
  }
  ```
</CodeGroup>

This will return a new response that can be used to prompt the buyer to complete the crypto payment.

<Note>
  Anytime you update the order you must ensure you use the newly returned `payment.preparation` property to proceed
  with the payment process.
</Note>

### Update the Locale

As mentioned above, the `locale` is used to set the language and currency for the email receipt sent to your buyer. The default is `en-US`.

Below is an example of the body you'd pass to update the locale setting:

```json theme={null}
{
    "locale": "es-ES"
}
```

The available locale values are:

`en-US`, `de-DE`, `es-ES`, `fr-FR`, `it-IT`, `ja-JP`, `ko-KR`, `pt-PT`, `ru-RU` `th-TH` `tr-TR` `uk-UA` `vi-VN` `zh-CN` `zh-TW`, `Klingon`

## Quote Expiration

The time before expiration depends on the payment method chosen. Check the `quote.expiresAt` property to determine how long the quote is valid for. Additionally, the `quote.status` property will be set to `expired` if this timeframe is exceeded.

If your quote has expired you'll need to create a new order.


# Payment Methods
Source: https://docs.crossmint.com/payments/headless/guides/payment-methods

Understand the supported payment methods and how to implement them

## Cross-Chain + Crypto Payments

You can easily create or update an order to receive a price quote, enabling your user to pay with crypto they have on the same chain or even liquidity they have on other chains.

There are several considerations you need to keep in mind when building your app to support cross-chain payments. Some recommendations include the following:

* How to test the process out in staging/testnet and then move to production/mainnet
* Filtering down the list of tokens for which the connected wallet has enough balance to cover the purchase
* Ensuring the wallet is set to the same network as the selected payment chain

Refer to the [Order Lifecycle](/payments/headless/guides/order-lifecycle/quote-phase) docs for details about creating and updating orders based on user selections.

<Check>
  For a full list of supported crypto currencies, refer to the [supported
  currencies](/payments/headless/guides/supported-currencies) page.
</Check>

You'll need to build out a UI that enables your buyer to select from the supported currencies, and then update the existing order upon any changes.

<Note>Code example(s) coming soon!</Note>

## Credit Card Payments

The option of accepting credit card payments via headless checkout is also available. For detailed examples of creating and updating orders, refer to the [Order Lifecycle](/payments/headless/guides/order-lifecycle/quote-phase) docs.

### Test Price Limits and Test Credit Cards

When building your applications using the staging environment, you can use various test credit cards numbers to see the entire process end-to-end, without actually having to transact using a real credit card.
Check out the Testing Tips page for more info on [price limits](/payments/advanced/testing-tips#limits-in-staging) and [test card numbers](/payments/advanced/testing-tips#test-credit-card-numbers).


# Plan Your Solution
Source: https://docs.crossmint.com/payments/headless/guides/plan-your-solution

Detailed integration guide to build out a fully custom digital asset checkout experience

The Headless Checkout suite of APIs offers the most sophisticated tooling available to build fully custom experiences for your users. This guide will walk you through the entire integration process in a logical order. The first step is to take a few minutes to plan out your solution.

## Client or Server Approach

Depending on how your application is architected, you may want to use server-side or client-side API keys. Check out the [client or server guide](/payments/headless/guides/client-or-server) for more info.

## Decide on Payment Methods

The Headless Checkout supports cross-chain crypto payments and credit cards. Decide if you want to enable both credit card and crypto payments, and which cross-chain tokens should be available.

### Cross-Chain Payments

Enable your users to pay for digital assets directly with crypto or with liquidity they have available on other chains by leveraging the cross-chain payments support.

Check the [cross-chain payments](/payments/headless/guides/payment-methods#cross-chain-payments) section for more in-depth guidance.

### Credit Card Payments

You can also use headless checkout to initiate credit card orders for your buyers.

Check the [credit card payments](/payments/headless/guides/payment-methods#credit-card-payments) section for more in-depth guidance.

## Staging or Production

In most cases, it makes sense to start the integration process in the staging environment where all features are available and free to try. You can find more information about [Staging and Production environments here](/introduction/platform/staging-vs-production).

<Check>
  Headless checkout requires enablement by the Customer Success Engineering team in production. [Contact
  Sales](https://www.crossmint.com/contact/sales) if your don't already have a CSE assigned.
</Check>

## Create or Import Your Collection in the Console

For NFTs, you will need to have a collection that your users can purchase NFTs from. You can deploy a collection directly from the Crossmint Developer Console or import a contract you've deployed elsewhere. Check these guides for more details on creating or importing collections.

* [Create a Collection](/payments/guides/create-collection)
* [Import a Collection](/payments/guides/register-collection)

Once you have a collection created or imported, you'll have a `collectionId`, which is necessary to create orders.

## Create Your API Key

With the above steps completed, you're ready to create an API key to use for your project.

1. Login to the developer console where your collection was created in the previous step
2. If you're on the collection detail view, navigate back to the home page of the console
   <Frame type="simple">
     <img alt="how to get back to home page" />
   </Frame>
3. Click the "Integrate" tab and select the "API Keys" section on top

Before creating an API key, you'll need to decide on server-side vs client-side implementation. You can find some more info in the [Client or Server Guide](/payments/headless/guides/client-or-server).

## Next Steps

You're ready to move on to implementing the Headless Checkout in your application!


# Production Launch
Source: https://docs.crossmint.com/payments/headless/guides/production-launch

Follow this checklist to ensure you are ready for production launch with Headless Checkout

## From Staging to Production with Headless Checkout

<Snippet />

***

### Launch Checklist

1. Change all environment URLs from `staging.crossmint.com/api/2022-06-09` to `www.crossmint.com/api/2022-06-09`.
2. Change your API keys to the production versions. *Ensure your production API key has the appropriate scopes enabled, such as `orders.create`, and that all authorized domains and mobile bundle identifiers are properly configured.*
3. Update your collection ID to the production one.
4. As needed, change your passed-in props to be production ready (e.g. email, `payment`, `lineItems`).

<Accordion title="See Code Example">
  <CodeGroup>
    ```javascript {2,6,20} Production theme={null}
    // Using the REST API
    fetch("https://www.crossmint.com/api/2022-06-09/orders", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-key": "YOUR_PROD_API_KEY"
      },
      body: JSON.stringify({
        "recipient": {
          "email": "steve@gmail.com"
        },
        "locale": "en-US",
        "payment": {
          "receiptEmail": "steve@gmail.com",
          "method": "ethereum",
          "currency": "eth",
          "payerAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
        },
        "lineItems": [
          {
            "collectionLocator": "crossmint:YOUR_PROD_COLLECTION_ID",
            "callData": {
              "totalPrice": "0.25",
              "quantity": 1
            }
          }
        ]
      })
    });
    ```

    ```javascript {2,6,20} Staging theme={null}
    // Using the REST API
    fetch("https://staging.crossmint.com/api/2022-06-09/orders", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-key": "YOUR_STAGING_API_KEY"
      },
      body: JSON.stringify({
        "recipient": {
          "email": "test@crossmint.com"
        },
        "locale": "en-US",
        "payment": {
          "receiptEmail": "test@crossmint.com",
          "method": "ethereum-sepolia",
          "currency": "eth",
          "payerAddress": "0x1234_payer_address"
        },
        "lineItems": [
          {
            "collectionLocator": "crossmint:YOUR_STAGING_COLLECTION_ID",
            "callData": {
              "totalPrice": "0.001",
              "quantity": 1
            }
          }
        ]
      })
    });
    ```
  </CodeGroup>
</Accordion>


# Specify Recipient
Source: https://docs.crossmint.com/payments/headless/guides/specify-recipient

Select where purchased items should be delivered in Headless Checkout

<Snippet />

## Specifying the Recipient

For Headless Checkout, you specify the recipient when creating or updating an order.

### Recipient by Email

When specifying a recipient by email, Crossmint will automatically create a secure custodial wallet on the fly for that email address:

<Tabs>
  <Tab title="Create Order">
    ```json {4} theme={null}
    POST /api/2022-06-09/orders
    {
      "recipient": {
        "email": "user@example.com" // Email address of the recipient
      },
      "locale": "en-US",
      "payment": {
        "method": "ethereum-sepolia",
        "currency": "eth",
        "payerAddress": "0x1234abcd...",
        "receiptEmail": "user@example.com"
      },
      "lineItems": [
        {
          "collectionLocator": "crossmint:cosdahdasda",
          "callData": {
            "totalPrice": "0.0001",
            "quantity": 1
          }
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Edit Order">
    ```json {4} theme={null}
    PATCH /api/2022-06-09/orders/{orderId}
    {
      "recipient": {
        "email": "user@example.com" // Email address of the recipient
      }
    }
    ```
  </Tab>
</Tabs>

The recipient will be able to access their purchased items by logging into their Crossmint wallet in [staging](https://staging.crossmint.com/user/collection) or [mainnet](https://www.crossmint.com/user/collection).

### Recipient by Wallet Address

To deliver items directly to a specific blockchain wallet address:

<Tabs>
  <Tab title="Create Order">
    <CodeGroup>
      ```json {4} EVM theme={null}
      POST /api/2022-06-09/orders
      {
        "recipient": {
          "walletAddress": "0x1234567890abcdef1234567890abcdef12345678" // For EVM chains
        },
        "locale": "en-US",
        "payment": {
          "method": "ethereum-sepolia",
          "currency": "eth",
          "payerAddress": "0x1234abcd...",
          "receiptEmail": "user@example.com" // Optional — recommended when using wallet address
        },
        "lineItems": [
          {
            "collectionLocator": "crossmint:_YOUR_EVM_COLLECTION_",
            "callData": {
              "totalPrice": "0.0001",
              "quantity": 1
            }
          }
        ]
      }
      ```

      ```json {4} Solana theme={null}
      POST /api/2022-06-09/orders
      {
        "recipient": {
          "walletAddress": "5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty" // For Solana
        },
        "locale": "en-US",
        "payment": {
          "method": "solana",
          "currency": "sol",
          "payerAddress": "5FHne...",
          "receiptEmail": "user@example.com" // Optional — recommended when using wallet address
        },
        "lineItems": [
          {
            "collectionLocator": "crossmint:_YOUR_SOLANA_COLLECTION_",
            "callData": {
              "totalPrice": "0.0001",
              "quantity": 1
            }
          }
        ]
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Edit Order">
    <CodeGroup>
      ```json {4} EVM theme={null}
      PATCH /api/2022-06-09/orders/{orderId}
      {
        "recipient": {
          "walletAddress": "0x1234567890abcdef1234567890abcdef12345678" // For EVM chains
        }
      }
      ```

      ```json {4} Solana theme={null}
      PATCH /api/2022-06-09/orders/{orderId}
      {
        "recipient": {
          "walletAddress": "5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty" // For Solana
        }
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>

<Note>
  If specifying a recipient by wallet address, ensure the address is valid for the chain your collection is on, which
  may differ from the chain the payment is performed on.
</Note>


# Status Codes
Source: https://docs.crossmint.com/payments/headless/guides/status-codes

Guide to understanding the status codes returned from the Headless Checkout APIs

Crossmint's headless checkout includes status codes for multiple aspects of the checkout process. Using status codes lets you build detailed user experiences and UIs that inform about the status of the payment process and delivery of their purchase.

There is the top level `order.phase` and then there are sub-statuses for `quote`, `payment`, and `delivery`.

## Quote statuses

* `item-unavailable` — No items in the order are available for purchase at the current time
* `valid` — The quote is valid
* `expired` — The quote has expired and needs to be refreshed
* `requires-recipient` — The order is missing recipient information (email or wallet address)

## Payment statuses

* `draft` — The order was created with `state: "draft"`. It is a quote preview only: not persisted, and it cannot be polled or paid
* `requires-quote` — The order is still in the quote phase
* `requires-crypto-payer-address` — A crypto wallet address needs to be provided for the payment
* `requires-email` — An email is required to proceed (typically for card payments or receipts)
* `requires-kyc` — The buyer must complete KYC verification to proceed
* `manual-kyc` — KYC requires manual review; the buyer will be notified of the outcome
* `failed-kyc` — KYC verification failed and the buyer cannot proceed
* `crypto-payer-insufficient-funds` — The specified payer address cannot cover the purchase
* `crypto-payer-insufficient-funds-for-gas` — The payer address cannot cover the required network fees
* `awaiting-payment` — Ready to submit the payment
* `in-progress` — The payment is underway
* `completed` — Payment completed; the order proceeds to delivery/completion

<Note>
  Payment statuses describe where the payment is in its lifecycle. When a card payment is declined, the order also
  carries a `payment.failureReason` object with a normalized error code, category, and retry policy. Those are
  documented separately in the [Payment Error Codes](/payments/api-reference/error-codes) reference.
</Note>

## Delivery statuses

* `draft` — The order is a draft (`state: "draft"`); nothing will be delivered until the order is created for real
* `awaiting-payment` — Delivery not started because payment is not yet complete
* `in-progress` — Delivery is being processed
* `failed` — Delivery failed; affected items will be refunded automatically
* `completed` — Delivery completed successfully


# Supporting Your Customers
Source: https://docs.crossmint.com/payments/headless/guides/supporting-your-customers

Support your customers facing issues with the checkout process

As an enterprise working with Crossmint, you receive priority customer support. Consequently, customer issues can be escalated to the Crossmint team.

## Information to pass onto Crossmint

When escalating customer issues to the Crossmint team, please ensure to pass on the following details, as it makes troubleshooting easier:

* **Email Address**: The email address they are using to purchase the digital asset.
* **Website URL**: The URL of the website they are trying to purchase the digital asset from.
* **Order Id**: The Order Id of the initiated payment.
* **Collection Id**: The Collection Id of the collection on Crossmint.
* **Project Id**: The Project Id of the project on Crossmint.
* **Payment error code**: The `payment.failureReason.code` on the order, if the payment was declined. See the [Payment Error Codes](/payments/api-reference/error-codes) reference for what each code means and the recommended next step.

## Additional items to check

* You can review the **Orders tab** to check the status of the checkout.
* If you are the dev reporting the error, please share the sample code as well.

<Tip>
  If nothing works and you are unable to troubleshoot the issue, you can redirect them to Crossmint's support
  [here](https://help.crossmint.com/hc/en-us/requests/new/?utm_source=docs).
</Tip>


# Overview
Source: https://docs.crossmint.com/payments/headless/overview

Create fully custom checkout experiences

For general information about Crossmint's Payments product, see the [introduction](/payments/introduction). This guide will focus on the features specific to the headless checkout.

## When is the Headless Checkout the best fit?

* **You want to build the entire user experience**
* **You want to use Crossmint checkout outside of a browser environment** (e.g. native mobile app, game, VR headset, etc.)
* **You are okay spending more time developing your own UX**

## Introduction

Crossmint's headless checkout API is a set of REST APIs that allow you to integrate credit card and cross-chain crypto payments inside your app with full control of the user experience.

It is the most customizable version of the Crossmint suite of payments products, which allows anyone to buy digital assets with familiar payment methods (credit card, crypto on any chain independent on where the asset lives) with the same backend, but allowing full UI customizability and deep integration with your app's UX.

<Tabs>
  <Tab title="In-app purchases">
    <Frame type="simple">
      <img alt="In-app purchases example" />
    </Frame>
  </Tab>

  <Tab title="Ticketing solutions">
    <Frame type="simple">
      <img alt="Ticketing solutions example" />
    </Frame>
  </Tab>

  <Tab title="Custom web3app UIs">
    <Frame type="simple">
      <img alt="Custom web3app UI example" />
    </Frame>
  </Tab>

  <Tab title="and many more...">
    <div>Wherever your imagination takes you...</div>
  </Tab>
</Tabs>

## Get Started

<CardGroup>
  <Card title="Pay with Crypto Quickstart" icon="hive" href="/payments/headless/quickstarts/crypto">
    Build a custom Pay with Crypto checkout experience for your digital assets
  </Card>

  <Card title="Pay with Card - NFT - Quickstart" icon="bolt" href="/payments/headless/quickstarts/credit-card-nft">
    Build a custom credit-card checkout experience
  </Card>

  <Card title="Pay with USDC Quickstart" icon="circle-dollar" href="/payments/headless/quickstarts/paying-usdc">
    Build a USDC checkout in 5 minutes (great for AI agents)
  </Card>

  <Card title="Pay for Card - Memecoins - Quickstart" icon="coin-front" href="/payments/headless/quickstarts/credit-card-memecoin-cko">
    Sell memecoins quickly with a credit card checkout
  </Card>
</CardGroup>

<Card title="Talk to an expert" icon="message" href="https://www.crossmint.com/contact/sales">
  Contact our sales team for advanced support.
</Card>

## Advanced Topics

<CardGroup>
  <Card title="Marketplaces & Launchpads" icon="cart-shopping" href="/payments/advanced/marketplaces-and-launchpads" />

  <Card title="Headless Status Codes" icon="temperature-empty" href="/payments/headless/guides/status-codes" />

  <Card title="Bring your own Collection" icon="file-import" href="/payments/guides/register-collection" />

  <Card title="Webhooks" icon="bars-progress" href="/payments/advanced/webhooks" />
</CardGroup>


# Pay with Card - Memecoins
Source: https://docs.crossmint.com/payments/headless/quickstarts/credit-card-memecoin-cko

Create a fully customized memecoin checkout experience that accepts credit cards

<Snippet />

## Introduction

This guide will show you how to accept credit card payments using Crossmint's Headless Checkout API for memecoin sales. You'll learn how to:

* Set up credit card payments for Solana memecoin purchases in JavaScript
* Implement a checkout UI
* Track order status and delivery

<Tip>
  For a faster, embedded checkout solution with minimal setup time, see our [embedded memecoin
  quickstart](/payments/embedded/quickstarts/credit-card-memecoin).
</Tip>

<Snippet />

<Snippet />

<Snippet />

## Headless Memecoin Checkout

The headless checkout API allows complete control over your checkout experience, including:

* Custom UI components and styling
* Custom checkout sequences
* Integrated analytics and tracking
* Custom error handling and retry logic
* Branded confirmation pages

### Create an Order

The first step in the headless checkout process is to create an order. An order is an object datastructure that represents an intent to purchase in Crossmint's systems. This guide will create a basic order, and then update it with required info step-by-step.

<Note>
  You can also create the entire order in one API call if the necessary information is available at the time of order
  creation. This can be used for custom "one-click-checkout" experiences, should you wish to make them.
</Note>

**Endpoint:** `POST` `https://www.crossmint.com/api/2022-06-09/orders`

Refer to the complete **create order** API reference [here](/api-reference/headless/create-order).

<Note>
  Memecoins are now testable in staging using the xmeme token (`7EivYFyNfgGj8xbUymR7J4LuxUHLKRzpLaERHLvi7Dgu`). All
  other token purchases will fail in staging. For production launch with other tokens, <a href="https://www.crossmint.com/contact/sales">contact the Crossmint sales team</a> — production Checkout requires a signed Order Form and successful KYB. See the [production launch guide](/payments/headless/guides/production-launch) for the full sequence.
</Note>

Use the JavaScript code snippet below to create a starting point for your order. Alternatively, use the API playground to explore and create your own order.

<CodeGroup>
  ```javascript Node.js theme={null}
  const apiKey = "your-server-api-key"; // CHANGE THIS TO YOUR SERVER API KEY
  const tokenId = "solana:7EivYFyNfgGj8xbUymR7J4LuxUHLKRzpLaERHLvi7Dgu"; // xmeme token for staging
  const deliveryAddress = "your-solana-wallet-address"; // CHANGE THIS TO YOUR RECEIVING SOLANA WALLET ADDRESS
  const receiptEmail = "your-email@example.com"; // CHANGE THIS TO YOUR EMAIL

  const options = {
      method: "POST",
      headers: {
          "x-api-key": apiKey,
          "Content-Type": "application/json",
      },
      body: JSON.stringify({
          lineItems: [
              {
                  tokenLocator: tokenId, // Token address in format solana:tokenAddress (e.g., solana:7EivYFyNfgGj8xbUymR7J4LuxUHLKRzpLaERHLvi7Dgu for xmeme token)
                  executionParameters: {
                      mode: "exact-in", // The execution method for the order. It tells Crossmint to operate in buying fungibles mode
                      amount: "1", // default currency USD
                      maxSlippageBps: "500", // Optional, or else default autogenerated slippage will be applied
                  },
              },
          ],
          payment: {
              method: "card",
              receiptEmail: receiptEmail,
          },
          recipient: {
              walletAddress: deliveryAddress,
          },
      }),
  };

  fetch("https://staging.crossmint.com/api/2022-06-09/orders", options)
      .then((response) => response.json())
      .then((response) => console.log(JSON.stringify(response, null, 2)))
      .catch((err) => console.error(err));
  ```

  ```json JSON theme={null}
  {
      "lineItems": [
          {
              "tokenLocator": "solana:tokenAddress",
              "executionParameters": {
                  "mode": "exact-in",
                  "amount": "1",
                  "maxSlippageBps": "500"
              }
          }
      ],
      "payment": {
          "method": "card",
          "receiptEmail": "receiptEmail"
      },
      "recipient": {
          "walletAddress": "deliveryAddress"
      }
  }
  ```

  For more details on tokenLocator formatting and other item selection options, see the [item selection page](/payments/headless/guides/item-selection#json-item-selection-examples).
</CodeGroup>

<Accordion title="Example Response">
  ```json theme={null}
  {
    "clientSecret": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvcmRlcklkZW50aWZpZXIiOiJlZDM0YTU3OS03ZmJjLTQ1MDktYjhkOC05ZTYxOTU0Y2Q1NTUiLCJpYXQiOjE3Mzk0MDI3NjEsImV4cCI6MTczOTQ4OTE2MX0.8AU0Y31lJhnQD2-vAXEZp3ZeMSyh_Wdm9An02Z5AW0M",
    "order": {
      "orderId": "ed34a579-7fbc-4509-b8d8-9e61954cd555",
      "phase": "payment",
      "locale": "en-US",
      "lineItems": [
        {
          "chain": "solana",
          "metadata": {
            "name": "xmeme",
            "description": "Token xmeme from the contract: 7EivYFyNfgGj8xbUymR7J4LuxUHLKRzpLaERHLvi7Dgu",
            "imageUrl": "https://arweave.net/VQrPjACwnQRmxdKBTqNwPiyo65x7LAT773t8Kd7YBzw"
          },
          "quote": {
            "status": "valid",
            "charges": {
              "unit": {
                "amount": "35.73",
                "currency": "usd"
              }
            },
            "totalPrice": {
              "amount": "1",
              "currency": "usd"
            },
            "quantityRange": {
              "lowerBound": "0.0265905",
              "upperBound": "0.0293895"
            }
          },
          "delivery": {
            "status": "awaiting-payment",
            "recipient": {
              "locator": "solana:BuWmGweapdysxU5VuUdi1RGoc4ibDG7TNirWjRtqF995",
              "walletAddress": "your-solana-wallet-address"
            }
          },
          "executionMode": "exact-in",
          "maxSlippageBps": "500",
          "executionParams": {
            "mintHash": "7EivYFyNfgGj8xbUymR7J4LuxUHLKRzpLaERHLvi7Dgu",
            "mode": "exact-in",
            "amount": "1",
            "maxSlippageBps": "500"
          }
        }
      ],
      "quote": {
        "status": "valid",
        "quotedAt": "2025-02-12T23:26:00.397Z",
        "expiresAt": "2025-02-12T23:26:30.397Z",
        "totalPrice": {
          "amount": "1",
          "currency": "usd"
        }
      },
      "payment": {
        "status": "awaiting-payment",
        "method": "basis-theory",
        "currency": "usd",
        "preparation": {},
        "receiptEmail": "test@example.com"
      }
    }
  }
  ```
</Accordion>

Note the following parameters in the request body:

* `maxSlippageBps`: Optional, or else default autogenerated slippage will be applied
* `receiptEmail`: Optional. If the buyer pays with Apple Pay or Google Pay, Crossmint obtains the email automatically. Providing it improves fraud signal quality.
* `executionParameters.mode`: The execution method for the order. "exact-out" is for NFTs, "exact-in" is for fungible tokens

### Render the Crossmint Embedded Component

After creating an order, you'll need to render the Crossmint Embedded Component to collect payment information. This secure, embeddable UI component lets you accept payment methods, validates input, and handles errors:

```javascript theme={null}
import { CrossmintEmbeddedCheckout, CrossmintProvider } from "@crossmint/client-sdk-react-ui";

export function MyCheckoutPage({ clientSecret, order, recipientWalletAddress, receiptEmail }) {
  return (
    <div className="w-full">
      <CrossmintProvider apiKey="<YOUR CLIENT SIDE KEY>">
        <CrossmintEmbeddedCheckout 
          recipient={{ walletAddress: recipientWalletAddress}}
          clientSecret={clientSecret}
          orderId={order.orderId}
          payment={{
            crypto: {
                enabled: false,
            },
            fiat: {
                enabled: true,
            },
            defaultMethod: "fiat",
            receiptEmail: receiptEmail,
          }}
          appearance={{
              rules: {
                  DestinationInput: {
                      display: "hidden",
                  },
                  ReceiptEmailInput: {
                      display: "hidden",
                  },
              },
          }} />
      </CrossmintProvider>
    </div>
  );
}
```

<Tip>
  The `CrossmintEmbeddedCheckout` component is highly customizable. You can adjust colors, styling, layout, and behavior to match your brand. Learn more in our [UI customization guide](/payments/embedded/guides/ui-customization).
</Tip>

### Poll for Status Updates

After making the payment, you'll need to poll the [Get Order API](/api-reference/headless/get-order) to check on the delivery status and present this information to your user.

**Endpoint:** `GET` `https://staging.crossmint.com/api/2022-06-09/orders/<orderId>`

Refer to the complete **get order** API reference [here](/api-reference/headless/get-order).

**Example Response:**

```json theme={null}
{
    "id": "order_xyz",
    "status": "completed",
    "phases": {
        "quote": { "status": "completed" },
        "payment": { "status": "completed" },
        "delivery": { "status": "completed", "details": "Memecoins delivered to specified wallet" }
    }
}
```

### Handling Refunded Payments

When polling for order status, you may encounter a situation where `payment.status` is `completed` but the order also contains a `payment.refunded` property. This indicates that the payment was initially successful but has since been refunded.

```json theme={null}
{
    "order": {
        "payment": {
            "status": "completed",
            "refunded": {
                "amount": "1.00",
                "currency": "usd",
                "txId": "0x1234abcd...",
                "chain": "ethereum"
            }
        }
    }
}
```

The `payment.refunded` object includes the following fields:

* `amount`: The amount that was refunded
* `currency`: The currency of the refund
* `txId`: The on-chain transaction ID the refund was sent in
* `chain`: The blockchain where the refund transaction occurred

When you encounter this state, your application should:

1. Display an appropriate message to the user indicating that their payment was refunded
2. Provide the transaction ID (`txId`) so users can verify the refund on-chain
3. Prevent any further actions related to the order (such as delivery expectations)
4. Provide options for the user to place a new order if desired

This state typically occurs when there was an issue with processing the order after payment was received, such as insufficient liquidity for memecoin purchases or compliance issues.

🎉 Congratulations! You've successfully set up your headless memecoin checkout. Check out the [Next Steps](#next-steps) section below to learn how to customize your integration.

<Snippet />

## Next Steps

<CardGroup>
  <Card title="Design Your UI" icon="paintbrush" href="/payments/headless/guides/design-your-ui">
    Learn how to design your headless checkout experience
  </Card>

  <Card title="Handle Webhooks" icon="bell" href="/payments/advanced/webhooks">
    Implement webhook handling for order updates
  </Card>
</CardGroup>

<Snippet />

## Refreshing Orders

For memecoin checkout, the order expiration is 1 minute. The Crossmint Embedded Checkout will automatically refresh the order for you when the time comes. Alternatively, you can either create a new order or use the refresh quote API:

```javascript theme={null}
async refreshOrder(orderId, clientSecret) {
  try {
    const ancestorOrigins = typeof window !== 'undefined' && window.location?.ancestorOrigins
      ? Array.from(window.location.ancestorOrigins)
      : [];

    const response = await this.callApi(`2022-06-09/orders/${orderId}/refresh`, "POST", {}, {
      "authorization": `${clientSecret}`,
      "x-ancestor-origins": JSON.stringify(ancestorOrigins)
    });

    const parsed = await response.json();
    return parsed;
  } catch (error) {
    console.error("Error refreshing quote:", error);
    throw error;
  }
}
```

<Snippet />


# Pay with Card - NFTs
Source: https://docs.crossmint.com/payments/headless/quickstarts/credit-card-nft

Create a fully customized checkout experience with credit cards.

<Snippet />

## Introduction

In this quickstart you'll learn how to accept credit card payments (including Apple and Google Pay) using Crossmint's headless APIs to purchase an NFT on the `polygon-amoy` testnet

## Prerequisites

<Snippet />

## Integration Steps

<Snippet />

### 1. Create an Order

<Snippet />

```json theme={null}
{
    "payment": {
        "method": "card",
    },
    "lineItems": [
        {
            "collectionLocator": "crossmint:<collectionId>", // Use the collectionId you created in the Prerequisites section
            "callData": {
                "totalPrice": "0.0001"
            }
        }
    ]
}
```

<Accordion title="Example Response">
  ```json theme={null}
  {
    "clientSecret": "_removed_",
    "order": {
      "orderId": "cc40e6af-f8dc-4ac2-8e26-d91a32f271cf",
      "phase": "quote",
      "locale": "en-US",
      "lineItems": [
        {
          "chain": "polygon-amoy",
          "quantity": 1,
          "callData": {
            "quantity": 1
          },
          "metadata": {
            "name": "Headless Demo",
            "description": "NFT Checkout Demo",
            "imageUrl": "https://utfs.io/f/cd8545b7-3410-4fcd-988d-cd11951ed53c-g287ok.png"
          },
          "quote": {
            "status": "requires-recipient",
            "charges": {
              "unit": {
                "amount": "0.000169004",
                "currency": "eth"
              }
            },
            "totalPrice": {
              "amount": "0.000169004",
              "currency": "eth"
            }
          },
          "delivery": {
            "status": "awaiting-payment"
          }
        }
      ],
      "quote": {
        "status": "requires-recipient",
        "quotedAt": "_DATE_",
        "expiresAt": "_DATE_",
        "totalPrice": {
          "amount": "0.000169004",
          "currency": "eth"
        }
      },
      "payment": {
        "status": "requires-quote",
        "method": "basis-theory",
        "preparation": {},
      }
    }
  }
  ```
</Accordion>

<Snippet />

### 2. Update the Order with Recipient

<Snippet />

<Warning>
  Legally, for card payments, **an email *must* be specified** in order to deliver a receipt to your user, either in
  `recipient.email` or in `payment.receiptEmail`. If one is not specified, the API will not return the fields
  necessary to collect the user's payment.
</Warning>

<Tabs>
  <Tab title="Email recipient">
    ```json theme={null}
    {
        "recipient": {
            "email": "test@example.com"
        }
    }
    ```
  </Tab>

  <Tab title="Wallet recipient with receipt email">
    ```json theme={null}
    {
        "recipient": {
            "walletAddress": "0xabcd1234..."
        },
        "payment": {
            "method": "card", // When updating the payment, you must pass the complete object
            "receiptEmail": "test@example.com"
        }
    }
    ```
  </Tab>
</Tabs>

### 3. Render the Crossmint Embedded Component

After creating an order, you'll need to render the Crossmint Embedded Component to collect payment information. This secure, embeddable UI component lets you accept payment methods, validates input, and handles errors:

```tsx theme={null}
import { CrossmintEmbeddedCheckout, CrossmintProvider } from "@crossmint/client-sdk-react-ui";

export function MyCheckoutPage({ clientSecret, order, recipientWalletAddress, receiptEmail }) {
  return (
    <div className="w-full">
      <CrossmintProvider apiKey="<YOUR CLIENT SIDE KEY>">
        <CrossmintEmbeddedCheckout 
          recipient={{ walletAddress: recipientWalletAddress}}
          clientSecret={clientSecret}
          orderId={order.orderId}
          payment={{
            crypto: {
                enabled: false,
            },
            fiat: {
                enabled: true,
            },
            defaultMethod: "fiat",
            receiptEmail: receiptEmail,
          }}
          appearance={{
              rules: {
                  DestinationInput: {
                      display: "hidden",
                  },
                  ReceiptEmailInput: {
                      display: "hidden",
                  },
              },
          }} />
      </CrossmintProvider>
    </div>
  );
}
```

<Tip>
  The `CrossmintEmbeddedCheckout` component is highly customizable. You can adjust colors, styling, layout, and behavior to match your brand. Learn more in our [UI customization guide](/payments/embedded/guides/ui-customization).
</Tip>

### 4. Poll for Status Updates

<Snippet />

## Next Steps

<Snippet />


# Pay with Other Crypto
Source: https://docs.crossmint.com/payments/headless/quickstarts/crypto

Create a fully customized checkout experience with crypto payments.

## Introduction

In this quickstart you'll learn how to accept multiple different cryptocurrencies as payment using Crossmint's headless APIs, to purchase an NFT on the `polygon-amoy` testnet.

## Prerequisites

<Snippet />

If you are choosing to do this quickstart in your own console or IDE, consider you will need to have a way to prompt and sign crypto payments, like using Metamask.

### External Prerequisites

* Your crypto wallet of choice - Metamask, Coinbase Wallet, etc.
* A small balance of testnet currency in whichever cryptocurrency you would like to pay with
  * [Ethereum, Base, Polygon](https://www.alchemy.com/faucets) - note that some of these faucets require a minimum of 0.1 ETH on mainnet, to prevent abuse
  * [Solana devnet](https://solana.com/developers/guides/getstarted/solana-token-airdrop-and-faucets)

## Integration Steps

This quickstart will primarily focus on the API calls necessary to implement headless checkout in your project. You will also need to build out the frontend experience for your users.

### 1. Create an Order

<Snippet />

<Tabs>
  <Tab title="Pay with ETH">
    ```json theme={null}
    {
        "payment": {
            "method": "base-sepolia",
            "currency": "eth",
            "payerAddress": "0xabcd1234..."
        },
        "lineItems": [
            {
                "collectionLocator": "crossmint:<collectionId>",
                "callData": {
                    "totalPrice": "0.0001"
                }
            }
        ]
    }
    ```
  </Tab>

  <Tab title="Pay with ERC20s">
    ```json theme={null}
    {
        "payment": {
            "method": "base-sepolia",
            "currency": "usdc" | "degen" | "brett" | ... ,
            "payerAddress": "0xabcd1234..."
        },
        "lineItems": [
            {
                "collectionLocator": "crossmint:<collectionId>",
                "callData": {
                    "totalPrice": "0.0001"
                }
            }
        ]
    }
    ```
  </Tab>

  <Tab title="Pay with SOL">
    ```json theme={null}
    {
        "payment": {
            "method": "solana",
            "currency": "sol",
            "payerAddress": "7NxpS1cMZ8..."
        },
        "lineItems": [
            {
                "collectionLocator": "crossmint:<collectionId>",
                "callData": {
                    "totalPrice": "0.0001"
                }
            }
        ]
    }
    ```
  </Tab>

  <Tab title="Pay with SPLs">
    ```json theme={null}
    {
        "payment": {
            "method": "solana",
            "currency": "usdc" | "bonk" | ... ,
            "payerAddress": "7NxpS1cMZ8..."
        },
        "lineItems": [
            {
                "collectionLocator": "crossmint:<collectionId>",
                "callData": {
                    "totalPrice": "0.0001"
                }
            }
        ]
    }
    ```
  </Tab>

  <Tab title="Pay with MATIC">
    ```json theme={null}
    {
        "payment": {
            "method": "polygon-amoy",
            "currency": "matic",
            "payerAddress": "0xabcd1234..."
        },
        "lineItems": [
            {
                "collectionLocator": "crossmint:<collectionId>",
                "callData": {
                    "totalPrice": "0.0001"
                }
            }
        ]
    }
    ```
  </Tab>
</Tabs>

<Accordion title="Example Response">
  ```json theme={null}
  {
    "clientSecret": "_removed_",
    "order": {
      "orderId": "cc40e6af-f8dc-4ac2-8e26-d91a32f271cf",
      "phase": "quote",
      "locale": "en-US",
      "lineItems": [
        {
          "chain": "polygon-amoy",
          "quantity": 1,
          "callData": {
            "quantity": 1
          },
          "metadata": {
            "name": "Headless Demo",
            "description": "NFT Checkout Demo",
            "imageUrl": "https://utfs.io/f/cd8545b7-3410-4fcd-988d-cd11951ed53c-g287ok.png"
          },
          "quote": {
            "status": "requires-recipient",
            "charges": {
              "unit": {
                "amount": "0.000169004",
                "currency": "eth"
              }
            },
            "totalPrice": {
              "amount": "0.000169004",
              "currency": "eth"
            }
          },
          "delivery": {
            "status": "awaiting-payment"
          }
        }
      ],
      "quote": {
        "status": "requires-recipient",
        "quotedAt": "_DATE_",
        "expiresAt": "_DATE_",
        "totalPrice": {
          "amount": "0.000169004",
          "currency": "eth"
        }
      },
      "payment": {
        "status": "requires-quote"
      }
    }
  }
  ```
</Accordion>

<Note>
  In the requests above the `payerAddress` has been included, however if your user has not yet connected their wallet
  you may omit this field, allow them to connect their wallet after creating the order, and submit the `payerAddress`
  at a later time.
</Note>

<Snippet />

### 2. Update the Order with Recipient

<Snippet />

<Tabs>
  <Tab title="Email recipient">
    ```json theme={null}
    {
        "recipient": {
            "email": "test@example.com"
        }
    }
    ```
  </Tab>

  <Tab title="Wallet recipient">
    ```json theme={null}
    {
        "recipient": {
            "walletAddress": "0xabcd1234..."
        }
    }
    ```
  </Tab>
</Tabs>

<Note>
  Notice you only need to pass the object that your are updating, in this case, `recipient`. You can also update
  multiple properties in the same call. Available properties for update include `recipient`, `locale`, and the
  `payment` object.
</Note>

<Note>
  If specifying a recipient by wallet address, ensure the address is valid for the chain your **collection** is on,
  which may differ from the chain the **payment is being performed** on.
</Note>

<Accordion title="Example Response">
  ```json theme={null}
  {
    "orderId": "cc40e6af-f8dc-4ac2-8e26-d91a32f271cf",
    "phase": "payment",
    "locale": "en-US",
    "lineItems": [
      {
        "chain": "polygon-amoy",
        "quantity": 1,
        "callData": {
          "quantity": 1
        },
        "metadata": {
          "name": "Headless Demo",
          "description": "NFT Checkout Demo",
          "imageUrl": "https://utfs.io/f/cd8545b7-3410-4fcd-988d-cd11951ed53c-g287ok.png"
        },
        "quote": {
          "status": "valid",
          "charges": {
            "unit": {
              "amount": "0.0001681558",
              "currency": "eth"
            }
          },
          "totalPrice": {
            "amount": "0.0001681558",
            "currency": "eth"
          }
        },
        "delivery": {
          "status": "awaiting-payment"
        }
      }
    ],
    "payment": {
      "status": "awaiting-payment",
      "preparation": {
        "method": "crypto",
        "chain": "base-sepolia",
        "payerAddress": "0x6C3b3225759Cbda68F96378A9F0277B4374f9F06",
        "serializedTransaction": "0x02f9012683aa36a744848917370085080992ce6c82629c94a105c311fa72b8fb78c992ecbdb8b02ea5bd394d869a9d359ca000b8f465794a68624763694f694a49557a49314e694973496e523563434936496b705856434a392e65794a756232356a5a534936496a4d3559544e6d4d444d334c544d7a4e6d51744e4441305a5331684d6a45774c575268593249335957526b5a4456694e794973496d39795a4756795357526c626e52705a6d6c6c63694936496d4e6a4e44426c4e6d466d4c5759345a474d744e47466a4d6930345a5449324c5751354d57457a4d6d59794e7a466a5a694973496d6c68644349364d5463784e546b334f54557a4e33302e662d4949646c653375314c58634c7845765438754e336d74786370764a686f31384a5a4b76483768456659c0"
      }
    }
  }
  ```

  <Warning>
    Notice at the bottom, the new `serializedTransaction` property. This is a unique identifier let's Crossmint know exactly which order you are updating.
    Anytime you update an order you ***must*** use the returned `serializedTransaction` property.
  </Warning>
</Accordion>

### 3. Show Purchase Preview to User

Now, after you've told Crossmint systems what you want, and you have passed a valid place to send the NFT, Crossmint will return a quote with prices for the desired items
Within the returned response, you'll find the `lineItems` array which contains the metadata and a quote for each line item. Within a quote, a detailed breakdown of its charges can be found.

<Tabs>
  <Tab title="Preview Screenshot">
    <Frame type="simple">
      <img alt="preview purchase screenshot" />
    </Frame>
  </Tab>

  <Tab title="Code Example">
    <Note>
      If you are developing in an IDE or in terminal, the returned `lineitems` may be stuck in an \[Object], or be in a
      hard-to-understand object format. You can make this human-readable for yourself by adding `JSON.stringify(response)`
    </Note>

    ```jsx theme={null}
    <div class="flex flex-col justify-start w-full mb-5 item">
        <div class="flex w-full items-center justify-start border-b border-[#E7E9ED] py-2">
            <div class="flex items-center justify-between w-full">
                <div class="flex items-center">
                    <img src="{order.lineItems[0].metadata.image}" class="flex w-10 h-10 mr-4 rounded-md" />
                    <div class="flex flex-col items-start justify-start">
                        <h3 class="font-medium">{order.lineItems[0].metadata.name}</h3>
                        <p class="text-sm text-text-secondary">{order.lineItems[0].metadata.description.slice(0, 20)}</p>
                    </div>
                </div>
                <div class="flex flex-col">
                    <p>Unit: {order.lineItems[0].quote.charges["unit"].amount}</p>
                    <p>Gas: {order.lineItems[0].quote.charges?.["gas"]?.amount}</p> // Gas charge may not be defined, depending
                    on the collection's chain
                </div>
            </div>
        </div>
        <div class="flex w-full flex-col items-center justify-start gap-y-0.5 pt-2">
            <div class="flex items-center justify-between w-full">
                <p class="text-sm font-medium text-text-primary">Total price</p>
                <span class="text-sm font-medium text-text-primary">
                    {order.quote.totalPrice.amount} {order.quote.totalPrice.currency}
                </span>
            </div>
        </div>
    </div>
    ```
  </Tab>

  <Tab title="lineItems Example">
    ```json theme={null}
    {
        // some properties removed for brevity
        "order": {
            "lineItems": [
                {
                    "chain": "polygon-amoy",
                    "quantity": 1,
                    "callData": {
                        "quantity": 1
                    },
                    "metadata": {
                        "name": "Headless Demo",
                        "description": "NFT Checkout Demo",
                        "imageUrl": "https://utfs.io/f/cd8545b7-3410-4fcd-988d-cd11951ed53c-g287ok.png"
                    },
                    "quote": {
                        "status": "valid",
                        "charges": {
                            "unit": {
                                "amount": "0.000169004",
                                "currency": "eth"
                            }
                        },
                        "totalPrice": {
                            "amount": "0.000169004",
                            "currency": "eth"
                        }
                    },
                    "delivery": {
                        "status": "awaiting-payment"
                    }
                }
            ]
        }
    }
    ```
  </Tab>
</Tabs>

### 4. Request Payment from User

You now need to request crypto payment from the user.

You will use the `serializedTransaction` returned in the purchase preview from the previous step. The `serializedTransaction` needs to be structured into a transaction object, which can then be passed to a crypto payment prompter, like viem's `sendTransaction` or wagmi's `sendTransactionAsync`.

Whichever method you use, it should open the user's default wallet extension in the browser and allow the user to complete the cross-chain payment.

<Check>
  If you've followed along this far you can simply paste the `serializedTransaction` property returned in your
  previous API call into the app below. This will allow you to sign and send the transaction.
</Check>

<Tabs>
  <Tab title="Send EVM Payment">
    <Frame type="simple">
      <iframe />
    </Frame>
  </Tab>

  <Tab title="Send Solana Payment">
    <Warning>
      Ensure your wallet is connected to the **devnet** network, otherwise your funds may be lost!
    </Warning>

    <Frame type="simple">
      <iframe />
    </Frame>
  </Tab>

  <Tab title="Code Example">
    ```tsx theme={null}
    "use client";

    import { ConnectButton } from "@rainbow-me/rainbowkit";
    import { useState } from "react";
    import { parseTransaction } from "viem"; // Refer to their documentation details to make viem work for your needs
    import { useSendTransaction } from "wagmi"; // Refer to their documentation details to make wagmi work for your needs

    export default function Home() {
        const { data: hash, isPending, sendTransactionAsync } = useSendTransaction();

        const signAndSendTransaction = async () => {
            const serializedTxn = "0x_your_serialized_transaction_response";
            const txn = parseTransaction(serializedTxn || "0x");

            await sendTransactionAsync({
                to: txn.to as `0x${string}`,
                value: BigInt(txn.value ? txn.value.toString() : "0"),
                data: txn.data as `0x${string}`,
                chainId: txn.chainId,
            });
        };
        return <button onClick={() => signAndSendTransaction()}>Send Transaction</button>;
    }
    ```
  </Tab>

  <Tab title="Full Repository Example">
    For a deeper example, refer to the repository linked below, which is the exact code running in the App tab.

    <Card title="headless-sendpayment" icon="github" href="https://github.com/crossmint/headless-sendpayment">
      Refer to the full repo for complete code examples
    </Card>
  </Tab>
</Tabs>

### 5. Poll for Status Updates

<Snippet />

## Next Steps

<Snippet />


# Pay with USDC
Source: https://docs.crossmint.com/payments/headless/quickstarts/paying-usdc

Buy or sell any tokenized asset with USDC, in an API call

## Introduction

This guide will show you how to quickly buy or sell any tokenized asset (NFT) with USDC, using Crossmint's headless APIs.

## Prerequisites

<Snippet />

## External prerequisites

<Steps>
  <Step icon="circle-dot" title="Wallet">
    Crypto wallet supporting USDC - [Metamask](https://metamask.io/), [Phantom](https://phantom.app/), [Coinbase Wallet](https://wallet.coinbase.com), etc.
  </Step>

  <Step icon="circle-dot" title="Testnet Balance">
    A small balance of **USDC** testnet currency in your wallet on the **Base-sepolia** network.

    Get testnet USDC here:

    * [Crossmint USDC Faucet (Base-sepolia)](https://usdc-faucet.vercel.app/)

    <Warning>
      The above faucet provides both USDC and USDXM. This quickstart uses USDC by default, but you can also use USDXM (see contract address below).
    </Warning>

    <Note>
      USDXM is a test token that represents USDC. It has the same behavior as USDC. In production, you'll use real USDC instead.
    </Note>

    **Adding USDC to MetaMask:**

    * Import the token to MetaMask:
      1. Open MetaMask and click "Import tokens"
      2. For USDC: Use the official USDC contract address from Circle `0x036CbD53842c5426634e7929541eC2318f3dCF7e`
      3. For USDXM: Use the USDXM contract address `0x14196F08a4Fa0B66B7331bC40dd6bCd8A1dEeA9F`
      4. Click Import
      5. Refresh your wallet
  </Step>
</Steps>

## Create an order and pay with USDC

<Steps>
  <Step title="Setup your environment">
    Clone the quickstart repo:

    ```bash theme={null}
    git clone https://github.com/Crossmint/headless-pay-usdc.git
    ```

    Navigate to the project directory:

    ```bash theme={null}
    cd headless-pay-usdc
    ```

    Install the dependencies:

    ```bash theme={null}
    pnpm i
    ```
  </Step>

  <Step title="Set keys in .env">
    Set the following keys in the `.env` file:

    ```bash theme={null}
    CROSSMINT_API_KEY="<your-api-key>"
    COLLECTION_ID="<your-collection-id>"
    PAYER_ADDRESS="<your-payer-address>"
    EMAIL_ADDRESS="<your-email-address>"
    ```

    * `CROSSMINT_API_KEY`, `COLLECTION_ID` are found from the [Developer Console](https://staging.crossmint.com/console/). See [Prerequisites](#prerequisites)
    * `PAYER_ADDRESS` is your wallet address that contains USDC.
    * `EMAIL_ADDRESS` is where you'll receive your NFT in a new Crossmint wallet that you can access later.
  </Step>

  <Step title="Create order with USDC payment">
    Run the application:

    ```bash theme={null}
    pnpm dev
    ```

    This will:

    1. Create an order that is waiting for a **USDC** payment on the **Base-sepolia** network
    2. Return the **serializedTransaction**, which will be used in the next step
    3. Poll the status of the order until it is complete

    <Frame type="simple">
      <img alt="Serialized transaction" />
    </Frame>
  </Step>

  <Step title="Receive Payment">
    1. Copy the `serializedTransaction` returned in the previous step and paste it below
    2. Connect to your USDC wallet that was specified in the `.env` file
    3. Send the transaction

    <Frame type="simple">
      <iframe />
    </Frame>
  </Step>

  <Step title="Status of order">
    The code will poll for the status of the order until it is marked as complete.
    You should see it changing from "payment" to "delivery" and finally to "completed".

    <Info>
      You will also see the final order details, including the transaction hash, in your terminal.
    </Info>

    <Frame type="simple">
      <img alt="Order status" />
    </Frame>
  </Step>
</Steps>

## Access your NFT

Once the order is complete, you will receive an email with a link to the purchased item, which can be viewed in the Crossmint website.

<Info>
  You can also access your NFT by logging in to your Crossmint wallet at
  [crossmint.com](https://staging.crossmint.com/user/collection) with the email address you specified in the `.env`
  file.
</Info>

## Understanding the code

### Creating an order

The order creation process involves sending a POST request to Crossmint's API with the necessary payment and recipient details. Let's break down the key components:

```ts src/createOrder.ts theme={null}
import { API_KEY, API_URL, COLLECTION_ID, EMAIL_ADDRESS, PAYER_ADDRESS } from "./utils";


export async function createOrder() {
    const payload = {
        recipient: {
            email: EMAIL_ADDRESS, // Replace with actual recipient wallet address
        },
        payment: {
            method: "base-sepolia",
            currency: "usdc",
            payerAddress: PAYER_ADDRESS,
        },
        lineItems: [
            {
                collectionLocator: `crossmint:${COLLECTION_ID}`
            },
        ],
    };
    ...
}
```

#### Key parameters explained

* **recipient**: Specifies where to deliver the tokenized asset

  * `email`: The email address where the tokenized asset will be delivered in a Crossmint wallet.
    Instead of an email, a `walletAddress` field can be used to deliver the asset to a specific wallet address.

* **payment**: Defines how the payment will be made

  * `method`: The blockchain network (`base-sepolia` for testnet)
  * `currency`: The payment currency (`usdc`)
  * `payerAddress`: The wallet address that will send the USDC payment

* **lineItems**: Specifies what is being purchased
  * `collectionLocator`: Identifies the collection

#### API request

```ts src/createOrder.ts theme={null}
    const response = await fetch(`${API_URL}/api/2022-06-09/orders`, {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            "x-api-key": API_KEY,
        },
        body: JSON.stringify(payload),
    });
```

The API request:

* Sends a POST request to Crossmint's order endpoint
* Includes your API key for authentication
* Sends the order data as JSON in the request body

#### Response handling

```ts src/createOrder.ts theme={null}
    if (!response.ok) {
        throw new Error(`Failed to create order: ${response.status} ${response.statusText}`);
    }
    const jsonResponse = await response.json();
    return {
        "clientSecret": jsonResponse["clientSecret"], // Used for order authentication
        "order": jsonResponse["order"] // Contains the order details
    }
```

The response includes:

* `clientSecret`: A unique token used for authenticating subsequent requests for this order
* `order`: The order details including the order ID and status

For more details on creating orders via the headless API, see the [Create Order API Reference](/api-reference/headless/create-order).

### Polling an order

The order status polling process involves periodically checking the order's status until it's completed. Let's examine how this works:

```ts src/getOrder.ts theme={null}
import { API_KEY, API_URL } from "./utils";

export async function getOrder(orderId: string) {
    const response = await fetch(`${API_URL}/api/2022-06-09/orders/${orderId}`, {
        method: "GET",
        headers: {
            "Content-Type": "application/json",
            "x-api-key": API_KEY, // API authentication
        }
    });
    if (!response.ok) {
        throw new Error(`Failed to create order: ${response.status} ${response.statusText}`);
    }
    return response.json();
}
```

#### Get order function explained

* Takes `orderId` as parameter
* Makes a GET request to fetch the current state of the order
* Uses API key for authentication
* Returns the order details as JSON

```ts src/getOrder.ts theme={null}
export async function pollOrder(orderId: string) {
    while (true) {
        const order = await getOrder(orderId);
        console.log(`Current order status: \x1b[33m${order.phase}\x1b[0m`);
        if (order.phase === "completed") {
            return order;
        }
        await new Promise(resolve => setTimeout(resolve, 3000));
    }
}
```

#### Poll order function explained

* Continuously checks the order status every 3 seconds.
* Prints the current phase of the order
* Possible order phases include:
  * `payment`: Waiting for the buyer's payment
  * `delivery`: NFT is being delivered
  * `completed`: Order is successfully completed
* Returns the final order details when completed

The 3-second polling interval helps prevent rate limiting while still providing timely updates. Adjust this value based on your needs.

For more details on polling for order status, see the [Get Order API Reference](/api-reference/headless/get-order).

<Warning>
  Always implement proper error handling, retry mechanisms, and asynchronous polling in production environments to
  handle network issues or API interruptions.
</Warning>


# Overview
Source: https://docs.crossmint.com/payments/introduction

Allow your users to buy onchain assets using any payment method

Crossmint enables seamless in-app checkout experiences that minimize onboarding friction and maximize conversion.

With Checkout, users can buy memecoins, closed-loop tokens, NFTs, and other assets with debit cards, credit cards, Apple Pay, Google Pay, and stablecoins. Learn more about the types of assets that can be supported <a href="https://help.crossmint.com/articles/8719615099-which-tokens-are-supported-with-crossmint-checkout#supported-assets">here</a>.

Checkout works across all non-sanctioned geographies, has market-leading conversion for buyers, and includes built-in chargeback protection for the platform. This product requires business verification (KYB) during onboarding to get production access — see [account verification](/introduction/platform/account-verification).

## See It in Action

The video below showcases Embedded Checkout for memecoins on <a href="https://fomo.family/">fomo</a>, highlighting a seamless mobile onboarding experience with Apple Pay.

<video />

## Key Features

<CardGroup>
  <Card title="Available globally" icon="globe">
    Support for any non-sanctioned geo.
  </Card>

  <Card title="Higher Approval Rates" icon="passport">
    Best-in-class conversion rates.
  </Card>

  <Card title="Apple & Google Pay" icon="apple">
    One-click mobile flows.
  </Card>

  <Card title="Chargeback Protection" icon="shield">
    Crossmint handles disputed transactions.
  </Card>

  <Card title="AML Monitoring" icon="fingerprint">
    Dedicated team of anti-fraud experts.
  </Card>

  <Card title="Analytics dashboards" icon="chart-line">
    Tools to measure and troubleshoot faster.
  </Card>
</CardGroup>

## Ways to Integrate

<CardGroup>
  <Card title="Hosted" icon="toggle-on" href="/payments/pay-button/quickstart">
    Crossmint-hosted pop-up.
  </Card>

  <Card title="Embedded" icon="object-group" href="/payments/embedded/quickstarts/credit-card-nft">
    Embedded iframe with customizable UI.
  </Card>

  <Card title="Headless" icon="code" href="/payments/headless/quickstarts/credit-card-nft">
    APIs for agents or custom UIs
  </Card>
</CardGroup>

<Note>Crossmint generally recommends to use Embedded Checkout. It yields experiences that feel completely native while handling PSP orchestration and error management, and offering better approval rates.</Note>

## Get started

<CardGroup>
  <Card title="Plan Your Integration" icon="gear" href="/payments/plan-your-solution" />
</CardGroup>

## FAQs

<AccordionGroup>
  <Accordion title="What's the difference between the Checkout and the Onramp?">
    The *checkout* is used when a user is buying a specific item — like an NFT, memecoin, or product — with fiat or crypto. It's a direct purchase of a specific item.

    The *onramp* is used when a user wants to fund their wallet with crypto — without buying a specific item. Think of it as topping up a balance instead of making a purchase.

    Use *checkout* when selling something. Use *onramp* when your users need crypto to spend later.
  </Accordion>

  <Accordion title="Which Geographies Does Checkout Support?">
    Checkout is available in all non-sanctioned geographies. Effective July 1, 2026, token checkout — including memecoins, closed-loop tokens, and other fungible tokens — is not available for buyers in the European Economic Area (EEA), United Kingdom, and Brazil. NFT checkout remains available. This restriction applies to all checkout modalities.
  </Accordion>

  <Accordion title="Should I use embedded or headless checkout?">
    Embedded is the best solution for most teams. It offers embeddable iframe / mobile components which feel native and allow for customizability. Integration takes minutes, as the SDK orchestrates all payment method integrations, different states, and errors.
  </Accordion>

  <Accordion title="Which memecoins can be supported?">
    Our team continuously monitors market activity and proactively reviews eligible memecoins across all of our partners.

    You may also request reviews for specific tokens at any time. Review timelines and throughput depend on your SaaS plan and request volume, and we'll always do our best to accommodate. If requests become too frequent relative to transaction volume, we may ask you to upgrade to a higher plan to continue supporting custom review requests.
  </Accordion>

  <Accordion title="How are chargebacks handled?">
    You don't have to worry about chargeback risk. Crossmint will take on the risk and manage disputes directly with the bank.
  </Accordion>

  <Accordion title="What happens if a transaction fails?">
    Crossmint places an authorization hold on the user's card before initiating the transaction. Funds are only captured once the transaction is successfully completed. If the transaction fails, the hold is released and the user is not charged.
  </Accordion>

  <Accordion title="How do I get production access for Checkout?">
    Staging is self-serve — create a <a href="https://staging.crossmint.com/console">staging console</a> account and start building immediately.

    Production access requires a signed Order Form and completed KYB verification. <a href="https://www.crossmint.com/contact/sales">Contact sales</a> to get started. See the [account verification documentation](/introduction/platform/account-verification) for the full sequence.
  </Accordion>

  <Accordion title="What are the transaction limits?">
    The standard transaction limits are **\$2,000 per user and day**. Limits reset daily at midnight US Eastern Time (05:00 UTC during standard time, 04:00 UTC during daylight saving time). If you need higher limits, <a href="https://www.crossmint.com/contact/sales">contact</a> the sales team.
  </Accordion>
</AccordionGroup>


# Localization
Source: https://docs.crossmint.com/payments/pay-button/customize/localization

Customize the language and currency displayed on checkout

<Snippet />

## How to Adjust the Currency and Language

To customize the language use the property `locale` and for currency, set `defaultCurrency`. Here's an example:

```tsx {3,16} theme={null}
<CrossmintProvider apiKey="_YOUR_CLIENT_API_KEY_">
    <CrossmintHostedCheckout
        locale="es-ES" // Change locale to Spanish
        lineItems={{
            collectionLocator: "crossmint:_YOUR_COLLECTION_ID_",
            callData: {
                // your callData args
            },
        }}
        payment={{
            crypto: {
                enabled: true,
            },
            fiat: {
                enabled: true,
                defaultCurrency: "eur", // Change default currency to be Euro
            },
        }}
    />
</CrossmintProvider>
```


# React Hooks
Source: https://docs.crossmint.com/payments/pay-button/guides/hooks

Learn how to use React hooks to control and customize the Hosted Checkout UI

<Snippet />

<Snippet />

## Complete Example

Here's a full example showing how to implement a custom checkout experience:

```tsx theme={null}
import {
    CrossmintProvider,
    CrossmintCheckoutProvider,
    CrossmintHostedCheckout,
    useCrossmintCheckout,
} from "@crossmint/client-sdk-react-ui";

function CheckoutPage() {
    return (
        <CrossmintProvider apiKey="YOUR_API_KEY">
            <CrossmintCheckoutProvider>
                <CrossmintHostedCheckout
                    lineItems={{
                        collectionLocator: "crossmint:your-collection-id",
                        callData: {
                            totalPrice: "0.001",
                            quantity: 1,
                        },
                    }}
                    payment={{
                        crypto: { enabled: true },
                        fiat: { enabled: true },
                    }}
                />
                <CheckoutStatus />
            </CrossmintCheckoutProvider>
        </CrossmintProvider>
    );
}

function CheckoutStatus() {
    const { order } = useCrossmintCheckout();

    if (!order) {
        return <div>Loading...</div>;
    }

    switch (order.phase) {
        case "completed":
            return <div>Purchase complete!</div>;
        case "delivery":
            return <div>Delivering your NFTs...</div>;
        case "payment":
            return <div>Processing payment...</div>;
        case "quote":
            return <div>Preparing your order...</div>;
    }
}
```

<Snippet />

## Related Resources

* [UI Customization](/payments/pay-button/guides/ui-customization)
* [Payment Methods](/payments/pay-button/guides/payment-methods)
* [Order Lifecycle](/payments/headless/guides/order-lifecycle)
* [Testing Tips](/payments/advanced/testing-tips)


# Item Selection
Source: https://docs.crossmint.com/payments/pay-button/guides/item-selection

Specify which items to purchase with Hosted Checkout

The Hosted Checkout (Pay Button) allows you to specify which items your users can purchase using the `lineItems` property. This guide explains how to configure item selection for different asset types.

<Snippet />

## Item Selection Examples

<CodeGroup>
  ```tsx collectionLocator theme={null}
  <CrossmintProvider apiKey="_YOUR_CLIENT_API_KEY_">
      <CrossmintHostedCheckout
          lineItems={{
              collectionLocator: "crossmint:_YOUR_COLLECTION_ID_", // Crossmint managed collection
              // collectionLocator: "crossmint:_YOUR_COLLECTION_ID_:_TEMPLATE_ID_", // With specific template
              callData: {
                  totalPrice: "5.00",
                  quantity: 1, // matches your contract's parameter name
              },
          }}
      />
  </CrossmintProvider>
  ```

  ```tsx collectionLocator - imported contract theme={null}
  <CrossmintProvider apiKey="_YOUR_CLIENT_API_KEY_">
      <CrossmintHostedCheckout
          lineItems={{
              collectionLocator: "ethereum:0x71c7656ec7ab88b098defb751b7401b5f6d897", // External collection registered in Crossmint Console
              callData: {
                  totalPrice: "5.00",
                  quantity: 1, // matches your contract's parameter name
                  // For external contracts, you might need additional parameters such as:
                  // _amount: 1, // if your mint function uses _amount instead of quantity
                  // tokenId: "123", // if your contract requires a specific tokenId
                  // metadata: "ipfs://...", // if your contract accepts metadata
              },
          }}
      />
  </CrossmintProvider>
  ```

  ```tsx Solana theme={null}
  <CrossmintHostedCheckout
      lineItems={{
          tokenLocator: "solana:7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
          callData: {
              totalPrice: "0.1",
              buyerCreatorRoyaltyPercent: 100, // Required for Solana
          },
      }}
  />
  ```

  ```tsx tokenLocator - EVM theme={null}
  <CrossmintProvider apiKey="_YOUR_CLIENT_API_KEY_">
      <CrossmintHostedCheckout
          lineItems={{
              tokenLocator: "ethereum:0x71c7656ec7ab88b098defb751b7401b5f6d897:1234", // <blockchain>:<contractAddress>:<tokenId>
              callData: {
                  totalPrice: "25.00", // Only totalPrice is required for token purchases
                  // For external EVM contracts, you might need additional parameters:
                  // _amount: 1, // if your contract uses _amount instead of quantity
                  // tokenId: "1234", // if your contract requires explicit tokenId
                  // metadata: "ipfs://...", // if your contract accepts metadata
              },
          }}
      />
  </CrossmintProvider>
  ```

  ```tsx tokenLocator - Solana theme={null}
  <CrossmintProvider apiKey="_YOUR_CLIENT_API_KEY_">
      <CrossmintHostedCheckout
          lineItems={{
              tokenLocator: "solana:7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU", // <blockchain>:<tokenAddress>
              callData: {
                  totalPrice: "25.00",
                  buyerCreatorRoyaltyPercent: 100, // Required for Solana
              },
          }}
      />
  </CrossmintProvider>
  ```
</CodeGroup>

<Snippet />

<Snippet />

<Snippet />

## Order Status Tracking

The Pay Button cannot use webhooks for order status tracking because it operates in a separate window. Therefore, you'll need to implement polling to check order status through alternative methods. See the [Order Status Guide](/payments/pay-button/guides/order-status) for more information on tracking order completion in pay button.


# Order Status
Source: https://docs.crossmint.com/payments/pay-button/guides/order-status

Track order status with Hosted Checkout

Since Hosted Checkout opens in a separate window, you can't use `useCrossmintCheckout` to track order status. Instead, you have three options:

## 1. Using Callback Functions

```tsx theme={null}
<CrossmintHostedCheckout
    lineItems={{
        collectionLocator: "crossmint:_YOUR_COLLECTION_ID_",
        callData: {
            totalPrice: "0.001",
            quantity: 1,
        },
    }}
    appearance={{
        display: "new-tab", // or "overlay"
        overlay: {
            enabled: true,
        },
    }}
    onSuccess={(orderId) => {
        // Handle successful order
        console.log("Order completed:", orderId);
    }}
    onFailure={(error) => {
        // Handle failed order
        console.error("Order failed:", error);
    }}
/>
```

## 2. Using Event Listeners

```tsx theme={null}
useEffect(() => {
    const handleMessage = (event: MessageEvent) => {
        if (event.data.type === "crossmint:checkout:completed") {
            console.log("Order completed:", event.data.orderId);
        }
    };

    window.addEventListener("message", handleMessage);
    return () => window.removeEventListener("message", handleMessage);
}, []);
```

## 3. Using Order Status API

For real-time order status updates, you can use the [Order Status API](/payments/pay-button/guides/order-status) to check the status of an order programmatically.


# Configure Payment Options
Source: https://docs.crossmint.com/payments/pay-button/guides/payment-methods

Customize the payment methods available to users

## Payment Methods Supported

<CardGroup>
  <Card title="Debit & Credit cards" icon="credit-card" />

  <Card title="Apple & Google Pay" icon="mobile" />

  <Card title="Cross-chain crypto" icon="coins" />
</CardGroup>

<Note>
  Buyers can purchase digital assets with any cryptocurrency. For example, they can pay for an asset on Optimism chain
  with mainnet ETH. This is done real time without bridging and lower gas fees.
</Note>

## Configure Payment Settings

You can configure payment preferences using the `payment` prop:

```tsx theme={null}
<CrossmintHostedCheckout
    payment={{
        // Enable/disable payment types
        fiat: {
            enabled: true,
            defaultCurrency: "usd", // Set preferred fiat currency
        },
        crypto: {
            enabled: true,
            defaultChain: "polygon", // Set preferred blockchain
            defaultCurrency: "matic", // Set preferred crypto
        },
        // Optional: Set default payment method
        defaultMethod: "fiat", // Options: "fiat" or "crypto"
        // Optional: Set receipt email
        receiptEmail: "buyer@example.com",
    }}
/>
```

### Fiat Payment Options

Configure fiat payment settings:

```tsx theme={null}
payment={{
  fiat: {
    enabled: true,
    defaultCurrency: "usd"
  }
}}
```

### Crypto Payment Options

Configure crypto payment preferences:

```tsx theme={null}
payment={{
  crypto: {
    enabled: true,
    defaultChain: "polygon", // Set preferred blockchain
    defaultCurrency: "matic" // Set preferred crypto currency
  }
}}
```

<Info>
  You will be paid in the currency expected by your registered mint function, regardless of how the buyer pays.
</Info>


# Production Launch
Source: https://docs.crossmint.com/payments/pay-button/guides/production-launch

Follow this checklist to ensure you are ready for production launch with Pay Button

## From Staging to Production with Pay Button

<Snippet />

***

### Launch Checklist

1. Change your API keys to the production versions. Ensure your production API key has the appropriate scopes enabled, such as `orders.create`.
2. Update your collection ID to the production one.
3. As needed, change your passed-in props to be production ready (e.g. make `email`, `payment`, `lineItems` programmatically filled).

<Accordion title="See Code Example">
  <CodeGroup>
    ```jsx {(1, 4)} Production theme={null}
    <CrossmintProvider apiKey="YOUR_PROD_API_KEY">
        <CrossmintPayButton
            lineItems={{
                collectionLocator: `crossmint:YOUR_PROD_COLLECTION_ID`,
                callData: {
                    totalPrice: "0.25",
                    quantity: 1,
                },
            }}
            payment={{
                crypto: { enabled: true },
                fiat: {
                    enabled: true,
                    defaultCurrency: "usd",
                },
            }}
        />
    </CrossmintProvider>
    ```

    ```jsx {(1, 4)} Staging theme={null}
    <CrossmintProvider apiKey="YOUR_STAGING_API_KEY">
        <CrossmintPayButton
            lineItems={{
                collectionLocator: `crossmint:YOUR_STAGING_COLLECTION_ID`,
                callData: {
                    totalPrice: "0.001",
                    quantity: 1,
                },
            }}
            payment={{
                crypto: { enabled: true },
                fiat: {
                    enabled: true,
                    defaultCurrency: "usd",
                },
            }}
        />
    </CrossmintProvider>
    ```
  </CodeGroup>
</Accordion>


# Specify Recipient
Source: https://docs.crossmint.com/payments/pay-button/guides/specify-recipient

Select where purchased items should be delivered in Hosted Checkout

<Snippet />

## Specifying the Recipient

For Hosted Checkout, you specify the recipient by adding a `recipient` object to your checkout component. The recipient can be specified by email or wallet address.

### Recipient by Email

When specifying a recipient by email, Crossmint will automatically create a secure custodial wallet on the fly for that email address:

```jsx React {3-5} theme={null}
<CrossmintProvider apiKey="YOUR_API_KEY">
    <CrossmintHostedCheckout
        recipient={{
            email: "user@example.com",
        }}
        lineItems={{
            collectionLocator: `crossmint:YOUR_COLLECTION_ID`,
            callData: {
                totalPrice: "0.0001",
                quantity: 1,
            },
        }}
        payment={{
            crypto: { enabled: true },
            fiat: { enabled: true },
        }}
    >
        Buy with Crossmint
    </CrossmintHostedCheckout>
</CrossmintProvider>
```

The recipient will be able to access their purchased items by logging into their Crossmint wallet in [staging](https://staging.crossmint.com/user/collection) or [mainnet](https://www.crossmint.com/user/collection).

### Recipient by Wallet Address

To deliver items directly to a specific blockchain wallet address:

```jsx React {3-6} theme={null}
<CrossmintProvider apiKey="YOUR_API_KEY">
    <CrossmintHostedCheckout
        recipient={{
            walletAddress: "0x1234567890abcdef1234567890abcdef12345678", // For EVM chains
            // walletAddress: "5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty", // For Solana
        }}
        lineItems={{
            collectionLocator: `crossmint:YOUR_COLLECTION_ID`,
            callData: {
                totalPrice: "0.0001",
                quantity: 1,
            },
        }}
        payment={{
            crypto: { enabled: true },
            fiat: { enabled: true },
        }}
    />
</CrossmintProvider>
```


# Customize the Button UI
Source: https://docs.crossmint.com/payments/pay-button/guides/ui-customization

Modify the payment button and checkout experience to match your website's style

You can customize both the payment button and the checkout modal appearance using the `appearance` prop.

## Button Customization

### Theme Options

The button can be styled using predefined themes:

```tsx theme={null}
<CrossmintHostedCheckout
    appearance={{
        theme: {
            button: "light", // Options: "light", "dark", "crossmint"
        },
    }}
/>
```

### Custom Colors

Customize the button's accent color:

```tsx theme={null}
<CrossmintHostedCheckout
    appearance={{
        variables: {
            colors: {
                accent: "#FF0000", // Your custom color
            },
        },
    }}
/>
```

## Checkout Experience Customization

### Display Mode

Choose how the checkout appears:

```tsx theme={null}
<CrossmintHostedCheckout
    appearance={{
        display: "popup", // Options: "popup", "new-tab", "same-tab"
    }}
/>
```

### Theme

Set the checkout interface theme:

```tsx theme={null}
<CrossmintHostedCheckout
    appearance={{
        theme: {
            checkout: "dark", // Options: "light", "dark"
        },
    }}
/>
```

### Overlay Options

Control the modal overlay behavior:

```tsx theme={null}
<CrossmintHostedCheckout
    appearance={{
        overlay: {
            enabled: false, // Disable the dark overlay behind the modal
        },
    }}
/>
```

## Complete Styling Example

Here's an example combining multiple customization options:

```tsx theme={null}
<CrossmintHostedCheckout
    appearance={{
        theme: {
            button: "light",
            checkout: "dark",
        },
        variables: {
            colors: {
                accent: "#FF0000",
            },
        },
        display: "popup",
        overlay: {
            enabled: true,
        },
    }}
    // ... other props
/>
```

<Note>
  The appearance configuration allows you to: - Customize button and checkout themes independently - Set custom accent
  colors - Control how the checkout displays (popup/tab) - Manage overlay behavior
</Note>


# Overview
Source: https://docs.crossmint.com/payments/pay-button/overview

Add a button to your site which opens the checkout in a pop-up or new tab

<Frame type="simple">
  <img alt="Crossmint Hosted Checkout Demo" />
</Frame>

<Info>
  The hosted variant of checkout is only available for React applications. If you're using a different framework like
  Vite or React Native, you can use the [Headless version](/payments/headless/overview) instead.
</Info>

For general information about Crossmint's Payments product, see the [introduction](/payments/introduction). This guide
will focus on the features specific to the Hosted modality.

## When is Hosted Checkout the best fit?

* **You want to launch quickly and don't need deep customization or a fully native user experience**.

## Get Started

<CardGroup>
  <Card title="Quickstart" icon="bolt" href="/payments/pay-button/quickstart">
    Start selling digital assets in 5 minutes.
  </Card>

  <Card title="Talk to an expert" icon="message" href="https://www.crossmint.com/contact/sales">
    Contact our sales team for advanced support.
  </Card>
</CardGroup>

## Advanced Topics

<CardGroup>
  <Card title="Marketplaces & Launchpads" icon="cart-shopping" href="/payments/advanced/marketplaces-and-launchpads" />

  <Card title="SDK Reference" icon="gear" href="/sdk-reference/checkout/react/components" />

  <Card title="Purchasing Multiple Assets" icon="rectangle-vertical-history" href="/payments/pay-button/guides/item-selection#multiple-item-orders" />

  <Card title="Bring your own Collection" icon="file-import" href="/payments/guides/register-collection" />

  <Card title="USDC Contracts" icon="circle-dollar" href="/payments/advanced/usdc-support" />

  <Card title="Checkout Localization" icon="globe" href="/payments/pay-button/customize/localization" />

  <Card title="Webhooks" icon="bars-progress" href="/payments/advanced/webhooks" />

  <Card title="Testing Tips" icon="flask" href="/payments/advanced/testing-tips" />
</CardGroup>


# Quickstart ⚡
Source: https://docs.crossmint.com/payments/pay-button/quickstart

Accept payments in under 5 min by just adding a button to your frontend

<Frame type="simple">
  <img alt="Hosted Checkout Demo" />
</Frame>

## Introduction

In this guide, you will create a web app with Next.js which allows customers to buy digital assets with credit card and
crypto payments using Crossmint's hosted checkout. We will add a button that opens a checkout hosted in a pop-up or new
tab.

<Snippet />

<Snippet />

### Basic Integration

This quickstart guide focuses on NFT Collections/Drops (primary sales), but Crossmint also supports marketplace integrations.

<Steps>
  <Step title="Add environment variables">
    Create `.env.local` in your project root:

    ```sh theme={null}
    NEXT_PUBLIC_CLIENT_API_KEY="_YOUR_CLIENT_API_KEY_"    # From API Keys page
    NEXT_PUBLIC_COLLECTION_ID="_YOUR_COLLECTION_ID_"      # From Collection details page
    ```
  </Step>

  <Step title="Create the checkout page">
    Create `/src/app/page.tsx` with:

    ```tsx theme={null}
    "use client";

    import { CrossmintProvider, CrossmintHostedCheckout } from "@crossmint/client-sdk-react-ui";

    export default function Home() {
        const clientApiKey = process.env.NEXT_PUBLIC_CLIENT_API_KEY as string;
        const collectionId = process.env.NEXT_PUBLIC_COLLECTION_ID as string;

        return (
            <CrossmintProvider apiKey={clientApiKey}>
                <CrossmintHostedCheckout
                    lineItems={{
                        collectionLocator: `crossmint:${collectionId}`,
                        callData: {
                            totalPrice: "0.001",
                            quantity: 1,
                        },
                    }}
                    payment={{
                        crypto: { enabled: true },
                        fiat: { enabled: true },
                    }}
                />
            </CrossmintProvider>
        );
    }
    ```
  </Step>

  <Step title="Run your app">
    Navigate to the directory your package.json is to run the app

    ```bash theme={null}
    cd hosted-checkout/crossmint-hosted-checkout-demo
    ```

    <Snippet />
  </Step>
</Steps>

### (Optional) Advanced Integration

Need purchase tracking, multiple line items, or more customization? Here's a complete setup with additional features:

<Tabs>
  <Tab title="For NFT Collections/Drops">
    ```tsx theme={null}
    "use client";

    import { useEffect } from "react";
    import {
        CrossmintProvider,
        CrossmintCheckoutProvider,
        CrossmintHostedCheckout,
        useCrossmintCheckout,
    } from "@crossmint/client-sdk-react-ui";

    // Component with purchase tracking
    function Checkout() {
        const { order } = useCrossmintCheckout();
        const collectionId = process.env.NEXT_PUBLIC_COLLECTION_ID as string;

        useEffect(() => {
            if (order && order.phase === "completed") {
                console.log("Purchase completed!");
                // Handle successful purchase
            }
        }, [order]);

        return (
            <CrossmintHostedCheckout
                lineItems={[
                    {
                        collectionLocator: `crossmint:${collectionId}`,
                        callData: {
                            totalPrice: "0.001",
                            quantity: 1,
                        },
                    },
                    {
                        collectionLocator: `crossmint:${collectionId}`,
                        callData: {
                            totalPrice: "0.002",
                            quantity: 2,
                        },
                    },
            ]}
            appearance={{
                display: "new-tab", // Open in a new tab
                overlay: {
                    enabled: false, // Disable overlay
                },
                theme: {
                    button: "dark", // Dark button theme
                    checkout: "dark", // Dark checkout theme
                },
            }}
            payment={{
                crypto: {
                    enabled: true,
                    defaultChain: "polygon", // Set preferred blockchain
                    defaultCurrency: "matic", // Set preferred crypto
                },
                fiat: {
                    enabled: true,
                    defaultCurrency: "usd", // Set preferred fiat currency
                },
                receiptEmail: "receipt@example.com", // Optional: Set receipt email
            }}
            recipient={{
                email: "buyer@example.com", // Digital assets will be delivered to this email's wallet
                // Or use walletAddress: "0x..." for direct delivery
            }}
            locale="en-US" // Set interface language
        />
    );

    }

    // Main component with providers
    export default function Home() {
        const clientApiKey = process.env.NEXT_PUBLIC_CLIENT_API_KEY as string;

        return (
            <div className="flex flex-col items-center justify-start min-h-screen p-6">
                <CrossmintProvider apiKey={clientApiKey}>
                    <CrossmintCheckoutProvider>
                        <Checkout />
                    </CrossmintCheckoutProvider>
                </CrossmintProvider>
            </div>
        );
    }
    ```
  </Tab>

  <Tab title="For Marketplaces">
    ```tsx theme={null}
    "use client";

    import { useEffect } from "react";
    import {
        CrossmintProvider,
        CrossmintCheckoutProvider,
        CrossmintHostedCheckout,
        useCrossmintCheckout,
    } from "@crossmint/client-sdk-react-ui";

    // Component with purchase tracking
    function Checkout() {
        const { order } = useCrossmintCheckout();

        useEffect(() => {
            if (order && order.phase === "completed") {
                console.log("Purchase completed!");
                // Handle successful purchase
            }
        }, [order]);

        return (
            <CrossmintHostedCheckout
                lineItems={[
                    {
                        // For Solana NFTs
                        tokenLocator: "solana:4oDd...x6NC",
                        callData: {
                            totalPrice: "0.1",
                            buyerCreatorRoyaltyPercent: 100
                        }
                    },
                    {
                        // For EVM NFTs (Ethereum, Polygon, etc)
                        tokenLocator: "ethereum:0xbC...307e:7777",
                        callData: {
                            totalPrice: "0.2"
                        }
                    }
                ]}
                appearance={{
                    display: "new-tab", // Open in a new tab
                    overlay: {
                        enabled: false, // Disable overlay
                    },
                    theme: {
                        button: "dark", // Dark button theme
                        checkout: "dark", // Dark checkout theme
                    },
                }}
                payment={{
                    crypto: {
                        enabled: true,
                        defaultChain: "solana", // Set preferred blockchain
                        defaultCurrency: "sol", // Set preferred crypto
                    },
                    fiat: {
                        enabled: true,
                        defaultCurrency: "usd", // Set preferred fiat currency
                    },
                }}
                locale="en-US" // Set interface language
            />
        );
    }

    // Main component with providers
    export default function Home() {
        const clientApiKey = process.env.NEXT_PUBLIC_CLIENT_API_KEY as string;

        return (
            <div className="flex flex-col items-center justify-start min-h-screen p-6">
                <CrossmintProvider apiKey={clientApiKey}>
                    <CrossmintCheckoutProvider>
                        <Checkout />
                    </CrossmintCheckoutProvider>
                </CrossmintProvider>
            </div>
        );
    }
    ```
  </Tab>
</Tabs>

<Note>
  This advanced example showcases: - Multiple NFTs in one checkout - Purchase status tracking - Preferred payment
  methods and currencies - Email-based digital asset delivery - Language settings Learn more in our guides: - [Payment
  Methods](/payments/pay-button/guides/payment-methods) - [Multi-purchases](/payments/pay-button/guides/item-selection#multiple-item-orders)

  * [React Hooks](/payments/pay-button/guides/hooks)
</Note>

### Testing Your Integration

This demo uses the staging environment:

* Use [test credit cards](/payments/advanced/testing-tips#test-credit-card-numbers) for payments
* Get test USDC from our [faucet](/payments/advanced/testing-tips#getting-test-tokens)
* Check [price limits](/payments/advanced/testing-tips#limits-in-staging) for staging

## All Set!

You've successfully integrated a hosted checkout with credit card and crypto payment methods!

<Frame type="simple">
  <img />
</Frame>

<Note>
  Remember this demo is built on staging, so the digital assets will show up on the testnets. To launch on production,
  check the [production launch checklist](/payments/advanced/production-launch). You will need to contact
  [Sales](https://www.crossmint.com/contact/sales) to enable the embedded checkout on production.
</Note>

## Next Steps

### Customize the UI and Behavior Further

<CardGroup>
  <Card title="UI Customization" icon="paintbrush" href="/payments/pay-button/guides/ui-customization">
    Learn how to customize the look and feel of the checkout button
  </Card>

  <Card title="Payment Methods" icon="credit-card" href="/payments/pay-button/guides/payment-methods">
    Configure available payment options for your users
  </Card>

  <Card title="React Hooks" icon="code" href="/payments/pay-button/guides/hooks">
    Use React hooks to build custom checkout experiences
  </Card>
</CardGroup>

### Advanced Topics

<CardGroup>
  <Card title="SDK Reference" icon="gear" href="/sdk-reference/checkout/react/components" />

  <Card title="Launch in Production" icon="ship" href="/payments/advanced/production-launch" />

  <Card title="Localization" icon="globe" href="/payments/pay-button/customize/localization" />

  <Card title="Multi-purchases" icon="cart-plus" href="/payments/pay-button/guides/item-selection#multiple-item-orders" />

  <Card title="Marketplaces" icon="store" href="/payments/advanced/marketplaces-and-launchpads" />

  <Card title="Testing Tips" icon="flask" href="/payments/advanced/testing-tips" />
</CardGroup>


# Plan Your Integration
Source: https://docs.crossmint.com/payments/plan-your-solution

Walk through key decisions to design your Crossmint Checkout integration

Crossmint Checkout supports multiple asset types and integration modalities. This guide helps you make key decisions for your integration.

## 1. Select the asset type you're selling

<CardGroup>
  <Card title="Memecoins" icon="coins" />

  <Card title="Closed-loop tokens" icon="rotate" />

  <Card title="NFTs" icon="hexagon-vertical-nft" />
</CardGroup>

Learn more about the types of assets that can be supported <a href="https://help.crossmint.com/articles/8719615099-which-tokens-are-supported-with-crossmint-checkout#supported-assets">here</a>.

## 2. Choose an integration modality

Crossmint checkout can be integrated into your application in three different ways, ranging from a bare metal headless
API with maximum UI flexibility, to a low-code hosted solution.

| Modality | Description | Integration Complexity | Supported Platforms | Recommended For |
| :- | :- | :- | :- | :- |
| [Headless](/payments/headless/overview) | Buy or sell using a REST API. Puts additional work on your side. | \~500 Lines of Code (LOC) | Everywhere | Best suited for backend flows and platforms not natively supported by other modalities. |
| [Embedded (strongly recommended)](/payments/embedded/overview) | Embed a checkout natively within your app. Handles orchestration, errors, and has better approval rates. | \~100 LOC | React, WebView | E-commerce sites, token marketplaces, embedded finance |
| [Hosted](/payments/pay-button/overview) | Add a button to your app that opens a checkout in a separate tab or window. | \~10 LOC | Web | One-off integrations for an event, quick prototypes |

<Note>Embedded Checkout is generally recommended. It yields experiences that feel completely native while handling PSP orchestration and error management, and offering better approval rates.</Note>

## 3. Choose payment method(s)

You can choose multiple options from the following payment methods to include. Consider the following as you decide:

* Is your audience crypto-native or mainstream consumers familiar with fiat payments?
* What level of optionality do you want to enable? Adding many methods may add complexity during a user's checkout flow.

| Payment Method | Description | Best For |
| :- | :- | :- |
| **Debit & Credit Cards** | All major credit cards supported - Visa, Mastercard, American Express, and more. | Mainstream consumers, global accessibility |
| **Apple & Google Pay** | Check out in under 30 seconds with faster payment methods. | Mobile-first users, quick transactions |
| **Stablecoins** | Pay with USDC, USDT, and other stablecoins for lower transaction fees. | Crypto-native users, lower fees |
| **Cross-Chain Crypto** | Pay with any token, on any chain. | Multi-chain users, existing crypto holders |

<Note>Stablecoins and cross-chain crypto not supported for memecoin checkout.</Note>

## 4. (For NFTs only) Do you need to create or import an existing collection?

**Choose one:** Do you want to create a new NFT collection or import an existing one?

<CardGroup>
  <Card title="Create New" icon="plus" href="/payments/guides/create-collection">
    Use our templates in the Console
  </Card>

  <Card title="Import Existing" icon="download" href="/payments/guides/register-collection">
    Connect your deployed smart contract
  </Card>
</CardGroup>

## Get Started

<Snippet />

<CardGroup>
  <Card title="Hosted Checkout" icon="toggle-on" href="/payments/pay-button/overview">
    Launch a Crossmint-hosted checkout page in a pop-up
  </Card>

  <Card title="Embedded Checkout" icon="object-group" href="/payments/embedded/overview">
    Import Crossmint checkout components in your application
  </Card>

  <Card title="Headless" icon="code" href="/payments/headless/overview">
    Buy or sell via an API, best suited for agents or deep UI customization
  </Card>
</CardGroup>


# Components
Source: https://docs.crossmint.com/sdk-reference/agents/react/components

React components for React SDK reference for Crossmint agent payments

## CrossmintPaymentMethodManagement

Lets the user save a new card or bank account, or pick one of their saved payment methods. Rendered in a Crossmint-hosted iframe, so payment details never touch your app. Takes the user's Crossmint `jwt`. `onPaymentMethodSelected` receives the chosen method; its `paymentMethodId` is what your backend uses to pay (for example to create order intents).

### Props

<ResponseField name="allowedModes" type="&#x22;new&#x22; | &#x22;existing&#x22;[]">
  Which sections the management UI renders. `["new"]` (default) shows only the "add new" section: no saved-methods fetch, no auto-open/auto-select of an existing method. Include `"existing"` to also show the saved-methods section.
</ResponseField>

<ResponseField name="allowedPaymentMethodTypes" type="PaymentMethodManagementAllowedType[]">
  Filter array of which method types the "add new" section offers (default `["card"]`). LM0 renders the first supported entry; passing more than one type does not yet render a type picker.
</ResponseField>

<ResponseField name="appearance" type="PaymentMethodManagementAppearance">
  <Expandable title="properties">
    <ResponseField name="fonts" type="EmbeddedCheckoutV3Appearance[&#x22;fonts&#x22;]" />

    <ResponseField name="rules" type="EmbeddedCheckoutV3Appearance[&#x22;rules&#x22;]" />

    <ResponseField name="variables" type="EmbeddedCheckoutV3Appearance[&#x22;variables&#x22;]" />
  </Expandable>
</ResponseField>

<ResponseField name="jwt" type="string" />

<ResponseField name="onPaymentMethodSelected" type="(paymentMethod: CrossmintPaymentMethod) => void | Promise<void>" />

### Usage

```tsx theme={null}
import { CrossmintPaymentMethodManagement } from "@crossmint/client-sdk-react-ui";

function PaymentMethods({ jwt }: { jwt: string }) {
    return (
        <CrossmintPaymentMethodManagement
            jwt={jwt}
            allowedModes={["new", "existing"]}
            allowedPaymentMethodTypes={["card"]}
            onPaymentMethodSelected={(paymentMethod) => {
                if (paymentMethod.type === "card") {
                    console.log("Card selected:", paymentMethod.card.last4);
                }
            }}
        />
    );
}
```

> **Note:** CrossmintPaymentMethodManagement renders an iframe-based UI for managing saved payment methods. Requires a valid JWT for authentication. The onPaymentMethodSelected callback receives a discriminated union — narrow on `type` before accessing variant-specific fields.

***

## OrderIntentVerification

Runs the card network's allowance verification for an order intent. Render it when the intent's `agentic-token` rail reports `status: "pending_verification"`; it renders nothing itself and opens the network's verification UI on mount.

### Props

<ResponseField name="appearance" type="VerificationAppearance">
  <Expandable title="properties">
    <ResponseField name="rules" type="VerificationAppearanceRules">
      <Expandable title="properties">
        <ResponseField name="CloseButton" type="{ colors?: { background?: string }; hover?: { colors?: object } }">
          <Expandable title="properties">
            <ResponseField name="colors" type="{ background?: string }" />

            <ResponseField name="hover" type="{ colors?: { background?: string } }" />
          </Expandable>
        </ResponseField>

        <ResponseField name="Input" type="{ borderRadius?: string; colors?: { background?: string; border?: string } }">
          <Expandable title="properties">
            <ResponseField name="borderRadius" type="string" />

            <ResponseField name="colors" type="{ background?: string; border?: string }" />
          </Expandable>
        </ResponseField>

        <ResponseField name="Modal" type="{ borderRadius?: string; colors?: { border?: string } }">
          <Expandable title="properties">
            <ResponseField name="borderRadius" type="string" />

            <ResponseField name="colors" type="{ border?: string }" />
          </Expandable>
        </ResponseField>

        <ResponseField name="Overlay" type="{ colors?: { background?: string } }">
          <Expandable title="properties">
            <ResponseField name="colors" type="{ background?: string }" />
          </Expandable>
        </ResponseField>

        <ResponseField name="PrimaryButton" type="object">
          <Expandable title="properties">
            <ResponseField name="borderRadius" type="string" />

            <ResponseField name="colors" type="{ background?: string; text?: string }" />

            <ResponseField name="disabled" type="{ colors?: { background?: string } }" />

            <ResponseField name="hover" type="{ colors?: { background?: string } }" />
          </Expandable>
        </ResponseField>

        <ResponseField name="Radio" type="{ colors?: { border?: string }; selected?: { colors?: object } }">
          <Expandable title="properties">
            <ResponseField name="colors" type="{ border?: string }" />

            <ResponseField name="selected" type="{ colors?: { background?: string; border?: string; dot?: string } }" />
          </Expandable>
        </ResponseField>

        <ResponseField name="SecondaryButton" type="{ colors?: { background?: string; text?: string }; hover?: { colors?: object } }">
          <Expandable title="properties">
            <ResponseField name="colors" type="{ background?: string; text?: string }" />

            <ResponseField name="hover" type="{ colors?: { background?: string } }" />
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="variables" type="VerificationAppearanceVariables">
      <Expandable title="properties">
        <ResponseField name="borderRadius" type="string" />

        <ResponseField name="colors" type="object">
          <Expandable title="properties">
            <ResponseField name="accent" type="string" />

            <ResponseField name="backgroundPrimary" type="string" />

            <ResponseField name="backgroundSecondary" type="string" />

            <ResponseField name="border" type="string" />

            <ResponseField name="danger" type="string" />

            <ResponseField name="success" type="string" />

            <ResponseField name="textPrimary" type="string" />

            <ResponseField name="textSecondary" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="fontFamily" type="string" />

        <ResponseField name="fontSizeUnit" type="string">
          Not applied by `OrderIntentVerification`: only `colors` (and the button / input colors under `rules`) reach the verification modal. Not the multiplier unit of `EmbeddedCheckoutV3AppearanceVariables.fontSizeUnit`, so do not share one object between the two.
        </ResponseField>

        <ResponseField name="spacingUnit" type="string">
          Not applied by `OrderIntentVerification`; see `fontSizeUnit`.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="displayName" type="string">
  Name of the agent shown to the user in the card network's verification UI.
</ResponseField>

<ResponseField name="onVerificationComplete" type="() => void">
  Called once the user has approved the allowance. Refetch the order intent afterwards.
</ResponseField>

<ResponseField name="onVerificationError" type="(error: unknown) => void" />

<ResponseField name="orderIntent" type="OrderIntentWithVerification">
  The order intent returned by the API, including its `verificationConfig`.

  <Expandable title="properties">
    <ResponseField name="amount" type="{ available: string; currency: string; reserved: string; spent: string; total: string }">
      <Expandable title="properties">
        <ResponseField name="available" type="string" />

        <ResponseField name="currency" type="string" />

        <ResponseField name="reserved" type="string" />

        <ResponseField name="spent" type="string" />

        <ResponseField name="total" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="description" type="string" />

    <ResponseField name="expiresAt" type="string" />

    <ResponseField name="merchant" type="OrderIntentMerchant">
      <Expandable title="properties">
        <ResponseField name="acquirerBin" type="string" />

        <ResponseField name="categoryCode" type="string" />

        <ResponseField name="countryCode" type="string">
          ISO 3166-1 alpha-2, upper case.
        </ResponseField>

        <ResponseField name="name" type="string" />

        <ResponseField name="url" type="string">
          http or https URL of the merchant.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="orderIntentId" type="string" />

    <ResponseField name="paymentMethodId" type="string" />

    <ResponseField name="rails" type="OrderIntentRail[]">
      <Expandable title="properties">
        <ResponseField name="credentialFormats" type="OrderIntentCredentialFormat[]" />

        <ResponseField name="provider" type="OrderIntentProvider" />

        <ResponseField name="rail" type="&#x22;agentic-token&#x22;" />
      </Expandable>
    </ResponseField>

    <ResponseField name="status" type="OrderIntentStatus" />

    <ResponseField name="verificationConfig" type="OrderIntentVerificationConfig">
      <Expandable title="properties">
        <ResponseField name="allowanceId" type="string" />

        <ResponseField name="environment" type="&#x22;production&#x22; | &#x22;test&#x22;" />

        <ResponseField name="publicApiKey" type="string" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Usage

```tsx theme={null}
import { OrderIntentVerification, type OrderIntentVerificationProps } from "@crossmint/client-sdk-react-ui";

function VerifyOrderIntent({
    orderIntent,
}: {
    orderIntent: OrderIntentVerificationProps["orderIntent"];
}) {
    return (
        <OrderIntentVerification
            orderIntent={orderIntent}
            displayName="Acme Shopping Agent"
            onVerificationComplete={() => {
                console.log("Allowance verified");
            }}
            onVerificationError={(error) => {
                console.error("Allowance verification failed", error);
            }}
        />
    );
}
```

> **Note:** After `onVerificationComplete`, fetch the order intent again and wait for the `agentic-token` rail to report `status: "active"` before creating a credential.

***

## CrossmintCvcRecollection

Asks the user to enter a saved card's CVC again. Render it when an order intent's `encrypted-card` rail reports `status: "pending_cvc_recollection"`, then refetch the order intent from `onComplete`.

### Props

<ResponseField name="appearance" type="PaymentMethodManagementAppearance">
  Same appearance model as `CrossmintPaymentMethodManagement` and the embedded checkout, not the one of the verification modal: `variables.fontSizeUnit` / `spacingUnit` are multiplier units (defaults `"4px"` / `"3.33px"`), not base sizes. See `EmbeddedCheckoutV3AppearanceVariables`.

  <Expandable title="properties">
    <ResponseField name="fonts" type="EmbeddedCheckoutV3Appearance[&#x22;fonts&#x22;]" />

    <ResponseField name="rules" type="EmbeddedCheckoutV3Appearance[&#x22;rules&#x22;]" />

    <ResponseField name="variables" type="EmbeddedCheckoutV3Appearance[&#x22;variables&#x22;]" />
  </Expandable>
</ResponseField>

<ResponseField name="jwt" type="string">
  The user's Crossmint auth token, the same one `CrossmintPaymentMethodManagement` takes.
</ResponseField>

<ResponseField name="onComplete" type="() => void">
  Called once Crossmint has stored the new CVC. Receives no CVC and no token payload.
</ResponseField>

<ResponseField name="onError" type="(error: object) => void" />

<ResponseField name="paymentMethodId" type="string">
  The saved card whose CVC has to be entered again.
</ResponseField>

### Usage

```tsx theme={null}
import { CrossmintCvcRecollection } from "@crossmint/client-sdk-react-ui";

function RefreshCardCvc({ jwt, paymentMethodId }: { jwt: string; paymentMethodId: string }) {
    return (
        <CrossmintCvcRecollection
            jwt={jwt}
            paymentMethodId={paymentMethodId}
            onComplete={() => {
                console.log("CVC stored, refetch the order intent");
            }}
            onError={(error) => {
                if (!error.retriable) {
                    console.error("CVC recollection failed", error);
                }
            }}
        />
    );
}
```

> **Note:** Render it when an order intent's `encrypted-card` rail reports `status: "pending_cvc_recollection"`, or when creating a credential is refused with HTTP 409 `ORDER_INTENT_CVC_RECOLLECTION_REQUIRED`. Retriable errors keep the form mounted; non-retriable ones unmount it, so show your own message.

***

## CrossmintProtectedInput

Collects the password of the buyer's account on a merchant site inside a Crossmint-hosted iframe and returns an opaque `protectedInputId` to hand to Universal Checkout. The password never reaches this component, the developer's JavaScript, or the agent. Takes the buyer's JWT as a prop, like `CrossmintPaymentMethodManagement`.

### Props

<ResponseField name="appearance" type="ProtectedInputAppearance" />

<ResponseField name="expiresAt" type="string">
  ISO 8601 datetime. Server default is 24 hours from creation; the maximum is 7 days.
</ResponseField>

<ResponseField name="jwt" type="string">
  The buyer's Crossmint auth token, the same one `CrossmintPaymentMethodManagement` takes.
</ResponseField>

<ResponseField name="label" type="string">
  Text shown above the field, for example the merchant name. At most 120 characters.
</ResponseField>

<ResponseField name="merchantUrl" type="string">
  The merchant sign-in page the password is for. Its host becomes the input's merchant domain; Universal Checkout may only use the input on that host or a subdomain of it.
</ResponseField>

<ResponseField name="onCreated" type="(created: { expiresAt: string; merchant: object; protectedInputId: string; purpose: &#x22;password&#x22; }) => void">
  Called once with the opaque `protectedInputId` to hand to Universal Checkout.
</ResponseField>

<ResponseField name="onError" type="(error: { code: string; message: string }) => void" />

### Usage

```tsx theme={null}
import { CrossmintProtectedInput } from "@crossmint/client-sdk-react-ui";

function MerchantPassword({ jwt, onProtectedInputId }: { jwt: string; onProtectedInputId: (id: string) => void }) {
    return (
        <CrossmintProtectedInput
            jwt={jwt}
            merchantUrl="https://shop.example.com/login"
            label="Example Shop"
            onCreated={({ protectedInputId }) => onProtectedInputId(protectedInputId)}
            onError={({ code, message }) => console.error(code, message)}
        />
    );
}
```

> **Note:** CrossmintProtectedInput collects the password of the buyer's account on a merchant site inside a Crossmint-hosted iframe and returns only an opaque protectedInputId. Pass that id to Universal Checkout as the `protected` input response; the password never reaches your JavaScript. Pass the buyer's JWT as `jwt`, like CrossmintPaymentMethodManagement. Lifecycle: the hosted page posts exactly one terminal event per mount, so after onCreated or onError remount the component (change its `key`) to collect again; the page posts `invalid_params` when it rejects the props.


# Get Started
Source: https://docs.crossmint.com/sdk-reference/agents/react/get-started

Installation and setup for the React SDK reference for Crossmint agent payments

### Latest React SDK version - <a href="https://www.npmjs.com/package/@crossmint/client-sdk-react-ui"><img alt="npm" /></a>

The Crossmint React SDK (`@crossmint/client-sdk-react-ui`) provides the user-facing pieces of agent card payments: saving a card, verifying an order intent's allowance with the card network, re-collecting a saved card's CVC, and collecting a merchant password for an agent checkout without it ever reaching your app. Agent wallets use the same wallet providers and hooks as the [Wallets React SDK](/sdk-reference/wallets/react/get-started).

## Installation

<Snippet />

## Provider Setup

Wrap your application with the required providers:

```tsx theme={null}
import type { ReactNode } from "react";
import { CrossmintProvider } from "@crossmint/client-sdk-react-ui";

function App({ children }: { children: ReactNode }) {
    return <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">{children}</CrossmintProvider>;
}
```

> **Note:** The agent card components take the user's JWT directly, so no additional provider is required. Add `CrossmintWalletProvider` only if your agent also uses wallets.

## Quick Example

Once the provider is set up, let the user save a card your agent can pay with:

```tsx theme={null}
import { CrossmintPaymentMethodManagement } from "@crossmint/client-sdk-react-ui";

function PaymentMethodsPage({ jwt }: { jwt: string }) {
    // jwt comes from your own auth provider (for example Stytch, Auth0, Dynamic)
    return (
        <CrossmintPaymentMethodManagement
            jwt={jwt}
            onPaymentMethodSelected={(paymentMethod) => {
                // Persist this ID so your backend can register the card and create order intents.
                console.log("Card saved:", paymentMethod.paymentMethodId);
            }}
        />
    );
}
```

> **Note:** Card data is collected directly by Crossmint and never passes through your servers. Store the returned paymentMethodId on your backend; it is the input for registering the card and creating order intents.

## Next Steps

* [Providers](/sdk-reference/agents/react/providers) — Configure providers and their options
* [Components](/sdk-reference/agents/react/components) — Drop-in UI components


# Providers
Source: https://docs.crossmint.com/sdk-reference/agents/react/providers

React context providers for React SDK reference for Crossmint agent payments

1. `CrossmintProvider` — SDK initialization (required for all Crossmint features)

## CrossmintProvider

### Props

<ResponseField name="apiKey" type="string">
  Your Crossmint client-side API key.
</ResponseField>

<ResponseField name="appId" type="string">
  Application identifier, sent as `x-app-identifier` header.
</ResponseField>

<ResponseField name="consoleLogLevel" type="ConsoleLogLevel">
  Minimum log level for console output (or "silent" to suppress all output). Logs below this level will not be written to the console. Set to "silent" to completely suppress console output. Defaults to "debug" (all logs shown) for backward compatibility.
</ResponseField>

<ResponseField name="extensionId" type="string">
  Extension identifier, sent as `x-extension-id` header.
</ResponseField>

<ResponseField name="jwt" type="string">
  JWT token for authentication.
</ResponseField>

<ResponseField name="overrideBaseUrl" type="string">
  Override the base API URL.
</ResponseField>

### Usage

```tsx theme={null}
import { CrossmintProvider } from "@crossmint/client-sdk-react-ui";

function App() {
    return (
        <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
            {/* Your app content */}
        </CrossmintProvider>
    );
}
```


# Get Started
Source: https://docs.crossmint.com/sdk-reference/auth/react-native/get-started

Installation and setup for the React Native SDK reference for Crossmint authentication

### Latest React Native SDK version - <a href="https://www.npmjs.com/package/@crossmint/client-sdk-react-native-ui"><img alt="npm" /></a>

The Crossmint React Native SDK (`@crossmint/client-sdk-react-native-ui`) provides React Native providers and hooks for integrating Crossmint authentication into your mobile application, including email OTP, social login (OAuth), and session management.

## Installation

<Snippet />

## Provider Setup

Wrap your application with the required providers:

```tsx theme={null}
import {
    CrossmintProvider,
    CrossmintAuthProvider,
} from "@crossmint/client-sdk-react-native-ui";

function App() {
    return (
        <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
            <CrossmintAuthProvider appSchema="myapp://">
                {/* Your app components */}
            </CrossmintAuthProvider>
        </CrossmintProvider>
    );
}
```

## Quick Example

Once providers are set up, use the `useCrossmintAuth` hook to access auth state:

```tsx theme={null}
import { useCrossmintAuth } from "@crossmint/client-sdk-react-native-ui";
import { View, Text, TouchableOpacity } from "react-native";

function LoginScreen() {
    const { loginWithOAuth, logout, user, status } = useCrossmintAuth();

    if (status === "initializing") return <Text>Loading...</Text>;

    if (user == null) {
        return (
            <TouchableOpacity onPress={() => loginWithOAuth("google")}>
                <Text>Sign in with Google</Text>
            </TouchableOpacity>
        );
    }

    return (
        <View>
            <Text>Welcome, {user.email}</Text>
            <TouchableOpacity onPress={logout}>
                <Text>Log out</Text>
            </TouchableOpacity>
        </View>
    );
}
```

## Next Steps

* [Providers](/sdk-reference/auth/react-native/providers) — Configure providers and their options
* [Hooks](/sdk-reference/auth/react-native/hooks) — Access SDK state via React hooks


# Hooks
Source: https://docs.crossmint.com/sdk-reference/auth/react-native/hooks

React Native hooks for React Native SDK reference for Crossmint authentication

## useCrossmintAuth()

Access Crossmint authentication state and actions: `loginWithOAuth`, `logout`, the current `user`, `jwt`, and auth `status`. Must be used within a `CrossmintAuthProvider`.

### Usage

```tsx theme={null}
import { useCrossmintAuth } from "@crossmint/client-sdk-react-native-ui";
import { View, Text, TouchableOpacity } from "react-native";

function AuthStatus() {
    const { loginWithOAuth, logout, user, jwt, status } = useCrossmintAuth();

    if (status === "initializing") return <Text>Loading...</Text>;

    return (
        <View>
            {user == null ? (
                <TouchableOpacity onPress={() => loginWithOAuth("google")}>
                    <Text>Log in</Text>
                </TouchableOpacity>
            ) : (
                <TouchableOpacity onPress={logout}>
                    <Text>Log out ({user.email})</Text>
                </TouchableOpacity>
            )}
        </View>
    );
}
```

> **Note:** Must be used within a CrossmintAuthProvider.


# Providers
Source: https://docs.crossmint.com/sdk-reference/auth/react-native/providers

React Native context providers for React Native SDK reference for Crossmint authentication

1. `CrossmintProvider` — SDK initialization (required for all Crossmint features)
2. `CrossmintAuthProvider` — Authentication state, login/logout, and the auth flow

## CrossmintProvider

Root provider for the Crossmint SDK. Must wrap your entire application. Initializes the SDK with your API key and sets up logging.

### Props

<ResponseField name="apiKey" type="string">
  Your Crossmint client-side API key.
</ResponseField>

<ResponseField name="appId" type="string">
  Application identifier, sent as `x-app-identifier` header.
</ResponseField>

<ResponseField name="consoleLogLevel" type="ConsoleLogLevel">
  Minimum log level for console output (or "silent" to suppress all output). Logs below this level will not be written to the console. Set to "silent" to completely suppress console output. Defaults to "debug" (all logs shown) for backward compatibility.
</ResponseField>

<ResponseField name="overrideBaseUrl" type="string">
  Override the base API URL.
</ResponseField>

### Usage

```tsx theme={null}
import { CrossmintProvider } from "@crossmint/client-sdk-react-native-ui";

function App() {
    return (
        <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
            {/* Your app content */}
        </CrossmintProvider>
    );
}
```

***

## CrossmintAuthProvider

Provides Crossmint authentication to your React Native app: social login (OAuth) and session management. Exposes auth state via the `useCrossmintAuth` hook and stores auth material in secure device storage. Must be nested inside `CrossmintProvider`.

### Props

<ResponseField name="appSchema" type="string | string[]">
  Your app's deep link scheme(s) (e.g. `"myapp://"`), used for OAuth redirects back into your app.
</ResponseField>

<ResponseField name="authModalTitle" type="string">
  Custom title for the auth modal.
</ResponseField>

<ResponseField name="logoutRoute" type="string">
  Custom route for logging out, for server-side session management.
</ResponseField>

<ResponseField name="onLoginSuccess" type="() => void">
  Callback invoked when the user successfully logs in.
</ResponseField>

<ResponseField name="prefetchOAuthUrls" type="boolean">
  Whether to prefetch OAuth provider URLs when the provider mounts.
</ResponseField>

<ResponseField name="refreshRoute" type="string">
  Custom route for refreshing the auth token, for server-side session management.
</ResponseField>

<ResponseField name="storageProvider" type="StorageProvider">
  Custom storage provider for auth material. Defaults to browser cookies on web and secure device storage on React Native.
</ResponseField>

### Usage

```tsx theme={null}
import {
    CrossmintProvider,
    CrossmintAuthProvider,
} from "@crossmint/client-sdk-react-native-ui";

function App() {
    return (
        <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
            <CrossmintAuthProvider appSchema="myapp://">
                {/* Your app content */}
            </CrossmintAuthProvider>
        </CrossmintProvider>
    );
}
```

> **Note:** CrossmintAuthProvider must be nested inside CrossmintProvider. Set appSchema to your app's deep link scheme so OAuth redirects return to your app.


# Components
Source: https://docs.crossmint.com/sdk-reference/auth/react/components

React components for React SDK reference for Crossmint authentication

## EmbeddedAuthForm

Renders the Crossmint auth form inline in your page instead of in a modal. Displays the same login methods configured on `CrossmintAuthProvider`, which it must be rendered inside of.

### Usage

```tsx theme={null}
import { EmbeddedAuthForm, useCrossmintAuth } from "@crossmint/client-sdk-react-ui";

function LoginPage() {
    const { status } = useCrossmintAuth();

    if (status === "logged-in") {
        return <p>You are logged in!</p>;
    }

    return (
        <div style={{ maxWidth: 400, margin: "0 auto" }}>
            <EmbeddedAuthForm />
        </div>
    );
}
```

> **Note:** Must be rendered inside CrossmintAuthProvider. Renders the same auth form shown in the login modal, but inline in your page.


# Get Started
Source: https://docs.crossmint.com/sdk-reference/auth/react/get-started

Installation and setup for the React SDK reference for Crossmint authentication

### Latest React SDK version - <a href="https://www.npmjs.com/package/@crossmint/client-sdk-react-ui"><img alt="npm" /></a>

The Crossmint React SDK (`@crossmint/client-sdk-react-ui`) provides React components and hooks for integrating Crossmint authentication into your application, including email OTP, social login (OAuth), and session management.

## Installation

<Snippet />

## Provider Setup

Wrap your application with the required providers:

```tsx theme={null}
import {
    CrossmintProvider,
    CrossmintAuthProvider,
} from "@crossmint/client-sdk-react-ui";

function App() {
    return (
        <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
            <CrossmintAuthProvider loginMethods={["email", "google"]}>
                {/* Your app content */}
            </CrossmintAuthProvider>
        </CrossmintProvider>
    );
}
```

> **Note:** CrossmintAuthProvider must be nested inside CrossmintProvider.

## Quick Example

Once providers are set up, use the `useCrossmintAuth` hook to access auth state:

```tsx theme={null}
import { useCrossmintAuth } from "@crossmint/client-sdk-react-ui";

function AuthButton() {
    const { login, logout, user, status } = useCrossmintAuth();

    if (status === "logged-in") {
        return (
            <div>
                <p>Welcome, {user?.email}</p>
                <button onClick={logout}>Logout</button>
            </div>
        );
    }

    return <button onClick={() => login()}>Sign In</button>;
}
```

## Next Steps

* [Providers](/sdk-reference/auth/react/providers) — Configure providers and their options
* [Hooks](/sdk-reference/auth/react/hooks) — Access SDK state via React hooks
* [Components](/sdk-reference/auth/react/components) — Drop-in UI components


# Hooks
Source: https://docs.crossmint.com/sdk-reference/auth/react/hooks

React hooks for React SDK reference for Crossmint authentication

## useCrossmintAuth()

Access Crossmint authentication state and actions: `login`, `logout`, the current `user`, `jwt`, and auth `status`. Must be used within a `CrossmintAuthProvider`.

### Returns

<ResponseField name="crossmintAuth" type="any">
  The underlying Crossmint auth client instance.
</ResponseField>

<ResponseField name="getUser" type="() => void">
  Fetch and refresh the current authenticated user.
</ResponseField>

<ResponseField name="jwt" type="string">
  Current JWT authentication token, if authenticated.
</ResponseField>

<ResponseField name="login" type="(defaultEmail: string | MouseEvent<Element, MouseEvent>) => void">
  Trigger the login flow. Optionally pass a default email.
</ResponseField>

<ResponseField name="loginMethods" type="LoginMethod[]">
  Configured login methods.
</ResponseField>

<ResponseField name="loginWithOAuth" type="(provider: OAuthProvider) => Promise<void>">
  Initiate a login flow with the specified OAuth provider (e.g. "google", "twitter").
</ResponseField>

<ResponseField name="logout" type="() => Promise<void>">
  Log the user out and clear the session.
</ResponseField>

<ResponseField name="status" type="AuthStatus">
  Authentication status: "logged-in" | "logged-out" | "in-progress" | "initializing".
</ResponseField>

<ResponseField name="user" type="SDKExternalUser">
  The currently authenticated user object.
</ResponseField>

### Usage

```tsx theme={null}
import { useCrossmintAuth } from "@crossmint/client-sdk-react-ui";

function LoginButton() {
    const { login, logout, user, status } = useCrossmintAuth();

    if (status === "logged-in") {
        return (
            <div>
                <p>Welcome, {user?.email}</p>
                <button onClick={logout}>Logout</button>
            </div>
        );
    }

    return <button onClick={() => login()}>Sign In</button>;
}
```


# Providers
Source: https://docs.crossmint.com/sdk-reference/auth/react/providers

React context providers for React SDK reference for Crossmint authentication

1. `CrossmintProvider` — SDK initialization (required for all Crossmint features)
2. `CrossmintAuthProvider` — Authentication state, login/logout, and the auth modal

## CrossmintProvider

### Props

<ResponseField name="apiKey" type="string">
  Your Crossmint client-side API key.
</ResponseField>

<ResponseField name="appId" type="string">
  Application identifier, sent as `x-app-identifier` header.
</ResponseField>

<ResponseField name="consoleLogLevel" type="ConsoleLogLevel">
  Minimum log level for console output (or "silent" to suppress all output). Logs below this level will not be written to the console. Set to "silent" to completely suppress console output. Defaults to "debug" (all logs shown) for backward compatibility.
</ResponseField>

<ResponseField name="extensionId" type="string">
  Extension identifier, sent as `x-extension-id` header.
</ResponseField>

<ResponseField name="jwt" type="string">
  JWT token for authentication.
</ResponseField>

<ResponseField name="overrideBaseUrl" type="string">
  Override the base API URL.
</ResponseField>

### Usage

```tsx theme={null}
import { CrossmintProvider } from "@crossmint/client-sdk-react-ui";

function App() {
    return (
        <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
            {/* Your app content */}
        </CrossmintProvider>
    );
}
```

***

## CrossmintAuthProvider

Provides Crossmint authentication to your app: email OTP, social login (OAuth), and session management. Exposes auth state via the `useCrossmintAuth` hook and renders the login modal when `login()` is called. Must be nested inside `CrossmintProvider`.

### Props

<ResponseField name="appearance" type="UIConfig">
  Custom UI configuration for the auth modal (colors, fonts, border radius).

  <Expandable title="properties">
    <ResponseField name="borderRadius" type="string" />

    <ResponseField name="colors" type="UiConfigColors">
      <Expandable title="properties">
        <ResponseField name="accent" type="string" />

        <ResponseField name="background" type="string" />

        <ResponseField name="backgroundSecondary" type="string" />

        <ResponseField name="backgroundTertiary" type="string" />

        <ResponseField name="border" type="string" />

        <ResponseField name="buttonBackground" type="string" />

        <ResponseField name="danger" type="string" />

        <ResponseField name="inputBackground" type="string" />

        <ResponseField name="textLink" type="string" />

        <ResponseField name="textPrimary" type="string" />

        <ResponseField name="textSecondary" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="fonts" type="UiConfigFonts">
      <Expandable title="properties">
        <ResponseField name="cssSrc" type="string" />

        <ResponseField name="family" type="string" />

        <ResponseField name="display" type="string" />

        <ResponseField name="src" type="string" />

        <ResponseField name="style" type="&#x22;normal&#x22; | &#x22;italic&#x22; | &#x22;oblique&#x22;" />

        <ResponseField name="weight" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="fontSizeBase" type="string" />

    <ResponseField name="fontWeightPrimary" type="string" />

    <ResponseField name="fontWeightSecondary" type="string" />

    <ResponseField name="hideCardForm" type="boolean" />

    <ResponseField name="spacingUnit" type="string" />
  </Expandable>
</ResponseField>

<ResponseField name="authModalTitle" type="string">
  Custom title for the auth modal.
</ResponseField>

<ResponseField name="loginMethods" type="LoginMethod[]">
  Login methods to enable (e.g. `["email", "google"]`). Defaults to `["email", "google"]`.
</ResponseField>

<ResponseField name="logoutRoute" type="string">
  Custom route for logging out, for server-side session management.
</ResponseField>

<ResponseField name="onLoginSuccess" type="() => void">
  Callback invoked when the user successfully logs in.
</ResponseField>

<ResponseField name="prefetchOAuthUrls" type="boolean">
  Whether to prefetch OAuth provider URLs when the provider mounts. Defaults to `true`.
</ResponseField>

<ResponseField name="refreshRoute" type="string">
  Custom route for refreshing the auth token, for server-side session management.
</ResponseField>

<ResponseField name="storageProvider" type="StorageProvider">
  Custom storage provider for auth material. Defaults to browser cookies on web and secure device storage on React Native.
</ResponseField>

<ResponseField name="termsOfServiceText" type="ReactNode">
  Custom terms of service text shown in the auth modal.
</ResponseField>

### Usage

```tsx theme={null}
import { CrossmintAuthProvider } from "@crossmint/client-sdk-react-ui";

function App() {
    return (
        <CrossmintAuthProvider
            loginMethods={["email", "google"]}
            onLoginSuccess={() => console.log("Logged in!")}
            authModalTitle="Sign in to My App"
        >
            {/* Your app content */}
        </CrossmintAuthProvider>
    );
}
```


# CrossmintAuth
Source: https://docs.crossmint.com/sdk-reference/auth/typescript/classes/CrossmintAuth



Defined in: [server/src/auth/CrossmintAuthServer.ts:38](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/server/src/auth/CrossmintAuthServer.ts#L38)

Server-side Crossmint authentication client: validate sessions, verify JWTs, refresh tokens,
fetch users, and manage auth cookies. Works with both Node.js (`IncomingMessage`/`ServerResponse`)
and Fetch API (`Request`/`Response`) request/response objects.

Create an instance with [CrossmintAuthServer.from](./#from).

## Extends

* `CrossmintAuth`

## Methods

### getJwksUri()

> **getJwksUri**(): `string`

Defined in: common/auth/dist/CrossmintAuth.d.ts:14

#### Returns

`string`

#### Inherited from

`CrossmintAuth.getJwksUri`

***

### getSession()

> **getSession**(`options`, `response`?): `Promise`\<`AuthSession`>

Defined in: [server/src/auth/CrossmintAuthServer.ts:59](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/server/src/auth/CrossmintAuthServer.ts#L59)

Validate the user's session and return it, refreshing it if expired.
Accepts either a request object (auth material is read from cookies) or the auth material
itself (`{ jwt, refreshToken }`). If a response object is provided, refreshed auth material
is stored in its cookies.

#### Parameters

| Parameter | Type |
| - | - |
| `options` | [`GenericRequest`](../type-aliases/GenericRequest) \| `AuthMaterialBasic` |
| `response`? | [`GenericResponse`](../type-aliases/GenericResponse) |

#### Returns

`Promise`\<`AuthSession`>

#### Throws

CrossmintAuthenticationError if no valid session can be established.

***

### getUser()

> **getUser**(`externalUserId`): `Promise`\<`any`>

Defined in: [server/src/auth/CrossmintAuthServer.ts:86](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/server/src/auth/CrossmintAuthServer.ts#L86)

Fetch the Crossmint user associated with the given external user ID.

#### Parameters

| Parameter | Type |
| - | - |
| `externalUserId` | `string` |

#### Returns

`Promise`\<`any`>

***

### handleCustomRefresh()

> **handleCustomRefresh**(`request`, `response`?): `Promise`\<[`GenericResponse`](../type-aliases/GenericResponse)>

Defined in: [server/src/auth/CrossmintAuthServer.ts:102](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/server/src/auth/CrossmintAuthServer.ts#L102)

Handle a token refresh request on a custom refresh route. Reads the refresh token from the
request body or cookies, refreshes the session, and returns a response with the new auth
material stored in cookies. Returns a 401 response if the refresh fails.

#### Parameters

| Parameter | Type |
| - | - |
| `request` | [`GenericRequest`](../type-aliases/GenericRequest) |
| `response`? | [`GenericResponse`](../type-aliases/GenericResponse) |

#### Returns

`Promise`\<[`GenericResponse`](../type-aliases/GenericResponse)>

***

### logout()

> **logout**(`request`?, `response`?): `Promise`\<[`GenericResponse`](../type-aliases/GenericResponse)>

Defined in: [server/src/auth/CrossmintAuthServer.ts:167](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/server/src/auth/CrossmintAuthServer.ts#L167)

Log the user out: invalidate the refresh token with Crossmint and clear the auth cookies on the response.

#### Parameters

| Parameter | Type |
| - | - |
| `request`? | [`GenericRequest`](../type-aliases/GenericRequest) |
| `response`? | [`GenericResponse`](../type-aliases/GenericResponse) |

#### Returns

`Promise`\<[`GenericResponse`](../type-aliases/GenericResponse)>

***

### storeAuthMaterial()

> **storeAuthMaterial**(`response`, `authMaterial`): `void`

Defined in: [server/src/auth/CrossmintAuthServer.ts:162](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/server/src/auth/CrossmintAuthServer.ts#L162)

Store auth material (JWT and refresh token) in the response's cookies.

#### Parameters

| Parameter | Type |
| - | - |
| `response` | [`GenericResponse`](../type-aliases/GenericResponse) |
| `authMaterial` | `AuthMaterial` |

#### Returns

`void`

***

### verifyCrossmintJwt()

> **verifyCrossmintJwt**(`token`, `jwks`?): `Promise`\<`JWTPayload`>

Defined in: [server/src/auth/CrossmintAuthServer.ts:154](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/server/src/auth/CrossmintAuthServer.ts#L154)

Verify a Crossmint-issued JWT and return its decoded payload. Uses Crossmint's JWKS endpoint unless a key set is provided.

#### Parameters

| Parameter | Type |
| - | - |
| `token` | `string` |
| `jwks`? | `JSONWebKeySet` |

#### Returns

`Promise`\<`JWTPayload`>

***

### defaultApiClient()

> `static` **defaultApiClient**(`crossmint`): `CrossmintApiClient`

Defined in: common/auth/dist/CrossmintAuth.d.ts:19

#### Parameters

| Parameter | Type |
| - | - |
| `crossmint` | `Crossmint` |

#### Returns

`CrossmintApiClient`

#### Inherited from

`CrossmintAuth.defaultApiClient`

***

### from()

> `static` **from**(`crossmint`, `options`): `CrossmintAuthServer`

Defined in: [server/src/auth/CrossmintAuthServer.ts:47](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/server/src/auth/CrossmintAuthServer.ts#L47)

Create a `CrossmintAuth` instance from a `Crossmint` object (created with `createCrossmint`).

#### Parameters

| Parameter | Type |
| - | - |
| `crossmint` | `Crossmint` |
| `options` | [`CrossmintAuthServerOptions`](../type-aliases/CrossmintAuthServerOptions) |

#### Returns

`CrossmintAuthServer`

#### Overrides

`CrossmintAuth.from`


# createCrossmint
Source: https://docs.crossmint.com/sdk-reference/auth/typescript/functions/createCrossmint



> **createCrossmint**(`config`, `apiKeyExpectations`?): `Crossmint`

Defined in: common/base/dist/types/Crossmint.d.ts:19

## Parameters

| Parameter | Type |
| - | - |
| `config` | `CrossmintConfig` |
| `apiKeyExpectations`? | `ValidateAPIKeyPrefixExpectations` |

## Returns

`Crossmint`


# verifyCrossmintJwt
Source: https://docs.crossmint.com/sdk-reference/auth/typescript/functions/verifyCrossmintJwt



> **verifyCrossmintJwt**(`token`, `jwks`): `Promise`\<`JWTPayload`>

Defined in: [server/src/auth/utils/jwt.ts:9](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/server/src/auth/utils/jwt.ts#L9)

Verify a Crossmint-issued JWT against the given JWKS (endpoint URI or key set) and return its decoded payload.

## Parameters

| Parameter | Type |
| - | - |
| `token` | `string` |
| `jwks` | [`JWKSInput`](../type-aliases/JWKSInput) |

## Returns

`Promise`\<`JWTPayload`>


# Getting Started
Source: https://docs.crossmint.com/sdk-reference/auth/typescript/overview



### Latest Node.js SDK version - <a href="https://www.npmjs.com/package/@crossmint/server-sdk"><img alt="npm" /></a>

The Crossmint server SDK (`@crossmint/server-sdk`) provides a set of tools for authenticating users in a Crossmint-powered application using server-side rendering (SSR). It simplifies the process of handling authentication tokens and managing user sessions, making it easier to integrate authentication into your Next.js applications.

## Installation

To install the SDK, you can use npm or yarn:

```bash theme={null}
npm install @crossmint/server-sdk
```

## Usage

To use the SDK in your application, follow these steps:

1. Import the SDK into your project:

```ts theme={null}
import { createCrossmint, CrossmintAuth } from "@crossmint/server-sdk";

const crossmint = createCrossmint({
    apiKey: process.env.SERVER_CROSSMINT_API_KEY || "",
});

const crossmintAuth = CrossmintAuth.from(crossmint);
```

2. Use the SDK to authenticate users:

With most frameworks, pass the request object:

```ts theme={null}
const { jwt, userId } = await crossmintAuth.getSession(request);
```

With Next.js, fetch the cookies and pass them to the `getSession` method:

```ts theme={null}
import { cookies } from "next/headers";

const cookieStore = cookies();
const jwtCookie = cookieStore.get("crossmint-jwt")?.value;
const refreshCookie = cookieStore.get("crossmint-refresh-token")?.value;

const { jwt, userId } = await crossmintAuth.getSession({
    jwt: jwtCookie,
    refreshToken: refreshCookie,
});
```

3. Store the authentication material in cookies

If you are using a framework with access to the response object, you can store the authentication material in cookies by passing the response object to the `getSession` method:

```ts theme={null}
const { jwt, userId } = await crossmintAuth.getSession(request, response);
```

4. Logout

```ts theme={null}
await crossmintAuth.logout(request);
```

## Security

The SDK allows you to set the `httpOnly`, `secure`, `domain` and `sameSite` options for the cookies. This way, you can control how the cookies are stored and transmitted. Putting this together with a custom refresh route, you can store the authentication material in HttpOnly cookies that are tied to the domain of the provided route.

Configure CrossmintAuth to do so when creating the custom refresh route:

```ts theme={null}
const crossmintAuth = CrossmintAuth.from(crossmint, {
    cookieOptions: {
        httpOnly: true,
        sameSite: "Strict",
        secure: true,
        domain: ".example.com",
    },
});
```

`httpOnly` only applies to the refresh token. The session token will not be HttpOnly as it is used in the client for API calls.

## Set up a custom refresh route

To set up a custom refresh route, you can use the `handleCustomRefresh` method. This method will refresh the token and return the new authentication material. This way, the authentication material can be stored in cookies that are tied to the domain of the provided route.

In environments that use the Fetch API for `Request` and `Response` objects, `handleCustomRefresh` will return the response object:

```ts theme={null}
return await crossmintAuth.handleCustomRefresh(request);
```

In environments that use Node.js API, you also need to provide the response object and end the response:

```ts theme={null}
await crossmintAuth.handleCustomRefresh(req, res);
res.end();
```

### Using a custom refresh route

You can also provide a custom refresh route:

```typescript theme={null}
const crossmintAuth = CrossmintAuth.from(crossmint, {
    refreshRoute: "/api/refresh",
});
```

This way, the SDK will use the provided route to refresh the token instead of the default one and the authentication material can be stored in HttpOnly cookies that are tied to the domain of the provided route.

## Set up a custom logout route

When using `HttpOnly` cookies, logout can't happen client-side as it doesn't have access to the cookies. You can set up a custom logout route to handle the logout process.

In environments that use the Fetch API, `logout` will return the response object:

```ts theme={null}
return await crossmintAuth.logout(request);
```

In environments that use Node.js API, you also need to provide the response object and end the response:

```ts theme={null}
await crossmintAuth.logout(req, res);
res.end();
```


# Reference
Source: https://docs.crossmint.com/sdk-reference/auth/typescript/reference



## Classes

* [CrossmintAuth](./classes/CrossmintAuth)

## Type Aliases

* [CrossmintAuthServerOptions](./type-aliases/CrossmintAuthServerOptions)
* [GenericRequest](./type-aliases/GenericRequest)
* [GenericResponse](./type-aliases/GenericResponse)
* [JWKSInput](./type-aliases/JWKSInput)

## Variables

* [CROSSMINT\_API\_VERSION](./variables/CROSSMINT_API_VERSION)
* [SDK\_NAME](./variables/SDK_NAME)
* [SDK\_VERSION](./variables/SDK_VERSION)

## Functions

* [createCrossmint](./functions/createCrossmint)
* [verifyCrossmintJwt](./functions/verifyCrossmintJwt)


# CrossmintAuthServerOptions
Source: https://docs.crossmint.com/sdk-reference/auth/typescript/type-aliases/CrossmintAuthServerOptions



> **CrossmintAuthServerOptions** = `CrossmintAuthOptions` & `object`

Defined in: [server/src/auth/CrossmintAuthServer.ts:26](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/server/src/auth/CrossmintAuthServer.ts#L26)

## Type Declaration

### cookieOptions?

> `optional` **cookieOptions**: `CookieOptions`

Options applied to the auth cookies set by the SDK (e.g. `domain`).


# GenericRequest
Source: https://docs.crossmint.com/sdk-reference/auth/typescript/type-aliases/GenericRequest



> **GenericRequest** = `IncomingMessage` | `Request`

Defined in: [server/src/auth/types/request.ts:4](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/server/src/auth/types/request.ts#L4)


# GenericResponse
Source: https://docs.crossmint.com/sdk-reference/auth/typescript/type-aliases/GenericResponse



> **GenericResponse** = `ServerResponse` | `Response`

Defined in: [server/src/auth/types/request.ts:5](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/server/src/auth/types/request.ts#L5)


# JWKSInput
Source: https://docs.crossmint.com/sdk-reference/auth/typescript/type-aliases/JWKSInput



> **JWKSInput** = `string` | `JSONWebKeySet`

Defined in: [server/src/auth/utils/jwt.ts:6](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/server/src/auth/utils/jwt.ts#L6)

A JWKS endpoint URI or an inline JSON Web Key Set.


# CROSSMINT_API_VERSION
Source: https://docs.crossmint.com/sdk-reference/auth/typescript/variables/CROSSMINT_API_VERSION



> `const` **CROSSMINT\_API\_VERSION**: `"2024-09-26"` = `"2024-09-26"`

Defined in: [server/src/auth/utils/constants.ts:5](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/server/src/auth/utils/constants.ts#L5)


# SDK_NAME
Source: https://docs.crossmint.com/sdk-reference/auth/typescript/variables/SDK_NAME



> `const` **SDK\_NAME**: `string` = `name`

Defined in: [server/src/auth/utils/constants.ts:4](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/server/src/auth/utils/constants.ts#L4)


# SDK_VERSION
Source: https://docs.crossmint.com/sdk-reference/auth/typescript/variables/SDK_VERSION



> `const` **SDK\_VERSION**: `string` = `version`

Defined in: [server/src/auth/utils/constants.ts:3](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/server/src/auth/utils/constants.ts#L3)


# CrossmintCheckoutAppearance
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/classes/crossmint-checkout-appearance

Flutter Final Class

**Final Class**

UI customization for the hosted checkout page.

```dart theme={null}
final class CrossmintCheckoutAppearance
```

Supports three levels of customization:

* `variables` — CSS custom properties (e.g. `colorPrimary`, `borderRadius`)
* `rules` — CSS rules targeting specific elements (e.g. `.Input`, `.Tab`)
* `fonts` — custom web fonts via `cssSrc`

## Constructors

### CrossmintCheckoutAppearance

```dart theme={null}
const CrossmintCheckoutAppearance({this.variables, this.rules, this.fonts})
```

## Properties

### variables

```dart theme={null}
final Map<String, Object?>? variables
```

CSS custom properties for theming (e.g. `{'colorPrimary': '#0F172A'}`).

### rules

```dart theme={null}
final Map<String, Object?>? rules
```

CSS rules for specific checkout elements (e.g. `{'.Input': {'borderColor': '#CBD5E1'}}`).

### fonts

```dart theme={null}
final List<Map<String, String>>? fonts
```

Custom font definitions (e.g. `[{'cssSrc': 'https://fonts.googleapis.com/...'}]`).

## Methods

### toJson

```dart theme={null}
Map<String, Object?> toJson()
```

Serializes the appearance configuration to a JSON-compatible map.


# CrossmintCheckoutCollectionLineItem
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/classes/crossmint-checkout-collection-line-item

Flutter Final Class

**Final Class**

Line item that mints from a Crossmint collection. Usually built via `CrossmintCheckoutLineItem.collection`.

```dart theme={null}
final class CrossmintCheckoutCollectionLineItem extends CrossmintCheckoutLineItem
```

## Constructors

### CrossmintCheckoutCollectionLineItem

```dart theme={null}
const CrossmintCheckoutCollectionLineItem({
  required this.collectionLocator,
  this.callData,
  this.additionalFields = const <String, Object?>{},
})
```

Creates a collection line item.

## Properties

### collectionLocator

```dart theme={null}
final String collectionLocator
```

Crossmint collection locator (e.g. `"crossmint:<collection-id>"`).

### callData

```dart theme={null}
final Map<String, Object?>? callData
```

Optional call data passed to the on-chain mint (e.g. quantity, metadata overrides).

### additionalFields

```dart theme={null}
final Map<String, Object?> additionalFields
```

Forward-compatibility escape hatch — extra keys appended to the JSON payload. Use for API fields the current SDK version does not model.


# CrossmintCheckoutConfig
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/classes/crossmint-checkout-config

Flutter Final Class

**Final Class**

Configuration for `CrossmintEmbeddedCheckout`.

```dart theme={null}
final class CrossmintCheckoutConfig
```

## Constructors

### CrossmintCheckoutConfig

```dart theme={null}
const CrossmintCheckoutConfig({
  required this.order,
  required this.payment,
  this.appearance,
  this.jwt,
  this.identityVerificationHandling,
})
```

Creates a checkout config.

## Properties

### order

```dart theme={null}
final CrossmintCheckoutOrder order
```

Order to check out — either a `CrossmintCheckoutNewOrder` built from line items, or a `CrossmintCheckoutExistingOrder` referencing an already-created order by id.

### payment

```dart theme={null}
final CrossmintCheckoutPayment payment
```

Payment method configuration — fiat, crypto, and default method.

### appearance

```dart theme={null}
final CrossmintCheckoutAppearance? appearance
```

Optional appearance customization — CSS variables, rules, fonts.

### jwt

```dart theme={null}
final String? jwt
```

Optional JWT for authenticated checkouts — attaches the user's Crossmint session to the hosted page so the experience is signed-in when the user lands. Pass `client.auth.state.session?.jwt` when you want the checkout to inherit the current app session.

### identityVerificationHandling

```dart theme={null}
final CrossmintIdentityVerificationHandling? identityVerificationHandling
```

Optional takeover of the identity verification step. Requires a Crossmint deployment that understands the flag; against an older one it is ignored and checkout renders verification itself.

## Methods

### toQueryParams

```dart theme={null}
Map<String, String> toQueryParams()
```

Serializes to query parameters for the checkout URL.


# CrossmintCheckoutController
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/classes/crossmint-checkout-controller

Flutter Class

**Class**

Reactive controller for checkout order state, matching the official Crossmint RN SDK's `useCrossmintCheckout()` hook.

```dart theme={null}
class CrossmintCheckoutController extends ChangeNotifier
```

Pass this to `CrossmintEmbeddedCheckout` to receive order updates
as observable state instead of (or in addition to) the `onOrderUpdated`
callback.

```dart theme={null}
// Pseudocode: replace `yourCheckoutConfig` with a real
// `CrossmintCheckoutConfig` instance.
final checkoutController = CrossmintCheckoutController();

// In widget tree:
CrossmintEmbeddedCheckout(
  apiKey: 'YOUR_API_KEY',
  config: yourCheckoutConfig,
  checkoutController: checkoutController,
)

// Listen reactively:
ListenableBuilder(
  listenable: checkoutController,
  builder: (context, _) {
    final order = checkoutController.order;
    return Text('Status: ${order?['status']}');
  },
)
```

## Properties

### order

```dart theme={null}
Map<String, Object?>? get order
```

The current order object from the checkout, or `null` if no order yet.

### orderClientSecret

```dart theme={null}
String? get orderClientSecret
```

The server-assigned client secret for the current order.

### identityVerificationCredentials

```dart theme={null}
CrossmintIdentityVerificationCredentials? get identityVerificationCredentials
```

Verification credentials for the current order, or `null` when the order does not need identity verification. Pass these to `CrossmintIdentityVerification` when checkout runs with `identityVerificationHandling` set to external.

## Methods

### updateOrder

```dart theme={null}
void updateOrder(Map<String, Object?> data)
```

Updates the order state from a checkout `order:updated` event.

### clear

```dart theme={null}
void clear()
```

Clears the order state.


# CrossmintCheckoutCryptoPayment
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/classes/crossmint-checkout-crypto-payment

Flutter Final Class

**Final Class**

Crypto payment configuration — on-chain payment via a user-connected wallet or the Crossmint-hosted wallet flow.

```dart theme={null}
final class CrossmintCheckoutCryptoPayment
```

Set `enabled` to `false` to hide the crypto tab. When enabled, optionally
attach a `payer` to let the app drive signing —
`CrossmintEvmWalletCheckoutPayer` is the easiest way to bridge a
`CrossmintEvmWallet` into a payer.

## Constructors

### CrossmintCheckoutCryptoPayment

```dart theme={null}
const CrossmintCheckoutCryptoPayment({
  required this.enabled,
  this.defaultChain,
  this.defaultCurrency,
  this.payer,
})
```

Creates a crypto payment config.

## Properties

### enabled

```dart theme={null}
final bool enabled
```

Whether crypto payments are enabled.

### defaultChain

```dart theme={null}
final String? defaultChain
```

Chain preselected in the crypto tab (e.g. `"base"`, `"solana"`). Must appear in the payer's `CrossmintCheckoutPayer.supportedChains` when a payer is attached.

### defaultCurrency

```dart theme={null}
final String? defaultCurrency
```

Currency preselected in the crypto tab (e.g. `"USDC"`).

### payer

```dart theme={null}
final CrossmintCheckoutPayer? payer
```

Optional app-side signer bridge. When null, the hosted page presents its own wallet-connect flow.


# CrossmintCheckoutDiagnostic
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/classes/crossmint-checkout-diagnostic

Flutter Class

**Class**

Structured runtime signal emitted by `CrossmintEmbeddedCheckout`.

```dart theme={null}
class CrossmintCheckoutDiagnostic
```

## Constructors

### CrossmintCheckoutDiagnostic

```dart theme={null}
const CrossmintCheckoutDiagnostic({
  required this.code,
  required this.message,
  required this.severity,
  this.event,
  this.uri,
  this.details = const <String, Object?>{},
})
```

Creates a diagnostic record.

## Properties

### code

```dart theme={null}
final String code
```

Short machine-readable identifier (e.g. `"navigation.blocked"`, `"message.parse_failed"`).

### message

```dart theme={null}
final String message
```

Human-readable description of the diagnostic.

### severity

```dart theme={null}
final CrossmintCheckoutDiagnosticSeverity severity
```

Severity classification — one of `CrossmintCheckoutDiagnosticSeverity`: `info` (interesting but not a problem, e.g. user closed the hosted modal), `warning` (likely recoverable — surface in dev / staging), `error` (hosted flow hit a problem that may affect checkout). Pass to logging infrastructure accordingly.

### event

```dart theme={null}
final String? event
```

Hosted-page event associated with this diagnostic, if any (e.g. the original postMessage event name that failed to parse).

### uri

```dart theme={null}
final Uri? uri
```

URL associated with this diagnostic — set for navigation-related diagnostics (blocked navigations, resource errors).

### details

```dart theme={null}
final Map<String, Object?> details
```

Extra structured context for the diagnostic. Keys are stable — safe to forward to logging.


# CrossmintCheckoutEmailRecipient
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/classes/crossmint-checkout-email-recipient

Flutter Final Class

**Final Class**

Email-based recipient — mints into a Crossmint-managed wallet associated with the email address. Pair with `physicalAddress` when the line items include physical fulfillment.

```dart theme={null}
final class CrossmintCheckoutEmailRecipient extends CrossmintCheckoutRecipient
```

## Constructors

### CrossmintCheckoutEmailRecipient

```dart theme={null}
const CrossmintCheckoutEmailRecipient({
  required this.email,
  this.physicalAddress,
})
```

Creates an email recipient.

## Properties

### email

```dart theme={null}
final String email
```

Recipient email address.

### physicalAddress

```dart theme={null}
final CrossmintCheckoutPhysicalAddress? physicalAddress
```

Optional shipping address for physical line items.


# CrossmintCheckoutExistingOrder
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/classes/crossmint-checkout-existing-order

Flutter Final Class

**Final Class**

Reference an existing Crossmint order by ID.

```dart theme={null}
final class CrossmintCheckoutExistingOrder extends CrossmintCheckoutOrder
```

## Constructors

### CrossmintCheckoutExistingOrder

```dart theme={null}
const CrossmintCheckoutExistingOrder({
  required this.orderId,
  this.clientSecret,
})
```

## Properties

### orderId

```dart theme={null}
final String orderId
```

Identifier of an order previously created via the Crossmint orders API (server-side) or a prior embedded-checkout session. The hosted checkout resumes this order instead of creating a new one.

### clientSecret

```dart theme={null}
final String? clientSecret
```

Client secret returned alongside `orderId` when the order was created server-side. Required for orders created with a server API key so the hosted checkout can authorize against the existing order. Leave null when the current session already has access to `orderId` (for example, orders created from this same client).


# CrossmintCheckoutFiatPayment
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/classes/crossmint-checkout-fiat-payment

Flutter Final Class

**Final Class**

Fiat payment configuration — credit card, Apple Pay, Google Pay.

```dart theme={null}
final class CrossmintCheckoutFiatPayment
```

Set `enabled` to `false` and leave the rest null to hide the fiat tab
entirely. When `enabled` is `true`, method availability defaults to the
merchant / project configuration on the server — override individual
methods via `allowCard`, `allowApplePay`, `allowGooglePay`.

## Constructors

### CrossmintCheckoutFiatPayment

```dart theme={null}
const CrossmintCheckoutFiatPayment({
  required this.enabled,
  this.defaultCurrency,
  this.allowCard,
  this.allowApplePay,
  this.allowGooglePay,
})
```

Creates a fiat payment config.

## Properties

### enabled

```dart theme={null}
final bool enabled
```

Whether fiat payments are enabled.

### defaultCurrency

```dart theme={null}
final String? defaultCurrency
```

ISO 4217 currency code preselected in the fiat tab (e.g. `"USD"`).

### allowCard

```dart theme={null}
final bool? allowCard
```

When `false`, hides the credit-card payment method. `null` keeps the project default.

### allowApplePay

```dart theme={null}
final bool? allowApplePay
```

When `false`, hides Apple Pay. `null` keeps the project default.

### allowGooglePay

```dart theme={null}
final bool? allowGooglePay
```

When `false`, hides Google Pay. `null` keeps the project default.


# CrossmintCheckoutLineItem
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/classes/crossmint-checkout-line-item

Flutter Sealed Class

**Sealed Class**

A single asset to purchase in a checkout order.

```dart theme={null}
sealed class CrossmintCheckoutLineItem
```

Use the named factory constructors to create line items:

* `CrossmintCheckoutLineItem.collection` — primary sale from a managed or
  imported collection. Supports optional `callData` for contract mint args.
* `CrossmintCheckoutLineItem.token` — secondary sale of a specific token,
  with optional `callData` for contract arguments.
* `CrossmintCheckoutLineItem.tokenWithExecutionParameters` — secondary sale
  (e.g. memecoin swap) with execution parameters controlling amount, mode,
  and slippage. Mutually exclusive with `callData`.
* `CrossmintCheckoutLineItem.product` — product-based purchase using a
  Crossmint product locator.
* `CrossmintCheckoutLineItem.raw` — forward-compatible escape hatch for
  line-item shapes not yet modeled by the SDK.

## Constructors

### CrossmintCheckoutLineItem

```dart theme={null}
const CrossmintCheckoutLineItem()
```

### CrossmintCheckoutLineItem.collection

```dart theme={null}
factory CrossmintCheckoutLineItem.collection({
  required String collectionLocator,
  Map<String, Object?>? callData,
  Map<String, Object?> additionalFields,
}) = CrossmintCheckoutCollectionLineItem
```

Creates a collection line item for primary sales.

### CrossmintCheckoutLineItem.token

```dart theme={null}
factory CrossmintCheckoutLineItem.token({
  required String tokenLocator,
  Map<String, Object?>? callData,
  Map<String, Object?> additionalFields,
}) = CrossmintCheckoutTokenLineItem
```

Creates a token line item for secondary sales with optional `callData`.

### CrossmintCheckoutLineItem.tokenWithExecutionParameters

```dart theme={null}
factory CrossmintCheckoutLineItem.tokenWithExecutionParameters({
  required String tokenLocator,
  required Map<String, Object?> executionParameters,
  Map<String, Object?> additionalFields,
}) = CrossmintCheckoutTokenExecutionLineItem
```

Creates a token line item with execution parameters for secondary sales (e.g. memecoins with slippage and amount control).

### CrossmintCheckoutLineItem.product

```dart theme={null}
factory CrossmintCheckoutLineItem.product({
  required String productLocator,
  Map<String, Object?> additionalFields,
}) = CrossmintCheckoutProductLineItem
```

Creates a product line item identified by a Crossmint `productLocator`. Use this for catalog-managed product purchases where the price and SKU are resolved server-side from the locator.

### CrossmintCheckoutLineItem.raw

```dart theme={null}
factory CrossmintCheckoutLineItem.raw({required Map<String, Object?> value}) =
CrossmintCheckoutRawLineItem
```

Forward-compatible escape hatch — passes `value` verbatim to the Crossmint orders API as the line item shape. Use when a new line-item field is not yet modeled by the typed factories above.


# CrossmintCheckoutNewOrder
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/classes/crossmint-checkout-new-order

Flutter Final Class

**Final Class**

Create a new order inline with line items, recipient, and locale.

```dart theme={null}
final class CrossmintCheckoutNewOrder extends CrossmintCheckoutOrder
```

The raw `lineItems` constructor remains available as the forward-compatible
escape hatch. Prefer `CrossmintCheckoutNewOrder.typed` when the current SDK
models the line-item shape you need.

## Constructors

### CrossmintCheckoutNewOrder

```dart theme={null}
const CrossmintCheckoutNewOrder({
  required this.lineItems,
  this.recipient,
  this.locale,
  this.metadata,
})
```

### CrossmintCheckoutNewOrder.typed

```dart theme={null}
CrossmintCheckoutNewOrder.typed({
  required List<CrossmintCheckoutLineItem> lineItems,
  this.recipient,
  this.locale,
  this.metadata,
})
```

## Properties

### lineItems

```dart theme={null}
final List<Map<String, Object?>> lineItems
```

Line items in the order, each represented as a raw JSON map. Prefer the `CrossmintCheckoutNewOrder.typed` constructor and pass typed `CrossmintCheckoutLineItem` values; use the raw map shape only when a new API field is not yet modeled by the SDK.

### recipient

```dart theme={null}
final CrossmintCheckoutRecipient? recipient
```

Optional recipient for the order. When omitted, the hosted checkout collects recipient details from the buyer.

### locale

```dart theme={null}
final String? locale
```

Optional BCP 47 locale tag (for example `en-US`, `es`, `pt-BR`) used to localize the hosted checkout UI. Defaults to the buyer's browser locale when null.

### metadata

```dart theme={null}
final Map<String, Object?>? metadata
```

Optional opaque metadata attached to the order. Forwarded verbatim to the Crossmint orders API and returned on order webhooks and status reads.


# CrossmintCheckoutOrder
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/classes/crossmint-checkout-order

Flutter Sealed Class

**Sealed Class**

How to create an order: reference an existing one or define new line items.

```dart theme={null}
sealed class CrossmintCheckoutOrder
```

## Constructors

### CrossmintCheckoutOrder

```dart theme={null}
const CrossmintCheckoutOrder()
```


# CrossmintCheckoutPayer
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/classes/crossmint-checkout-payer

Flutter Abstract Interface Class

**Abstract Interface Class**

Interface for apps to provide crypto wallet signing capabilities.

```dart theme={null}
abstract interface class CrossmintCheckoutPayer
```

When crypto payments are enabled in the checkout, the hosted page will
request transaction signing via postMessage. The app implements this
interface to bridge to its wallet.

Prefer attaching the payer under `payment.crypto.payer` in
`CrossmintCheckoutConfig`. The widget-level
`CrossmintEmbeddedCheckout.payer` override is retained for compatibility.

## Properties

### address

```dart theme={null}
String get address
```

Current wallet address.

### initialChain

```dart theme={null}
String get initialChain
```

Chain the wallet is initially connected on.

### supportedChains

```dart theme={null}
List<String> get supportedChains
```

Chains the wallet can sign transactions on. The hosted checkout only offers chains that appear here.

### walletProviderKey

```dart theme={null}
String? get walletProviderKey
```

Optional wallet provider identifier (e.g. "metamask", "coinbase"). Returns null if not applicable.

## Methods

### signAndSendTransaction

```dart theme={null}
Future<CrossmintCheckoutTransactionResult> signAndSendTransaction(
  String serializedTransaction,
)
```

Signs and broadcasts a serialized transaction. Return `CrossmintCheckoutTransactionSuccess` with the transaction id on success, or `CrossmintCheckoutTransactionFailure` with a user-facing message on failure.

### switchChain

```dart theme={null}
Future<void> switchChain(String chain)
```

Switches the wallet to `chain`. Called by the hosted page when the user changes chain in the UI.

### signMessage

```dart theme={null}
Future<String>? signMessage(String message)
```

Optional — return null if message signing is not supported.


# CrossmintCheckoutPayment
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/classes/crossmint-checkout-payment

Flutter Final Class

**Final Class**

Payment configuration for the embedded checkout.

```dart theme={null}
final class CrossmintCheckoutPayment
```

At least one of `fiat` or `crypto` must be enabled. When both are
configured, `defaultMethodType` (or `defaultMethod`) controls which
method the checkout opens on first.

## Constructors

### CrossmintCheckoutPayment

```dart theme={null}
const CrossmintCheckoutPayment({
  this.fiat,
  this.crypto,
  this.defaultMethod,
  this.defaultMethodType,
  this.receiptEmail,
})
```

Creates a payment configuration.

## Properties

### fiat

```dart theme={null}
final CrossmintCheckoutFiatPayment? fiat
```

Fiat (card, Apple Pay, Google Pay) configuration — null disables the fiat tab entirely.

### crypto

```dart theme={null}
final CrossmintCheckoutCryptoPayment? crypto
```

Crypto payment configuration — null disables the crypto tab.

### defaultMethod

```dart theme={null}
final String? defaultMethod
```

Raw default payment method string. Prefer `defaultMethodType` for compile-time safety. When both are set, `defaultMethodType` wins.

### defaultMethodType

```dart theme={null}
final CrossmintCheckoutDefaultMethod? defaultMethodType
```

Typed default payment method — one of `CrossmintCheckoutDefaultMethod`: `fiat` (open on credit card / Apple Pay / Google Pay) or `crypto` (open on on-chain payment). Takes precedence over `defaultMethod`.

### receiptEmail

```dart theme={null}
final String? receiptEmail
```

Email to receive the order receipt. Leave null to use the recipient email (for `CrossmintCheckoutEmailRecipient`) or rely on the user entering an email inside the hosted page.


# CrossmintCheckoutPhysicalAddress
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/classes/crossmint-checkout-physical-address

Flutter Final Class

**Final Class**

Shipping address used for physical goods. Required on `CrossmintCheckoutPhysicalRecipient`; optional on email and wallet recipients whose line items include physical fulfillment.

```dart theme={null}
final class CrossmintCheckoutPhysicalAddress
```

All fields except `line2` are required and must be non-blank.

## Constructors

### CrossmintCheckoutPhysicalAddress

```dart theme={null}
const CrossmintCheckoutPhysicalAddress({
  required this.name,
  required this.line1,
  this.line2,
  required this.city,
  required this.state,
  required this.postalCode,
  required this.country,
})
```

Creates a physical address.

## Properties

### name

```dart theme={null}
final String name
```

Recipient name.

### line1

```dart theme={null}
final String line1
```

Primary street address line.

### line2

```dart theme={null}
final String? line2
```

Optional secondary street address line (apt, suite, etc.).

### city

```dart theme={null}
final String city
```

City / locality.

### state

```dart theme={null}
final String state
```

State, province, or administrative region.

### postalCode

```dart theme={null}
final String postalCode
```

Postal / ZIP code.

### country

```dart theme={null}
final String country
```

ISO 3166-1 alpha-2 country code (e.g. `"US"`, `"GB"`, `"JP"`).


# CrossmintCheckoutPhysicalRecipient
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/classes/crossmint-checkout-physical-recipient

Flutter Final Class

**Final Class**

Physical-only recipient — ships a physical good without minting to a wallet. Requires both `email` (for receipts / order updates) and `physicalAddress`.

```dart theme={null}
final class CrossmintCheckoutPhysicalRecipient extends CrossmintCheckoutRecipient
```

Use this for pure-merchandise line items where there is no on-chain
asset to deliver.

## Constructors

### CrossmintCheckoutPhysicalRecipient

```dart theme={null}
const CrossmintCheckoutPhysicalRecipient({
  required this.email,
  required this.physicalAddress,
})
```

Creates a physical-only recipient.

## Properties

### email

```dart theme={null}
final String email
```

Recipient email — used for order receipts and updates.

### physicalAddress

```dart theme={null}
final CrossmintCheckoutPhysicalAddress physicalAddress
```

Required shipping address.


# CrossmintCheckoutProductLineItem
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/classes/crossmint-checkout-product-line-item

Flutter Final Class

**Final Class**

Line item that purchases a product (often physical or hybrid). Usually built via `CrossmintCheckoutLineItem.product`.

```dart theme={null}
final class CrossmintCheckoutProductLineItem extends CrossmintCheckoutLineItem
```

## Constructors

### CrossmintCheckoutProductLineItem

```dart theme={null}
const CrossmintCheckoutProductLineItem({
  required this.productLocator,
  this.additionalFields = const <String, Object?>{},
})
```

Creates a product line item.

## Properties

### productLocator

```dart theme={null}
final String productLocator
```

Product locator registered with Crossmint.

### additionalFields

```dart theme={null}
final Map<String, Object?> additionalFields
```

Forward-compatibility escape hatch.


# CrossmintCheckoutRawLineItem
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/classes/crossmint-checkout-raw-line-item

Flutter Final Class

**Final Class**

Escape-hatch line item that passes an arbitrary JSON shape straight to the Crossmint API. Use when the current SDK models do not cover a new API field. Usually built via `CrossmintCheckoutLineItem.raw`.

```dart theme={null}
final class CrossmintCheckoutRawLineItem extends CrossmintCheckoutLineItem
```

## Constructors

### CrossmintCheckoutRawLineItem

```dart theme={null}
const CrossmintCheckoutRawLineItem({required this.value})
```

Creates a raw line item.

## Properties

### value

```dart theme={null}
final Map<String, Object?> value
```

Raw JSON payload sent to the API.


# CrossmintCheckoutRecipient
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/classes/crossmint-checkout-recipient

Flutter Sealed Class

**Sealed Class**

Who receives the minted NFT (or ships the physical good) — sealed across email, wallet, and physical-only variants. Concrete subclasses: `CrossmintCheckoutEmailRecipient`, `CrossmintCheckoutWalletRecipient`, `CrossmintCheckoutPhysicalRecipient`.

```dart theme={null}
sealed class CrossmintCheckoutRecipient
```

## Constructors

### CrossmintCheckoutRecipient

```dart theme={null}
const CrossmintCheckoutRecipient()
```

Creates a recipient. Only subclasses may extend this sealed type.


# CrossmintCheckoutTokenExecutionLineItem
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/classes/crossmint-checkout-token-execution-line-item

Flutter Final Class

**Final Class**

Line item that executes a token purchase with arbitrary execution parameters. Usually built via `CrossmintCheckoutLineItem.tokenWithExecutionParameters`.

```dart theme={null}
final class CrossmintCheckoutTokenExecutionLineItem extends CrossmintCheckoutLineItem
```

## Constructors

### CrossmintCheckoutTokenExecutionLineItem

```dart theme={null}
const CrossmintCheckoutTokenExecutionLineItem({
  required this.tokenLocator,
  required this.executionParameters,
  this.additionalFields = const <String, Object?>{},
})
```

Creates a token-execution line item.

## Properties

### tokenLocator

```dart theme={null}
final String tokenLocator
```

Token locator.

### executionParameters

```dart theme={null}
final Map<String, Object?> executionParameters
```

Structured execution parameters — shape depends on the token contract.

### additionalFields

```dart theme={null}
final Map<String, Object?> additionalFields
```

Forward-compatibility escape hatch.


# CrossmintCheckoutTokenLineItem
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/classes/crossmint-checkout-token-line-item

Flutter Final Class

**Final Class**

Line item that purchases a specific token. Usually built via `CrossmintCheckoutLineItem.token`.

```dart theme={null}
final class CrossmintCheckoutTokenLineItem extends CrossmintCheckoutLineItem
```

## Constructors

### CrossmintCheckoutTokenLineItem

```dart theme={null}
const CrossmintCheckoutTokenLineItem({
  required this.tokenLocator,
  this.callData,
  this.additionalFields = const <String, Object?>{},
})
```

Creates a token line item.

## Properties

### tokenLocator

```dart theme={null}
final String tokenLocator
```

Token locator (e.g. `"crossmint:<token-id>"`).

### callData

```dart theme={null}
final Map<String, Object?>? callData
```

Optional call data passed to the on-chain purchase transaction.

### additionalFields

```dart theme={null}
final Map<String, Object?> additionalFields
```

Forward-compatibility escape hatch — extra keys appended to the JSON payload.


# CrossmintCheckoutTransactionFailure
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/classes/crossmint-checkout-transaction-failure

Flutter Final Class

**Final Class**

Returned when the payer could not complete the transaction. The hosted page surfaces `errorMessage` to the user.

```dart theme={null}
final class CrossmintCheckoutTransactionFailure extends CrossmintCheckoutTransactionResult
```

## Constructors

### CrossmintCheckoutTransactionFailure

```dart theme={null}
const CrossmintCheckoutTransactionFailure({required this.errorMessage})
```

Creates a failure result.

## Properties

### errorMessage

```dart theme={null}
final String errorMessage
```

Short, user-facing failure description.


# CrossmintCheckoutTransactionResult
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/classes/crossmint-checkout-transaction-result

Flutter Sealed Class

**Sealed Class**

Result of a `CrossmintCheckoutPayer.signAndSendTransaction` call — sealed across success and failure variants.

```dart theme={null}
sealed class CrossmintCheckoutTransactionResult
```

## Constructors

### CrossmintCheckoutTransactionResult

```dart theme={null}
const CrossmintCheckoutTransactionResult()
```

Creates a result instance. Only subclasses may extend.


# CrossmintCheckoutTransactionSuccess
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/classes/crossmint-checkout-transaction-success

Flutter Final Class

**Final Class**

Returned when the payer successfully signed and broadcast a transaction.

```dart theme={null}
final class CrossmintCheckoutTransactionSuccess extends CrossmintCheckoutTransactionResult
```

## Constructors

### CrossmintCheckoutTransactionSuccess

```dart theme={null}
const CrossmintCheckoutTransactionSuccess({required this.txId})
```

Creates a success result.

## Properties

### txId

```dart theme={null}
final String txId
```

Transaction id (e.g. EVM tx hash `0x...`, Solana signature base58).


# CrossmintCheckoutWalletRecipient
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/classes/crossmint-checkout-wallet-recipient

Flutter Final Class

**Final Class**

External-wallet recipient — mints directly to a wallet address the user controls. Use this when checking out to a MetaMask / Phantom / other third-party wallet. Pair with `physicalAddress` when the line items include physical fulfillment.

```dart theme={null}
final class CrossmintCheckoutWalletRecipient extends CrossmintCheckoutRecipient
```

## Constructors

### CrossmintCheckoutWalletRecipient

```dart theme={null}
const CrossmintCheckoutWalletRecipient({
  required this.walletAddress,
  this.physicalAddress,
})
```

Creates a wallet recipient.

## Properties

### walletAddress

```dart theme={null}
final String walletAddress
```

Destination wallet address — EVM 0x-prefixed hex, Solana base58, etc.

### physicalAddress

```dart theme={null}
final CrossmintCheckoutPhysicalAddress? physicalAddress
```

Optional shipping address for physical line items.


# CrossmintEmbeddedCheckout
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/classes/crossmint-embedded-checkout

Flutter Class

**Class**

Embedded checkout widget matching the official Crossmint RN SDK `CrossmintEmbeddedCheckoutV3`.

```dart theme={null}
class CrossmintEmbeddedCheckout extends StatefulWidget
```

Loads the Crossmint hosted checkout page in a WebView and communicates
bidirectionally via postMessage for dynamic sizing, order updates, and
crypto transaction signing.

```dart theme={null}
CrossmintEmbeddedCheckout(
  apiKey: 'YOUR_API_KEY',
  config: CrossmintCheckoutConfig(
    order: CrossmintCheckoutNewOrder(
      lineItems: [{'collectionLocator': 'YOUR_COLLECTION_LOCATOR'}],
    ),
    payment: CrossmintCheckoutPayment(
      fiat: CrossmintCheckoutFiatPayment(enabled: true),
      crypto: CrossmintCheckoutCryptoPayment(enabled: false),
    ),
  ),
  onOrderUpdated: (order) => print('Order: $order'),
)
```

Host lifecycle notes:

* changing `apiKey` or `config` reloads the hosted checkout
* if the host app reuses a `checkoutController` across different checkout
  scenarios, clear it or replace it before rebuilding to avoid stale order
  state
* use `onDiagnostic` to observe blocked navigation, malformed hosted
  messages, and WebView resource errors in staging or production

## Constructors

### CrossmintEmbeddedCheckout

```dart theme={null}
const CrossmintEmbeddedCheckout({
  super.key,
  required this.apiKey,
  required this.config,
  this.payer,
  this.checkoutController,
  this.onOrderUpdated,
  this.onOrderCreationFailed,
  this.onDiagnostic,
  this.loadingBuilder,
  this.defaultHeight = 400,
})
```

## Properties

### apiKey

```dart theme={null}
final String apiKey
```

Crossmint API key.

### config

```dart theme={null}
final CrossmintCheckoutConfig config
```

Checkout configuration (order, payment, appearance).

### payer

```dart theme={null}
final CrossmintCheckoutPayer? payer
```

Optional crypto payer override for signing transactions within checkout.

### checkoutController

```dart theme={null}
final CrossmintCheckoutController? checkoutController
```

Optional reactive controller for checkout order state.

### onOrderUpdated

```dart theme={null}
final void Function(Map<String, Object?> order)? onOrderUpdated
```

Called when the order state changes.

### onOrderCreationFailed

```dart theme={null}
final void Function(String errorMessage)? onOrderCreationFailed
```

Called when order creation fails.

### onDiagnostic

```dart theme={null}
final void Function(CrossmintCheckoutDiagnostic diagnostic)? onDiagnostic
```

Called when the hosted checkout emits a runtime diagnostic.

### loadingBuilder

```dart theme={null}
final CrossmintCheckoutLoadingBuilder? loadingBuilder
```

Optional builder for the loading overlay rendered on top of the hosted checkout WebView while the page is loading. When `null`, the widget falls back to a Material `CircularProgressIndicator` inside a themed background container (the React Native Crossmint SDK parity default).

### defaultHeight

```dart theme={null}
final double defaultHeight
```

Initial height before the hosted page reports its actual height.

## Methods

### createState

```dart theme={null}
State<CrossmintEmbeddedCheckout> createState()
```


# CrossmintEvmWalletCheckoutPayer
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/classes/crossmint-evm-wallet-checkout-payer

Flutter Final Class

**Final Class**

Bridges a `CrossmintEvmWallet` into the checkout payer contract.

```dart theme={null}
final class CrossmintEvmWalletCheckoutPayer implements CrossmintCheckoutPayer
```

This adapter is intentionally EVM-only. The embedded checkout sends raw
serialized EVM transactions, and the runtime wallet forwards those
through the wallet transaction APIs using the same raw-transaction shape as
the JS wallet SDK.

## Constructors

### CrossmintEvmWalletCheckoutPayer

```dart theme={null}
CrossmintEvmWalletCheckoutPayer({
  required CrossmintEvmWallet wallet,
  List<String>? supportedChains,
  String? initialChain,
})
```

Creates an EVM payer backed by `wallet`.

## Properties

### supportedChains

```dart theme={null}
final List<String> supportedChains
```

EVM chains the wallet can sign transactions on. Computed from the `supportedChains` argument (defaulting to `[wallet.chain]`) and normalized to drop duplicates and blanks.

### address

```dart theme={null}
String get address
```

EVM address of the backing `CrossmintEvmWallet`.

### walletProviderKey

```dart theme={null}
String? get walletProviderKey
```

Always `null` — this adapter wraps an SDK-owned `CrossmintEvmWallet` rather than a third-party wallet provider, so there is no provider key to report.

### initialChain

```dart theme={null}
String get initialChain
```

Chain currently selected for outgoing transactions. Starts at the `initialChain` constructor argument (defaulting to `wallet.chain`) and updates when the hosted checkout calls `switchChain`.

## Methods

### signAndSendTransaction

```dart theme={null}
Future<CrossmintCheckoutTransactionResult> signAndSendTransaction(
  String serializedTransaction,
)
```

Signs and broadcasts a raw serialized EVM transaction received from the hosted checkout via the backing `CrossmintEvmWallet`. Returns `CrossmintCheckoutTransactionSuccess` with the transaction id on success. Errors are caught and surfaced as `CrossmintCheckoutTransactionFailure` — this method never throws so the hosted checkout can render a user-facing message.

### switchChain

```dart theme={null}
Future<void> switchChain(String chain)
```

Switches the selected chain used for subsequent transactions. Throws `ArgumentError` when `chain` is not in `supportedChains`. Called by the hosted checkout when the user changes chain in the UI.

### signMessage

```dart theme={null}
Future<String> signMessage(String message)
```

Signs an arbitrary message with the backing EVM wallet's approval signer. Returns the hex-encoded signature.


# CrossmintIdentityVerification
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/classes/crossmint-identity-verification

Flutter Class

**Class**

Renders Crossmint's hosted identity verification step in a WebView.

```dart theme={null}
class CrossmintIdentityVerification extends StatefulWidget
```

Read-only: the hosted page reports lifecycle events and nothing is sent
back to it.

```dart theme={null}
CrossmintIdentityVerification(
  apiKey: 'YOUR_API_KEY',
  credentials: checkoutController.identityVerificationCredentials!,
  onComplete: (status) => print('verification: $status'),
)
```

## Constructors

### CrossmintIdentityVerification

```dart theme={null}
const CrossmintIdentityVerification({
  super.key,
  required this.apiKey,
  required this.credentials,
  this.locale,
  this.onReady,
  this.onComplete,
  this.onCancel,
  this.onError,
  this.loadingBuilder,
  this.defaultHeight = 300,
})
```

## Properties

### apiKey

```dart theme={null}
final String apiKey
```

Crossmint API key. Resolves staging versus production and is forwarded to the hosted page, matching the React Native SDK and the other Crossmint widgets in this package.

### credentials

```dart theme={null}
final CrossmintIdentityVerificationCredentials credentials
```

Credentials for the verification session.

### locale

```dart theme={null}
final String? locale
```

Optional locale tag. Must be one the hosted page recognises, for example `en-US`, `es-ES`, `pt-PT`. An unrecognised tag is not ignored: the page rejects it and reports a non-retriable `invalidConfiguration` error, which leaves the buyer with a dead screen.

### onReady

```dart theme={null}
final void Function()? onReady
```

Called when the verification UI is ready.

### onComplete

```dart theme={null}
final void Function(CrossmintIdentityVerificationStatus status)? onComplete
```

Called with the outcome when verification finishes.

### onCancel

```dart theme={null}
final void Function()? onCancel
```

Called when the buyer abandons verification.

### onError

```dart theme={null}
final void Function(CrossmintIdentityVerificationError error)? onError
```

Called when verification cannot run or continue.

### loadingBuilder

```dart theme={null}
final CrossmintIdentityVerificationLoadingBuilder? loadingBuilder
```

Optional builder for the loading overlay. Falls back to a themed Material spinner, matching `CrossmintPaymentMethodManagement`.

### defaultHeight

```dart theme={null}
final double defaultHeight
```

Initial height before the hosted page reports its actual height.

## Methods

### createState

```dart theme={null}
State<CrossmintIdentityVerification> createState()
```


# CrossmintIdentityVerificationCredentials
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/classes/crossmint-identity-verification-credentials

Flutter Final Class

**Final Class**

Credentials for one verification session, read from an order's `payment.preparation.kyc`.

```dart theme={null}
final class CrossmintIdentityVerificationCredentials
```

## Constructors

### CrossmintIdentityVerificationCredentials

```dart theme={null}
const CrossmintIdentityVerificationCredentials({
  required this.inquiryId,
  this.sessionToken,
})
```

## Properties

### inquiryId

```dart theme={null}
final String inquiryId
```

Provider-side inquiry identifier.

### sessionToken

```dart theme={null}
final String? sessionToken
```

Optional provider session token.

## Static Methods

### tryFromJson

```dart theme={null}
static CrossmintIdentityVerificationCredentials? tryFromJson(Object? value)
```

Parses an order's `payment.preparation.kyc` map. Returns `null` when the order does not need verification, names a provider this SDK does not know, or carries no usable inquiry id.

## Methods

### toJson

```dart theme={null}
Map<String, Object?> toJson()
```

Serializes to the shape the hosted page's `credentials` query param expects. The provider discriminator is fixed: Persona is the only provider this SDK and the hosted page accept.


# CrossmintIdentityVerificationError
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/classes/crossmint-identity-verification-error

Flutter Final Class

**Final Class**

A verification error. `retriable` is the bit to act on: `false` means the flow is dead and the buyer cannot finish it.

```dart theme={null}
final class CrossmintIdentityVerificationError
```

## Constructors

### CrossmintIdentityVerificationError

```dart theme={null}
const CrossmintIdentityVerificationError({
  required this.retriable,
  required this.reason,
  required this.message,
})
```

### CrossmintIdentityVerificationError.fromEventData

```dart theme={null}
factory CrossmintIdentityVerificationError.fromEventData(
  Map<String, Object?> data,
)
```

Builds an error from a `kyc:error` payload, defaulting to non-retriable when the payload is malformed.

## Properties

### retriable

```dart theme={null}
final bool retriable
```

### reason

```dart theme={null}
final CrossmintIdentityVerificationErrorReason reason
```

### message

```dart theme={null}
final String message
```


# CrossmintCheckoutDefaultMethod
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/enums/crossmint-checkout-default-method

Flutter Enum

**Enum**

Typed default payment method — which tab/method the hosted checkout opens on.

```dart theme={null}
enum CrossmintCheckoutDefaultMethod
```

## Constructors

### CrossmintCheckoutDefaultMethod

```dart theme={null}
const CrossmintCheckoutDefaultMethod(this.wireValue)
```

Creates an enum variant with the wire-level string Crossmint expects.

## Properties

### wireValue

```dart theme={null}
final String wireValue
```

Wire-level string value (`"fiat"` or `"crypto"`) sent to the Crossmint-hosted page.

## Functions

### fiat

```dart theme={null}
fiat('fiat'),

/// Open the checkout on crypto (on-chain payment).
crypto('crypto')
```

Open the checkout on fiat (credit card / Apple Pay / Google Pay).


# CrossmintCheckoutDiagnosticSeverity
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/enums/crossmint-checkout-diagnostic-severity

Flutter Enum

**Enum**

Severity classification for `CrossmintCheckoutDiagnostic`.

```dart theme={null}
enum CrossmintCheckoutDiagnosticSeverity
```


# CrossmintIdentityVerificationErrorReason
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/enums/crossmint-identity-verification-error-reason

Flutter Enum

**Enum**

Why verification could not run or continue.

```dart theme={null}
enum CrossmintIdentityVerificationErrorReason
```

## Constructors

### CrossmintIdentityVerificationErrorReason

```dart theme={null}
const CrossmintIdentityVerificationErrorReason(this.wireValue)
```

## Properties

### wireValue

```dart theme={null}
final String wireValue
```

The value as it appears on the wire.

## Static Methods

### fromWireValue

```dart theme={null}
static CrossmintIdentityVerificationErrorReason fromWireValue(Object? value)
```

## Functions

### widgetUnavailable

```dart theme={null}
widgetUnavailable('widget-unavailable'),
invalidConfiguration('invalid-configuration'),
invalidCredentials('invalid-credentials'),
providerError('provider-error'),
unknown('unknown')
```


# CrossmintIdentityVerificationHandling
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/enums/crossmint-identity-verification-handling

Flutter Enum

**Enum**

Who renders the identity verification step when an order requires it.

```dart theme={null}
enum CrossmintIdentityVerificationHandling
```

## Constructors

### CrossmintIdentityVerificationHandling

```dart theme={null}
const CrossmintIdentityVerificationHandling(this.wireValue)
```

## Properties

### wireValue

```dart theme={null}
final String wireValue
```

The value as it appears on the wire.

## Functions

### external

```dart theme={null}
external('external')
```

Checkout does not render verification. You mount `CrossmintIdentityVerification` yourself from the controller's `identityVerificationCredentials`, or the buyer cannot finish.


# CrossmintIdentityVerificationStatus
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/enums/crossmint-identity-verification-status

Flutter Enum

**Enum**

Provider-agnostic verification outcome. `unknown` is an unrecognised state and must never be read as success.

```dart theme={null}
enum CrossmintIdentityVerificationStatus
```

## Constructors

### CrossmintIdentityVerificationStatus

```dart theme={null}
const CrossmintIdentityVerificationStatus(this.wireValue)
```

## Properties

### wireValue

```dart theme={null}
final String wireValue
```

The value as it appears on the wire.

## Static Methods

### fromWireValue

```dart theme={null}
static CrossmintIdentityVerificationStatus fromWireValue(Object? value)
```

## Functions

### verified

```dart theme={null}
verified('verified'),
pendingReview('pending-review'),
pendingManualReview('pending-manual-review'),
declined('declined'),
expired('expired'),
failed('failed'),
unknown('unknown')
```


# Get Started
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/get-started

Installation and setup for the Flutter SDK reference for Crossmint checkout

The Crossmint Flutter SDK (`crossmint_flutter`) provides an embedded checkout widget for integrating Crossmint checkout into your Flutter application. It supports fiat (credit card, Apple Pay, Google Pay) and crypto payment methods.

***

## Quick Start

Install the SDK and add the embedded checkout widget to your Flutter app.

### Usage

```dart checkout_screen.dart theme={null}
import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

class CheckoutScreen extends StatefulWidget {
  const CheckoutScreen({super.key});

  @override
  State<CheckoutScreen> createState() => _CheckoutScreenState();
}

class _CheckoutScreenState extends State<CheckoutScreen> {
  final _controller = CrossmintCheckoutController();

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: CrossmintEmbeddedCheckout(
        apiKey: 'YOUR_CLIENT_API_KEY',
        config: CrossmintCheckoutConfig(
          order: CrossmintCheckoutNewOrder.typed(
            lineItems: [
              CrossmintCheckoutLineItem.collection(
                collectionLocator: 'crossmint:YOUR_COLLECTION_ID',
              ),
            ],
          ),
          payment: CrossmintCheckoutPayment(
            fiat: CrossmintCheckoutFiatPayment(enabled: true),
            crypto: CrossmintCheckoutCryptoPayment(enabled: true),
          ),
        ),
        checkoutController: _controller,
        onOrderUpdated: (order) {
          debugPrint('Order updated: ${order['status']}');
        },
      ),
    );
  }
}
```


# Models
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/models

Configuration and data models for the Flutter SDK reference for Crossmint checkout

Configuration classes used to set up the embedded checkout widget. All models are imported from `crossmint_flutter_ui.dart`.

***

## CrossmintCheckoutConfig

Top-level configuration for `CrossmintEmbeddedCheckout`. Combines an order, payment method configuration, and optional appearance customization.

### Props

<ResponseField name="order" type="CrossmintCheckoutOrder">
  Order to check out — either a \[CrossmintCheckoutNewOrder] built from line items, or a \[CrossmintCheckoutExistingOrder] referencing an already-created order by id.
</ResponseField>

<ResponseField name="payment" type="CrossmintCheckoutPayment">
  Payment method configuration — fiat, crypto, and default method.

  <Expandable title="properties">
    <ResponseField name="fiat" type="CrossmintCheckoutFiatPayment?">
      Fiat (card, Apple Pay, Google Pay) configuration — null disables the fiat tab entirely.

      <Expandable title="properties">
        <ResponseField name="enabled" type="bool">
          Whether fiat payments are enabled.
        </ResponseField>

        <ResponseField name="defaultCurrency" type="String?">
          ISO 4217 currency code preselected in the fiat tab (e.g. `"USD"`).
        </ResponseField>

        <ResponseField name="allowCard" type="bool?">
          When `false`, hides the credit-card payment method. `null` keeps the project default.
        </ResponseField>

        <ResponseField name="allowApplePay" type="bool?">
          When `false`, hides Apple Pay. `null` keeps the project default.
        </ResponseField>

        <ResponseField name="allowGooglePay" type="bool?">
          When `false`, hides Google Pay. `null` keeps the project default.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="crypto" type="CrossmintCheckoutCryptoPayment?">
      Crypto payment configuration — null disables the crypto tab.

      <Expandable title="properties">
        <ResponseField name="enabled" type="bool">
          Whether crypto payments are enabled.
        </ResponseField>

        <ResponseField name="defaultChain" type="String?">
          Chain preselected in the crypto tab (e.g. `"base"`, `"solana"`). Must appear in the payer's \[CrossmintCheckoutPayer.supportedChains] when a payer is attached.
        </ResponseField>

        <ResponseField name="defaultCurrency" type="String?">
          Currency preselected in the crypto tab (e.g. `"USDC"`).
        </ResponseField>

        <ResponseField name="payer" type="CrossmintCheckoutPayer?">
          Optional app-side signer bridge. When null, the hosted page presents its own wallet-connect flow.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="defaultMethod" type="String?">
      Raw default payment method string. Prefer \[defaultMethodType] for compile-time safety. When both are set, \[defaultMethodType] wins.
    </ResponseField>

    <ResponseField name="defaultMethodType" type="CrossmintCheckoutDefaultMethod?">
      Typed default payment method — one of \[CrossmintCheckoutDefaultMethod]: `fiat` (open on credit card / Apple Pay / Google Pay) or `crypto` (open on on-chain payment). Takes precedence over \[defaultMethod].
    </ResponseField>

    <ResponseField name="receiptEmail" type="String?">
      Email to receive the order receipt. Leave null to use the recipient email (for \[CrossmintCheckoutEmailRecipient]) or rely on the user entering an email inside the hosted page.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="appearance" type="CrossmintCheckoutAppearance?">
  Optional appearance customization — CSS variables, rules, fonts.

  <Expandable title="properties">
    <ResponseField name="variables" type="Map<String, Object?>?">
      CSS custom properties for theming (e.g. `{'colorPrimary': '#0F172A'}`).
    </ResponseField>

    <ResponseField name="rules" type="Map<String, Object?>?">
      CSS rules for specific checkout elements (e.g. `{'.Input': {'borderColor': '#CBD5E1'}}`).
    </ResponseField>

    <ResponseField name="fonts" type="List<Map<String, String>>?">
      Custom font definitions (e.g. `[{'cssSrc': 'https://fonts.googleapis.com/...'}]`).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="jwt" type="String?">
  Optional JWT for authenticated checkouts — attaches the user's Crossmint session to the hosted page so the experience is signed-in when the user lands. Pass `client.auth.state.session?.jwt` when you want the checkout to inherit the current app session.
</ResponseField>

<ResponseField name="identityVerificationHandling" type="CrossmintIdentityVerificationHandling?">
  Optional takeover of the identity verification step. Requires a Crossmint deployment that understands the flag; against an older one it is ignored and checkout renders verification itself.
</ResponseField>

***

## CrossmintCheckoutNewOrder / CrossmintCheckoutExistingOrder

Order configuration — either create a new order inline with line items, or resume an existing order by ID.

### Props

<ResponseField name="lineItems" type="List<Map<String, Object?>>">
  Line items in the order, each represented as a raw JSON map. Prefer the \[CrossmintCheckoutNewOrder.typed] constructor and pass typed \[CrossmintCheckoutLineItem] values; use the raw map shape only when a new API field is not yet modeled by the SDK.
</ResponseField>

<ResponseField name="recipient" type="CrossmintCheckoutRecipient?">
  Optional recipient for the order. When omitted, the hosted checkout collects recipient details from the buyer.
</ResponseField>

<ResponseField name="locale" type="String?">
  Optional BCP 47 locale tag (for example `en-US`, `es`, `pt-BR`) used to localize the hosted checkout UI. Defaults to the buyer's browser locale when null.
</ResponseField>

<ResponseField name="metadata" type="Map<String, Object?>?">
  Optional opaque metadata attached to the order. Forwarded verbatim to the Crossmint orders API and returned on order webhooks and status reads.
</ResponseField>

### Usage

```dart theme={null}
// New order with typed line items
CrossmintCheckoutNewOrder.typed(
  lineItems: [
    CrossmintCheckoutLineItem.collection(
      collectionLocator: 'crossmint:YOUR_COLLECTION_ID',
      callData: {'quantity': 1},
    ),
  ],
  recipient: CrossmintCheckoutEmailRecipient(
    email: 'buyer@example.com',
  ),
  locale: 'en-US',
)

// Resume an existing order
CrossmintCheckoutExistingOrder(
  orderId: 'ORDER_ID',
  clientSecret: 'CLIENT_SECRET',
)
```

***

## CrossmintCheckoutLineItem

A single asset to purchase in a checkout order. Use the named factory constructors: `.collection()`, `.token()`, `.tokenWithExecutionParameters()`, `.product()`, or `.raw()` for forward-compatible escape hatches.

### Usage

```dart theme={null}
// Collection (primary sale)
CrossmintCheckoutLineItem.collection(
  collectionLocator: 'crossmint:YOUR_COLLECTION_ID',
  callData: {'quantity': 2},
)

// Token (secondary sale)
CrossmintCheckoutLineItem.token(
  tokenLocator: 'crossmint:YOUR_TOKEN_ID',
)

// Token with execution parameters (e.g. memecoin swap)
CrossmintCheckoutLineItem.tokenWithExecutionParameters(
  tokenLocator: 'crossmint:YOUR_TOKEN_ID',
  executionParameters: {
    'amount': '1000000',
    'mode': 'exact-in',
    'maxSlippageBps': 100,
  },
)

// Product (catalog-managed)
CrossmintCheckoutLineItem.product(
  productLocator: 'crossmint:YOUR_PRODUCT_ID',
)
```

***

## CrossmintCheckoutPayment

Payment method configuration — at least one of fiat or crypto must be enabled. Controls which payment methods are shown and which is selected by default.

### Props

<ResponseField name="fiat" type="CrossmintCheckoutFiatPayment?">
  Fiat (card, Apple Pay, Google Pay) configuration — null disables the fiat tab entirely.

  <Expandable title="properties">
    <ResponseField name="enabled" type="bool">
      Whether fiat payments are enabled.
    </ResponseField>

    <ResponseField name="defaultCurrency" type="String?">
      ISO 4217 currency code preselected in the fiat tab (e.g. `"USD"`).
    </ResponseField>

    <ResponseField name="allowCard" type="bool?">
      When `false`, hides the credit-card payment method. `null` keeps the project default.
    </ResponseField>

    <ResponseField name="allowApplePay" type="bool?">
      When `false`, hides Apple Pay. `null` keeps the project default.
    </ResponseField>

    <ResponseField name="allowGooglePay" type="bool?">
      When `false`, hides Google Pay. `null` keeps the project default.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="crypto" type="CrossmintCheckoutCryptoPayment?">
  Crypto payment configuration — null disables the crypto tab.

  <Expandable title="properties">
    <ResponseField name="enabled" type="bool">
      Whether crypto payments are enabled.
    </ResponseField>

    <ResponseField name="defaultChain" type="String?">
      Chain preselected in the crypto tab (e.g. `"base"`, `"solana"`). Must appear in the payer's \[CrossmintCheckoutPayer.supportedChains] when a payer is attached.
    </ResponseField>

    <ResponseField name="defaultCurrency" type="String?">
      Currency preselected in the crypto tab (e.g. `"USDC"`).
    </ResponseField>

    <ResponseField name="payer" type="CrossmintCheckoutPayer?">
      Optional app-side signer bridge. When null, the hosted page presents its own wallet-connect flow.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="defaultMethod" type="String?">
  Raw default payment method string. Prefer \[defaultMethodType] for compile-time safety. When both are set, \[defaultMethodType] wins.
</ResponseField>

<ResponseField name="defaultMethodType" type="CrossmintCheckoutDefaultMethod?">
  Typed default payment method — one of \[CrossmintCheckoutDefaultMethod]: `fiat` (open on credit card / Apple Pay / Google Pay) or `crypto` (open on on-chain payment). Takes precedence over \[defaultMethod].
</ResponseField>

<ResponseField name="receiptEmail" type="String?">
  Email to receive the order receipt. Leave null to use the recipient email (for \[CrossmintCheckoutEmailRecipient]) or rely on the user entering an email inside the hosted page.
</ResponseField>

***

## CrossmintCheckoutFiatPayment

Fiat payment configuration — credit card, Apple Pay, Google Pay. Set `enabled: false` to hide the fiat tab entirely.

### Props

<ResponseField name="enabled" type="bool">
  Whether fiat payments are enabled.
</ResponseField>

<ResponseField name="defaultCurrency" type="String?">
  ISO 4217 currency code preselected in the fiat tab (e.g. `"USD"`).
</ResponseField>

<ResponseField name="allowCard" type="bool?">
  When `false`, hides the credit-card payment method. `null` keeps the project default.
</ResponseField>

<ResponseField name="allowApplePay" type="bool?">
  When `false`, hides Apple Pay. `null` keeps the project default.
</ResponseField>

<ResponseField name="allowGooglePay" type="bool?">
  When `false`, hides Google Pay. `null` keeps the project default.
</ResponseField>

***

## CrossmintCheckoutCryptoPayment

Crypto payment configuration — on-chain payment via a connected wallet. Set `enabled: false` to hide the crypto tab.

### Props

<ResponseField name="enabled" type="bool">
  Whether crypto payments are enabled.
</ResponseField>

<ResponseField name="defaultChain" type="String?">
  Chain preselected in the crypto tab (e.g. `"base"`, `"solana"`). Must appear in the payer's \[CrossmintCheckoutPayer.supportedChains] when a payer is attached.
</ResponseField>

<ResponseField name="defaultCurrency" type="String?">
  Currency preselected in the crypto tab (e.g. `"USDC"`).
</ResponseField>

<ResponseField name="payer" type="CrossmintCheckoutPayer?">
  Optional app-side signer bridge. When null, the hosted page presents its own wallet-connect flow.
</ResponseField>

***

## CrossmintCheckoutPayer

Interface for apps to provide crypto wallet signing capabilities. Implement this to bridge your wallet into the checkout. Use `CrossmintEvmWalletCheckoutPayer` for a ready-made EVM adapter.

### Properties

<ResponseField name="address" type="String">
  Current wallet address.
</ResponseField>

<ResponseField name="initialChain" type="String">
  Chain the wallet is initially connected on.
</ResponseField>

<ResponseField name="supportedChains" type="List<String>">
  Chains the wallet can sign transactions on. The hosted checkout only offers chains that appear here.
</ResponseField>

<ResponseField name="walletProviderKey" type="String?">
  Optional wallet provider identifier (e.g. "metamask", "coinbase"). Returns null if not applicable.
</ResponseField>

### Methods

<ResponseField name="signAndSendTransaction(serializedTransaction)" type="Future<CrossmintCheckoutTransactionResult>">
  Signs and broadcasts a serialized transaction. Return \[CrossmintCheckoutTransactionSuccess] with the transaction id on success, or \[CrossmintCheckoutTransactionFailure] with a user-facing message on failure.

  <Expandable title="parameters">
    <ResponseField name="serializedTransaction" type="String" />
  </Expandable>
</ResponseField>

<ResponseField name="switchChain(chain)" type="Future<void>">
  Switches the wallet to \[chain]. Called by the hosted page when the user changes chain in the UI.

  <Expandable title="parameters">
    <ResponseField name="chain" type="String" />
  </Expandable>
</ResponseField>

<ResponseField name="signMessage(message)" type="Future<String>?">
  Optional — return null if message signing is not supported.

  <Expandable title="parameters">
    <ResponseField name="message" type="String" />
  </Expandable>
</ResponseField>

***

## CrossmintEvmWalletCheckoutPayer

Ready-made adapter that bridges a `CrossmintEvmWallet` into the checkout payer contract. Handles transaction signing and chain switching automatically.

### Props

<ResponseField name="wallet" type="CrossmintEvmWallet" />

<ResponseField name="supportedChains" type="List<String>?" />

<ResponseField name="initialChain" type="String?" />

### Usage

```dart theme={null}
// Bridge a CrossmintEvmWallet into the checkout payer contract.
// `walletController` is a CrossmintWalletController with a loaded wallet.
final wallet = walletController.createEvmWallet();

final payer = CrossmintEvmWalletCheckoutPayer(
  wallet: wallet,
  supportedChains: ['base', 'ethereum', 'polygon'],
);

CrossmintEmbeddedCheckout(
  apiKey: 'YOUR_CLIENT_API_KEY',
  config: CrossmintCheckoutConfig(
    order: yourOrder,
    payment: CrossmintCheckoutPayment(
      crypto: CrossmintCheckoutCryptoPayment(
        enabled: true,
        payer: payer,
      ),
      fiat: CrossmintCheckoutFiatPayment(enabled: true),
    ),
  ),
)
```

***

## Recipients

Sealed type for who receives the purchased asset. Three variants: `CrossmintCheckoutEmailRecipient`, `CrossmintCheckoutWalletRecipient`, and `CrossmintCheckoutPhysicalRecipient`.

### Usage

```dart theme={null}
// Email recipient (mints to Crossmint-managed wallet)
CrossmintCheckoutEmailRecipient(
  email: 'buyer@example.com',
)

// External wallet recipient
CrossmintCheckoutWalletRecipient(
  walletAddress: '0x1234...abcd',
)

// Physical-only recipient (no on-chain asset)
CrossmintCheckoutPhysicalRecipient(
  email: 'buyer@example.com',
  physicalAddress: CrossmintCheckoutPhysicalAddress(
    name: 'Jane Doe',
    line1: '123 Main St',
    city: 'San Francisco',
    state: 'CA',
    postalCode: '94105',
    country: 'US',
  ),
)
```

***

## CrossmintCheckoutAppearance

UI customization for the hosted checkout page — CSS custom properties, rules targeting specific elements, and custom web fonts.

### Props

<ResponseField name="variables" type="Map<String, Object?>?">
  CSS custom properties for theming (e.g. `{'colorPrimary': '#0F172A'}`).
</ResponseField>

<ResponseField name="rules" type="Map<String, Object?>?">
  CSS rules for specific checkout elements (e.g. `{'.Input': {'borderColor': '#CBD5E1'}}`).
</ResponseField>

<ResponseField name="fonts" type="List<Map<String, String>>?">
  Custom font definitions (e.g. `[{'cssSrc': 'https://fonts.googleapis.com/...'}]`).
</ResponseField>

### Usage

```dart theme={null}
CrossmintCheckoutAppearance(
  variables: {
    'colorPrimary': '#0F172A',
    'borderRadius': '8px',
    'fontFamily': 'Inter, sans-serif',
  },
  rules: {
    '.Input': {'borderColor': '#CBD5E1'},
    '.Tab--selected': {'backgroundColor': '#0F172A'},
  },
  fonts: [
    {'cssSrc': 'https://fonts.googleapis.com/css2?family=Inter'},
  ],
)
```

***

## CrossmintCheckoutTransactionResult

Sealed result type from `CrossmintCheckoutPayer.signAndSendTransaction()` — either `CrossmintCheckoutTransactionSuccess` (with `txId`) or `CrossmintCheckoutTransactionFailure` (with `errorMessage`).

***

## CrossmintCheckoutDiagnostic

Structured runtime signal emitted by the embedded checkout widget. Covers blocked navigations, malformed messages, WebView resource errors, and console warnings/errors from the hosted page.

### Props

<ResponseField name="code" type="String">
  Short machine-readable identifier (e.g. `"navigation.blocked"`, `"message.parse_failed"`).
</ResponseField>

<ResponseField name="message" type="String">
  Human-readable description of the diagnostic.
</ResponseField>

<ResponseField name="severity" type="CrossmintCheckoutDiagnosticSeverity">
  Severity classification — one of \[CrossmintCheckoutDiagnosticSeverity]: `info` (interesting but not a problem, e.g. user closed the hosted modal), `warning` (likely recoverable — surface in dev / staging), `error` (hosted flow hit a problem that may affect checkout). Pass to logging infrastructure accordingly.
</ResponseField>

<ResponseField name="event" type="String?">
  Hosted-page event associated with this diagnostic, if any (e.g. the original postMessage event name that failed to parse).
</ResponseField>

<ResponseField name="uri" type="Uri?">
  URL associated with this diagnostic — set for navigation-related diagnostics (blocked navigations, resource errors).
</ResponseField>

<ResponseField name="details" type="Map<String, Object?>">
  Extra structured context for the diagnostic. Keys are stable — safe to forward to logging.
</ResponseField>


# CrossmintCheckoutLoadingBuilder
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/type-aliases/crossmint-checkout-loading-builder

Flutter Type Alias

**Type Alias**

Builder signature for the overlay rendered on top of the hosted checkout WebView while the hosted page is loading. Consumers can supply a custom builder via `CrossmintEmbeddedCheckout.loadingBuilder` to swap the default Material spinner for their own design-system loading state (Cupertino, fluent\_ui, a custom animation, etc.).

```dart theme={null}
typedef CrossmintCheckoutLoadingBuilder = Widget Function(BuildContext context)
```


# CrossmintIdentityVerificationLoadingBuilder
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/type-aliases/crossmint-identity-verification-loading-builder

Flutter Type Alias

**Type Alias**

Builder signature for the overlay rendered on top of the hosted verification WebView while the page is loading.

```dart theme={null}
typedef CrossmintIdentityVerificationLoadingBuilder = Widget Function(BuildContext context)
```


# Widgets
Source: https://docs.crossmint.com/sdk-reference/checkout/flutter/widgets

Flutter widgets for the Flutter SDK reference for Crossmint checkout

The Flutter SDK provides a WebView-based checkout widget that renders the Crossmint embedded checkout experience. Import it from `crossmint_flutter_ui.dart`.

***

## CrossmintEmbeddedCheckout

WebView-based checkout widget that renders the Crossmint embedded checkout experience inline. Communicates bidirectionally with the hosted checkout page for dynamic sizing, order updates, and crypto transaction signing.

### Props

<ResponseField name="apiKey" type="String">
  Crossmint API key.
</ResponseField>

<ResponseField name="config" type="CrossmintCheckoutConfig">
  Checkout configuration (order, payment, appearance).

  <Expandable title="properties">
    <ResponseField name="order" type="CrossmintCheckoutOrder">
      Order to check out — either a \[CrossmintCheckoutNewOrder] built from line items, or a \[CrossmintCheckoutExistingOrder] referencing an already-created order by id.
    </ResponseField>

    <ResponseField name="payment" type="CrossmintCheckoutPayment">
      Payment method configuration — fiat, crypto, and default method.

      <Expandable title="properties">
        <ResponseField name="fiat" type="CrossmintCheckoutFiatPayment?">
          Fiat (card, Apple Pay, Google Pay) configuration — null disables the fiat tab entirely.
        </ResponseField>

        <ResponseField name="crypto" type="CrossmintCheckoutCryptoPayment?">
          Crypto payment configuration — null disables the crypto tab.
        </ResponseField>

        <ResponseField name="defaultMethod" type="String?">
          Raw default payment method string. Prefer \[defaultMethodType] for compile-time safety. When both are set, \[defaultMethodType] wins.
        </ResponseField>

        <ResponseField name="defaultMethodType" type="CrossmintCheckoutDefaultMethod?">
          Typed default payment method — one of \[CrossmintCheckoutDefaultMethod]: `fiat` (open on credit card / Apple Pay / Google Pay) or `crypto` (open on on-chain payment). Takes precedence over \[defaultMethod].
        </ResponseField>

        <ResponseField name="receiptEmail" type="String?">
          Email to receive the order receipt. Leave null to use the recipient email (for \[CrossmintCheckoutEmailRecipient]) or rely on the user entering an email inside the hosted page.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="appearance" type="CrossmintCheckoutAppearance?">
      Optional appearance customization — CSS variables, rules, fonts.

      <Expandable title="properties">
        <ResponseField name="variables" type="Map<String, Object?>?">
          CSS custom properties for theming (e.g. `{'colorPrimary': '#0F172A'}`).
        </ResponseField>

        <ResponseField name="rules" type="Map<String, Object?>?">
          CSS rules for specific checkout elements (e.g. `{'.Input': {'borderColor': '#CBD5E1'}}`).
        </ResponseField>

        <ResponseField name="fonts" type="List<Map<String, String>>?">
          Custom font definitions (e.g. `[{'cssSrc': 'https://fonts.googleapis.com/...'}]`).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="jwt" type="String?">
      Optional JWT for authenticated checkouts — attaches the user's Crossmint session to the hosted page so the experience is signed-in when the user lands. Pass `client.auth.state.session?.jwt` when you want the checkout to inherit the current app session.
    </ResponseField>

    <ResponseField name="identityVerificationHandling" type="CrossmintIdentityVerificationHandling?">
      Optional takeover of the identity verification step. Requires a Crossmint deployment that understands the flag; against an older one it is ignored and checkout renders verification itself.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="payer" type="CrossmintCheckoutPayer?">
  Optional crypto payer override for signing transactions within checkout.
</ResponseField>

<ResponseField name="checkoutController" type="CrossmintCheckoutController?">
  Optional reactive controller for checkout order state.
</ResponseField>

<ResponseField name="onOrderUpdated" type="void Function(Map<String, Object?> order)?">
  Called when the order state changes.
</ResponseField>

<ResponseField name="onOrderCreationFailed" type="void Function(String errorMessage)?">
  Called when order creation fails.
</ResponseField>

<ResponseField name="onDiagnostic" type="void Function(CrossmintCheckoutDiagnostic diagnostic)?">
  Called when the hosted checkout emits a runtime diagnostic.
</ResponseField>

<ResponseField name="loadingBuilder" type="CrossmintCheckoutLoadingBuilder?">
  Optional builder for the loading overlay rendered on top of the hosted checkout WebView while the page is loading. When `null`, the widget falls back to a Material `CircularProgressIndicator` inside a themed background container (the React Native Crossmint SDK parity default).
</ResponseField>

<ResponseField name="defaultHeight" type="double">
  Initial height before the hosted page reports its actual height.
</ResponseField>

### Usage

```dart theme={null}
final checkoutController = CrossmintCheckoutController();

CrossmintEmbeddedCheckout(
  apiKey: 'YOUR_CLIENT_API_KEY',
  config: CrossmintCheckoutConfig(
    order: CrossmintCheckoutNewOrder.typed(
      lineItems: [
        CrossmintCheckoutLineItem.collection(
          collectionLocator: 'crossmint:collection-id',
          callData: {'quantity': 1},
        ),
      ],
    ),
    payment: CrossmintCheckoutPayment(
      fiat: CrossmintCheckoutFiatPayment(enabled: true),
      crypto: CrossmintCheckoutCryptoPayment(enabled: false),
    ),
  ),
  checkoutController: checkoutController,
  onOrderUpdated: (order) => print('Order: ${order['status']}'),
  onOrderCreationFailed: (error) => print('Error: $error'),
)
```

***

## CrossmintCheckoutController

Reactive controller for checkout order state, matching the official Crossmint RN SDK's `useCrossmintCheckout()` hook. Pass this to `CrossmintEmbeddedCheckout` to receive order updates as observable state.

### Properties

<ResponseField name="order" type="Map<String, Object?>?">
  The current order object from the checkout, or `null` if no order yet.
</ResponseField>

<ResponseField name="orderClientSecret" type="String?">
  The server-assigned client secret for the current order.
</ResponseField>

<ResponseField name="identityVerificationCredentials" type="CrossmintIdentityVerificationCredentials?">
  Verification credentials for the current order, or `null` when the order does not need identity verification. Pass these to `CrossmintIdentityVerification` when checkout runs with `identityVerificationHandling` set to external.

  <Expandable title="properties">
    <ResponseField name="inquiryId" type="String">
      Provider-side inquiry identifier.
    </ResponseField>

    <ResponseField name="sessionToken" type="String?">
      Optional provider session token.
    </ResponseField>
  </Expandable>
</ResponseField>

### Methods

<ResponseField name="updateOrder(data)" type="void">
  Updates the order state from a checkout `order:updated` event.

  <Expandable title="parameters">
    <ResponseField name="data" type="Map<String, Object?>" />
  </Expandable>
</ResponseField>

<ResponseField name="clear()" type="void">
  Clears the order state.
</ResponseField>

### Usage

```dart theme={null}
final controller = CrossmintCheckoutController();

// Pass to the widget:
CrossmintEmbeddedCheckout(
  apiKey: 'YOUR_CLIENT_API_KEY',
  config: yourCheckoutConfig,
  checkoutController: controller,
)

// Listen reactively:
ListenableBuilder(
  listenable: controller,
  builder: (context, _) {
    final order = controller.order;
    if (order == null) return const Text('No order yet');
    return Text('Status: ${order['status']}');
  },
)
```

***

## CrossmintIdentityVerification

WebView-based widget that renders Crossmint's hosted identity verification step in your own route. Use it when checkout runs with `identityVerificationHandling: CrossmintIdentityVerificationHandling.external` — checkout then stops rendering verification itself, and the buyer cannot finish unless you mount this widget with the credentials from `CrossmintCheckoutController.identityVerificationCredentials`.

### Props

<ResponseField name="apiKey" type="String">
  Crossmint API key. Resolves staging versus production and is forwarded to the hosted page, matching the React Native SDK and the other Crossmint widgets in this package.
</ResponseField>

<ResponseField name="credentials" type="CrossmintIdentityVerificationCredentials">
  Credentials for the verification session.

  <Expandable title="properties">
    <ResponseField name="inquiryId" type="String">
      Provider-side inquiry identifier.
    </ResponseField>

    <ResponseField name="sessionToken" type="String?">
      Optional provider session token.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="locale" type="String?">
  Optional locale tag. Must be one the hosted page recognises, for example `en-US`, `es-ES`, `pt-PT`. An unrecognised tag is not ignored: the page rejects it and reports a non-retriable `invalidConfiguration` error, which leaves the buyer with a dead screen.
</ResponseField>

<ResponseField name="onReady" type="void Function()?">
  Called when the verification UI is ready.
</ResponseField>

<ResponseField name="onComplete" type="void Function(CrossmintIdentityVerificationStatus status)?">
  Called with the outcome when verification finishes.
</ResponseField>

<ResponseField name="onCancel" type="void Function()?">
  Called when the buyer abandons verification.
</ResponseField>

<ResponseField name="onError" type="void Function(CrossmintIdentityVerificationError error)?">
  Called when verification cannot run or continue.
</ResponseField>

<ResponseField name="loadingBuilder" type="CrossmintIdentityVerificationLoadingBuilder?">
  Optional builder for the loading overlay. Falls back to a themed Material spinner, matching `CrossmintPaymentMethodManagement`.
</ResponseField>

<ResponseField name="defaultHeight" type="double">
  Initial height before the hosted page reports its actual height.
</ResponseField>

### Usage

```dart theme={null}
// Run checkout with the verification step handed to you.
CrossmintEmbeddedCheckout(
  apiKey: 'YOUR_CLIENT_API_KEY',
  config: CrossmintCheckoutConfig(
    order: yourOrder,
    payment: yourPayment,
    identityVerificationHandling:
        CrossmintIdentityVerificationHandling.external,
  ),
  checkoutController: _controller,
)

// Then mount the verification widget on your own route when the
// controller reports that the order needs it.
final credentials = _controller.identityVerificationCredentials;
if (credentials != null)
  CrossmintIdentityVerification(
    apiKey: 'YOUR_CLIENT_API_KEY',
    credentials: credentials,
    onComplete: (status) {
      debugPrint('verification: ${status.wireValue}');
    },
    onError: (error) {
      debugPrint('verification failed: ${error.message}');
    },
  )
```


# CheckoutColor
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/classes/checkout-color

Kotlin Class

**Class**

```kotlin theme={null}
class CheckoutColor
```


# CheckoutError.EncodingError
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/classes/checkout-error-encoding-error

Kotlin Class

**Class**

```kotlin theme={null}
class EncodingError(message: String, cause: Throwable? = null) : CheckoutError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `message` | `String?` | - |


# CheckoutError.InvalidConfiguration
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/classes/checkout-error-invalid-configuration

Kotlin Class

**Class**

```kotlin theme={null}
class InvalidConfiguration(message: String) : CheckoutError
```

## Constructors

```kotlin theme={null}
constructor(message: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `message` | `String?` | - |


# CheckoutError.NotImplemented
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/classes/checkout-error-not-implemented

Kotlin Class

**Class**

```kotlin theme={null}
class NotImplemented(message: String) : CheckoutError
```

## Constructors

```kotlin theme={null}
constructor(message: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `message` | `String?` | - |


# CheckoutFontWeight
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/classes/checkout-font-weight

Kotlin Class

**Class**

```kotlin theme={null}
class CheckoutFontWeight
```

## Constructors

```kotlin theme={null}
constructor(weight: Int)
```


# CheckoutLength
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/classes/checkout-length

Kotlin Class

**Class**

```kotlin theme={null}
class CheckoutLength
```


# CrossmintEmbeddedCheckout
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/composables/crossmint-embedded-checkout

Composable Function

**Composable**

```kotlin theme={null}
@Composable
fun CrossmintEmbeddedCheckout(orderId: String? = null, clientSecret: String? = null, lineItems: CheckoutLineItems? = null, payment: CheckoutPayment? = null, recipient: CheckoutRecipient? = null, apiKey: String? = null, appearance: CheckoutAppearance? = null, environment: CheckoutEnvironment = CheckoutEnvironment.STAGING, identityVerificationHandling: IdentityVerificationHandling? = null, modifier: Modifier = Modifier)
```

Crossmint Embedded Checkout component.

## Parameters

| Name | Description |
| - | - |
| orderId | The order ID for an existing order (optional) |
| clientSecret | The client secret for authentication (optional) |
| lineItems | Line items configuration - NOT YET IMPLEMENTED |
| payment | Payment configuration (crypto/fiat options) |
| recipient | Recipient configuration - NOT YET IMPLEMENTED |
| apiKey | API key for authentication (optional) |
| appearance | UI appearance customization |
| environment | Target environment (default: STAGING) |
| identityVerificationHandling | Set to IdentityVerificationHandling.EXTERNAL to render the KYC step yourself with `CrossmintIdentityVerification`. When null, checkout renders the KYC step inline (default) |
| modifier | Compose modifier for the checkout container |


# CheckoutAllowedMethods
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/data-classes/checkout-allowed-methods

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class CheckoutAllowedMethods(val googlePay: Boolean? = true, val applePay: Boolean? = true, val card: Boolean? = true)
```

## Constructors

```kotlin theme={null}
constructor(googlePay: Boolean? = true, applePay: Boolean? = true, card: Boolean? = true)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `applePay` | `Boolean?` | - |
| `card` | `Boolean?` | - |
| `googlePay` | `Boolean?` | - |


# CheckoutAppearance
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/data-classes/checkout-appearance

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class CheckoutAppearance(val rules: CheckoutAppearanceRules? = null, val variables: CheckoutAppearanceVariables? = null, val fonts: List<CheckoutFontSource>? = null)
```

## Constructors

```kotlin theme={null}
constructor(rules: CheckoutAppearanceRules? = null, variables: CheckoutAppearanceVariables? = null, fonts: List<CheckoutFontSource>? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `fonts` | `List<CheckoutFontSource>?` | The stylesheets that load custom fonts into the checkout. |
| `rules` | `CheckoutAppearanceRules?` | - |
| `variables` | `CheckoutAppearanceVariables?` | - |


# CheckoutAppearanceRules
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/data-classes/checkout-appearance-rules

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class CheckoutAppearanceRules(val destinationInput: CheckoutDestinationInputRule? = null, val receiptEmailInput: CheckoutReceiptEmailInputRule? = null, val globalMessage: CheckoutGlobalMessageRule? = null, val label: CheckoutLabelRule? = null, val input: CheckoutInputRule? = null, val tab: CheckoutTabRule? = null, val primaryButton: CheckoutPrimaryButtonRule? = null)
```

## Constructors

```kotlin theme={null}
constructor(destinationInput: CheckoutDestinationInputRule? = null, receiptEmailInput: CheckoutReceiptEmailInputRule? = null, globalMessage: CheckoutGlobalMessageRule? = null, label: CheckoutLabelRule? = null, input: CheckoutInputRule? = null, tab: CheckoutTabRule? = null, primaryButton: CheckoutPrimaryButtonRule? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `destinationInput` | `CheckoutDestinationInputRule?` | - |
| `globalMessage` | `CheckoutGlobalMessageRule?` | - |
| `input` | `CheckoutInputRule?` | - |
| `label` | `CheckoutLabelRule?` | - |
| `primaryButton` | `CheckoutPrimaryButtonRule?` | - |
| `receiptEmailInput` | `CheckoutReceiptEmailInputRule?` | - |
| `tab` | `CheckoutTabRule?` | - |


# CheckoutAppearanceVariables
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/data-classes/checkout-appearance-variables

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class CheckoutAppearanceVariables(val fontFamily: String? = null, val spacingUnitLength: CheckoutLength? = null, val fontSizeUnitLength: CheckoutLength? = null, val cornerRadius: CheckoutLength? = null, val colors: CheckoutVariablesColorStyle? = null)
```

## Constructors

```kotlin theme={null}
constructor(fontFamily: String? = null, spacingUnitLength: CheckoutLength? = null, fontSizeUnitLength: CheckoutLength? = null, cornerRadius: CheckoutLength? = null, colors: CheckoutVariablesColorStyle? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `colors` | `CheckoutVariablesColorStyle?` | The global colors. |
| `cornerRadius` | `CheckoutLength?` | The corner radius of the checkout elements, for example `CheckoutLength.px(8)`. The corner radius of a rule, such as CheckoutInputRule.cornerRadius, has priority over it. |
| `fontFamily` | `String?` | The CSS `font-family` value for all the checkout text, for example `"Inter, sans-serif"`. If the device does not have the font, load the font with CheckoutAppearance.fonts. |
| `fontSizeUnitLength` | `CheckoutLength?` | The base unit of all the checkout font sizes, for example `CheckoutLength.px(4)`. The checkout sets each font size as a multiple of this unit. A CheckoutFontStyle.fontSize in a rule has priority over this unit. |
| `spacingUnitLength` | `CheckoutLength?` | The base unit of all the checkout spacing, for example `CheckoutLength.px(4)`. The checkout sets the space around and inside each element as a multiple of this unit. |

## Deprecated

### ~~borderRadius~~

<Warning>Deprecated. Use cornerRadius instead.</Warning>

```kotlin theme={null}
val borderRadius: String?
```

The corner radius as a CSS string.

### ~~fontSizeUnit~~

<Warning>Deprecated. Use fontSizeUnitLength instead.</Warning>

```kotlin theme={null}
val fontSizeUnit: String?
```

The font size unit as a CSS string.

### ~~spacingUnit~~

<Warning>Deprecated. Use spacingUnitLength instead.</Warning>

```kotlin theme={null}
val spacingUnit: String?
```

The spacing unit as a CSS string.


# CheckoutColorStyle
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/data-classes/checkout-color-style

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class CheckoutColorStyle(val textColor: CheckoutColor? = null, val backgroundColor: CheckoutColor? = null, val backgroundPrimaryColor: CheckoutColor? = null, val borderColor: CheckoutColor? = null, val boxShadow: String? = null, val placeholderColor: CheckoutColor? = null)
```

## Constructors

```kotlin theme={null}
constructor(textColor: CheckoutColor? = null, backgroundColor: CheckoutColor? = null, backgroundPrimaryColor: CheckoutColor? = null, borderColor: CheckoutColor? = null, boxShadow: String? = null, placeholderColor: CheckoutColor? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `backgroundColor` | `CheckoutColor?` | The background color. |
| `backgroundPrimaryColor` | `CheckoutColor?` | The primary background color of the element. For the checkout as a whole, use CheckoutVariablesColorStyle.backgroundPrimaryColor instead. |
| `borderColor` | `CheckoutColor?` | The border color. |
| `boxShadow` | `String?` | The CSS `box-shadow` value. |
| `placeholderColor` | `CheckoutColor?` | The color of the placeholder text. |
| `textColor` | `CheckoutColor?` | The text color. |

## Deprecated

### ~~background~~

<Warning>Deprecated. Use backgroundColor instead.</Warning>

```kotlin theme={null}
val background: String?
```

The background color as a CSS string.

### ~~border~~

<Warning>Deprecated. Use borderColor instead.</Warning>

```kotlin theme={null}
val border: String?
```

The border color as a CSS string.

### ~~placeholder~~

<Warning>Deprecated. Use placeholderColor instead.</Warning>

```kotlin theme={null}
val placeholder: String?
```

The placeholder text color as a CSS string.

### ~~text~~

<Warning>Deprecated. Use textColor instead.</Warning>

```kotlin theme={null}
val text: String?
```

The text color as a CSS string.


# CheckoutCryptoPayment
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/data-classes/checkout-crypto-payment

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class CheckoutCryptoPayment(val enabled: Boolean, val defaultChain: String? = null, val defaultCurrency: String? = null)
```

## Constructors

```kotlin theme={null}
constructor(enabled: Boolean, defaultChain: String? = null, defaultCurrency: String? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `defaultChain` | `String?` | - |
| `defaultCurrency` | `String?` | - |
| `enabled` | `Boolean` | - |


# CheckoutDestinationInputRule
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/data-classes/checkout-destination-input-rule

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class CheckoutDestinationInputRule(val display: String? = null)
```

## Constructors

```kotlin theme={null}
constructor(display: String? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `display` | `String?` | - |


# CheckoutFiatPayment
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/data-classes/checkout-fiat-payment

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class CheckoutFiatPayment(val enabled: Boolean, val defaultCurrency: String? = null, val allowedMethods: CheckoutAllowedMethods? = null)
```

## Constructors

```kotlin theme={null}
constructor(enabled: Boolean, defaultCurrency: String? = null, allowedMethods: CheckoutAllowedMethods? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `allowedMethods` | `CheckoutAllowedMethods?` | - |
| `defaultCurrency` | `String?` | - |
| `enabled` | `Boolean` | - |


# CheckoutFontSource
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/data-classes/checkout-font-source

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class CheckoutFontSource
```


# CheckoutFontStyle
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/data-classes/checkout-font-style

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class CheckoutFontStyle(val family: String? = null, val fontSize: CheckoutLength? = null, val fontWeight: CheckoutFontWeight? = null)
```

## Constructors

```kotlin theme={null}
constructor(family: String? = null, fontSize: CheckoutLength? = null, fontWeight: CheckoutFontWeight? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `family` | `String?` | The CSS `font-family` value, for example `"Inter, sans-serif"`. If the device does not have the font, load the font with CheckoutAppearance.fonts. |
| `fontSize` | `CheckoutLength?` | The font size. This size has priority over CheckoutAppearanceVariables.fontSizeUnitLength. |
| `fontWeight` | `CheckoutFontWeight?` | The font weight. |

## Deprecated

### ~~size~~

<Warning>Deprecated. Use fontSize instead.</Warning>

```kotlin theme={null}
val size: String?
```

The font size as a CSS string.

### ~~weight~~

<Warning>Deprecated. Use fontWeight instead.</Warning>

```kotlin theme={null}
val weight: String?
```

The font weight as a CSS string.


# CheckoutGlobalMessageRule
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/data-classes/checkout-global-message-rule

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class CheckoutGlobalMessageRule(val display: String? = null)
```

## Constructors

```kotlin theme={null}
constructor(display: String? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `display` | `String?` | - |


# CheckoutInputRule
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/data-classes/checkout-input-rule

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class CheckoutInputRule(val cornerRadius: CheckoutLength? = null, val font: CheckoutFontStyle? = null, val colors: CheckoutColorStyle? = null, val hover: CheckoutStateStyle? = null, val focus: CheckoutStateStyle? = null)
```

## Constructors

```kotlin theme={null}
constructor(cornerRadius: CheckoutLength? = null, font: CheckoutFontStyle? = null, colors: CheckoutColorStyle? = null, hover: CheckoutStateStyle? = null, focus: CheckoutStateStyle? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `colors` | `CheckoutColorStyle?` | The colors. |
| `cornerRadius` | `CheckoutLength?` | The corner radius, for example `CheckoutLength.px(8)`. |
| `focus` | `CheckoutStateStyle?` | The style when the field has focus. |
| `font` | `CheckoutFontStyle?` | The font. |
| `hover` | `CheckoutStateStyle?` | The style when the pointer is on the field. |

## Deprecated

### ~~borderRadius~~

<Warning>Deprecated. Use cornerRadius instead.</Warning>

```kotlin theme={null}
val borderRadius: String?
```

The corner radius as a CSS string.


# CheckoutLabelRule
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/data-classes/checkout-label-rule

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class CheckoutLabelRule(val font: CheckoutFontStyle? = null, val colors: CheckoutColorStyle? = null)
```

## Constructors

```kotlin theme={null}
constructor(font: CheckoutFontStyle? = null, colors: CheckoutColorStyle? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `colors` | `CheckoutColorStyle?` | - |
| `font` | `CheckoutFontStyle?` | - |


# CheckoutLineItems
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/data-classes/checkout-line-items

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class CheckoutLineItems(val tokenLocator: String? = null, val collectionLocator: String? = null, val executionParameters: Map<String, JsonElement>? = null, val callData: Map<String, JsonElement>? = null)
```

## Constructors

```kotlin theme={null}
constructor(tokenLocator: String? = null, collectionLocator: String? = null, executionParameters: Map<String, JsonElement>? = null, callData: Map<String, JsonElement>? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `callData` | `Map<String, JsonElement>?` | Raw on-chain call data for advanced use cases where higher-level parameters are insufficient. |
| `collectionLocator` | `String?` | Locator for a collection to mint from. Format: `chain:contractAddress` (e.g., `polygon:0x123...`) or `crossmint:collectionId` for Crossmint-managed collections. |
| `executionParameters` | `Map<String, JsonElement>?` | Custom parameters passed to the minting or purchase execution, such as quantity, recipient, or slippage settings. |
| `tokenLocator` | `String?` | Locator for a specific token to purchase. Supports NFTs, memecoins, and onramp tokens. Format: `chain:contractAddress:tokenId` (e.g., `polygon:0x123...:1`) or `chain:tokenAddress` for fungible tokens (e.g., `solana:7EivYFyNfgGj8...`). |


# CheckoutPayment
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/data-classes/checkout-payment

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class CheckoutPayment(val crypto: CheckoutCryptoPayment, val fiat: CheckoutFiatPayment, val receiptEmail: String? = null, val defaultMethod: CheckoutPaymentMethod? = null)
```

## Constructors

```kotlin theme={null}
constructor(crypto: CheckoutCryptoPayment, fiat: CheckoutFiatPayment, receiptEmail: String? = null, defaultMethod: CheckoutPaymentMethod? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `crypto` | `CheckoutCryptoPayment` | - |
| `defaultMethod` | `CheckoutPaymentMethod?` | - |
| `fiat` | `CheckoutFiatPayment` | - |
| `receiptEmail` | `String?` | - |


# CheckoutPrimaryButtonRule
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/data-classes/checkout-primary-button-rule

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class CheckoutPrimaryButtonRule(val cornerRadius: CheckoutLength? = null, val font: CheckoutFontStyle? = null, val colors: CheckoutColorStyle? = null, val hover: CheckoutStateStyle? = null, val disabled: CheckoutStateStyle? = null)
```

## Constructors

```kotlin theme={null}
constructor(cornerRadius: CheckoutLength? = null, font: CheckoutFontStyle? = null, colors: CheckoutColorStyle? = null, hover: CheckoutStateStyle? = null, disabled: CheckoutStateStyle? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `colors` | `CheckoutColorStyle?` | The colors. The button uses only CheckoutColorStyle.textColor and CheckoutColorStyle.backgroundColor. |
| `cornerRadius` | `CheckoutLength?` | The corner radius, for example `CheckoutLength.px(12)`. |
| `disabled` | `CheckoutStateStyle?` | The style when the button is disabled. |
| `font` | `CheckoutFontStyle?` | The font. |
| `hover` | `CheckoutStateStyle?` | The style when the pointer is on the button. |

## Deprecated

### ~~borderRadius~~

<Warning>Deprecated. Use cornerRadius instead.</Warning>

```kotlin theme={null}
val borderRadius: String?
```

The corner radius as a CSS string.


# CheckoutReceiptEmailInputRule
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/data-classes/checkout-receipt-email-input-rule

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class CheckoutReceiptEmailInputRule(val display: String? = null)
```

## Constructors

```kotlin theme={null}
constructor(display: String? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `display` | `String?` | - |


# CheckoutRecipient
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/data-classes/checkout-recipient

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class CheckoutRecipient(val walletAddress: String? = null, val email: String? = null)
```

## Constructors

```kotlin theme={null}
constructor(walletAddress: String? = null, email: String? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `email` | `String?` | - |
| `walletAddress` | `String?` | - |


# CheckoutStateStyle
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/data-classes/checkout-state-style

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class CheckoutStateStyle(val colors: CheckoutColorStyle? = null)
```

## Constructors

```kotlin theme={null}
constructor(colors: CheckoutColorStyle? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `colors` | `CheckoutColorStyle?` | - |


# CheckoutTabRule
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/data-classes/checkout-tab-rule

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class CheckoutTabRule(val cornerRadius: CheckoutLength? = null, val font: CheckoutFontStyle? = null, val colors: CheckoutColorStyle? = null, val hover: CheckoutStateStyle? = null, val selected: CheckoutStateStyle? = null)
```

## Constructors

```kotlin theme={null}
constructor(cornerRadius: CheckoutLength? = null, font: CheckoutFontStyle? = null, colors: CheckoutColorStyle? = null, hover: CheckoutStateStyle? = null, selected: CheckoutStateStyle? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `colors` | `CheckoutColorStyle?` | The colors. |
| `cornerRadius` | `CheckoutLength?` | The corner radius, for example `CheckoutLength.px(8)`. |
| `font` | `CheckoutFontStyle?` | The font. |
| `hover` | `CheckoutStateStyle?` | The style when the pointer is on the tab. |
| `selected` | `CheckoutStateStyle?` | The style of the selected tab. |

## Deprecated

### ~~borderRadius~~

<Warning>Deprecated. Use cornerRadius instead.</Warning>

```kotlin theme={null}
val borderRadius: String?
```

The corner radius as a CSS string.


# CheckoutVariablesColorStyle
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/data-classes/checkout-variables-color-style

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class CheckoutVariablesColorStyle(val textPrimaryColor: CheckoutColor? = null, val textSecondaryColor: CheckoutColor? = null, val backgroundPrimaryColor: CheckoutColor? = null, val borderPrimaryColor: CheckoutColor? = null, val dangerColor: CheckoutColor? = null, val warningColor: CheckoutColor? = null, val accentColor: CheckoutColor? = null)
```

## Constructors

```kotlin theme={null}
constructor(textPrimaryColor: CheckoutColor? = null, textSecondaryColor: CheckoutColor? = null, backgroundPrimaryColor: CheckoutColor? = null, borderPrimaryColor: CheckoutColor? = null, dangerColor: CheckoutColor? = null, warningColor: CheckoutColor? = null, accentColor: CheckoutColor? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `accentColor` | `CheckoutColor?` | The color of selected and active elements. |
| `backgroundPrimaryColor` | `CheckoutColor?` | The main background color. |
| `borderPrimaryColor` | `CheckoutColor?` | The main border color. |
| `dangerColor` | `CheckoutColor?` | The color of errors. |
| `textPrimaryColor` | `CheckoutColor?` | The main text color. |
| `textSecondaryColor` | `CheckoutColor?` | The color of less important text. |
| `warningColor` | `CheckoutColor?` | The color of warnings. |

## Deprecated

### ~~accent~~

<Warning>Deprecated. Use accentColor instead.</Warning>

```kotlin theme={null}
val accent: String?
```

The accent color as a CSS string.

### ~~backgroundPrimary~~

<Warning>Deprecated. Use backgroundPrimaryColor instead.</Warning>

```kotlin theme={null}
val backgroundPrimary: String?
```

The main background color as a CSS string.

### ~~borderPrimary~~

<Warning>Deprecated. Use borderPrimaryColor instead.</Warning>

```kotlin theme={null}
val borderPrimary: String?
```

The main border color as a CSS string.

### ~~danger~~

<Warning>Deprecated. Use dangerColor instead.</Warning>

```kotlin theme={null}
val danger: String?
```

The error color as a CSS string.

### ~~textPrimary~~

<Warning>Deprecated. Use textPrimaryColor instead.</Warning>

```kotlin theme={null}
val textPrimary: String?
```

The main text color as a CSS string.

### ~~textSecondary~~

<Warning>Deprecated. Use textSecondaryColor instead.</Warning>

```kotlin theme={null}
val textSecondary: String?
```

The secondary text color as a CSS string.

### ~~warning~~

<Warning>Deprecated. Use warningColor instead.</Warning>

```kotlin theme={null}
val warning: String?
```

The warning color as a CSS string.


# CheckoutEnvironment
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/enums/checkout-environment

Kotlin Enum Class

**Enum Class**

```kotlin theme={null}
enum CheckoutEnvironment : Enum<CheckoutEnvironment>
```

## Entries

| Entry | Description |
| - | - |
| `STAGING` | - |
| `PRODUCTION` | - |

## Properties

| Property | Type | Description |
| - | - | - |
| `entries` | `EnumEntries<CheckoutEnvironment>` | Returns a representation of an immutable list of all enum entries, in the order they're declared. |
| `name` | `String` | - |
| `ordinal` | `Int` | - |

## Functions

| Function | Description |
| - | - |
| `valueOf` | Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.) |
| `values` | Returns an array containing the constants of this enum type, in the order they're declared. |

### valueOf

```kotlin theme={null}
fun valueOf(value: String): CheckoutEnvironment
```

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

### values

```kotlin theme={null}
fun values(): Array<CheckoutEnvironment>
```

Returns an array containing the constants of this enum type, in the order they're declared.


# CheckoutPaymentMethod
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/enums/checkout-payment-method

Kotlin Enum Class

**Enum Class**

```kotlin theme={null}
enum CheckoutPaymentMethod : Enum<CheckoutPaymentMethod>
```

## Entries

| Entry | Description |
| - | - |
| `crypto` | crypto |
| `fiat` | fiat |

## Properties

| Property | Type | Description |
| - | - | - |
| `entries` | `EnumEntries<CheckoutPaymentMethod>` | Returns a representation of an immutable list of all enum entries, in the order they're declared. |
| `name` | `String` | - |
| `ordinal` | `Int` | - |

## Functions

| Function | Description |
| - | - |
| `valueOf` | Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.) |
| `values` | Returns an array containing the constants of this enum type, in the order they're declared. |

### valueOf

```kotlin theme={null}
fun valueOf(value: String): CheckoutPaymentMethod
```

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

### values

```kotlin theme={null}
fun values(): Array<CheckoutPaymentMethod>
```

Returns an array containing the constants of this enum type, in the order they're declared.


# IdentityVerificationHandling
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/enums/identity-verification-handling

Kotlin Enum Class

**Enum Class**

```kotlin theme={null}
enum IdentityVerificationHandling : Enum<IdentityVerificationHandling>
```

## Entries

| Entry | Description |
| - | - |
| `EXTERNAL` | Checkout does not render the verification step. You render `CrossmintIdentityVerification` from the `sdk-identity` module in your own layout, with the credentials from the order's `payment.preparation.kyc`. Show it when the order first carries credentials, keep passing the latest non-null credentials until its `onComplete` or `onCancel` runs, then do not show it again for that order. Checkout polls the order and continues after verification completes. |

## Properties

| Property | Type | Description |
| - | - | - |
| `entries` | `EnumEntries<IdentityVerificationHandling>` | Returns a representation of an immutable list of all enum entries, in the order they're declared. |
| `name` | `String` | - |
| `ordinal` | `Int` | - |

## Functions

| Function | Description |
| - | - |
| `valueOf` | Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.) |
| `values` | Returns an array containing the constants of this enum type, in the order they're declared. |

### valueOf

```kotlin theme={null}
fun valueOf(value: String): IdentityVerificationHandling
```

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

### values

```kotlin theme={null}
fun values(): Array<IdentityVerificationHandling>
```

Returns an array containing the constants of this enum type, in the order they're declared.


# Kotlin SDK Reference
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/index

API reference for the Crossmint Kotlin SDK

# Kotlin SDK Reference

## Composables

* [CrossmintEmbeddedCheckout](/sdk-reference/checkout/kotlin/composables/crossmint-embedded-checkout)

## Classes

* [CheckoutColor](/sdk-reference/checkout/kotlin/classes/checkout-color)
* [CheckoutError.EncodingError](/sdk-reference/checkout/kotlin/classes/checkout-error-encoding-error)
* [CheckoutError.InvalidConfiguration](/sdk-reference/checkout/kotlin/classes/checkout-error-invalid-configuration)
* [CheckoutError.NotImplemented](/sdk-reference/checkout/kotlin/classes/checkout-error-not-implemented)
* [CheckoutFontWeight](/sdk-reference/checkout/kotlin/classes/checkout-font-weight)
* [CheckoutLength](/sdk-reference/checkout/kotlin/classes/checkout-length)

## Data Classes

* [CheckoutAllowedMethods](/sdk-reference/checkout/kotlin/data-classes/checkout-allowed-methods)
* [CheckoutAppearance](/sdk-reference/checkout/kotlin/data-classes/checkout-appearance)
* [CheckoutAppearanceRules](/sdk-reference/checkout/kotlin/data-classes/checkout-appearance-rules)
* [CheckoutAppearanceVariables](/sdk-reference/checkout/kotlin/data-classes/checkout-appearance-variables)
* [CheckoutColorStyle](/sdk-reference/checkout/kotlin/data-classes/checkout-color-style)
* [CheckoutCryptoPayment](/sdk-reference/checkout/kotlin/data-classes/checkout-crypto-payment)
* [CheckoutDestinationInputRule](/sdk-reference/checkout/kotlin/data-classes/checkout-destination-input-rule)
* [CheckoutFiatPayment](/sdk-reference/checkout/kotlin/data-classes/checkout-fiat-payment)
* [CheckoutFontSource](/sdk-reference/checkout/kotlin/data-classes/checkout-font-source)
* [CheckoutFontStyle](/sdk-reference/checkout/kotlin/data-classes/checkout-font-style)
* [CheckoutGlobalMessageRule](/sdk-reference/checkout/kotlin/data-classes/checkout-global-message-rule)
* [CheckoutInputRule](/sdk-reference/checkout/kotlin/data-classes/checkout-input-rule)
* [CheckoutLabelRule](/sdk-reference/checkout/kotlin/data-classes/checkout-label-rule)
* [CheckoutLineItems](/sdk-reference/checkout/kotlin/data-classes/checkout-line-items)
* [CheckoutPayment](/sdk-reference/checkout/kotlin/data-classes/checkout-payment)
* [CheckoutPrimaryButtonRule](/sdk-reference/checkout/kotlin/data-classes/checkout-primary-button-rule)
* [CheckoutReceiptEmailInputRule](/sdk-reference/checkout/kotlin/data-classes/checkout-receipt-email-input-rule)
* [CheckoutRecipient](/sdk-reference/checkout/kotlin/data-classes/checkout-recipient)
* [CheckoutStateStyle](/sdk-reference/checkout/kotlin/data-classes/checkout-state-style)
* [CheckoutTabRule](/sdk-reference/checkout/kotlin/data-classes/checkout-tab-rule)
* [CheckoutVariablesColorStyle](/sdk-reference/checkout/kotlin/data-classes/checkout-variables-color-style)

## Sealed Classes

* [CheckoutError](/sdk-reference/checkout/kotlin/sealed-classes/checkout-error)

## Enums

* [CheckoutEnvironment](/sdk-reference/checkout/kotlin/enums/checkout-environment)
* [CheckoutPaymentMethod](/sdk-reference/checkout/kotlin/enums/checkout-payment-method)
* [IdentityVerificationHandling](/sdk-reference/checkout/kotlin/enums/identity-verification-handling)

## Objects

* [CheckoutAppearanceVariables.Companion](/sdk-reference/checkout/kotlin/objects/checkout-appearance-variables-companion)
* [CheckoutColor.Companion](/sdk-reference/checkout/kotlin/objects/checkout-color-companion)
* [CheckoutColorStyle.Companion](/sdk-reference/checkout/kotlin/objects/checkout-color-style-companion)
* [CheckoutFontSource.Companion](/sdk-reference/checkout/kotlin/objects/checkout-font-source-companion)
* [CheckoutFontStyle.Companion](/sdk-reference/checkout/kotlin/objects/checkout-font-style-companion)
* [CheckoutFontWeight.Companion](/sdk-reference/checkout/kotlin/objects/checkout-font-weight-companion)
* [CheckoutInputRule.Companion](/sdk-reference/checkout/kotlin/objects/checkout-input-rule-companion)
* [CheckoutLength.Companion](/sdk-reference/checkout/kotlin/objects/checkout-length-companion)
* [CheckoutPrimaryButtonRule.Companion](/sdk-reference/checkout/kotlin/objects/checkout-primary-button-rule-companion)
* [CheckoutTabRule.Companion](/sdk-reference/checkout/kotlin/objects/checkout-tab-rule-companion)
* [CheckoutVariablesColorStyle.Companion](/sdk-reference/checkout/kotlin/objects/checkout-variables-color-style-companion)


# CheckoutAppearanceVariables.Companion
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/objects/checkout-appearance-variables-companion

Kotlin Object

**Object**

```kotlin theme={null}
companion object
```

## Deprecated

### ~~invoke~~

<Warning>Deprecated. Pass spacingUnitLength, fontSizeUnitLength, and cornerRadius as a CheckoutLength, for example CheckoutLength.px(4) or CheckoutLength.custom("4px").</Warning>

```kotlin theme={null}
operator fun invoke(fontFamily: String? = null, spacingUnit: String? = null, fontSizeUnit: String? = null, borderRadius: String? = null, colors: CheckoutVariablesColorStyle? = null): CheckoutAppearanceVariables
```

Creates the variables with CSS strings for the spacing unit, font size unit, and corner radius.


# CheckoutColor.Companion
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/objects/checkout-color-companion

Kotlin Object

**Object**

```kotlin theme={null}
companion object
```

## Functions

| Function | Description |
| - | - |
| `color` | Creates a color from a Compose color, for example `Color(0xFF0066FF)`. |
| `css` | Creates a color from a CSS color value, for example `"rgb(26, 26, 26)"`. |
| `hex` | Creates a color from a hex string, for example `"#1A1A1A"` or `"#1A1A1A80"`. |

### color

```kotlin theme={null}
fun color(color: Color): CheckoutColor
```

Creates a color from a Compose color, for example `Color(0xFF0066FF)`.

### css

```kotlin theme={null}
fun css(value: String): CheckoutColor
```

Creates a color from a CSS color value, for example `"rgb(26, 26, 26)"`.

### hex

```kotlin theme={null}
fun hex(value: String): CheckoutColor
```

Creates a color from a hex string, for example `"#1A1A1A"` or `"#1A1A1A80"`.


# CheckoutColorStyle.Companion
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/objects/checkout-color-style-companion

Kotlin Object

**Object**

```kotlin theme={null}
companion object
```

## Deprecated

### ~~invoke~~

<Warning>Deprecated. Pass each color as a CheckoutColor, for example textColor = CheckoutColor.color(Color.Blue), CheckoutColor.hex("#0066FF"), or CheckoutColor.css("rgb(0, 102, 255)").</Warning>

```kotlin theme={null}
operator fun invoke(text: String? = null, background: String? = null, border: String? = null, boxShadow: String? = null, placeholder: String? = null): CheckoutColorStyle
```

Creates a color style from CSS color strings.


# CheckoutFontSource.Companion
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/objects/checkout-font-source-companion

Kotlin Object

**Object**

```kotlin theme={null}
companion object
```

## Functions

| Function | Description |
| - | - |
| `cssUrl` | Loads the fonts that a CSS stylesheet declares. |
| `googleFonts` | Loads a font family from Google Fonts. |

### cssUrl

```kotlin theme={null}
fun cssUrl(url: String): CheckoutFontSource
```

Loads the fonts that a CSS stylesheet declares.

### googleFonts

```kotlin theme={null}
fun googleFonts(family: String, weights: List<CheckoutFontWeight> = emptyList()): CheckoutFontSource
```

Loads a font family from Google Fonts.


# CheckoutFontStyle.Companion
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/objects/checkout-font-style-companion

Kotlin Object

**Object**

```kotlin theme={null}
companion object
```

## Deprecated

### ~~invoke~~

<Warning>Deprecated. Pass fontSize as a CheckoutLength and fontWeight as a CheckoutFontWeight, for example CheckoutLength.px(14) and CheckoutFontWeight.SemiBold.</Warning>

```kotlin theme={null}
operator fun invoke(family: String? = null, size: String? = null, weight: String? = null): CheckoutFontStyle
```

Creates a font style from CSS strings.


# CheckoutFontWeight.Companion
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/objects/checkout-font-weight-companion

Kotlin Object

**Object**

```kotlin theme={null}
companion object
```

## Properties

| Property | Type | Description |
| - | - | - |
| `Black` | `CheckoutFontWeight` | The weight `900`. |
| `Bold` | `CheckoutFontWeight` | The weight `700`. |
| `ExtraBold` | `CheckoutFontWeight` | The weight `800`. |
| `ExtraLight` | `CheckoutFontWeight` | The weight `200`. |
| `Light` | `CheckoutFontWeight` | The weight `300`. |
| `Medium` | `CheckoutFontWeight` | The weight `500`. |
| `Normal` | `CheckoutFontWeight` | The weight `400`. |
| `SemiBold` | `CheckoutFontWeight` | The weight `600`. |
| `Thin` | `CheckoutFontWeight` | The weight `100`. |

## Functions

| Function | Description |
| - | - |
| `custom` | Any CSS `font-weight` value, for example `"bolder"` or `"lighter"`. |

### custom

```kotlin theme={null}
fun custom(css: String): CheckoutFontWeight
```

Any CSS `font-weight` value, for example `"bolder"` or `"lighter"`.


# CheckoutInputRule.Companion
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/objects/checkout-input-rule-companion

Kotlin Object

**Object**

```kotlin theme={null}
companion object
```

## Deprecated

### ~~invoke~~

<Warning>Deprecated. Pass cornerRadius as a CheckoutLength, for example CheckoutLength.px(8) or CheckoutLength.custom("8px").</Warning>

```kotlin theme={null}
operator fun invoke(borderRadius: String? = null, font: CheckoutFontStyle? = null, colors: CheckoutColorStyle? = null, hover: CheckoutStateStyle? = null, focus: CheckoutStateStyle? = null): CheckoutInputRule
```

Creates an input rule with a CSS string for the corner radius.


# CheckoutLength.Companion
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/objects/checkout-length-companion

Kotlin Object

**Object**

```kotlin theme={null}
companion object
```

## Functions

| Function | Description |
| - | - |
| `custom` | Any CSS length value, for example `"50%"` or `"clamp(14px, 4vw, 18px)"`. |
| `em` | A length relative to the font size of the parent element. |
| `px` | A length in CSS pixels. |
| `rem` | A length relative to the font size of the root element. |

### custom

```kotlin theme={null}
fun custom(css: String): CheckoutLength
```

Any CSS length value, for example `"50%"` or `"clamp(14px, 4vw, 18px)"`.

### em

```kotlin theme={null}
fun em(value: Double): CheckoutLength
```

```kotlin theme={null}
fun em(value: Int): CheckoutLength
```

A length relative to the font size of the parent element.

### px

```kotlin theme={null}
fun px(value: Double): CheckoutLength
```

```kotlin theme={null}
fun px(value: Int): CheckoutLength
```

A length in CSS pixels.

### rem

```kotlin theme={null}
fun rem(value: Double): CheckoutLength
```

```kotlin theme={null}
fun rem(value: Int): CheckoutLength
```

A length relative to the font size of the root element.


# CheckoutPrimaryButtonRule.Companion
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/objects/checkout-primary-button-rule-companion

Kotlin Object

**Object**

```kotlin theme={null}
companion object
```

## Deprecated

### ~~invoke~~

<Warning>Deprecated. Pass cornerRadius as a CheckoutLength, for example CheckoutLength.px(12) or CheckoutLength.custom("12px").</Warning>

```kotlin theme={null}
operator fun invoke(borderRadius: String? = null, font: CheckoutFontStyle? = null, colors: CheckoutColorStyle? = null, hover: CheckoutStateStyle? = null, disabled: CheckoutStateStyle? = null): CheckoutPrimaryButtonRule
```

Creates a primary button rule with a CSS string for the corner radius.


# CheckoutTabRule.Companion
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/objects/checkout-tab-rule-companion

Kotlin Object

**Object**

```kotlin theme={null}
companion object
```

## Deprecated

### ~~invoke~~

<Warning>Deprecated. Pass cornerRadius as a CheckoutLength, for example CheckoutLength.px(8) or CheckoutLength.custom("8px").</Warning>

```kotlin theme={null}
operator fun invoke(borderRadius: String? = null, font: CheckoutFontStyle? = null, colors: CheckoutColorStyle? = null, hover: CheckoutStateStyle? = null, selected: CheckoutStateStyle? = null): CheckoutTabRule
```

Creates a tab rule with a CSS string for the corner radius.


# CheckoutVariablesColorStyle.Companion
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/objects/checkout-variables-color-style-companion

Kotlin Object

**Object**

```kotlin theme={null}
companion object
```

## Deprecated

### ~~invoke~~

<Warning>Deprecated. Pass each color as a CheckoutColor, for example accentColor = CheckoutColor.color(Color.Blue), CheckoutColor.hex("#0066FF"), or CheckoutColor.css("rgb(0, 102, 255)").</Warning>

```kotlin theme={null}
operator fun invoke(textPrimary: String? = null, textSecondary: String? = null, backgroundPrimary: String? = null, borderPrimary: String? = null, danger: String? = null, warning: String? = null, accent: String? = null): CheckoutVariablesColorStyle
```

Creates the global colors from CSS color strings.


# CheckoutError
Source: https://docs.crossmint.com/sdk-reference/checkout/kotlin/sealed-classes/checkout-error

Kotlin Sealed Class

**Sealed Class**

```kotlin theme={null}
sealed class CheckoutError : Exception
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `message` | `String?` | - |


# Components
Source: https://docs.crossmint.com/sdk-reference/checkout/react-native/components

React Native components for React Native SDK reference for Crossmint checkout

## CrossmintEmbeddedCheckout

### Props

<ResponseField name="appearance" type="EmbeddedCheckoutV3Appearance">
  <Expandable title="properties">
    <ResponseField name="fonts" type="{ cssSrc: string }[]">
      <Expandable title="properties">
        <ResponseField name="cssSrc" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="rules" type="EmbeddedCheckoutV3AppearanceRules">
      <Expandable title="properties">
        <ResponseField name="DestinationInput" type="{ display?: &#x22;hidden&#x22; }">
          <Expandable title="properties">
            <ResponseField name="display" type="&#x22;hidden&#x22;" />
          </Expandable>
        </ResponseField>

        <ResponseField name="GlobalMessage" type="{ display?: &#x22;hidden&#x22; | &#x22;visible&#x22; }">
          <Expandable title="properties">
            <ResponseField name="display" type="&#x22;hidden&#x22; | &#x22;visible&#x22;" />
          </Expandable>
        </ResponseField>

        <ResponseField name="Input" type="object">
          <Expandable title="properties">
            <ResponseField name="borderRadius" type="string" />

            <ResponseField name="colors" type="{ background?: string; border?: string; boxShadow?: string; placeholder?: string; text?: string }" />

            <ResponseField name="focus" type="{ colors?: { background?: string; border?: string; boxShadow?: string } }" />

            <ResponseField name="font" type="{ family?: string; size?: string; weight?: string }" />

            <ResponseField name="hover" type="{ colors?: { background?: string; border?: string; boxShadow?: string; text?: string } }" />
          </Expandable>
        </ResponseField>

        <ResponseField name="Label" type="{ colors?: { text?: string }; font?: { family?: string; size?: string; weight?: string } }">
          <Expandable title="properties">
            <ResponseField name="colors" type="{ text?: string }" />

            <ResponseField name="font" type="{ family?: string; size?: string; weight?: string }" />
          </Expandable>
        </ResponseField>

        <ResponseField name="PrimaryButton" type="object">
          <Expandable title="properties">
            <ResponseField name="borderRadius" type="string" />

            <ResponseField name="colors" type="{ background?: string; text?: string }" />

            <ResponseField name="disabled" type="{ colors?: { background?: string; text?: string } }" />

            <ResponseField name="font" type="{ family?: string; size?: string; weight?: string }" />

            <ResponseField name="hover" type="{ colors?: { background?: string; text?: string } }" />
          </Expandable>
        </ResponseField>

        <ResponseField name="ReceiptEmailInput" type="{ display?: &#x22;hidden&#x22; }">
          <Expandable title="properties">
            <ResponseField name="display" type="&#x22;hidden&#x22;" />
          </Expandable>
        </ResponseField>

        <ResponseField name="Tab" type="object">
          <Expandable title="properties">
            <ResponseField name="borderRadius" type="string" />

            <ResponseField name="colors" type="{ background?: string; border?: string; boxShadow?: string; text?: string }" />

            <ResponseField name="font" type="{ family?: string; size?: string; weight?: string }" />

            <ResponseField name="hover" type="{ colors?: { background?: string; border?: string; boxShadow?: string; text?: string } }" />

            <ResponseField name="selected" type="{ colors?: { background?: string; border?: string; boxShadow?: string; text?: string } }" />
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="variables" type="EmbeddedCheckoutV3AppearanceVariables">
      <Expandable title="properties">
        <ResponseField name="borderRadius" type="string" />

        <ResponseField name="colors" type="object">
          <Expandable title="properties">
            <ResponseField name="accent" type="string" />

            <ResponseField name="backgroundPrimary" type="string" />

            <ResponseField name="borderPrimary" type="string" />

            <ResponseField name="danger" type="string" />

            <ResponseField name="textPrimary" type="string" />

            <ResponseField name="textSecondary" type="string" />

            <ResponseField name="warning" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="fontFamily" type="string" />

        <ResponseField name="fontSizeUnit" type="string">
          Multiplier unit for font sizes, not a base font size. Default `"4px"`: labels render at `fontSizeUnit * 3.75` (15px), inputs at `* 4` (16px), the primary button at `* 4.25` (17px). Passing a body size such as `"14px"` (the `VerificationAppearance` convention) yields \~52px labels.
        </ResponseField>

        <ResponseField name="spacingUnit" type="string">
          Multiplier unit for paddings and gaps, not a base spacing. Default `"3.33px"`; each spacing is `calc(spacingUnit * k)` with k between 3.6 and 4.42.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="clientSecret" type="string" />

<ResponseField name="identityVerificationHandling" type="&#x22;external&#x22;">
  `"external"`: you mount `CrossmintIdentityVerification` from `getIdentityVerificationCredentials(order)`, or the buyer cannot finish.
</ResponseField>

<ResponseField name="jwt" type="string" />

<ResponseField name="orderId" type="string" />

<ResponseField name="payment" type="EmbeddedCheckoutV3Payment">
  <Expandable title="properties">
    <ResponseField name="crypto" type="EmbeddedCheckoutV3CryptoPayment">
      <Expandable title="properties">
        <ResponseField name="defaultChain" type="BlockchainIncludingTestnet" />

        <ResponseField name="defaultCurrency" type="CryptoCurrency" />

        <ResponseField name="enabled" type="boolean" />

        <ResponseField name="payer" type="EmbeddedCheckoutPayer">
          <Expandable title="properties">
            <ResponseField name="address" type="string" />

            <ResponseField name="initialChain" type="PayerSupportedBlockchains" />

            <ResponseField name="supportedChains" type="PayerSupportedBlockchains[]" />

            <ResponseField name="handleChainSwitch" type="unknown" />

            <ResponseField name="handleSignAndSendTransaction" type="unknown" />

            <ResponseField name="handleSignMessage" type="unknown" />
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="defaultMethod" type="&#x22;fiat&#x22; | &#x22;crypto&#x22;" />

    <ResponseField name="fiat" type="EmbeddedCheckoutV3FiatPayment">
      <Expandable title="properties">
        <ResponseField name="allowedMethods" type="{ applePay?: boolean; card?: boolean; googlePay?: boolean }">
          <Expandable title="properties">
            <ResponseField name="applePay" type="boolean" />

            <ResponseField name="card" type="boolean" />

            <ResponseField name="googlePay" type="boolean" />
          </Expandable>
        </ResponseField>

        <ResponseField name="defaultCurrency" type="FiatCurrency" />

        <ResponseField name="enabled" type="boolean" />
      </Expandable>
    </ResponseField>

    <ResponseField name="receiptEmail" type="string" />
  </Expandable>
</ResponseField>

<ResponseField name="lineItems" type="EmbeddedCheckoutV3LineItem | EmbeddedCheckoutV3LineItem[]">
  <Expandable title="properties">
    <ResponseField name="callData" type="Record<string, any>" />

    <ResponseField name="collectionLocator" type="string" />

    <ResponseField name="tokenLocator" type="string" />

    <ResponseField name="executionParameters" type="Record<string, any>" />

    <ResponseField name="productLocator" type="string" />
  </Expandable>
</ResponseField>

<ResponseField name="locale" type="Locale" />

<ResponseField name="metadata" type="JSONObject" />

<ResponseField name="recipient" type="EmbeddedCheckoutV3Recipient">
  <Expandable title="properties">
    <ResponseField name="email" type="string" />

    <ResponseField name="physicalAddress" type="EmbeddedCheckoutV3PhysicalAddress">
      <Expandable title="properties">
        <ResponseField name="city" type="string" />

        <ResponseField name="country" type="&#x22;US&#x22;" />

        <ResponseField name="line1" type="string" />

        <ResponseField name="line2" type="string" />

        <ResponseField name="name" type="string" />

        <ResponseField name="postalCode" type="string" />

        <ResponseField name="state" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="walletAddress" type="string" />
  </Expandable>
</ResponseField>

### Usage

```tsx theme={null}
import { CrossmintEmbeddedCheckout } from "@crossmint/client-sdk-react-native-ui";

function CheckoutScreen() {
    return (
        <CrossmintEmbeddedCheckout
            lineItems={{
                collectionLocator: "crossmint:YOUR_COLLECTION_ID",
                callData: {
                    totalPrice: "0.001",
                },
            }}
            payment={{
                crypto: {
                    enabled: true,
                    defaultChain: "base-sepolia",
                    defaultCurrency: "usdc",
                    payer: {
                        address: "0x...",
                        initialChain: "base-sepolia",
                        handleChainSwitch: async (chain) => {
                            // Switch your wallet to the requested chain
                        },
                        handleSignAndSendTransaction: async (serializedTransaction) => {
                            const txId = await sendTransaction(serializedTransaction);
                            return { success: true, txId };
                        },
                    },
                },
                fiat: {
                    enabled: true,
                    defaultCurrency: "usd",
                    allowedMethods: {
                        card: true,
                        applePay: true,
                        googlePay: true,
                    },
                },
                receiptEmail: "buyer@example.com",
            }}
            recipient={{ email: "buyer@example.com" }}
            locale="en-US"
        />
    );
}
```

> **Note:** In React Native, when payment.crypto.enabled is true, you must provide a payment.crypto.payer object with the required callback handlers for signing transactions and switching chains.

***

## CrossmintIdentityVerification

### Props

<ResponseField name="credentials" type="IdentityVerificationCredentials">
  <Expandable title="properties">
    <ResponseField name="inquiryId" type="string" />

    <ResponseField name="provider" type="&#x22;persona&#x22;" />

    <ResponseField name="sessionToken" type="string" />
  </Expandable>
</ResponseField>

<ResponseField name="locale" type="Locale" />

<ResponseField name="onCancel" type="() => void" />

<ResponseField name="onComplete" type="(result: { status: &#x22;expired&#x22; | &#x22;unknown&#x22; | &#x22;failed&#x22; | &#x22;verified&#x22; | &#x22;pending-review&#x22; | &#x22;pending-manual-review&#x22; | &#x22;declined&#x22; }) => void" />

<ResponseField name="onError" type="(error: object) => void" />

<ResponseField name="onReady" type="() => void" />

### Usage

```tsx theme={null}
import {
    CrossmintIdentityVerification,
    useIdentityVerificationCredentials,
} from "@crossmint/client-sdk-react-native-ui";

function VerificationStep() {
    const credentials = useIdentityVerificationCredentials();

    if (credentials == null) {
        return null;
    }

    return (
        <CrossmintIdentityVerification
            credentials={credentials}
            onComplete={({ status }) => console.log(status)}
        />
    );
}
```

> **Note:** Document capture needs camera access granted by the host app. On Android the WebView requests `android.permission.CAMERA` at runtime, which only succeeds if your app declares it in AndroidManifest.xml; on iOS you must set `NSCameraUsageDescription` in Info.plist. Neither is added for you.


# Get Started
Source: https://docs.crossmint.com/sdk-reference/checkout/react-native/get-started

Installation and setup for the React Native SDK reference for Crossmint checkout

### Latest React Native SDK version - <a href="https://www.npmjs.com/package/@crossmint/client-sdk-react-native-ui"><img alt="npm" /></a>

The Crossmint React Native SDK (`@crossmint/client-sdk-react-native-ui`) provides React Native components and hooks for integrating Crossmint checkout into your mobile application. It supports embedded checkout via a WebView.

## Installation

<Snippet />

## Provider Setup

Wrap your application with the required providers:

```tsx theme={null}
import {
    CrossmintProvider,
    CrossmintCheckoutProvider,
} from "@crossmint/client-sdk-react-native-ui";

function App() {
    return (
        <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
            <CrossmintCheckoutProvider>
                {/* Your checkout components */}
            </CrossmintCheckoutProvider>
        </CrossmintProvider>
    );
}
```

## Quick Example

Once providers are set up, use the checkout components to accept payments:

```tsx theme={null}
import { CrossmintEmbeddedCheckout } from "@crossmint/client-sdk-react-native-ui";

function CheckoutScreen() {
    return (
        <CrossmintEmbeddedCheckout
            lineItems={{
                collectionLocator: "crossmint:YOUR_COLLECTION_ID",
                callData: {
                    totalPrice: "0.001",
                },
            }}
            payment={{
                crypto: {
                    enabled: true,
                    payer: {
                        address: "0x...",
                        initialChain: "base-sepolia",
                        handleChainSwitch: async (chain) => {
                            // Switch your wallet to the requested chain
                        },
                        handleSignAndSendTransaction: async (serializedTransaction) => {
                            const txId = await sendTransaction(serializedTransaction);
                            return { success: true, txId };
                        },
                    },
                },
                fiat: { enabled: true, defaultCurrency: "usd" },
                receiptEmail: "buyer@example.com",
            }}
            recipient={{ email: "buyer@example.com" }}
        />
    );
}
```

## Next Steps

* [Providers](/sdk-reference/checkout/react-native/providers) — Configure providers and their options
* [Hooks](/sdk-reference/checkout/react-native/hooks) — Access SDK state via React hooks
* [Components](/sdk-reference/checkout/react-native/components) — Drop-in UI components


# Hooks
Source: https://docs.crossmint.com/sdk-reference/checkout/react-native/hooks

React Native hooks for React Native SDK reference for Crossmint checkout

## useCrossmintCheckout()

### Returns

<ResponseField name="order" type="object">
  <Expandable title="parameters">
    <ResponseField name="lineItems" type="object[]">
      <Expandable title="parameters">
        <ResponseField name="callData" type="Record<string, any>" />

        <ResponseField name="chain" type="&#x22;solana&#x22; | &#x22;sui&#x22; | &#x22;aptos&#x22; | &#x22;ethereum&#x22; | &#x22;polygon&#x22; | &#x22;bsc&#x22; | &#x22;optimism&#x22; | &#x22;arbitrum&#x22; | &#x22;base&#x22; | &#x22;zora&#x22; | ..." />

        <ResponseField name="delivery" type="{ recipient?: object | object; status: &#x22;completed&#x22;; tokens: ... | ...[]; txId: string } | ...">
          <Expandable title="parameters">
            <ResponseField name="recipient" type="{ locator: string; physicalAddress?: object; walletAddress: string } | ..." />

            <ResponseField name="status" type="&#x22;completed&#x22;" />

            <ResponseField name="tokens" type="object | object[]" />

            <ResponseField name="txId" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="metadata" type="object">
          <Expandable title="parameters">
            <ResponseField name="collection" type="{ description?: string; imageUrl?: string; name?: string }" />

            <ResponseField name="description" type="string" />

            <ResponseField name="imageUrl" type="string" />

            <ResponseField name="name" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="quantity" type="number" />

        <ResponseField name="quote" type="object">
          <Expandable title="parameters">
            <ResponseField name="charges" type="{ gas?: object; unit: object }" />

            <ResponseField name="status" type="&#x22;valid&#x22; | &#x22;expired&#x22; | &#x22;requires-recipient&#x22; | &#x22;item-unavailable&#x22;" />

            <ResponseField name="totalPrice" type="object" />

            <ResponseField name="unavailabilityReason" type="{ code: &#x22;to&#x22; | &#x22;do&#x22;; message: string }" />
          </Expandable>
        </ResponseField>

        <ResponseField name="slippageBps" type="number" />
      </Expandable>
    </ResponseField>

    <ResponseField name="locale" type="&#x22;en-US&#x22; | &#x22;es-ES&#x22; | &#x22;fr-FR&#x22; | &#x22;it-IT&#x22; | &#x22;ja-JP&#x22; | &#x22;ko-KR&#x22; | &#x22;pt-PT&#x22; | &#x22;zh-CN&#x22; | &#x22;zh-TW&#x22; | &#x22;de-DE&#x22; | &#x22;ru-RU&#x22; | ..." />

    <ResponseField name="orderId" type="string" />

    <ResponseField name="payment" type="object">
      <Expandable title="parameters">
        <ResponseField name="currency" type="&#x22;usd&#x22; | &#x22;eur&#x22; | &#x22;gbp&#x22; | &#x22;aud&#x22; | &#x22;sgd&#x22; | &#x22;hkd&#x22; | &#x22;krw&#x22; | &#x22;inr&#x22; | &#x22;vnd&#x22; | &#x22;jpy&#x22; | &#x22;eth&#x22; | &#x22;matic&#x22; | &#x22;usdc&#x22; | ..." />

        <ResponseField name="failureReason" type="{ code: string; message?: string } | { code: &#x22;unknown&#x22; | &#x22;tx-id-not-found&#x22; | &#x22;insufficient-funds&#x22;; message?: string }">
          <Expandable title="parameters">
            <ResponseField name="code" type="string" />

            <ResponseField name="message" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="method" type="&#x22;solana&#x22; | &#x22;ethereum&#x22; | &#x22;polygon&#x22; | &#x22;bsc&#x22; | &#x22;optimism&#x22; | &#x22;arbitrum&#x22; | &#x22;base&#x22; | &#x22;zora&#x22; | &#x22;arbitrumnova&#x22; | ..." />

        <ResponseField name="preparation" type="object | object">
          <Expandable title="parameters">
            <ResponseField name="chain" type="&#x22;solana&#x22; | &#x22;sui&#x22; | &#x22;aptos&#x22; | &#x22;ethereum&#x22; | &#x22;polygon&#x22; | &#x22;bsc&#x22; | &#x22;optimism&#x22; | &#x22;arbitrum&#x22; | &#x22;base&#x22; | &#x22;zora&#x22; | ..." />

            <ResponseField name="payerAddress" type="string" />

            <ResponseField name="serializedTransaction" type="string" />

            <ResponseField name="stripeClientSecret" type="string" />

            <ResponseField name="stripeEphemeralKeySecret" type="string" />

            <ResponseField name="stripePublishableKey" type="string" />

            <ResponseField name="stripeSubscriptionId" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="receiptEmail" type="string" />

        <ResponseField name="received" type="object | object">
          <Expandable title="parameters">
            <ResponseField name="amount" type="string" />

            <ResponseField name="currency" type="&#x22;usd&#x22; | &#x22;eur&#x22; | &#x22;gbp&#x22; | &#x22;aud&#x22; | &#x22;sgd&#x22; | &#x22;hkd&#x22; | &#x22;krw&#x22; | &#x22;inr&#x22; | &#x22;vnd&#x22; | &#x22;jpy&#x22; | &#x22;eth&#x22; | &#x22;matic&#x22; | &#x22;usdc&#x22; | ..." />

            <ResponseField name="chain" type="&#x22;solana&#x22; | &#x22;sui&#x22; | &#x22;aptos&#x22; | &#x22;ethereum&#x22; | &#x22;polygon&#x22; | &#x22;bsc&#x22; | &#x22;optimism&#x22; | &#x22;arbitrum&#x22; | &#x22;base&#x22; | &#x22;zora&#x22; | ..." />

            <ResponseField name="txId" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="refunded" type="object | object">
          <Expandable title="parameters">
            <ResponseField name="amount" type="string" />

            <ResponseField name="currency" type="&#x22;usd&#x22; | &#x22;eur&#x22; | &#x22;gbp&#x22; | &#x22;aud&#x22; | &#x22;sgd&#x22; | &#x22;hkd&#x22; | &#x22;krw&#x22; | &#x22;inr&#x22; | &#x22;vnd&#x22; | &#x22;jpy&#x22; | &#x22;eth&#x22; | &#x22;matic&#x22; | &#x22;usdc&#x22; | ..." />

            <ResponseField name="chain" type="&#x22;solana&#x22; | &#x22;sui&#x22; | &#x22;aptos&#x22; | &#x22;ethereum&#x22; | &#x22;polygon&#x22; | &#x22;bsc&#x22; | &#x22;optimism&#x22; | &#x22;arbitrum&#x22; | &#x22;base&#x22; | &#x22;zora&#x22; | ..." />

            <ResponseField name="txId" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="status" type="&#x22;in-progress&#x22; | &#x22;completed&#x22; | &#x22;awaiting-payment&#x22; | &#x22;requires-quote&#x22; | &#x22;requires-crypto-payer-address&#x22; | ..." />
      </Expandable>
    </ResponseField>

    <ResponseField name="phase" type="&#x22;completed&#x22; | &#x22;quote&#x22; | &#x22;delivery&#x22; | &#x22;payment&#x22;" />

    <ResponseField name="quote" type="object">
      <Expandable title="parameters">
        <ResponseField name="expiresAt" type="string" />

        <ResponseField name="quotedAt" type="string" />

        <ResponseField name="status" type="&#x22;valid&#x22; | &#x22;expired&#x22; | &#x22;requires-recipient&#x22; | &#x22;requires-physical-address&#x22; | &#x22;all-line-items-unavailable&#x22;" />

        <ResponseField name="totalPrice" type="object">
          <Expandable title="parameters">
            <ResponseField name="amount" type="string" />

            <ResponseField name="currency" type="&#x22;usd&#x22; | &#x22;eur&#x22; | &#x22;gbp&#x22; | &#x22;aud&#x22; | &#x22;sgd&#x22; | &#x22;hkd&#x22; | &#x22;krw&#x22; | &#x22;inr&#x22; | &#x22;vnd&#x22; | &#x22;jpy&#x22; | &#x22;eth&#x22; | &#x22;matic&#x22; | &#x22;usdc&#x22; | ..." />
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="orderClientSecret" type="string" />

### Usage

```tsx theme={null}
import { useCrossmintCheckout } from "@crossmint/client-sdk-react-native-ui";
import { View, Text } from "react-native";

function OrderStatus() {
    const { order } = useCrossmintCheckout();

    if (!order) return <Text>No active order</Text>;

    return (
        <View>
            <Text>Order ID: {order.orderId}</Text>
            <Text>Phase: {order.phase}</Text>
        </View>
    );
}
```

***

## useIdentityVerificationCredentials()

Reads the current order's verification credentials, for a merchant taking the step over with `identityVerificationHandling="external"`. Undefined until the order needs verification.

### Usage

```tsx theme={null}
import {
    CrossmintIdentityVerification,
    useIdentityVerificationCredentials,
} from "@crossmint/client-sdk-react-native-ui";

function VerificationStep() {
    const credentials = useIdentityVerificationCredentials();

    if (credentials == null) {
        return null;
    }

    return (
        <CrossmintIdentityVerification
            credentials={credentials}
            onComplete={({ status }) => console.log(status)}
        />
    );
}
```


# Providers
Source: https://docs.crossmint.com/sdk-reference/checkout/react-native/providers

React Native context providers for React Native SDK reference for Crossmint checkout

1. `CrossmintProvider` — SDK initialization (required for all Crossmint features)
2. `CrossmintCheckoutProvider` — Checkout order state management

## CrossmintProvider

Root provider for the Crossmint SDK. Must wrap your entire application. Initializes the SDK with your API key and sets up logging.

### Props

<ResponseField name="apiKey" type="string">
  Your Crossmint client-side API key.
</ResponseField>

<ResponseField name="appId" type="string">
  Application identifier, sent as `x-app-identifier` header.
</ResponseField>

<ResponseField name="consoleLogLevel" type="ConsoleLogLevel">
  Minimum log level for console output (or "silent" to suppress all output). Logs below this level will not be written to the console. Set to "silent" to completely suppress console output. Defaults to "debug" (all logs shown) for backward compatibility.
</ResponseField>

<ResponseField name="overrideBaseUrl" type="string">
  Override the base API URL.
</ResponseField>

### Usage

```tsx theme={null}
import { CrossmintProvider } from "@crossmint/client-sdk-react-native-ui";

function App() {
    return (
        <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
            {/* Your app content */}
        </CrossmintProvider>
    );
}
```

***

## CrossmintCheckoutProvider

### Usage

```tsx theme={null}
import {
    CrossmintProvider,
    CrossmintCheckoutProvider,
} from "@crossmint/client-sdk-react-native-ui";

function App() {
    return (
        <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
            <CrossmintCheckoutProvider>
                {/* Your checkout components */}
            </CrossmintCheckoutProvider>
        </CrossmintProvider>
    );
}
```

> **Note:** CrossmintCheckoutProvider must be nested inside CrossmintProvider.


# Components
Source: https://docs.crossmint.com/sdk-reference/checkout/react/components

React components for React SDK reference for Crossmint checkout

## CrossmintEmbeddedCheckout

### Props

<ResponseField name="appearance" type="EmbeddedCheckoutV3Appearance">
  <Expandable title="properties">
    <ResponseField name="fonts" type="{ cssSrc: string }[]">
      <Expandable title="properties">
        <ResponseField name="cssSrc" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="rules" type="EmbeddedCheckoutV3AppearanceRules">
      <Expandable title="properties">
        <ResponseField name="DestinationInput" type="{ display?: &#x22;hidden&#x22; }">
          <Expandable title="properties">
            <ResponseField name="display" type="&#x22;hidden&#x22;" />
          </Expandable>
        </ResponseField>

        <ResponseField name="GlobalMessage" type="{ display?: &#x22;hidden&#x22; | &#x22;visible&#x22; }">
          <Expandable title="properties">
            <ResponseField name="display" type="&#x22;hidden&#x22; | &#x22;visible&#x22;" />
          </Expandable>
        </ResponseField>

        <ResponseField name="Input" type="object">
          <Expandable title="properties">
            <ResponseField name="borderRadius" type="string" />

            <ResponseField name="colors" type="{ background?: string; border?: string; boxShadow?: string; placeholder?: string; text?: string }" />

            <ResponseField name="focus" type="{ colors?: { background?: string; border?: string; boxShadow?: string } }" />

            <ResponseField name="font" type="{ family?: string; size?: string; weight?: string }" />

            <ResponseField name="hover" type="{ colors?: { background?: string; border?: string; boxShadow?: string; text?: string } }" />
          </Expandable>
        </ResponseField>

        <ResponseField name="Label" type="{ colors?: { text?: string }; font?: { family?: string; size?: string; weight?: string } }">
          <Expandable title="properties">
            <ResponseField name="colors" type="{ text?: string }" />

            <ResponseField name="font" type="{ family?: string; size?: string; weight?: string }" />
          </Expandable>
        </ResponseField>

        <ResponseField name="PrimaryButton" type="object">
          <Expandable title="properties">
            <ResponseField name="borderRadius" type="string" />

            <ResponseField name="colors" type="{ background?: string; text?: string }" />

            <ResponseField name="disabled" type="{ colors?: { background?: string; text?: string } }" />

            <ResponseField name="font" type="{ family?: string; size?: string; weight?: string }" />

            <ResponseField name="hover" type="{ colors?: { background?: string; text?: string } }" />
          </Expandable>
        </ResponseField>

        <ResponseField name="ReceiptEmailInput" type="{ display?: &#x22;hidden&#x22; }">
          <Expandable title="properties">
            <ResponseField name="display" type="&#x22;hidden&#x22;" />
          </Expandable>
        </ResponseField>

        <ResponseField name="Tab" type="object">
          <Expandable title="properties">
            <ResponseField name="borderRadius" type="string" />

            <ResponseField name="colors" type="{ background?: string; border?: string; boxShadow?: string; text?: string }" />

            <ResponseField name="font" type="{ family?: string; size?: string; weight?: string }" />

            <ResponseField name="hover" type="{ colors?: { background?: string; border?: string; boxShadow?: string; text?: string } }" />

            <ResponseField name="selected" type="{ colors?: { background?: string; border?: string; boxShadow?: string; text?: string } }" />
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="variables" type="EmbeddedCheckoutV3AppearanceVariables">
      <Expandable title="properties">
        <ResponseField name="borderRadius" type="string" />

        <ResponseField name="colors" type="object">
          <Expandable title="properties">
            <ResponseField name="accent" type="string" />

            <ResponseField name="backgroundPrimary" type="string" />

            <ResponseField name="borderPrimary" type="string" />

            <ResponseField name="danger" type="string" />

            <ResponseField name="textPrimary" type="string" />

            <ResponseField name="textSecondary" type="string" />

            <ResponseField name="warning" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="fontFamily" type="string" />

        <ResponseField name="fontSizeUnit" type="string">
          Multiplier unit for font sizes, not a base font size. Default `"4px"`: labels render at `fontSizeUnit * 3.75` (15px), inputs at `* 4` (16px), the primary button at `* 4.25` (17px). Passing a body size such as `"14px"` (the `VerificationAppearance` convention) yields \~52px labels.
        </ResponseField>

        <ResponseField name="spacingUnit" type="string">
          Multiplier unit for paddings and gaps, not a base spacing. Default `"3.33px"`; each spacing is `calc(spacingUnit * k)` with k between 3.6 and 4.42.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="clientSecret" type="string" />

<ResponseField name="identityVerificationHandling" type="&#x22;external&#x22;">
  `"external"`: you mount `CrossmintIdentityVerification` from `getIdentityVerificationCredentials(order)`, or the buyer cannot finish.
</ResponseField>

<ResponseField name="jwt" type="string" />

<ResponseField name="orderId" type="string" />

<ResponseField name="payment" type="EmbeddedCheckoutV3Payment">
  <Expandable title="properties">
    <ResponseField name="crypto" type="EmbeddedCheckoutV3CryptoPayment">
      <Expandable title="properties">
        <ResponseField name="defaultChain" type="BlockchainIncludingTestnet" />

        <ResponseField name="defaultCurrency" type="CryptoCurrency" />

        <ResponseField name="enabled" type="boolean" />

        <ResponseField name="payer" type="EmbeddedCheckoutPayer">
          <Expandable title="properties">
            <ResponseField name="address" type="string" />

            <ResponseField name="initialChain" type="PayerSupportedBlockchains" />

            <ResponseField name="supportedChains" type="PayerSupportedBlockchains[]" />

            <ResponseField name="handleChainSwitch" type="unknown" />

            <ResponseField name="handleSignAndSendTransaction" type="unknown" />

            <ResponseField name="handleSignMessage" type="unknown" />
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="defaultMethod" type="&#x22;fiat&#x22; | &#x22;crypto&#x22;" />

    <ResponseField name="fiat" type="EmbeddedCheckoutV3FiatPayment">
      <Expandable title="properties">
        <ResponseField name="allowedMethods" type="{ applePay?: boolean; card?: boolean; googlePay?: boolean }">
          <Expandable title="properties">
            <ResponseField name="applePay" type="boolean" />

            <ResponseField name="card" type="boolean" />

            <ResponseField name="googlePay" type="boolean" />
          </Expandable>
        </ResponseField>

        <ResponseField name="defaultCurrency" type="FiatCurrency" />

        <ResponseField name="enabled" type="boolean" />
      </Expandable>
    </ResponseField>

    <ResponseField name="receiptEmail" type="string" />
  </Expandable>
</ResponseField>

<ResponseField name="lineItems" type="EmbeddedCheckoutV3LineItem | EmbeddedCheckoutV3LineItem[]">
  <Expandable title="properties">
    <ResponseField name="callData" type="Record<string, any>" />

    <ResponseField name="collectionLocator" type="string" />

    <ResponseField name="tokenLocator" type="string" />

    <ResponseField name="executionParameters" type="Record<string, any>" />

    <ResponseField name="productLocator" type="string" />
  </Expandable>
</ResponseField>

<ResponseField name="locale" type="Locale" />

<ResponseField name="metadata" type="JSONObject" />

<ResponseField name="recipient" type="EmbeddedCheckoutV3Recipient">
  <Expandable title="properties">
    <ResponseField name="email" type="string" />

    <ResponseField name="physicalAddress" type="EmbeddedCheckoutV3PhysicalAddress">
      <Expandable title="properties">
        <ResponseField name="city" type="string" />

        <ResponseField name="country" type="&#x22;US&#x22;" />

        <ResponseField name="line1" type="string" />

        <ResponseField name="line2" type="string" />

        <ResponseField name="name" type="string" />

        <ResponseField name="postalCode" type="string" />

        <ResponseField name="state" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="walletAddress" type="string" />
  </Expandable>
</ResponseField>

### Usage

```tsx theme={null}
import { CrossmintEmbeddedCheckout } from "@crossmint/client-sdk-react-ui";

function Checkout() {
    return (
        <CrossmintEmbeddedCheckout
            lineItems={{
                collectionLocator: "crossmint:YOUR_COLLECTION_ID",
                callData: {
                    totalPrice: "0.001",
                },
            }}
            payment={{
                crypto: {
                    enabled: true,
                    defaultChain: "base-sepolia",
                    defaultCurrency: "usdc",
                },
                fiat: {
                    enabled: true,
                    defaultCurrency: "usd",
                    allowedMethods: {
                        card: true,
                        applePay: true,
                        googlePay: true,
                    },
                },
                receiptEmail: "buyer@example.com",
            }}
            recipient={{ email: "buyer@example.com" }}
            locale="en-US"
        />
    );
}
```

***

## CrossmintHostedCheckout

### Props

<ResponseField name="appearance" type="CrossmintHostedCheckoutV3Appearance">
  <Expandable title="properties">
    <ResponseField name="display" type="&#x22;popup&#x22; | &#x22;new-tab&#x22; | &#x22;same-tab&#x22;" />

    <ResponseField name="overlay" type="CrossmintHostedCheckoutV3OverlayOptions">
      <Expandable title="properties">
        <ResponseField name="enabled" type="boolean" />
      </Expandable>
    </ResponseField>

    <ResponseField name="rules" type="HostedCheckoutV3AppearanceRules">
      <Expandable title="properties">
        <ResponseField name="DestinationInput" type="{ display?: &#x22;hidden&#x22; }">
          <Expandable title="properties">
            <ResponseField name="display" type="&#x22;hidden&#x22;" />
          </Expandable>
        </ResponseField>

        <ResponseField name="ReceiptEmailInput" type="{ display?: &#x22;hidden&#x22; }">
          <Expandable title="properties">
            <ResponseField name="display" type="&#x22;hidden&#x22;" />
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="theme" type="{ button?: CrossmintHostedCheckoutV3ButtonTheme; checkout?: CrossmintHostedCheckoutV3Theme }">
      <Expandable title="properties">
        <ResponseField name="button" type="CrossmintHostedCheckoutV3ButtonTheme" />

        <ResponseField name="checkout" type="CrossmintHostedCheckoutV3Theme" />
      </Expandable>
    </ResponseField>

    <ResponseField name="variables" type="CrossmintHostedCheckoutV3AppearanceVariables">
      <Expandable title="properties">
        <ResponseField name="colors" type="{ accent?: string }">
          <Expandable title="properties">
            <ResponseField name="accent" type="string" />
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="lineItems" type="EmbeddedCheckoutV3LineItem | EmbeddedCheckoutV3LineItem[]">
  <Expandable title="properties">
    <ResponseField name="callData" type="Record<string, any>" />

    <ResponseField name="collectionLocator" type="string" />

    <ResponseField name="tokenLocator" type="string" />

    <ResponseField name="executionParameters" type="Record<string, any>" />

    <ResponseField name="productLocator" type="string" />
  </Expandable>
</ResponseField>

<ResponseField name="locale" type="Locale" />

<ResponseField name="metadata" type="JSONObject" />

<ResponseField name="payment" type="HostedCheckoutV3Payment">
  <Expandable title="properties">
    <ResponseField name="crypto" type="HostedCheckoutV3CryptoPayment">
      <Expandable title="properties">
        <ResponseField name="defaultChain" type="BlockchainIncludingTestnet" />

        <ResponseField name="defaultCurrency" type="CryptoCurrency" />

        <ResponseField name="enabled" type="boolean" />
      </Expandable>
    </ResponseField>

    <ResponseField name="defaultMethod" type="&#x22;fiat&#x22; | &#x22;crypto&#x22;" />

    <ResponseField name="fiat" type="HostedCheckoutV3FiatPayment">
      <Expandable title="properties">
        <ResponseField name="defaultCurrency" type="FiatCurrency" />

        <ResponseField name="enabled" type="boolean" />
      </Expandable>
    </ResponseField>

    <ResponseField name="receiptEmail" type="string" />
  </Expandable>
</ResponseField>

<ResponseField name="recipient" type="EmbeddedCheckoutV3Recipient">
  <Expandable title="properties">
    <ResponseField name="email" type="string" />

    <ResponseField name="physicalAddress" type="EmbeddedCheckoutV3PhysicalAddress">
      <Expandable title="properties">
        <ResponseField name="city" type="string" />

        <ResponseField name="country" type="&#x22;US&#x22;" />

        <ResponseField name="line1" type="string" />

        <ResponseField name="line2" type="string" />

        <ResponseField name="name" type="string" />

        <ResponseField name="postalCode" type="string" />

        <ResponseField name="state" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="walletAddress" type="string" />
  </Expandable>
</ResponseField>

<ResponseField name="clientSecret" type="string" />

<ResponseField name="orderId" type="string" />

### Usage

```tsx theme={null}
import { CrossmintHostedCheckout } from "@crossmint/client-sdk-react-ui";

function BuyButton() {
    return (
        <CrossmintHostedCheckout
            lineItems={{
                collectionLocator: "crossmint:YOUR_COLLECTION_ID",
                callData: {
                    totalPrice: "0.001",
                },
            }}
            payment={{
                crypto: {
                    enabled: true,
                    defaultChain: "base-sepolia",
                    defaultCurrency: "usdc",
                },
                fiat: {
                    enabled: true,
                    defaultCurrency: "usd",
                },
                receiptEmail: "buyer@example.com",
            }}
            recipient={{ email: "buyer@example.com" }}
            appearance={{
                display: "popup",
                overlay: { enabled: true },
                theme: {
                    button: "dark",
                    checkout: "light",
                },
            }}
            locale="en-US"
        />
    );
}
```

***

## CrossmintPaymentMethodManagement

Lets the user save a new card or bank account, or pick one of their saved payment methods. Rendered in a Crossmint-hosted iframe, so payment details never touch your app. Takes the user's Crossmint `jwt`. `onPaymentMethodSelected` receives the chosen method; its `paymentMethodId` is what your backend uses to pay (for example to create order intents).

### Props

<ResponseField name="allowedModes" type="&#x22;new&#x22; | &#x22;existing&#x22;[]">
  Which sections the management UI renders. `["new"]` (default) shows only the "add new" section: no saved-methods fetch, no auto-open/auto-select of an existing method. Include `"existing"` to also show the saved-methods section.
</ResponseField>

<ResponseField name="allowedPaymentMethodTypes" type="PaymentMethodManagementAllowedType[]">
  Filter array of which method types the "add new" section offers (default `["card"]`). LM0 renders the first supported entry; passing more than one type does not yet render a type picker.
</ResponseField>

<ResponseField name="appearance" type="PaymentMethodManagementAppearance">
  <Expandable title="properties">
    <ResponseField name="fonts" type="EmbeddedCheckoutV3Appearance[&#x22;fonts&#x22;]" />

    <ResponseField name="rules" type="EmbeddedCheckoutV3Appearance[&#x22;rules&#x22;]" />

    <ResponseField name="variables" type="EmbeddedCheckoutV3Appearance[&#x22;variables&#x22;]" />
  </Expandable>
</ResponseField>

<ResponseField name="jwt" type="string" />

<ResponseField name="onPaymentMethodSelected" type="(paymentMethod: CrossmintPaymentMethod) => void | Promise<void>" />

### Usage

```tsx theme={null}
import { CrossmintPaymentMethodManagement } from "@crossmint/client-sdk-react-ui";

function PaymentMethods({ jwt }: { jwt: string }) {
    return (
        <CrossmintPaymentMethodManagement
            jwt={jwt}
            allowedModes={["new", "existing"]}
            allowedPaymentMethodTypes={["card"]}
            onPaymentMethodSelected={(paymentMethod) => {
                if (paymentMethod.type === "card") {
                    console.log("Card selected:", paymentMethod.card.last4);
                }
            }}
        />
    );
}
```

> **Note:** CrossmintPaymentMethodManagement renders an iframe-based UI for managing saved payment methods. Requires a valid JWT for authentication. The onPaymentMethodSelected callback receives a discriminated union — narrow on `type` before accessing variant-specific fields.

***

## CrossmintProtectedInput

Collects the password of the buyer's account on a merchant site inside a Crossmint-hosted iframe and returns an opaque `protectedInputId` to hand to Universal Checkout. The password never reaches this component, the developer's JavaScript, or the agent. Takes the buyer's JWT as a prop, like `CrossmintPaymentMethodManagement`.

### Props

<ResponseField name="appearance" type="ProtectedInputAppearance" />

<ResponseField name="expiresAt" type="string">
  ISO 8601 datetime. Server default is 24 hours from creation; the maximum is 7 days.
</ResponseField>

<ResponseField name="jwt" type="string">
  The buyer's Crossmint auth token, the same one `CrossmintPaymentMethodManagement` takes.
</ResponseField>

<ResponseField name="label" type="string">
  Text shown above the field, for example the merchant name. At most 120 characters.
</ResponseField>

<ResponseField name="merchantUrl" type="string">
  The merchant sign-in page the password is for. Its host becomes the input's merchant domain; Universal Checkout may only use the input on that host or a subdomain of it.
</ResponseField>

<ResponseField name="onCreated" type="(created: { expiresAt: string; merchant: object; protectedInputId: string; purpose: &#x22;password&#x22; }) => void">
  Called once with the opaque `protectedInputId` to hand to Universal Checkout.
</ResponseField>

<ResponseField name="onError" type="(error: { code: string; message: string }) => void" />

### Usage

```tsx theme={null}
import { CrossmintProtectedInput } from "@crossmint/client-sdk-react-ui";

function MerchantPassword({ jwt, onProtectedInputId }: { jwt: string; onProtectedInputId: (id: string) => void }) {
    return (
        <CrossmintProtectedInput
            jwt={jwt}
            merchantUrl="https://shop.example.com/login"
            label="Example Shop"
            onCreated={({ protectedInputId }) => onProtectedInputId(protectedInputId)}
            onError={({ code, message }) => console.error(code, message)}
        />
    );
}
```

> **Note:** CrossmintProtectedInput collects the password of the buyer's account on a merchant site inside a Crossmint-hosted iframe and returns only an opaque protectedInputId. Pass that id to Universal Checkout as the `protected` input response; the password never reaches your JavaScript. Pass the buyer's JWT as `jwt`, like CrossmintPaymentMethodManagement. Lifecycle: the hosted page posts exactly one terminal event per mount, so after onCreated or onError remount the component (change its `key`) to collect again; the page posts `invalid_params` when it rejects the props.

***

## CrossmintAgentCardAuthorization

Lets a buyer authorize a bounded card spend for Universal Checkout and hands back an `orderIntentId`. Composes card selection, order-intent registration, order-intent creation and rail verification; the rail is chosen by a fixed policy, never by the model or the buyer. The card number, CVC and vault token id never reach this component's callbacks.

### Props

<ResponseField name="allowedModes" type="&#x22;new&#x22; | &#x22;existing&#x22;[]">
  Sections of the payment-method UI to render. Defaults to `["existing", "new"]`.
</ResponseField>

<ResponseField name="amount" type="{ currency: string; value: string }">
  `value` is a decimal string with up to 4 places, greater than 0; `currency` is a 3-letter code.

  <Expandable title="properties">
    <ResponseField name="currency" type="string" />

    <ResponseField name="value" type="string" />
  </Expandable>
</ResponseField>

<ResponseField name="appearance" type="AgentCardAuthorizationAppearance">
  <Expandable title="properties">
    <ResponseField name="paymentMethodManagement" type="PaymentMethodManagementAppearance">
      Styles the card selection and the CVC recollection form, which share this appearance model.

      <Expandable title="properties">
        <ResponseField name="fonts" type="EmbeddedCheckoutV3Appearance[&#x22;fonts&#x22;]" />

        <ResponseField name="rules" type="EmbeddedCheckoutV3Appearance[&#x22;rules&#x22;]" />

        <ResponseField name="variables" type="EmbeddedCheckoutV3Appearance[&#x22;variables&#x22;]" />
      </Expandable>
    </ResponseField>

    <ResponseField name="verification" type="VerificationAppearance">
      Styles the card-network verification modal.

      <Expandable title="properties">
        <ResponseField name="rules" type="VerificationAppearanceRules">
          <Expandable title="properties">
            <ResponseField name="CloseButton" type="{ colors?: { background?: string }; hover?: { colors?: object } }" />

            <ResponseField name="Input" type="{ borderRadius?: string; colors?: { background?: string; border?: string } }" />

            <ResponseField name="Modal" type="{ borderRadius?: string; colors?: { border?: string } }" />

            <ResponseField name="Overlay" type="{ colors?: { background?: string } }" />

            <ResponseField name="PrimaryButton" type="object" />

            <ResponseField name="Radio" type="{ colors?: { border?: string }; selected?: { colors?: object } }" />

            <ResponseField name="SecondaryButton" type="{ colors?: { background?: string; text?: string }; hover?: { colors?: object } }" />
          </Expandable>
        </ResponseField>

        <ResponseField name="variables" type="VerificationAppearanceVariables">
          <Expandable title="properties">
            <ResponseField name="borderRadius" type="string" />

            <ResponseField name="colors" type="object" />

            <ResponseField name="fontFamily" type="string" />

            <ResponseField name="fontSizeUnit" type="string">
              Not applied by `OrderIntentVerification`: only `colors` (and the button / input colors under `rules`) reach the verification modal. Not the multiplier unit of `EmbeddedCheckoutV3AppearanceVariables.fontSizeUnit`, so do not share one object between the two.
            </ResponseField>

            <ResponseField name="spacingUnit" type="string">
              Not applied by `OrderIntentVerification`; see `fontSizeUnit`.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="description" type="string" />

<ResponseField name="displayName" type="string">
  Shown to the buyer by the rail verification UI.
</ResponseField>

<ResponseField name="expiresAt" type="string">
  ISO 8601 datetime in the future. Defaults to 24 hours from mount.
</ResponseField>

<ResponseField name="jwt" type="string">
  The buyer's Crossmint auth token, the same one `CrossmintPaymentMethodManagement` takes.
</ResponseField>

<ResponseField name="merchant" type="OrderIntentMerchant">
  <Expandable title="properties">
    <ResponseField name="acquirerBin" type="string" />

    <ResponseField name="categoryCode" type="string" />

    <ResponseField name="countryCode" type="string">
      ISO 3166-1 alpha-2, upper case.
    </ResponseField>

    <ResponseField name="name" type="string" />

    <ResponseField name="url" type="string">
      http or https URL of the merchant.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="onAuthorized" type="(result: AgentCardAuthorizationResult) => void" />

<ResponseField name="onError" type="(error: AgentCardAuthorizationError) => void" />

### Usage

```tsx theme={null}
import { CrossmintAgentCardAuthorization } from "@crossmint/client-sdk-react-ui";

function AuthorizeCard({ jwt, onOrderIntentId }: { jwt: string; onOrderIntentId: (id: string) => void }) {
    return (
        <CrossmintAgentCardAuthorization
            jwt={jwt}
            amount={{ value: "120.00", currency: "USD" }}
            merchant={{ name: "Example Shop", url: "https://shop.example.com", countryCode: "US" }}
            description="Running shoes, order placed by your shopping agent"
            displayName="Example Shop"
            onAuthorized={({ orderIntentId }) => onOrderIntentId(orderIntentId)}
            onError={({ code, message }) => console.error(code, message)}
        />
    );
}
```

> **Note:** CrossmintAgentCardAuthorization composes card selection, order-intent registration, order-intent creation and rail verification, and calls onAuthorized once with an orderIntentId. Pass that id to Universal Checkout as the run's `payment: { orderIntentId }` or as the `payment` input response. The rail is chosen by the same policy the server applies (vic, then agentpay, then encrypted-card, preferring a rail that is already active); card numbers, CVCs and vault token ids never reach your JavaScript. Lifecycle: after onAuthorized the component renders nothing; after onError it returns to card selection so the buyer can try again; state lives for one mount, so a remount (a `key` or route change) creates a new order intent for the same spend and your app must store the orderIntentId from onAuthorized. Pass the buyer's JWT as `jwt`, like CrossmintPaymentMethodManagement. `appearance.paymentMethodManagement` styles the card selection and the CVC recollection form, `appearance.verification` the card-network verification modal.


# Get Started
Source: https://docs.crossmint.com/sdk-reference/checkout/react/get-started

Installation and setup for the React SDK reference for Crossmint checkout

### Latest React SDK version - <a href="https://www.npmjs.com/package/@crossmint/client-sdk-react-ui"><img alt="npm" /></a>

The Crossmint React SDK (`@crossmint/client-sdk-react-ui`) provides React components and hooks for integrating Crossmint checkout into your application. It supports both embedded checkout (inline iframe) and hosted checkout (popup/new-tab button).

## Installation

<Snippet />

## Provider Setup

Wrap your application with the required providers:

```tsx theme={null}
import {
    CrossmintProvider,
    CrossmintCheckoutProvider,
} from "@crossmint/client-sdk-react-ui";

function App() {
    return (
        <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
            <CrossmintCheckoutProvider>
                {/* Your checkout components */}
            </CrossmintCheckoutProvider>
        </CrossmintProvider>
    );
}
```

## Quick Example

Once providers are set up, use the checkout components to accept payments:

```tsx theme={null}
import { CrossmintEmbeddedCheckout } from "@crossmint/client-sdk-react-ui";

function CheckoutPage() {
    return (
        <CrossmintEmbeddedCheckout
            lineItems={{
                collectionLocator: "crossmint:YOUR_COLLECTION_ID",
                callData: {
                    totalPrice: "0.001",
                },
            }}
            payment={{
                crypto: { enabled: true },
                fiat: { enabled: true, defaultCurrency: "usd" },
                receiptEmail: "buyer@example.com",
            }}
            recipient={{ email: "buyer@example.com" }}
        />
    );
}
```

## Next Steps

* [Providers](/sdk-reference/checkout/react/providers) — Configure providers and their options
* [Hooks](/sdk-reference/checkout/react/hooks) — Access SDK state via React hooks
* [Components](/sdk-reference/checkout/react/components) — Drop-in UI components


# Hooks
Source: https://docs.crossmint.com/sdk-reference/checkout/react/hooks

React hooks for React SDK reference for Crossmint checkout

## useCrossmintCheckout()

### Returns

<ResponseField name="order" type="object">
  <Expandable title="parameters">
    <ResponseField name="lineItems" type="object[]">
      <Expandable title="parameters">
        <ResponseField name="callData" type="Record<string, any>" />

        <ResponseField name="chain" type="&#x22;solana&#x22; | &#x22;sui&#x22; | &#x22;aptos&#x22; | &#x22;ethereum&#x22; | &#x22;polygon&#x22; | &#x22;bsc&#x22; | &#x22;optimism&#x22; | &#x22;arbitrum&#x22; | &#x22;base&#x22; | &#x22;zora&#x22; | ..." />

        <ResponseField name="delivery" type="{ recipient?: object | object; status: &#x22;completed&#x22;; tokens: ... | ...[]; txId: string } | ...">
          <Expandable title="parameters">
            <ResponseField name="recipient" type="{ locator: string; physicalAddress?: object; walletAddress: string } | ..." />

            <ResponseField name="status" type="&#x22;completed&#x22;" />

            <ResponseField name="tokens" type="object | object[]" />

            <ResponseField name="txId" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="metadata" type="object">
          <Expandable title="parameters">
            <ResponseField name="collection" type="{ description?: string; imageUrl?: string; name?: string }" />

            <ResponseField name="description" type="string" />

            <ResponseField name="imageUrl" type="string" />

            <ResponseField name="name" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="quantity" type="number" />

        <ResponseField name="quote" type="object">
          <Expandable title="parameters">
            <ResponseField name="charges" type="{ gas?: object; unit: object }" />

            <ResponseField name="status" type="&#x22;valid&#x22; | &#x22;expired&#x22; | &#x22;requires-recipient&#x22; | &#x22;item-unavailable&#x22;" />

            <ResponseField name="totalPrice" type="object" />

            <ResponseField name="unavailabilityReason" type="{ code: &#x22;to&#x22; | &#x22;do&#x22;; message: string }" />
          </Expandable>
        </ResponseField>

        <ResponseField name="slippageBps" type="number" />
      </Expandable>
    </ResponseField>

    <ResponseField name="locale" type="&#x22;en-US&#x22; | &#x22;es-ES&#x22; | &#x22;fr-FR&#x22; | &#x22;it-IT&#x22; | &#x22;ja-JP&#x22; | &#x22;ko-KR&#x22; | &#x22;pt-PT&#x22; | &#x22;zh-CN&#x22; | &#x22;zh-TW&#x22; | &#x22;de-DE&#x22; | &#x22;ru-RU&#x22; | ..." />

    <ResponseField name="orderId" type="string" />

    <ResponseField name="payment" type="object">
      <Expandable title="parameters">
        <ResponseField name="currency" type="&#x22;usd&#x22; | &#x22;eur&#x22; | &#x22;gbp&#x22; | &#x22;aud&#x22; | &#x22;sgd&#x22; | &#x22;hkd&#x22; | &#x22;krw&#x22; | &#x22;inr&#x22; | &#x22;vnd&#x22; | &#x22;jpy&#x22; | &#x22;eth&#x22; | &#x22;matic&#x22; | &#x22;usdc&#x22; | ..." />

        <ResponseField name="failureReason" type="{ code: string; message?: string } | { code: &#x22;unknown&#x22; | &#x22;tx-id-not-found&#x22; | &#x22;insufficient-funds&#x22;; message?: string }">
          <Expandable title="parameters">
            <ResponseField name="code" type="string" />

            <ResponseField name="message" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="method" type="&#x22;solana&#x22; | &#x22;ethereum&#x22; | &#x22;polygon&#x22; | &#x22;bsc&#x22; | &#x22;optimism&#x22; | &#x22;arbitrum&#x22; | &#x22;base&#x22; | &#x22;zora&#x22; | &#x22;arbitrumnova&#x22; | ..." />

        <ResponseField name="preparation" type="object | object">
          <Expandable title="parameters">
            <ResponseField name="chain" type="&#x22;solana&#x22; | &#x22;sui&#x22; | &#x22;aptos&#x22; | &#x22;ethereum&#x22; | &#x22;polygon&#x22; | &#x22;bsc&#x22; | &#x22;optimism&#x22; | &#x22;arbitrum&#x22; | &#x22;base&#x22; | &#x22;zora&#x22; | ..." />

            <ResponseField name="payerAddress" type="string" />

            <ResponseField name="serializedTransaction" type="string" />

            <ResponseField name="stripeClientSecret" type="string" />

            <ResponseField name="stripeEphemeralKeySecret" type="string" />

            <ResponseField name="stripePublishableKey" type="string" />

            <ResponseField name="stripeSubscriptionId" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="receiptEmail" type="string" />

        <ResponseField name="received" type="object | object">
          <Expandable title="parameters">
            <ResponseField name="amount" type="string" />

            <ResponseField name="currency" type="&#x22;usd&#x22; | &#x22;eur&#x22; | &#x22;gbp&#x22; | &#x22;aud&#x22; | &#x22;sgd&#x22; | &#x22;hkd&#x22; | &#x22;krw&#x22; | &#x22;inr&#x22; | &#x22;vnd&#x22; | &#x22;jpy&#x22; | &#x22;eth&#x22; | &#x22;matic&#x22; | &#x22;usdc&#x22; | ..." />

            <ResponseField name="chain" type="&#x22;solana&#x22; | &#x22;sui&#x22; | &#x22;aptos&#x22; | &#x22;ethereum&#x22; | &#x22;polygon&#x22; | &#x22;bsc&#x22; | &#x22;optimism&#x22; | &#x22;arbitrum&#x22; | &#x22;base&#x22; | &#x22;zora&#x22; | ..." />

            <ResponseField name="txId" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="refunded" type="object | object">
          <Expandable title="parameters">
            <ResponseField name="amount" type="string" />

            <ResponseField name="currency" type="&#x22;usd&#x22; | &#x22;eur&#x22; | &#x22;gbp&#x22; | &#x22;aud&#x22; | &#x22;sgd&#x22; | &#x22;hkd&#x22; | &#x22;krw&#x22; | &#x22;inr&#x22; | &#x22;vnd&#x22; | &#x22;jpy&#x22; | &#x22;eth&#x22; | &#x22;matic&#x22; | &#x22;usdc&#x22; | ..." />

            <ResponseField name="chain" type="&#x22;solana&#x22; | &#x22;sui&#x22; | &#x22;aptos&#x22; | &#x22;ethereum&#x22; | &#x22;polygon&#x22; | &#x22;bsc&#x22; | &#x22;optimism&#x22; | &#x22;arbitrum&#x22; | &#x22;base&#x22; | &#x22;zora&#x22; | ..." />

            <ResponseField name="txId" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="status" type="&#x22;completed&#x22; | &#x22;awaiting-payment&#x22; | &#x22;in-progress&#x22; | &#x22;requires-quote&#x22; | &#x22;requires-crypto-payer-address&#x22; | ..." />
      </Expandable>
    </ResponseField>

    <ResponseField name="phase" type="&#x22;completed&#x22; | &#x22;quote&#x22; | &#x22;delivery&#x22; | &#x22;payment&#x22;" />

    <ResponseField name="quote" type="object">
      <Expandable title="parameters">
        <ResponseField name="expiresAt" type="string" />

        <ResponseField name="quotedAt" type="string" />

        <ResponseField name="status" type="&#x22;valid&#x22; | &#x22;expired&#x22; | &#x22;requires-recipient&#x22; | &#x22;requires-physical-address&#x22; | &#x22;all-line-items-unavailable&#x22;" />

        <ResponseField name="totalPrice" type="object">
          <Expandable title="parameters">
            <ResponseField name="amount" type="string" />

            <ResponseField name="currency" type="&#x22;usd&#x22; | &#x22;eur&#x22; | &#x22;gbp&#x22; | &#x22;aud&#x22; | &#x22;sgd&#x22; | &#x22;hkd&#x22; | &#x22;krw&#x22; | &#x22;inr&#x22; | &#x22;vnd&#x22; | &#x22;jpy&#x22; | &#x22;eth&#x22; | &#x22;matic&#x22; | &#x22;usdc&#x22; | ..." />
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="orderClientSecret" type="string" />

### Usage

```tsx theme={null}
import { useCrossmintCheckout } from "@crossmint/client-sdk-react-ui";

function OrderStatus() {
    const { order } = useCrossmintCheckout();

    if (!order) return <p>No active order</p>;

    return (
        <div>
            <p>Order ID: {order.orderId}</p>
            <p>Phase: {order.phase}</p>
        </div>
    );
}
```

***

## useIdentityVerificationCredentials()

Reads the current order's verification credentials, for a merchant taking the step over with `identityVerificationHandling="external"`. Undefined until the order needs verification.

### Usage

```tsx theme={null}
import {
    CrossmintIdentityVerification,
    useIdentityVerificationCredentials,
} from "@crossmint/client-sdk-react-ui";

function VerificationStep() {
    const credentials = useIdentityVerificationCredentials();

    if (credentials == null) {
        return null;
    }

    return (
        <CrossmintIdentityVerification
            credentials={credentials}
            onComplete={({ status }) => console.log(status)}
        />
    );
}
```


# Providers
Source: https://docs.crossmint.com/sdk-reference/checkout/react/providers

React context providers for React SDK reference for Crossmint checkout

1. `CrossmintProvider` — SDK initialization (required for all Crossmint features)
2. `CrossmintCheckoutProvider` — Checkout order state management

## CrossmintProvider

### Props

<ResponseField name="apiKey" type="string">
  Your Crossmint client-side API key.
</ResponseField>

<ResponseField name="appId" type="string">
  Application identifier, sent as `x-app-identifier` header.
</ResponseField>

<ResponseField name="consoleLogLevel" type="ConsoleLogLevel">
  Minimum log level for console output (or "silent" to suppress all output). Logs below this level will not be written to the console. Set to "silent" to completely suppress console output. Defaults to "debug" (all logs shown) for backward compatibility.
</ResponseField>

<ResponseField name="extensionId" type="string">
  Extension identifier, sent as `x-extension-id` header.
</ResponseField>

<ResponseField name="jwt" type="string">
  JWT token for authentication.
</ResponseField>

<ResponseField name="overrideBaseUrl" type="string">
  Override the base API URL.
</ResponseField>

### Usage

```tsx theme={null}
import { CrossmintProvider } from "@crossmint/client-sdk-react-ui";

function App() {
    return (
        <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
            {/* Your app content */}
        </CrossmintProvider>
    );
}
```

***

## CrossmintCheckoutProvider

### Usage

```tsx theme={null}
import {
    CrossmintProvider,
    CrossmintCheckoutProvider,
} from "@crossmint/client-sdk-react-ui";

function App() {
    return (
        <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
            <CrossmintCheckoutProvider>
                {/* Your checkout components */}
            </CrossmintCheckoutProvider>
        </CrossmintProvider>
    );
}
```

> **Note:** CrossmintCheckoutProvider must be nested inside CrossmintProvider.


# CrossmintCheckoutController
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/classes/crossmintcheckoutcontroller

Swift Class

**Class**

The observable order state of one embedded checkout session.

```swift theme={null}
@MainActor final class CrossmintCheckoutController
```

Give an instance to `CrossmintEmbeddedCheckout`. Observe the instance to react to order changes. `identityVerificationCredentials` has a value when the order needs identity verification. Call `clear()` before you use one controller for a new checkout session.

## Initializers

### init()

Creates a controller with no order.

```swift theme={null}
@MainActor init()
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `identityVerificationCredentials` | `IdentityVerificationCredentials?` | The credentials for the pending identity verification. |
| `order` | `CheckoutOrder?` | The order in its latest state. |
| `orderClientSecret` | `String?` | The secret that authorizes reads of the order. |

## Instance Methods

### clear()

Removes the stored order state.

```swift theme={null}
@MainActor func clear()
```


# CheckoutEnvironment
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/enums/checkoutenvironment

Swift Enumeration

**Enumeration**

The Crossmint environment the SDK connects to.

```swift theme={null}
enum CheckoutEnvironment
```

## Enumeration Cases

| Case | Description |
| - | - |
| `production` | The live environment. |
| `staging` | The test environment. |


# CheckoutError
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/enums/checkouterror

Swift Enumeration

**Enumeration**

```swift theme={null}
enum CheckoutError
```

## Enumeration Cases

| Case | Description |
| - | - |
| `invalidConfiguration(_:)` | - |
| `legacyAPIKey` | - |
| `malformedAPIKey` | - |
| `missingAPIKey` | - |
| `notImplemented(_:)` | - |
| `serverAPIKey` | - |

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `errorDescription` | `String?` | Inherited from `LocalizedError.errorDescription`. |


# CheckoutLength
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/enums/checkoutlength

Swift Enumeration

**Enumeration**

A CSS length, such as a font size, a corner radius, or a spacing unit.

```swift theme={null}
enum CheckoutLength
```

Use `CheckoutLength.px(_:)`, `CheckoutLength.rem(_:)`, or `CheckoutLength.em(_:)` for the common units. Use `CheckoutLength.custom(_:)` for a different CSS value. A number literal is a length in CSS pixels, so `12` is the same as `.px(12)`. In the checkout, one CSS pixel is one point.

## Enumeration Cases

| Case | Description |
| - | - |
| `custom(_:)` | A CSS length value, for example `"clamp(14px, 4vw, 18px)"`. |
| `em(_:)` | A length relative to the font size of the parent element. |
| `px(_:)` | A length in CSS pixels. |
| `rem(_:)` | A length relative to the font size of the root element. |

## Initializers

### init(floatLiteral:)

Creates a length in CSS pixels from a floating-point literal.

```swift theme={null}
init(floatLiteral value: Double)
```

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: Decoder) throws
```

### init(integerLiteral:)

Creates a length in CSS pixels from an integer literal.

```swift theme={null}
init(integerLiteral value: Int)
```

## Instance Methods

### encode(to:)

Inherited from `Encodable.encode(to:)`.

```swift theme={null}
func encode(to encoder: Encoder) throws
```


# CheckoutLocale
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/enums/checkoutlocale

Swift Enumeration

**Enumeration**

A language for the hosted pages of Crossmint.

```swift theme={null}
enum CheckoutLocale
```

The hosted pages support only these languages.

## Enumeration Cases

| Case | Description |
| - | - |
| `deDE` | - |
| `enUS` | - |
| `esES` | - |
| `frFR` | - |
| `itIT` | - |
| `jaJP` | - |
| `koKR` | - |
| `ptPT` | - |
| `ruRU` | - |
| `thTH` | - |
| `trTR` | - |
| `ukUA` | - |
| `viVN` | - |
| `zhCN` | - |
| `zhTW` | - |

## Initializers

### init(rawValue:)

Inherited from `RawRepresentable.init(rawValue:)`.

```swift theme={null}
init?(rawValue: String)
```


# CheckoutLogLevel
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/enums/checkoutloglevel

Swift Enumeration

**Enumeration**

The minimum level of the SDK messages that reach the system console.

```swift theme={null}
enum CheckoutLogLevel
```

The level filters only the local console output. Diagnostic messages go to Crossmint at every level.

## Enumeration Cases

| Case | Description |
| - | - |
| `debug` | Every message, including the verbose ones. |
| `error` | Errors only. The default. |
| `info` | Informational messages and above. |
| `silent` | No console output. |
| `warning` | Warnings and errors. |

## Initializers

### init(rawValue:)

Inherited from `RawRepresentable.init(rawValue:)`.

```swift theme={null}
init?(rawValue: Int)
```


# IdentityVerificationHandling
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/enums/identityverificationhandling

Swift Enumeration

**Enumeration**

The presentation mode for the identity verification (KYC) step of embedded checkout.

```swift theme={null}
enum IdentityVerificationHandling
```

If you do not set a value, the checkout shows the step itself. If you set `IdentityVerificationHandling.external`, the checkout does not show the step. You must then show `CrossmintIdentityVerification` with the credentials of the order, and keep it on screen until it calls `onComplete` or `onCancel`. If you do not, the buyer cannot finish.

## Enumeration Cases

| Case | Description |
| - | - |
| `external` | The mode where your app shows the identity verification step with `CrossmintIdentityVerification`. |

## Initializers

### init(rawValue:)

Inherited from `RawRepresentable.init(rawValue:)`.

```swift theme={null}
init?(rawValue: String)
```


# IdentityVerificationStatus
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/enums/identityverificationstatus

Swift Enumeration

**Enumeration**

The outcome of an identity verification.

```swift theme={null}
enum IdentityVerificationStatus
```

The value `unknown` shows a provider state this SDK version does not know. It is never a success.

## Enumeration Cases

| Case | Description |
| - | - |
| `declined` | The provider rejected the identity of the buyer. |
| `expired` | The inquiry expired before the buyer finished it. |
| `failed` | The verification did not complete. |
| `pendingManualReview` | A person at the provider must review the inquiry. |
| `pendingReview` | The provider needs more time to review the inquiry. |
| `unknown` | A provider state this SDK version does not know. |
| `verified` | The provider verified the identity of the buyer. |

## Initializers

### init(rawValue:)

Inherited from `RawRepresentable.init(rawValue:)`.

```swift theme={null}
init?(rawValue: String)
```


# AnyCodable
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/structs/anycodable

Swift Structure

**Structure**

```swift theme={null}
struct AnyCodable
```

## Initializers

### init(\_:)

```swift theme={null}
init(_ value: any Sendable)
```

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `value` | `any Sendable` | - |

## Instance Methods

### encode(to:)

Inherited from `Encodable.encode(to:)`.

```swift theme={null}
func encode(to encoder: Encoder) throws
```


# CheckoutAllowedMethods
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/structs/checkoutallowedmethods

Swift Structure

**Structure**

The fiat payment methods the checkout offers.

```swift theme={null}
struct CheckoutAllowedMethods
```

Every method is available by default. A method set to `false` does not appear in the checkout.

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

### init(googlePay:applePay:card:)

Creates the allowed methods. Every method defaults to `true`.

```swift theme={null}
init(googlePay: Bool? = true, applePay: Bool? = true, card: Bool? = true)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `applePay` | `Bool?` | A Boolean value that shows whether the checkout offers Apple Pay. |
| `card` | `Bool?` | A Boolean value that shows whether the checkout offers card payment. |
| `googlePay` | `Bool?` | A Boolean value that shows whether the checkout offers Google Pay. |


# CheckoutAppearance
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/structs/checkoutappearance

Swift Structure

**Structure**

The visual customization of `CrossmintEmbeddedCheckout`.

```swift theme={null}
struct CheckoutAppearance
```

Set `fonts` to load custom fonts. Set `variables` for the base look of the checkout. Set `rules` to change single elements. A rule has priority over a variable.

```swift theme={null}
let appearance = CheckoutAppearance(
    fonts: [.googleFonts("Inter", weights: [.regular, .semibold])],
    variables: CheckoutAppearanceVariables(
        fontFamily: "Inter, sans-serif",
        spacingUnit: 4,
        colors: CheckoutVariablesColorStyle(accent: .color(.accentColor))
    ),
    rules: CheckoutAppearanceRules(
        primaryButton: CheckoutPrimaryButtonRule(
            borderRadius: 12,
            font: CheckoutFontStyle(size: .px(17), weight: .semibold)
        )
    )
)
```

## Initializers

### init(fonts:variables:rules:)

Creates an appearance.

```swift theme={null}
init(fonts: [CheckoutFontSource]? = nil, variables: CheckoutAppearanceVariables? = nil, rules: CheckoutAppearanceRules? = nil)
```

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `fonts` | `[CheckoutFontSource]?` | The stylesheets that load custom fonts into the checkout. |
| `rules` | `CheckoutAppearanceRules?` | The per-element style overrides. |
| `variables` | `CheckoutAppearanceVariables?` | The global style variables. |


# CheckoutAppearanceRules
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/structs/checkoutappearancerules

Swift Structure

**Structure**

Per-element style overrides for the checkout.

```swift theme={null}
struct CheckoutAppearanceRules
```

Each property targets one element of the checkout. A rule has priority over the values that the element gets from `CheckoutAppearanceVariables`. Set a property to `nil` to keep the checkout default for that element.

## Initializers

### init(destinationInput:receiptEmailInput:globalMessage:label:input:tab:primaryButton:)

Creates the rule set.

```swift theme={null}
init(destinationInput: CheckoutDestinationInputRule? = nil, receiptEmailInput: CheckoutReceiptEmailInputRule? = nil, globalMessage: CheckoutGlobalMessageRule? = nil, label: CheckoutLabelRule? = nil, input: CheckoutInputRule? = nil, tab: CheckoutTabRule? = nil, primaryButton: CheckoutPrimaryButtonRule? = nil)
```

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `destinationInput` | `CheckoutDestinationInputRule?` | The rule for the destination input. |
| `globalMessage` | `CheckoutGlobalMessageRule?` | The rule for the global message above the payment form. |
| `input` | `CheckoutInputRule?` | The rule for the text inputs. |
| `label` | `CheckoutLabelRule?` | The rule for the form field labels. |
| `primaryButton` | `CheckoutPrimaryButtonRule?` | The rule for the primary action button. |
| `receiptEmailInput` | `CheckoutReceiptEmailInputRule?` | The rule for the receipt email input. |
| `tab` | `CheckoutTabRule?` | The rule for the payment method tabs. |


# CheckoutAppearanceVariables
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/structs/checkoutappearancevariables

Swift Structure

**Structure**

Global style variables that every element of the checkout inherits.

```swift theme={null}
struct CheckoutAppearanceVariables
```

Use variables to set the base look once. Use `CheckoutAppearanceRules` to override single elements.

## Initializers

### init(fontFamily:spacingUnit:fontSizeUnit:borderRadius:colors:)

Creates the variable set.

```swift theme={null}
init(fontFamily: String? = nil, spacingUnit: CheckoutLength? = nil, fontSizeUnit: CheckoutLength? = nil, borderRadius: CheckoutLength? = nil, colors: CheckoutVariablesColorStyle? = nil)
```

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `colors` | `CheckoutVariablesColorStyle?` | The global colors. |
| `cornerRadius` | `CheckoutLength?` | The corner radius of the checkout elements, for example `.px(8)` or `8`. |
| `fontFamily` | `String?` | The CSS `font-family` value of all the checkout text, for example `"Inter, sans-serif"`. |
| `fontSizeUnit` | `CheckoutLength?` | The base unit of all the checkout font sizes, for example `.px(4)`. |
| `spacingUnit` | `CheckoutLength?` | The base unit of all the checkout spacing, for example `.px(4)` or `4`. |


# CheckoutColor
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/structs/checkoutcolor

Swift Structure

**Structure**

A color of the checkout.

```swift theme={null}
struct CheckoutColor
```

Use `color(_:)` for a SwiftUI color, or `uiColor(_:)` for a UIKit color. Use `hex(_:)` for a hex string, or `css(_:)` for a different CSS color value.
Some colors change between light and dark mode, such as `Color.primary`. The checkout uses the value for its mode when it loads. If the mode changes later, the checkout keeps that value.

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: Decoder) throws
```

## Instance Methods

### encode(to:)

Inherited from `Encodable.encode(to:)`.

```swift theme={null}
func encode(to encoder: Encoder) throws
```

## Type Methods

### color(\_:)

Creates a color from a SwiftUI color, for example `.accentColor`.

```swift theme={null}
static func color(_ color: Color) -> CheckoutColor
```

### css(\_:)

Creates a color from a CSS color value, for example `"rgb(26, 26, 26)"`.

```swift theme={null}
static func css(_ value: String) -> CheckoutColor
```

The SDK sends the value to the checkout as it is.

### hex(\_:)

Creates a color from a hex string, for example `"#1A1A1A"` or `"#1A1A1A80"`.

```swift theme={null}
static func hex(_ value: String) -> CheckoutColor
```

#### Parameters

| Parameter | Description |
| - | - |
| `value` | A `#` and then three, four, six, or eight hex digits. If the value has a different format, the SDK logs an error and sends the value to the checkout as it is. |

### uiColor(\_:)

Creates a color from a UIKit color, for example `.systemBlue`.

```swift theme={null}
static func uiColor(_ color: UIColor) -> CheckoutColor
```


# CheckoutColorStyle
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/structs/checkoutcolorstyle

Swift Structure

**Structure**

The colors of one checkout element.

```swift theme={null}
struct CheckoutColorStyle
```

Each element reads only the keys that apply to it. A key the element does not use has no effect.

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

### init(text:background:backgroundPrimary:border:boxShadow:placeholder:)

Creates a color style from CSS color strings.

```swift theme={null}
init(text: String? = nil, background: String? = nil, backgroundPrimary: String? = nil, border: String? = nil, boxShadow: String? = nil, placeholder: String? = nil)
```

Use `init(text:background:backgroundPrimary:border:boxShadow:placeholder:)` instead.

### init(text:background:backgroundPrimary:border:boxShadow:placeholder:)

Creates a color style.

```swift theme={null}
init(text: CheckoutColor? = nil, background: CheckoutColor? = nil, backgroundPrimary: CheckoutColor? = nil, border: CheckoutColor? = nil, boxShadow: String? = nil, placeholder: CheckoutColor? = nil)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `background` | `String?` | The background color as a CSS string. |
| `backgroundColor` | `CheckoutColor?` | The background color. |
| `backgroundPrimary` | `String?` | The primary background color as a CSS string. |
| `backgroundPrimaryColor` | `CheckoutColor?` | The primary background color. |
| `border` | `String?` | The border color as a CSS string. |
| `borderColor` | `CheckoutColor?` | The border color. |
| `boxShadow` | `String?` | The CSS `box-shadow` value, for example `"0 0 0 2px #0066FF"`. |
| `placeholder` | `String?` | The placeholder text color as a CSS string. |
| `placeholderColor` | `CheckoutColor?` | The placeholder text color. |
| `text` | `String?` | The text color as a CSS string. |
| `textColor` | `CheckoutColor?` | The text color. |


# CheckoutCryptoPayment
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/structs/checkoutcryptopayment

Swift Structure

**Structure**

The settings for payment with crypto.

```swift theme={null}
struct CheckoutCryptoPayment
```

## Initializers

### init(enabled:defaultChain:defaultCurrency:)

Creates the crypto payment settings.

```swift theme={null}
init(enabled: Bool, defaultChain: String? = nil, defaultCurrency: String? = nil)
```

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `defaultChain` | `String?` | The blockchain the checkout selects first, for example `"base"` or `"solana"`. |
| `defaultCurrency` | `String?` | The currency the checkout selects first, for example `"usdc"`. |
| `enabled` | `Bool` | A Boolean value that shows whether the buyer can pay with crypto. |


# CheckoutDestinationInputRule
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/structs/checkoutdestinationinputrule

Swift Structure

**Structure**

The rule for the destination input, where the buyer enters the wallet address or email that receives the purchase.

```swift theme={null}
struct CheckoutDestinationInputRule
```

## Initializers

### init(display:)

Creates a destination input rule from a CSS `display` value.

```swift theme={null}
init(display: String? = nil)
```

Use `init(isHidden:)` instead.

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

### init(isHidden:)

Creates a destination input rule.

```swift theme={null}
init(isHidden: Bool = false)
```

#### Parameters

| Parameter | Description |
| - | - |
| `isHidden` | If the value is `true`, the checkout removes the input from the page. |

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `display` | `String?` | The CSS `display` value of the input. |
| `isHidden` | `Bool` | A Boolean value that shows if the checkout hides the input. |


# CheckoutFiatPayment
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/structs/checkoutfiatpayment

Swift Structure

**Structure**

The settings for payment with fiat currency.

```swift theme={null}
struct CheckoutFiatPayment
```

## Initializers

### init(enabled:defaultCurrency:allowedMethods:)

Creates the fiat payment settings.

```swift theme={null}
init(enabled: Bool, defaultCurrency: String? = nil, allowedMethods: CheckoutAllowedMethods? = nil)
```

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `allowedMethods` | `CheckoutAllowedMethods?` | The fiat payment methods the checkout offers. |
| `defaultCurrency` | `String?` | The currency the checkout selects first, for example `"usd"` or `"eur"`. |
| `enabled` | `Bool` | A Boolean value that shows whether the buyer can pay with fiat currency. |


# CheckoutFontSource
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/structs/checkoutfontsource

Swift Structure

**Structure**

A stylesheet that loads a custom font into the checkout.

```swift theme={null}
struct CheckoutFontSource
```

Use `googleFonts(_:weights:)` to load a font from Google Fonts. Use `cssURL(_:)` for a Google Fonts link that `googleFonts(_:weights:)` cannot build, such as one with italic styles. The checkout ignores stylesheets from other domains.
To use the loaded font, set its name in `fontFamily` or in `family` of a rule.

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Type Methods

### cssURL(\_:)

Loads the fonts that a CSS stylesheet declares.

```swift theme={null}
static func cssURL(_ url: URL) -> CheckoutFontSource
```

#### Parameters

| Parameter | Description |
| - | - |
| `url` | The URL of a CSS file with `@font-face` rules, such as a Google Fonts link. A URL to a font file, such as a `.woff2` file, does not work. |

### googleFonts(\_:weights:)

Loads a font family from Google Fonts.

```swift theme={null}
static func googleFonts(_ family: String, weights: [CheckoutFontWeight]? = nil) -> CheckoutFontSource
```

#### Parameters

| Parameter | Description |
| - | - |
| `family` | The name of the font family as Google Fonts shows it, for example `"Chakra Petch"`. |
| `weights` | The weights to load. Only number weights apply, such as `semibold` or `600`. A weight such as `CheckoutFontWeight("bold")` has no effect here. If the value is `nil`, Google Fonts loads the regular weight. |


# CheckoutFontStyle
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/structs/checkoutfontstyle

Swift Structure

**Structure**

The font of one checkout element.

```swift theme={null}
struct CheckoutFontStyle
```

The checkout applies only the values you set. It keeps the default for the rest.

## Initializers

### init(family:size:weight:)

Creates a font style from CSS strings.

```swift theme={null}
init(family: String? = nil, size: String? = nil, weight: String? = nil)
```

Use `init(family:size:weight:)` instead.

### init(family:size:weight:)

Creates a font style.

```swift theme={null}
init(family: String? = nil, size: CheckoutLength? = nil, weight: CheckoutFontWeight? = nil)
```

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `family` | `String?` | The CSS `font-family` value, for example `"Inter, sans-serif"`. |
| `fontSize` | `CheckoutLength?` | The font size. |
| `fontWeight` | `CheckoutFontWeight?` | The font weight. |
| `size` | `String?` | The font size as a CSS string. |
| `weight` | `String?` | The font weight as a CSS string. |


# CheckoutFontWeight
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/structs/checkoutfontweight

Swift Structure

**Structure**

A CSS font weight.

```swift theme={null}
struct CheckoutFontWeight
```

Use a named weight such as `semibold`, or a number from `1` to `1000`. Use `init(_:)` for a different CSS `font-weight` value, for example `"bold"`.

## Initializers

### init(\_:)

Creates a weight from a number, for example `600`.

```swift theme={null}
init(_ value: Int)
```

> **Note**: `value` is in the range `1...1000`.

### init(\_:)

Creates a weight from a CSS `font-weight` value, for example `"bold"`.

```swift theme={null}
init(_ value: String)
```

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: Decoder) throws
```

### init(integerLiteral:)

Creates a weight from an integer literal.

```swift theme={null}
init(integerLiteral value: Int)
```

## Instance Methods

### encode(to:)

Inherited from `Encodable.encode(to:)`.

```swift theme={null}
func encode(to encoder: Encoder) throws
```

## Type Properties

| Property | Type | Description |
| - | - | - |
| `black` | `CheckoutFontWeight` | The weight `900`. |
| `bold` | `CheckoutFontWeight` | The weight `700`. |
| `extraBold` | `CheckoutFontWeight` | The weight `800`. |
| `extraLight` | `CheckoutFontWeight` | The weight `200`. |
| `light` | `CheckoutFontWeight` | The weight `300`. |
| `medium` | `CheckoutFontWeight` | The weight `500`. |
| `regular` | `CheckoutFontWeight` | The weight `400`. |
| `semibold` | `CheckoutFontWeight` | The weight `600`. |
| `thin` | `CheckoutFontWeight` | The weight `100`. |


# CheckoutGlobalMessageRule
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/structs/checkoutglobalmessagerule

Swift Structure

**Structure**

The rule for the global message the checkout shows above the payment form.

```swift theme={null}
struct CheckoutGlobalMessageRule
```

## Initializers

### init(display:)

Creates a global message rule from a CSS `display` value.

```swift theme={null}
init(display: String? = nil)
```

Use `init(isHidden:)` instead.

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

### init(isHidden:)

Creates a global message rule.

```swift theme={null}
init(isHidden: Bool? = nil)
```

#### Parameters

| Parameter | Description |
| - | - |
| `isHidden` | If the value is `true`, the checkout removes the message. If the value is `false`, the checkout shows the message. If the value is `nil`, the checkout uses its default. |

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `display` | `String?` | The CSS `display` value of the message. |
| `isHidden` | `Bool?` | A Boolean value that shows if the checkout hides the message. |


# CheckoutInputRule
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/structs/checkoutinputrule

Swift Structure

**Structure**

The rule for the text inputs of the payment form.

```swift theme={null}
struct CheckoutInputRule
```

## Initializers

### init(borderRadius:font:colors:hover:focus:)

Creates an input rule with a CSS string for the corner radius.

```swift theme={null}
init(borderRadius: String? = nil, font: CheckoutFontStyle? = nil, colors: CheckoutColorStyle? = nil, hover: CheckoutStateStyle? = nil, focus: CheckoutStateStyle? = nil)
```

Use `init(borderRadius:font:colors:hover:focus:)` instead.

### init(borderRadius:font:colors:hover:focus:)

Creates an input rule.

```swift theme={null}
init(borderRadius: CheckoutLength? = nil, font: CheckoutFontStyle? = nil, colors: CheckoutColorStyle? = nil, hover: CheckoutStateStyle? = nil, focus: CheckoutStateStyle? = nil)
```

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `borderRadius` | `String?` | The corner radius as a CSS string. |
| `colors` | `CheckoutColorStyle?` | The input colors in the rest state. |
| `cornerRadius` | `CheckoutLength?` | The corner radius, for example `.px(8)` or `8`. |
| `focus` | `CheckoutStateStyle?` | The input colors while the input has focus. |
| `font` | `CheckoutFontStyle?` | The input font. |
| `hover` | `CheckoutStateStyle?` | The input colors while the pointer is over the input. |


# CheckoutLabelRule
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/structs/checkoutlabelrule

Swift Structure

**Structure**

The rule for the labels above the form fields.

```swift theme={null}
struct CheckoutLabelRule
```

## Initializers

### init(font:colors:)

Creates a label rule.

```swift theme={null}
init(font: CheckoutFontStyle? = nil, colors: CheckoutColorStyle? = nil)
```

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `colors` | `CheckoutColorStyle?` | The label colors. |
| `font` | `CheckoutFontStyle?` | The label font. |


# CheckoutLineItems
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/structs/checkoutlineitems

Swift Structure

**Structure**

```swift theme={null}
struct CheckoutLineItems
```

## Initializers

### init(collectionLocator:tokenLocator:productLocator:callData:executionParameters:)

```swift theme={null}
init(collectionLocator: String? = nil, tokenLocator: String? = nil, productLocator: String? = nil, callData: [String : AnyCodable]? = nil, executionParameters: [String : AnyCodable]? = nil)
```

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `callData` | `[String : AnyCodable]?` | - |
| `collectionLocator` | `String?` | - |
| `executionParameters` | `[String : AnyCodable]?` | - |
| `productLocator` | `String?` | - |
| `tokenLocator` | `String?` | - |


# CheckoutOrder
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/structs/checkoutorder

Swift Structure

**Structure**

An order as the embedded checkout page reports it.

```swift theme={null}
struct CheckoutOrder
```

## Structures

### CheckoutOrder.Payment

The payment section of an order.

```swift theme={null}
struct Payment
```

The `status` value `requires-kyc` means the order waits on identity verification.

### CheckoutOrder.Preparation

The payment preparation section of an order.

```swift theme={null}
struct Preparation
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `identityVerificationCredentials` | `IdentityVerificationCredentials?` | The credentials for the pending identity verification. |
| `orderId` | `String?` | The identifier of the order. |
| `payment` | `Payment?` | The payment section of the order. |
| `phase` | `Phase?` | The stage the order is in. |

## Enumerations

### CheckoutOrder.Phase

A stage in the life of an order.

```swift theme={null}
enum Phase
```


# CheckoutOrderUpdate
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/structs/checkoutorderupdate

Swift Structure

**Structure**

The payload of one `order:updated` event from the checkout page.

```swift theme={null}
struct CheckoutOrderUpdate
```

The `orderClientSecret` authorizes reads of the order. A later update can omit it.

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `order` | `CheckoutOrder?` | The order in its new state. |
| `orderClientSecret` | `String?` | The secret that authorizes reads of the order. |


# CheckoutPayment
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/structs/checkoutpayment

Swift Structure

**Structure**

The payment settings for `CrossmintEmbeddedCheckout`.

```swift theme={null}
struct CheckoutPayment
```

At least one of `crypto` and `fiat` must be enabled. The checkout shows a tab for each enabled method.

## Initializers

### init(crypto:fiat:receiptEmail:defaultMethod:)

Creates the payment settings.

```swift theme={null}
init(crypto: CheckoutCryptoPayment, fiat: CheckoutFiatPayment, receiptEmail: String? = nil, defaultMethod: Method? = nil)
```

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `crypto` | `CheckoutCryptoPayment` | The settings for payment with crypto. |
| `defaultMethod` | `Method?` | The payment method the checkout selects first. |
| `fiat` | `CheckoutFiatPayment` | The settings for payment with fiat currency. |
| `receiptEmail` | `String?` | The email address that receives the receipt. |

## Enumerations

### CheckoutPayment.Method

A payment method.

```swift theme={null}
enum Method
```


# CheckoutPrimaryButtonRule
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/structs/checkoutprimarybuttonrule

Swift Structure

**Structure**

The rule for the primary action button, such as the pay button.

```swift theme={null}
struct CheckoutPrimaryButtonRule
```

## Initializers

### init(borderRadius:font:colors:hover:disabled:)

Creates a primary button rule.

```swift theme={null}
init(borderRadius: CheckoutLength? = nil, font: CheckoutFontStyle? = nil, colors: CheckoutColorStyle? = nil, hover: CheckoutStateStyle? = nil, disabled: CheckoutStateStyle? = nil)
```

### init(borderRadius:font:colors:hover:disabled:)

Creates a primary button rule with a CSS string for the corner radius.

```swift theme={null}
init(borderRadius: String? = nil, font: CheckoutFontStyle? = nil, colors: CheckoutColorStyle? = nil, hover: CheckoutStateStyle? = nil, disabled: CheckoutStateStyle? = nil)
```

Use `init(borderRadius:font:colors:hover:disabled:)` instead.

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `borderRadius` | `String?` | The corner radius as a CSS string. |
| `colors` | `CheckoutColorStyle?` | The button colors in the rest state. |
| `cornerRadius` | `CheckoutLength?` | The corner radius, for example `.px(8)` or `8`. |
| `disabled` | `CheckoutStateStyle?` | The button colors in the disabled state. |
| `font` | `CheckoutFontStyle?` | The button font. |
| `hover` | `CheckoutStateStyle?` | The button colors while the pointer is over the button. |


# CheckoutReceiptEmailInputRule
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/structs/checkoutreceiptemailinputrule

Swift Structure

**Structure**

The rule for the receipt email input.

```swift theme={null}
struct CheckoutReceiptEmailInputRule
```

## Initializers

### init(display:)

Creates a receipt email input rule from a CSS `display` value.

```swift theme={null}
init(display: String? = nil)
```

Use `init(isHidden:)` instead.

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

### init(isHidden:)

Creates a receipt email input rule.

```swift theme={null}
init(isHidden: Bool = false)
```

#### Parameters

| Parameter | Description |
| - | - |
| `isHidden` | If the value is `true`, the checkout removes the input from the page. When the buyer pays by card, the checkout always shows the input. |

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `display` | `String?` | The CSS `display` value of the input. |
| `isHidden` | `Bool` | A Boolean value that shows if the checkout hides the input. |


# CheckoutRecipient
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/structs/checkoutrecipient

Swift Structure

**Structure**

```swift theme={null}
struct CheckoutRecipient
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

### init(walletAddress:email:)

```swift theme={null}
init(walletAddress: String? = nil, email: String? = nil)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `email` | `String?` | - |
| `walletAddress` | `String?` | - |


# CheckoutStateStyle
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/structs/checkoutstatestyle

Swift Structure

**Structure**

The colors of an element while it is in one interaction state, such as hover or focus.

```swift theme={null}
struct CheckoutStateStyle
```

## Initializers

### init(colors:)

Creates a state style.

```swift theme={null}
init(colors: CheckoutColorStyle? = nil)
```

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `colors` | `CheckoutColorStyle?` | The colors the element uses while it is in this state. |


# CheckoutTabRule
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/structs/checkouttabrule

Swift Structure

**Structure**

The rule for the payment method tabs, such as the card and crypto tabs.

```swift theme={null}
struct CheckoutTabRule
```

## Initializers

### init(borderRadius:font:colors:hover:selected:)

Creates a tab rule with a CSS string for the corner radius.

```swift theme={null}
init(borderRadius: String? = nil, font: CheckoutFontStyle? = nil, colors: CheckoutColorStyle? = nil, hover: CheckoutStateStyle? = nil, selected: CheckoutStateStyle? = nil)
```

Use `init(borderRadius:font:colors:hover:selected:)` instead.

### init(borderRadius:font:colors:hover:selected:)

Creates a tab rule.

```swift theme={null}
init(borderRadius: CheckoutLength? = nil, font: CheckoutFontStyle? = nil, colors: CheckoutColorStyle? = nil, hover: CheckoutStateStyle? = nil, selected: CheckoutStateStyle? = nil)
```

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `borderRadius` | `String?` | The corner radius as a CSS string. |
| `colors` | `CheckoutColorStyle?` | The tab colors in the rest state. |
| `cornerRadius` | `CheckoutLength?` | The corner radius, for example `.px(8)` or `8`. |
| `font` | `CheckoutFontStyle?` | The tab font. |
| `hover` | `CheckoutStateStyle?` | The tab colors while the pointer is over the tab. |
| `selected` | `CheckoutStateStyle?` | The tab colors while the tab is the selected one. |


# CheckoutVariablesColorStyle
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/structs/checkoutvariablescolorstyle

Swift Structure

**Structure**

The colors that every element of the checkout inherits.

```swift theme={null}
struct CheckoutVariablesColorStyle
```

To change the colors of one element, use `CheckoutColorStyle` in a rule.

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

### init(textPrimary:textSecondary:backgroundPrimary:borderPrimary:danger:warning:accent:)

Creates the global colors.

```swift theme={null}
init(textPrimary: CheckoutColor? = nil, textSecondary: CheckoutColor? = nil, backgroundPrimary: CheckoutColor? = nil, borderPrimary: CheckoutColor? = nil, danger: CheckoutColor? = nil, warning: CheckoutColor? = nil, accent: CheckoutColor? = nil)
```

### init(textPrimary:textSecondary:backgroundPrimary:borderPrimary:danger:warning:accent:)

Creates the global colors from CSS color strings.

```swift theme={null}
init(textPrimary: String? = nil, textSecondary: String? = nil, backgroundPrimary: String? = nil, borderPrimary: String? = nil, danger: String? = nil, warning: String? = nil, accent: String? = nil)
```

Use `init(textPrimary:textSecondary:backgroundPrimary:borderPrimary:danger:warning:accent:)` instead.

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `accent` | `String?` | The accent color as a CSS string. |
| `accentColor` | `CheckoutColor?` | The accent color of highlights, links, and selected items. |
| `backgroundPrimary` | `String?` | The background color of the checkout as a CSS string. |
| `backgroundPrimaryColor` | `CheckoutColor?` | The background color of the checkout. |
| `borderPrimary` | `String?` | The default border color as a CSS string. |
| `borderPrimaryColor` | `CheckoutColor?` | The default border color of inputs and containers. |
| `danger` | `String?` | The color of error messages as a CSS string. |
| `dangerColor` | `CheckoutColor?` | The color of error messages. |
| `textPrimary` | `String?` | The color of primary text as a CSS string. |
| `textPrimaryColor` | `CheckoutColor?` | The color of primary text, such as headings and amounts. |
| `textSecondary` | `String?` | The color of secondary text as a CSS string. |
| `textSecondaryColor` | `CheckoutColor?` | The color of secondary text, such as helper text and captions. |
| `warning` | `String?` | The color of warning messages as a CSS string. |
| `warningColor` | `CheckoutColor?` | The color of warning messages. |


# CrossmintEmbeddedCheckout
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/structs/crossmintembeddedcheckout

Swift Structure

**Structure**

A view that shows Crossmint’s hosted checkout for an order.

```swift theme={null}
@MainActor struct CrossmintEmbeddedCheckout
```

Create the order from your backend with the Crossmint Orders API. Pass the `orderId` and `clientSecret` from the response. The checkout page collects the payment. It also takes the buyer through the other steps the order needs, such as identity verification.

```swift theme={null}
CrossmintEmbeddedCheckout(
    apiKey: apiKey,
    orderId: orderId,
    clientSecret: clientSecret
)
```

Pass a `CrossmintCheckoutController` to observe the order as the buyer progresses. As an alternative, attach `onOrderUpdated(_:)` and `onOrderCreationFailed(_:)` to handle the events yourself.

## Initializers

### init(apiKey:orderId:clientSecret:lineItems:payment:recipient:appearance:identityVerificationHandling:controller:consoleLogLevel:)

Creates a checkout for an order.

```swift theme={null}
@MainActor init(apiKey: String, orderId: String? = nil, clientSecret: String? = nil, lineItems: CheckoutLineItems? = nil, payment: CheckoutPayment? = nil, recipient: CheckoutRecipient? = nil, appearance: CheckoutAppearance? = nil, identityVerificationHandling: IdentityVerificationHandling? = nil, controller: CrossmintCheckoutController? = nil, consoleLogLevel: CheckoutLogLevel = .error)
```

#### Parameters

| Parameter | Description |
| - | - |
| `apiKey` | Your client-side API key. The key starts with `ck_`. |
| `orderId` | The identifier of the order your backend created. |
| `clientSecret` | The client secret from the same order response. |
| `lineItems` | The items of a new order. Not supported yet, so pass `nil`. |
| `payment` | The payment settings. A `nil` value keeps the checkout defaults. |
| `recipient` | The recipient of a new order. Not supported yet, so pass `nil`. |
| `appearance` | The visual customization. A `nil` value keeps the checkout defaults. |
| `identityVerificationHandling` | The presentation mode for the identity verification step. Pass `IdentityVerificationHandling.external` to show the step yourself. |
| `controller` | The controller that receives the order updates. |
| `consoleLogLevel` | The minimum level of the SDK messages that reach the system console. |

### init(apiKey:orderId:clientSecret:lineItems:payment:recipient:appearance:identityVerificationHandling:controller:environment:)

Creates a checkout for an order with an explicit environment.

```swift theme={null}
@MainActor init(apiKey: String, orderId: String? = nil, clientSecret: String? = nil, lineItems: CheckoutLineItems? = nil, payment: CheckoutPayment? = nil, recipient: CheckoutRecipient? = nil, appearance: CheckoutAppearance? = nil, identityVerificationHandling: IdentityVerificationHandling? = nil, controller: CrossmintCheckoutController? = nil, environment: CheckoutEnvironment)
```

The environment normally comes from the API key. Do not use this initializer in new code. Use `init(apiKey:orderId:clientSecret:lineItems:payment:recipient:appearance:identityVerificationHandling:controller:)` instead.

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `body` | `some View` | Inherited from `View.body`. |

## Instance Methods

### onOrderCreationFailed(\_:)

Adds an action to perform when order creation fails. The message describes the failure.

```swift theme={null}
@MainActor func onOrderCreationFailed(_ action: @escaping (String) -> Void) -> CrossmintEmbeddedCheckout
```

### onOrderUpdated(\_:)

Adds an action to perform on every order update from the checkout page.

```swift theme={null}
@MainActor func onOrderUpdated(_ action: @escaping (CheckoutOrderUpdate) -> Void) -> CrossmintEmbeddedCheckout
```


# CrossmintIdentityVerification
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/structs/crossmintidentityverification

Swift Structure

**Structure**

A view that shows Crossmint’s hosted identity verification (KYC) step.

```swift theme={null}
@MainActor struct CrossmintIdentityVerification
```

The view fills the space the layout gives it. The verification content scrolls inside the view. The Crossmint environment comes from the API key. Attach event handlers with `onReady(_:)`, `onComplete(_:)`, `onCancel(_:)`, and `onError(_:)`.
Show the view when the order first has credentials, and pass it the latest ones while it is open. Keep it on screen until `onComplete(_:)` or `onCancel(_:)`, even if the order drops its credentials first. Once it closes, do not show it again for that order.
Document capture needs camera access. Add `NSCameraUsageDescription` to your app’s Info.plist.

## Initializers

### init(apiKey:credentials:locale:consoleLogLevel:)

Creates an identity verification view.

```swift theme={null}
@MainActor init(apiKey: String, credentials: IdentityVerificationCredentials, locale: CheckoutLocale? = nil, consoleLogLevel: CheckoutLogLevel = .error)
```

#### Parameters

| Parameter | Description |
| - | - |
| `apiKey` | Your client-side API key. The key starts with `ck_`. |
| `credentials` | The credentials of the pending verification, from the order. |
| `locale` | The language of the verification UI. A `nil` value uses the default of the hosted page. |
| `consoleLogLevel` | The minimum level of the SDK messages that reach the system console. |

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `body` | `some View` | Inherited from `View.body`. |

## Instance Methods

### onCancel(\_:)

Adds an action to perform when the buyer dismisses the verification flow.

```swift theme={null}
@MainActor func onCancel(_ action: @escaping () -> Void) -> CrossmintIdentityVerification
```

### onComplete(\_:)

Adds an action to perform when the buyer finishes the verification. The status gives the result.

```swift theme={null}
@MainActor func onComplete(_ action: @escaping (IdentityVerificationStatus) -> Void) -> CrossmintIdentityVerification
```

### onError(\_:)

Adds an action to perform when the verification fails. `retriable` shows if a new attempt can work.

```swift theme={null}
@MainActor func onError(_ action: @escaping (IdentityVerificationError) -> Void) -> CrossmintIdentityVerification
```

### onReady(\_:)

Adds an action to perform when the verification UI finishes loading.

```swift theme={null}
@MainActor func onReady(_ action: @escaping () -> Void) -> CrossmintIdentityVerification
```


# IdentityVerificationCredentials
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/structs/identityverificationcredentials

Swift Structure

**Structure**

The credentials for one identity verification session.

```swift theme={null}
struct IdentityVerificationCredentials
```

An order that needs verification includes them in `payment.preparation.kyc`. Read the credentials from `identityVerificationCredentials`. You can also read them from the order response of your backend.
The order picks the shape: a Persona inquiry, or a Crossmint verification session. Pass the credentials through as they come.

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: Decoder) throws
```

### init(inquiryId:sessionToken:)

Creates the credentials for a Persona inquiry.

```swift theme={null}
init(inquiryId: String, sessionToken: String? = nil)
```

An empty `sessionToken` becomes `nil`.

### init(verificationId:clientSecret:deviceSessionKey:)

Creates the credentials for a Crossmint verification session.

```swift theme={null}
init(verificationId: String, clientSecret: String, deviceSessionKey: String? = nil)
```

An empty `deviceSessionKey` becomes `nil`.

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `id` | `String` | The stable identity of the credentials: the inquiry identifier for Persona, or the verification identifier for a Crossmint verification session. |
| `inquiryId` | `String?` | The identifier of the verification inquiry at Persona. |
| `provider` | `String?` | The verification provider, `"persona"` for a Persona inquiry. |
| `sessionToken` | `String?` | The token that resumes a Persona inquiry the buyer started before. |

## Instance Methods

### encode(to:)

Inherited from `Encodable.encode(to:)`.

```swift theme={null}
func encode(to encoder: Encoder) throws
```


# IdentityVerificationError
Source: https://docs.crossmint.com/sdk-reference/checkout/swift/structs/identityverificationerror

Swift Structure

**Structure**

An error from the identity verification flow.

```swift theme={null}
struct IdentityVerificationError
```

When `retriable` is false, the flow cannot continue. The buyer cannot finish it.

## Initializers

### init(retriable:reason:message:)

Creates an error.

```swift theme={null}
init(retriable: Bool, reason: Reason, message: String)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `errorDescription` | `String?` | Inherited from `LocalizedError.errorDescription`. |
| `message` | `String` | The text that describes the error. |
| `reason` | `Reason` | The cause of the error. |
| `retriable` | `Bool` | A Boolean value that shows whether a new attempt can work. |

## Enumerations

### IdentityVerificationError.Reason

The cause of the error.

```swift theme={null}
enum Reason
```


# ContractMetadataService
Source: https://docs.crossmint.com/sdk-reference/credentials/classes/ContractMetadataService



Service for retrieving and managing contract metadata.

## Constructors

### new ContractMetadataService()

> **new ContractMetadataService**(`chain`): [`ContractMetadataService`](./ContractMetadataService)

Initializes a new instance of the ContractMetadataService.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `chain` | [`VCChain`](../type-aliases/VCChain) | The blockchain to be used. |

#### Returns

[`ContractMetadataService`](./ContractMetadataService)

#### Defined in

[verifiableCredentialsSDK/presentation/contractMetadata.ts:20](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/presentation/contractMetadata.ts#L20)

## Properties

| Property | Type | Description | Defined in |
| - | - | - | - |
| `chain` | [`VCChain`](../type-aliases/VCChain) | The blockchain on which the contract is deployed. | [verifiableCredentialsSDK/presentation/contractMetadata.ts:14](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/presentation/contractMetadata.ts#L14) |

## Methods

### getContractMetadata()

> **getContractMetadata**(`contractAddress`): `Promise`\<`any`>

Retrieves metadata for a given contract.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `contractAddress` | `string` | The address of the contract. |

#### Returns

`Promise`\<`any`>

The metadata object or `null` if the contractURI call returns null.

#### Throws

Will throw an error if the retrieval process fails.

#### Defined in

[verifiableCredentialsSDK/presentation/contractMetadata.ts:31](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/presentation/contractMetadata.ts#L31)

***

### getContractsWithCredentialMetadata()

> **getContractsWithCredentialMetadata**(`collections`): `Promise`\<[`CredentialsCollection`](../interfaces/CredentialsCollection)\[]>

Retrieves metadata for multiple contracts and filters those that are verifiable credentials collections.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `collections` | [`Collection`](../interfaces/Collection)\[] | An array of collections containing contract addresses. |

#### Returns

`Promise`\<[`CredentialsCollection`](../interfaces/CredentialsCollection)\[]>

A promise that resolves to an array of collections with valid verifiable credential metadata.

#### Throws

Will continue to the next collection if an error occurs during metadata retrieval.

#### Defined in

[verifiableCredentialsSDK/presentation/contractMetadata.ts:48](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/presentation/contractMetadata.ts#L48)


# CredentialService
Source: https://docs.crossmint.com/sdk-reference/credentials/classes/CredentialService



Service for managing and retrieving verifiable credentials from different sources. By default, it includes procedures for IPFS and Crossmint, but additional procedures can be added by the user.

* CredentialService().getById(credentialId: string) : Fetches the credential from crossmint using the credentialId.
* CredentialService().getCredential(collection: CredentialsCollection, tokenId: string) : Fetches the credential from the source that matches the storage location of the credential.

## Remarks

To use the Crossmint procedure, a Crossmint API key with the `credentials.read` scope must be set.

## Extends

* `CredentialService`

## Constructors

### new CredentialService()

> **new CredentialService**(`retrievalProcedures`): [`CredentialService`](./CredentialService)

#### Parameters

| Parameter | Type |
| - | - |
| `retrievalProcedures` | `CredentialRetrievalProcedure`\[] |

#### Returns

[`CredentialService`](./CredentialService)

#### Overrides

`CredentialServiceRaw.constructor`

#### Defined in

[presentation/getCredential.ts:100](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/presentation/getCredential.ts#L100)

## Properties

| Property | Type | Inherited from | Defined in |
| - | - | - | - |
| `retrievalProcedures` | `CredentialRetrievalProcedure`\[] | `CredentialServiceRaw.retrievalProcedures` | [verifiableCredentialsSDK/presentation/getCredential.ts:45](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/presentation/getCredential.ts#L45) |

## Methods

### getById()

> **getById**(`credentialId`): `Promise`\<`null` | [`VerifiableCredentialType`](../type-aliases/VerifiableCredentialType)>

Retrieves a verifiable credential from Crossmint using its credential ID.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `credentialId` | `string` | The ID of the credential to retrieve. |

#### Returns

`Promise`\<`null` | [`VerifiableCredentialType`](../type-aliases/VerifiableCredentialType)>

A promise that resolves to a `VerifiableCredentialType` or `null` if the credential is not found.

#### Throws

Will throw an error if the credential retrieval fails.

#### Defined in

[presentation/getCredential.ts:112](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/presentation/getCredential.ts#L112)

***

### getCredential()

> **getCredential**(`collection`, `tokenId`): `Promise`\<[`VerifiableCredentialType`](../type-aliases/VerifiableCredentialType)>

Retrieves a Verifiable Credential from a given collection and token ID.

This function finds the appropriate retrieval procedure based on the collection's metadata and uses it to fetch the credential.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `collection` | [`CredentialsCollection`](../interfaces/CredentialsCollection) | The `CredentialsCollection` containing the credential's metadata. |
| `tokenId` | `string` | The token ID of the credential to retrieve. |

#### Returns

`Promise`\<[`VerifiableCredentialType`](../type-aliases/VerifiableCredentialType)>

A promise that resolves to a `VerifiableCredentialType`.

#### Throws

Will throw an error if the collection is not a verifiable credential collection or if the retrieval endpoint is unsupported.

#### Inherited from

`CredentialServiceRaw.getCredential`

#### Defined in

[verifiableCredentialsSDK/presentation/getCredential.ts:65](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/presentation/getCredential.ts#L65)


# CrossmintDecrypt
Source: https://docs.crossmint.com/sdk-reference/credentials/classes/CrossmintDecrypt



Class for decrypting verifiable credentials that have been encrypted with the `VerifiableCredentialEncryptionType.CROSSMINT_RECOVERABLE` encryption type.

This class uses a provided signature callback to authenticate the user and decrypt the credential.
To use the Crossmint decrypt endpoint, an API key with the `credentials.decrypt` scope must be provided.

## Constructors

### new CrossmintDecrypt()

> **new CrossmintDecrypt**(`userAddress`, `signCallback`, `authService`): [`CrossmintDecrypt`](./CrossmintDecrypt)

#### Parameters

| Parameter | Type |
| - | - |
| `userAddress` | `string` |
| `signCallback` | (`wallet`, `challenge`) => `Promise`\<`string`> |
| `authService` | [`WalletAuthService`](./WalletAuthService) |

#### Returns

[`CrossmintDecrypt`](./CrossmintDecrypt)

#### Defined in

[decryption/wallet.ts:25](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/decryption/wallet.ts#L25)

## Properties

| Property | Type | Description | Defined in |
| - | - | - | - |
| `signCallback` | (`wallet`: `string`, `challenge`: `string`) => `Promise`\<`string`> | A callback function that signs the challenge with the user's wallet. | [decryption/wallet.ts:24](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/decryption/wallet.ts#L24) |
| `userAddress` | `string` | - | [decryption/wallet.ts:16](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/decryption/wallet.ts#L16) |

## Methods

### decrypt()

> **decrypt**(`credential`): `Promise`\<[`VerifiableCredential`](../interfaces/VerifiableCredential)>

Decrypts an encrypted verifiable credential.

This method validates the decrypted data to ensure it is a valid verifiable credential.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `credential` | [`EncryptedVerifiableCredential`](../interfaces/EncryptedVerifiableCredential) | The encrypted verifiable credential to decrypt. |

#### Returns

`Promise`\<[`VerifiableCredential`](../interfaces/VerifiableCredential)>

A promise that resolves to a `VerifiableCredential`.

#### Throws

Will throw an error if the decrypted data is not a valid verifiable credential.

#### Defined in

[decryption/wallet.ts:52](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/decryption/wallet.ts#L52)


# CrossmintMetamaskDecrypt
Source: https://docs.crossmint.com/sdk-reference/credentials/classes/CrossmintMetamaskDecrypt



Class for decrypting verifiable credentials encrypted with the `VerifiableCredentialEncryptionType.CROSSMINT_RECOVERABLE` encryption type using Metamask.

This class uses Metamask to prompt the user to sign a message to decrypt the credential.
If you want to use a different signature method, refer to the `CrossmintDecrypt` class.
To use the Crossmint decrypt endpoint, an API key with the `credentials.decrypt` scope must be provided.

## Constructors

### new CrossmintMetamaskDecrypt()

> **new CrossmintMetamaskDecrypt**(`metamask`): [`CrossmintMetamaskDecrypt`](./CrossmintMetamaskDecrypt)

#### Parameters

| Parameter | Type |
| - | - |
| `metamask` | `MetamaskService` |

#### Returns

[`CrossmintMetamaskDecrypt`](./CrossmintMetamaskDecrypt)

#### Defined in

[decryption/wallet.ts:69](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/decryption/wallet.ts#L69)

## Methods

### decrypt()

> **decrypt**(`credential`, `wallet`?): `Promise`\<[`VerifiableCredential`](../interfaces/VerifiableCredential)>

Decrypts an encrypted verifiable credential using Metamask.

This method prompts the user via Metamask to sign the necessary message for decrypting the credential.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `credential` | [`EncryptedVerifiableCredential`](../interfaces/EncryptedVerifiableCredential) | The encrypted verifiable credential to decrypt. |
| `wallet`? | `string` | (Optional) The user's wallet address. If not provided, the connected wallet address from Metamask will be used. |

#### Returns

`Promise`\<[`VerifiableCredential`](../interfaces/VerifiableCredential)>

A promise that resolves to a `VerifiableCredential`.

#### Throws

Will throw an error if decryption fails or if Metamask is not properly configured.

#### Defined in

[decryption/wallet.ts:84](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/decryption/wallet.ts#L84)


# Lit
Source: https://docs.crossmint.com/sdk-reference/credentials/classes/Lit



Lit class for decrypting verifiable credentials that have been encrypted with the
VerifiableCredentialEncryptionType.DECENTRALIZED\_LIT encryption type.

## Extends

* `Lit`

## Constructors

### new Lit()

> **new Lit**(`network`, `capacityDelegationAuthSig`?, `debug`?): [`Lit`](./Lit)

Creates an instance of the Lit class for decrypting verifiable credentials.

#### Parameters

| Parameter | Type | Default value | Description |
| - | - | - | - |
| `network` | `"habanero"` \| `"manzano"` \| `"cayenne"` | `undefined` | The network on which the credentials are encrypted (use CredentialMetadata.encryption.details.network). |
| `capacityDelegationAuthSig`? | `AuthSig` | `undefined` | The capacity delegation signature used to pay for decrypting the credentials. If not provided, the Crossmint signature will be used. To use the Crossmint delegation signature, the user must have provided an API key with the `credentials.decrypt` scope. |
| `debug`? | `boolean` | `false` | If true, enables debug mode for additional logging. |

#### Returns

[`Lit`](./Lit)

#### Overrides

`LitRaw.constructor`

#### Defined in

[decryption/lit.ts:27](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/decryption/lit.ts#L27)

## Methods

### connect()

> **connect**(): `Promise`\<`LitNodeClient`>

#### Returns

`Promise`\<`LitNodeClient`>

#### Inherited from

`LitRaw.connect`

#### Defined in

[verifiableCredentialsSDK/encryption/lit.ts:50](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/encryption/lit.ts#L50)

***

### decrypt()

> **decrypt**(`credential`): `Promise`\<[`VerifiableCredential`](../interfaces/VerifiableCredential)>

Decrypts a verifiable credential that has been encrypted with the Lit protocol.
The user will be prompted to sign a message to decrypt the credential.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `credential` | [`EncryptedVerifiableCredential`](../interfaces/EncryptedVerifiableCredential) | The encrypted verifiable credential to decrypt. |

#### Returns

`Promise`\<[`VerifiableCredential`](../interfaces/VerifiableCredential)>

A promise that resolves to the decrypted verifiable credential.

#### Overrides

`LitRaw.decrypt`

#### Defined in

[decryption/lit.ts:49](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/decryption/lit.ts#L49)


# WalletAuthService
Source: https://docs.crossmint.com/sdk-reference/credentials/classes/WalletAuthService



Service for handling wallet-based authentication and decryption with Crossmint.

The `WalletAuthService` class provides methods to retrieve a challenge for wallet authentication and to decrypt credentials using that challenge.

## Constructors

### new WalletAuthService()

> **new WalletAuthService**(): [`WalletAuthService`](./WalletAuthService)

#### Returns

[`WalletAuthService`](./WalletAuthService)

## Methods

### decrypt()

> **decrypt**(`credential`, `challenge`, `signature`, `userAddress`): `Promise`\<`any`>

Decrypts an encrypted verifiable credential using a signed challenge.

This method sends the signed challenge, the user's address, and the encrypted credential to Crossmint for decryption.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `credential` | [`EncryptedVerifiableCredential`](../interfaces/EncryptedVerifiableCredential) | The encrypted verifiable credential to decrypt. |
| `challenge` | `string` | The challenge that was signed by the user's wallet. |
| `signature` | `string` | The signature of the challenge signed by the user's wallet. |
| `userAddress` | `string` | The blockchain address of the user requesting decryption. |

#### Returns

`Promise`\<`any`>

A promise that resolves to the decrypted data.

#### Throws

Will throw an error if the decryption request fails or if the response is invalid.

#### Defined in

[services/walletAuth.ts:57](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/services/walletAuth.ts#L57)

***

### getChallenge()

> **getChallenge**(`userAddress`): `Promise`\<`string`>

Retrieves a challenge nonce for wallet authentication.

This method requests a challenge from Crossmint that can be signed by the user's wallet to authenticate the user.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `userAddress` | `string` | The blockchain address of the user requesting the challenge. |

#### Returns

`Promise`\<`string`>

A promise that resolves to a string representing the challenge to sign.

#### Throws

Will throw an error if the challenge request fails or if the response is invalid.

#### Defined in

[services/walletAuth.ts:20](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/services/walletAuth.ts#L20)


# VerifiableCredentialEncryptionType
Source: https://docs.crossmint.com/sdk-reference/credentials/enumerations/VerifiableCredentialEncryptionType



VerifiableCredentialEncryptionType defines the types of encryption used for the credentials.

## Enumeration Members

### CROSSMINT\_RECOVERABLE

> **CROSSMINT\_RECOVERABLE**: `"crossmint-recoverable"`

Wallet based encryption that is recoverable via Crossmint.

#### Defined in

[verifiableCredentialsSDK/types/collection.ts:114](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/collection.ts#L114)

***

### DECENTRALIZED\_LIT

> **DECENTRALIZED\_LIT**: `"decentralized-lit"`

Decentralized encryption using the Lit protocol.

#### Defined in

[verifiableCredentialsSDK/types/collection.ts:109](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/collection.ts#L109)

***

### NONE

> **NONE**: `"none"`

No encryption applied to the verifiable credentials.

#### Defined in

[verifiableCredentialsSDK/types/collection.ts:104](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/collection.ts#L104)


# getCredentialNFTFromLocator
Source: https://docs.crossmint.com/sdk-reference/credentials/functions/getCredentialNFTFromLocator



> **getCredentialNFTFromLocator**(`locator`): `Promise`\<`object`>

Retrieves a Verifiable Credential NFT from a locator.

This function performs the following steps:

1. Parses the locator string to extract NFT details.
2. Verifies that the NFT belongs to a supported Verifiable Credentials chain.
3. Fetches the NFT's metadata and verifies it belongs to a Verifiable Credentials collection.
4. Returns the NFT and the corresponding credentials collection.

## Parameters

| Parameter | Type | Description |
| - | - | - |
| `locator` | `string` | The locator string of the credential, formatted as "chain:contractAddress:tokenId" (e.g., "polygon:0x1B887669437644aA348c518844660ef8d63bd643:1"). |

## Returns

`Promise`\<`object`>

An object containing:

* `collection`: The collection that the NFT belongs to, including the credential metadata.
* `nft`: The NFT with its metadata.

### collection

> **collection**: [`CredentialsCollection`](../interfaces/CredentialsCollection)

### nft

> **nft**: `NftWithMetadata` = `vcNft`

## Throws

Will throw an error if the NFT is not on a supported Verifiable Credentials chain or if the NFT is not associated with a Verifiable Credentials collection.

## Defined in

[verifiableCredentialsSDK/presentation/nftByLocator.ts:25](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/presentation/nftByLocator.ts#L25)


# getCredentialNfts
Source: https://docs.crossmint.com/sdk-reference/credentials/functions/getCredentialNfts



> **getCredentialNfts**(`chain`, `wallet`, `filters`): `Promise`\<[`CredentialsCollection`](../interfaces/CredentialsCollection)\[]>

Get all the NFTs of a given user that are verifiable credentials
To use this method an api key with the `credentials.read` scope must have been provided.

## Parameters

| Parameter | Type | Description |
| - | - | - |
| `chain` | [`VCChain`](../type-aliases/VCChain) | Chain to get the NFTs from |
| `wallet` | `string` | Wallet address of the user |
| `filters` | [`CredentialFilter`](../interfaces/CredentialFilter) | Filters to select only desired credentials (i.e. credential type, credential issuer) |

## Returns

`Promise`\<[`CredentialsCollection`](../interfaces/CredentialsCollection)\[]>

* List CredentialsCollection that match the filters each containing a list of nfts

## Defined in

[presentation/getCredentialNfts.ts:18](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/presentation/getCredentialNfts.ts#L18)


# isCredentialType
Source: https://docs.crossmint.com/sdk-reference/credentials/functions/isCredentialType



> **isCredentialType**(`obj`): `obj is VerifiableCredentialType`

Checks if an object is of type `VerifiableCredential` or `EncryptedVerifiableCredential`.

## Parameters

| Parameter | Type | Description |
| - | - | - |
| `obj` | `any` | The object to check. |

## Returns

`obj is VerifiableCredentialType`

`true` if the object is of type `VerifiableCredential` or `EncryptedVerifiableCredential`, otherwise `false`.

## Defined in

[verifiableCredentialsSDK/types/utils.ts:35](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/utils.ts#L35)


# isEncryptedVerifiableCredential
Source: https://docs.crossmint.com/sdk-reference/credentials/functions/isEncryptedVerifiableCredential



> **isEncryptedVerifiableCredential**(`credential`): `credential is EncryptedVerifiableCredential`

Checks if an object is an `EncryptedVerifiableCredential`.

## Parameters

| Parameter | Type | Description |
| - | - | - |
| `credential` | [`VerifiableCredentialType`](../type-aliases/VerifiableCredentialType) | The credential object to check. |

## Returns

`credential is EncryptedVerifiableCredential`

`true` if the object is a valid `EncryptedVerifiableCredential`, otherwise `false`.

## Throws

Will throw an error if the object does not have a valid structure for a verifiable credential.

## Defined in

[verifiableCredentialsSDK/types/utils.ts:93](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/utils.ts#L93)


# isVcChain
Source: https://docs.crossmint.com/sdk-reference/credentials/functions/isVcChain



> **isVcChain**(`chain`): `chain is VCChain`

Checks if a string is a valid and supported chain for VCs.

## Parameters

| Parameter | Type | Description |
| - | - | - |
| `chain` | `string` | The chain string to check. |

## Returns

`chain is VCChain`

`true` if the string is a valid `VCChain`, otherwise `false`.

## Defined in

[verifiableCredentialsSDK/types/utils.ts:111](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/utils.ts#L111)


# isVerifiableCredential
Source: https://docs.crossmint.com/sdk-reference/credentials/functions/isVerifiableCredential



> **isVerifiableCredential**(`credential`): `credential is VerifiableCredential`

Checks if an object is a `VerifiableCredential`.

## Parameters

| Parameter | Type | Description |
| - | - | - |
| `credential` | [`VerifiableCredentialType`](../type-aliases/VerifiableCredentialType) | The credential object to check. |

## Returns

`credential is VerifiableCredential`

`true` if the object is a valid `VerifiableCredential`, otherwise `false`.

## Defined in

[verifiableCredentialsSDK/types/utils.ts:55](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/utils.ts#L55)


# verifyCredential
Source: https://docs.crossmint.com/sdk-reference/credentials/functions/verifyCredential



> **verifyCredential**(`credential`): `Promise`\<`object`>

Verify a Verifiable Credential

This function checks the validity of a given Verifiable Credential (VC) by performing several checks:

1. Ensures the `validUntil` date is a valid ISO string and not expired.
2. Verifies the cryptographic proof attached to the credential.
3. Checks if the associated NFT has been revoked (burned).

## Parameters

| Parameter | Type | Description |
| - | - | - |
| `credential` | [`VerifiableCredential`](../interfaces/VerifiableCredential) | the credential object to verify |

## Returns

`Promise`\<`object`>

* `error`: A string with the error message if the credential is invalid, or `undefined` if the credential is valid.
* `validVC`: A boolean indicating if the credential is valid.

### error

> **error**: `string` | `undefined`

### validVC

> **validVC**: `boolean`

## Throws

Will throw an error if `validUntil` is present and is not a valid ISO string or if the date is invalid.

## Defined in

[verifiableCredentialsSDK/verification/verify.ts:22](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/verification/verify.ts#L22)


# Collection
Source: https://docs.crossmint.com/sdk-reference/credentials/interfaces/Collection



Collection represents a generic collection of NFTs.

## Extended by

* [`CredentialsCollection`](./CredentialsCollection)

## Properties

### chain

> **chain**: [`VCChain`](../type-aliases/VCChain)

The blockchain chain on which the contract is deployed.

#### Defined in

[verifiableCredentialsSDK/types/collection.ts:21](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/collection.ts#L21)

***

### contractAddress

> **contractAddress**: `string`

Address of the contract associated with the collection.

#### Defined in

[verifiableCredentialsSDK/types/collection.ts:16](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/collection.ts#L16)

***

### metadata

> **metadata**: `any`

Metadata associated with the collection.

#### Defined in

[verifiableCredentialsSDK/types/collection.ts:26](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/collection.ts#L26)

***

### nfts

> **nfts**: [`VCNFT`](./VCNFT)\[]

List of NFTs within the collection.

#### Defined in

[verifiableCredentialsSDK/types/collection.ts:11](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/collection.ts#L11)


# CredentialFilter
Source: https://docs.crossmint.com/sdk-reference/credentials/interfaces/CredentialFilter



CredentialFilter defines the criteria for filtering credentials.

## Properties

### issuers?

> `optional` **issuers**: `string`\[]

List of issuers to filter by.

#### Example

```ts theme={null}
["did:polygon-amoy:0x1B887669437644aA348c518844660ef8d63bd643"];
```

#### Defined in

[verifiableCredentialsSDK/types/credentialFilter.ts:9](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/credentialFilter.ts#L9)

***

### types?

> `optional` **types**: `string`\[]

List of accepted credential types.

#### Example

```ts theme={null}
["driving_license", "crossmint:e62564a7-06eb-4f65-b389-eb3b7a4f6f98:userAge"];
```

#### Defined in

[verifiableCredentialsSDK/types/credentialFilter.ts:15](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/credentialFilter.ts#L15)


# CredentialMetadata
Source: https://docs.crossmint.com/sdk-reference/credentials/interfaces/CredentialMetadata



CredentialMetadata represents credentials-specific metadata inside the contract metadata.

## Properties

### credentialsEndpoint

> **credentialsEndpoint**: `string`

Endpoint to fetch the credentials.

#### Defined in

[verifiableCredentialsSDK/types/collection.ts:70](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/collection.ts#L70)

***

### encryption

> **encryption**: [`VerifiableCredentialEncryption`](./VerifiableCredentialEncryption)

Specifies the encryption type used for the credentials in the collection.

#### Defined in

[verifiableCredentialsSDK/types/collection.ts:65](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/collection.ts#L65)

***

### issuerDid

> **issuerDid**: `string`

The DID (Decentralized Identifier) of the issuer of the credentials for this collection.

#### Defined in

[verifiableCredentialsSDK/types/collection.ts:75](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/collection.ts#L75)

***

### type

> **type**: `string`\[]

Specifies the types of credentials in the collection.

#### Defined in

[verifiableCredentialsSDK/types/collection.ts:60](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/collection.ts#L60)


# CredentialsCollection
Source: https://docs.crossmint.com/sdk-reference/credentials/interfaces/CredentialsCollection



CredentialsCollection represents a collection of credential NFTs.

## Extends

* [`Collection`](./Collection)

## Properties

### chain

> **chain**: [`VCChain`](../type-aliases/VCChain)

The blockchain chain on which the contract is deployed.

#### Inherited from

[`Collection`](./Collection).[`chain`](./Collection#chain)

#### Defined in

[verifiableCredentialsSDK/types/collection.ts:21](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/collection.ts#L21)

***

### contractAddress

> **contractAddress**: `string`

Address of the contract associated with the collection.

#### Inherited from

[`Collection`](./Collection).[`contractAddress`](./Collection#contractaddress)

#### Defined in

[verifiableCredentialsSDK/types/collection.ts:16](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/collection.ts#L16)

***

### metadata

> **metadata**: `VCContractMetadata`

Metadata of the contract, including credential-specific metadata.

#### Overrides

[`Collection`](./Collection).[`metadata`](./Collection#metadata)

#### Defined in

[verifiableCredentialsSDK/types/collection.ts:40](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/collection.ts#L40)

***

### nfts

> **nfts**: [`VCNFT`](./VCNFT)\[]

List of NFTs within the collection.

#### Inherited from

[`Collection`](./Collection).[`nfts`](./Collection#nfts)

#### Defined in

[verifiableCredentialsSDK/types/collection.ts:11](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/collection.ts#L11)


# EncryptedVerifiableCredential
Source: https://docs.crossmint.com/sdk-reference/credentials/interfaces/EncryptedVerifiableCredential



## Properties

### id

> **id**: `string`

#### Defined in

[verifiableCredentialsSDK/types/verifiableCredential.ts:18](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/verifiableCredential.ts#L18)

***

### payload

> **payload**: `string`

#### Defined in

[verifiableCredentialsSDK/types/verifiableCredential.ts:19](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/verifiableCredential.ts#L19)


# VCNFT
Source: https://docs.crossmint.com/sdk-reference/credentials/interfaces/VCNFT



## Properties

### chain

> **chain**: [`VCChain`](../type-aliases/VCChain)

#### Defined in

[verifiableCredentialsSDK/types/nft.ts:4](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/nft.ts#L4)

***

### contractAddress

> **contractAddress**: `string`

#### Defined in

[verifiableCredentialsSDK/types/nft.ts:5](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/nft.ts#L5)

***

### tokenId

> **tokenId**: `string`

#### Defined in

[verifiableCredentialsSDK/types/nft.ts:6](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/nft.ts#L6)


# VerifiableCredential
Source: https://docs.crossmint.com/sdk-reference/credentials/interfaces/VerifiableCredential



## Properties

### @context

> **@context**: `string`\[]

#### Defined in

[verifiableCredentialsSDK/types/verifiableCredential.ts:13](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/verifiableCredential.ts#L13)

***

### credentialSubject

> **credentialSubject**: `any`

#### Defined in

[verifiableCredentialsSDK/types/verifiableCredential.ts:5](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/verifiableCredential.ts#L5)

***

### description?

> `optional` **description**: `string`

#### Defined in

[verifiableCredentialsSDK/types/verifiableCredential.ts:8](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/verifiableCredential.ts#L8)

***

### id

> **id**: `string`

#### Defined in

[verifiableCredentialsSDK/types/verifiableCredential.ts:4](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/verifiableCredential.ts#L4)

***

### issuer

> **issuer**: `object`

#### id

> **id**: `string`

#### Defined in

[verifiableCredentialsSDK/types/verifiableCredential.ts:10](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/verifiableCredential.ts#L10)

***

### name?

> `optional` **name**: `string`

#### Defined in

[verifiableCredentialsSDK/types/verifiableCredential.ts:7](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/verifiableCredential.ts#L7)

***

### nft

> **nft**: [`VCNFT`](./VCNFT)

#### Defined in

[verifiableCredentialsSDK/types/verifiableCredential.ts:9](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/verifiableCredential.ts#L9)

***

### proof?

> `optional` **proof**: `object`

#### Index Signature

\[`key`: `string`]: `any`

#### proofValue

> **proofValue**: `string`

#### Defined in

[verifiableCredentialsSDK/types/verifiableCredential.ts:14](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/verifiableCredential.ts#L14)

***

### type

> **type**: `string`\[]

#### Defined in

[verifiableCredentialsSDK/types/verifiableCredential.ts:11](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/verifiableCredential.ts#L11)

***

### validFrom

> **validFrom**: `string`

#### Defined in

[verifiableCredentialsSDK/types/verifiableCredential.ts:12](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/verifiableCredential.ts#L12)

***

### validUntil?

> `optional` **validUntil**: `string`

#### Defined in

[verifiableCredentialsSDK/types/verifiableCredential.ts:6](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/verifiableCredential.ts#L6)


# VerifiableCredentialEncryption
Source: https://docs.crossmint.com/sdk-reference/credentials/interfaces/VerifiableCredentialEncryption



VerifiableCredentialEncryption defines the encryption settings for verifiable credentials collection.

## Properties

### details?

> `optional` **details**: `LitEncryptionDetails`

Optional additional details about the encryption useful for decryption.

#### Defined in

[verifiableCredentialsSDK/types/collection.ts:90](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/collection.ts#L90)

***

### type

> **type**: [`VerifiableCredentialEncryptionType`](../enumerations/VerifiableCredentialEncryptionType)

Specifies the type of encryption used for the verifiable credentials.

#### Defined in

[verifiableCredentialsSDK/types/collection.ts:85](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/collection.ts#L85)


# Introduction
Source: https://docs.crossmint.com/sdk-reference/credentials/introduction



The Verifiable Credentials Client SDK is a powerful tool for managing verifiable credentials. It simplifies several key processes, making it easier to work with these credentials.

<Note> NOTE: The SDK can be used also server-side.</Note>

You can download the SDK from [here](https://www.npmjs.com/package/@crossmint/client-sdk-verifiable-credentials).

The SDK assists with the following processes:

* **Verification**: The SDK provides a straightforward method to verify any given credential.

* **Presentation**: By inputting a user's wallet address, the SDK allows you to retrieve all credentials issued to that address. It also provides a filtering option for easy navigation through the credentials.

* **Decryption**: In case of encrypted credentials, the SDK enables you to decrypt a credential for a specific user interacting with the lit protocol.

Generate a client-side-api-key from the Crossmint console: Go to the `Developers -> API Keys` tab, click on `New API Key` in the `Client-side keys` section, and select the scopes `credentials.read` and `credentials.decrypt`.

```typescript theme={null}
import { CrossmintAPI } from "@crossmint/verifiable-credentials";

CrossmintAPI.init("<api_key>");
```

## SDK Reference Table of Contents

### Classes

* [ContractMetadataService](./classes/ContractMetadataService)
* [CredentialService](./classes/CredentialService)
* [CrossmintDecrypt](./classes/CrossmintDecrypt)
* [CrossmintMetamaskDecrypt](./classes/CrossmintMetamaskDecrypt)
* [Lit](./classes/Lit)
* [WalletAuthService](./classes/WalletAuthService)

### Interfaces

* [Collection](./interfaces/Collection)
* [CredentialFilter](./interfaces/CredentialFilter)
* [CredentialMetadata](./interfaces/CredentialMetadata)
* [CredentialsCollection](./interfaces/CredentialsCollection)
* [EncryptedVerifiableCredential](./interfaces/EncryptedVerifiableCredential)
* [VCNFT](./interfaces/VCNFT)
* [VerifiableCredential](./interfaces/VerifiableCredential)
* [VerifiableCredentialEncryption](./interfaces/VerifiableCredentialEncryption)

### Type Aliases

* [ChainRPCConfig](./type-aliases/ChainRPCConfig)
* [VCChain](./type-aliases/VCChain)
* [VerifiableCredentialType](./type-aliases/VerifiableCredentialType)

### Variables

* [VCChain](./variables/VCChain)
* [crossmintAPI](./variables/crossmintAPI)
* [crossmintRetrievalProcedure](./variables/crossmintRetrievalProcedure)
* [ipfsRetrievalProcedure](./variables/ipfsRetrievalProcedure)

### Functions

* [getCredentialNFTFromLocator](./functions/getCredentialNFTFromLocator)
* [getCredentialNfts](./functions/getCredentialNfts)
* [isCredentialType](./functions/isCredentialType)
* [isEncryptedVerifiableCredential](./functions/isEncryptedVerifiableCredential)
* [isVcChain](./functions/isVcChain)
* [isVerifiableCredential](./functions/isVerifiableCredential)
* [verifyCredential](./functions/verifyCredential)

### Enumerations

* [VerifiableCredentialEncryptionType](./enumerations/VerifiableCredentialEncryptionType)


# ChainRPCConfig
Source: https://docs.crossmint.com/sdk-reference/credentials/type-aliases/ChainRPCConfig



> **ChainRPCConfig**: `Record`\<[`VCChain`](./VCChain), `string`>

ChainRPCConfig is a mapping of blockchain chains to their respective RPC endpoints.

## Example

```ts theme={null}
const config: ChainRPCConfig = {
    polygon: "https://polygon.llamarpc.com/",
};
```

## Defined in

[verifiableCredentialsSDK/types/chain.ts:17](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/chain.ts#L17)


# VCChain
Source: https://docs.crossmint.com/sdk-reference/credentials/type-aliases/VCChain



> **VCChain**: *typeof* [`VCChain`](../variables/VCChain)\[keyof *typeof* [`VCChain`](../variables/VCChain)]

## Defined in

[verifiableCredentialsSDK/types/chain.ts:1](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/chain.ts#L1)


# VerifiableCredentialType
Source: https://docs.crossmint.com/sdk-reference/credentials/type-aliases/VerifiableCredentialType



> **VerifiableCredentialType**: [`VerifiableCredential`](../interfaces/VerifiableCredential) | [`EncryptedVerifiableCredential`](../interfaces/EncryptedVerifiableCredential)

VerifiableCredentialType
A wrapper type for VerifiableCredential and EncryptedVerifiableCredential

## Defined in

[verifiableCredentialsSDK/types/verifiableCredential.ts:26](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/verifiableCredential.ts#L26)


# VCChain
Source: https://docs.crossmint.com/sdk-reference/credentials/variables/VCChain



> `const` **VCChain**: `object`

## Type declaration

### POLYGON

> `readonly` **POLYGON**: `"polygon"` = `"polygon"`

### POLYGON\_AMOY

> `readonly` **POLYGON\_AMOY**: `"polygon-amoy"` = `"polygon-amoy"`

### POLY\_AMOY

> `readonly` **POLY\_AMOY**: `"poly-amoy"` = `"poly-amoy"`

## Defined in

[verifiableCredentialsSDK/types/chain.ts:1](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/types/chain.ts#L1)


# crossmintAPI
Source: https://docs.crossmint.com/sdk-reference/credentials/variables/crossmintAPI



> `const` **crossmintAPI**: `CrossmintAPI`

Crossmint API singleton, used to init the SDK
To use the SDK you must call `init` before any other method

## Example

```typescript theme={null}
crossmintAPI.init(
 "your-api-key",
 config: \{
   environment: "staging",
   ipfsGateways: ["https://ipfs.io"], // Optional, a list of defualt ones is provided
   ipfsTimeout: 5000, // ms, Optional, default is 10 seconds
   blockchainRpcs: \{...\} // Optional, default rpcs for polygon are provided
 \}
)

## Defined in

[crossmintAPI.ts:124](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/crossmintAPI.ts#L124)
```


# crossmintRetrievalProcedure
Source: https://docs.crossmint.com/sdk-reference/credentials/variables/crossmintRetrievalProcedure



> `const` **crossmintRetrievalProcedure**: `CredentialRetrievalProcedure`

Crossmint retrieval procedure for credentials stored in Crossmint.

This procedure uses the Crossmint API to fetch credentials and matches all credentials that are stored in Crossmint.

## Remarks

This procedure requires a Crossmint API key with the `credentials.read` scope.

## Defined in

[presentation/getCredential.ts:83](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/presentation/getCredential.ts#L83)


# ipfsRetrievalProcedure
Source: https://docs.crossmint.com/sdk-reference/credentials/variables/ipfsRetrievalProcedure



> `const` **ipfsRetrievalProcedure**: `CredentialRetrievalProcedure`

Default retrieval procedure for ipfs, can be overridden by the user.
Will match all credentials with a retrieval endpoint starting with ipfs\://
Will use the ipfs gataways provided in SDK init to fetch the credential

## Defined in

[verifiableCredentialsSDK/presentation/getCredential.ts:34](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/client/verifiable-credentials/src/verifiableCredentialsSDK/presentation/getCredential.ts#L34)


# ChainExplorerRegistry
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/chain-explorer-registry

Flutter Abstract Final Class

**Abstract Final Class**

Best-effort explorer-link construction for transactions whose backend response omits an `explorerLink` field.

```dart theme={null}
abstract final class ChainExplorerRegistry
```

Kept separate from `CrossmintRuntimeWalletBase` so adding a new chain is
a one-file change and the 18 URL rows do not bloat the wallet base.

## Static Methods

### explorerLinkForTransaction

```dart theme={null}
static String? explorerLinkForTransaction({
  required String chain,
  required String hash,
})
```

Builds a `https://<explorer>/tx/<hash>` URL for the given chain + hash, or `null` when either the chain is not registered or the hash is empty.

### transactionHashFromRaw

```dart theme={null}
static String transactionHashFromRaw(CrossmintJsonMap raw)
```

Extracts a transaction hash from a wallet transaction's raw envelope.


# CrossmintApiConfig
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-api-config

Flutter Class

**Class**

Base configuration shared by every Crossmint SDK client.

```dart theme={null}
class CrossmintApiConfig
```

Platform-specific subclasses (e.g. `CrossmintClientConfig` in
`crossmint_flutter`) extend this class with platform-only fields such as
storage adapters or loggers.

## Constructors

### CrossmintApiConfig

```dart theme={null}
const CrossmintApiConfig({
  required this.apiKey,
  this.appId,
  this.appScheme,
  this.origin,
  this.overrideBaseUrl,
  this.extensionId,
})
```

Creates a `CrossmintApiConfig`.

## Properties

### apiKey

```dart theme={null}
final String apiKey
```

Crossmint API key.

### appId

```dart theme={null}
final String? appId
```

Application identifier registered with Crossmint — usually matches the mobile bundle ID (iOS) or package name (Android). If omitted, the SDK auto-resolves it from platform metadata during `initialize()`.

### appScheme

```dart theme={null}
final String? appScheme
```

Deep-link scheme the Crossmint auth page redirects back to after sign-in. Typically equals `appId` on mobile. Required for OAuth flows.

### origin

```dart theme={null}
final String? origin
```

Origin header sent with requests when using a client key. Required on web; optional on mobile (the SDK derives it from `appId` when omitted).

### overrideBaseUrl

```dart theme={null}
final Uri? overrideBaseUrl
```

Overrides the default Crossmint API base URL — used for local development or pointing at a custom-hosted environment.

### extensionId

```dart theme={null}
final String? extensionId
```

Browser-extension identifier used by extension-embedded flows.


# CrossmintApiKeySigner
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-api-key-signer

Flutter Final Class

**Final Class**

A signer that delegates all signing to the Crossmint backend via API key authentication.

```dart theme={null}
final class CrossmintApiKeySigner implements CrossmintWalletApprovalSigner
```

This signer never performs local signing.  When a wallet uses an API key
signer, the Crossmint backend automatically approves transactions and
signatures on behalf of the user.

Calling `signMessage` or `signTransaction` directly will throw; signing
is handled server-side during the transaction/signature creation API call.

## Constructors

### CrossmintApiKeySigner

```dart theme={null}
const CrossmintApiKeySigner({String? locator})
```

Creates an API key signer.

## Properties

### type

```dart theme={null}
String get type
```

### locator

```dart theme={null}
final String locator
```

## Methods

### signMessage

```dart theme={null}
Future<Object> signMessage(String message)
```

Always throws — API key signers do not support local message signing.

### signTransaction

```dart theme={null}
Future<Object> signTransaction(String transaction)
```

Always throws — API key signers do not support local transaction signing.


# CrossmintApiVersions
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-api-versions

Flutter Abstract Final Class

**Abstract Final Class**

Centralised API version path prefixes used by every Crossmint service.

```dart theme={null}
abstract final class CrossmintApiVersions
```

Each constant maps to a specific backend contract. Keeping them here means
rolling an API version is a one-line change and grep is enough to audit
which endpoints would be affected.

## Static Properties

### users

```dart theme={null}
static const String users
```

Users API (`/users`).

### wallets

```dart theme={null}
static const String wallets
```

Wallets API — mainstream endpoints (wallets, signers, signatures, transactions).

### walletsAlpha

```dart theme={null}
static const String walletsAlpha
```

Wallets API — alpha endpoints (balance-only token queries).

### walletsLegacy

```dart theme={null}
static const String walletsLegacy
```

Wallets API — legacy endpoints (NFT enumeration).

### walletsUnstable

```dart theme={null}
static const String walletsUnstable
```

Wallets API — unstable endpoints (transfer history).

### orders

```dart theme={null}
static const String orders
```

Orders API (checkout).

### ordersUnstable

```dart theme={null}
static const String ordersUnstable
```

Orders API — unstable WebSocket endpoints.

### tokens

```dart theme={null}
static const String tokens
```

Tokens metadata API.

### credentials

```dart theme={null}
static const String credentials
```

Verifiable credentials API.


# CrossmintAuthClient
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-auth-client

Flutter Abstract Interface Class

**Abstract Interface Class**

Authentication sub-client — email OTP, OAuth, wallet sign-in, and session lifecycle. Exposed on `CrossmintClient.auth`.

```dart theme={null}
abstract interface class CrossmintAuthClient
```

Observable via `state` (immediate), `stateListenable` (Flutter
`ValueListenable`), or `states` (`Stream`). Call `restoreSession` on
app startup (once `CrossmintClient.initialize` has completed) so any
persisted JWT can hydrate before the first frame.

## Properties

### state

```dart theme={null}
CrossmintAuthState get state
```

The current auth state snapshot.

### stateListenable

```dart theme={null}
ValueListenable<CrossmintAuthState> get stateListenable
```

Reactive handle on `state` — suitable for `ValueListenableBuilder`.

### states

```dart theme={null}
Stream<CrossmintAuthState> get states
```

Stream of auth-state changes. Emits on every state mutation.

## Methods

### restoreSession

```dart theme={null}
Future<void> restoreSession()
```

Reads any persisted session from `CrossmintAuthStorage` and applies it to the client. Safe to call once per app launch — prefer using the result of `CrossmintClient.initialize` which calls this internally.

### loginWithOAuth

```dart theme={null}
Future<void> loginWithOAuth(CrossmintOAuthProvider provider)
```

Opens the Crossmint-hosted OAuth flow for `provider` (Google, Twitter, etc.). The response comes back through `CrossmintAuthCallbackRouter` — make sure it is started before calling this.

### sendEmailOtp

```dart theme={null}
Future<CrossmintEmailOtpChallenge> sendEmailOtp(String email)
```

Requests the Crossmint API to send an email OTP to `email`. Returns a challenge that `confirmEmailOtp` completes.

### confirmEmailOtp

```dart theme={null}
Future<bool> confirmEmailOtp({
  required String email,
  required String emailId,
  required String token,
})
```

Submits an email OTP challenge — pass the `emailId` from the challenge and the `token` the user entered. Returns `true` on success.

### completeOAuth

```dart theme={null}
Future<bool> completeOAuth(Uri callbackUri)
```

Completes an OAuth flow from a deep-link callback URI. Normally invoked by `CrossmintAuthCallbackRouter`; call directly only for custom routing.

### completeOAuthWithOneTimeSecret

```dart theme={null}
Future<bool> completeOAuthWithOneTimeSecret(String oneTimeSecret)
```

Completes an OAuth flow from a one-time secret (SSR / server-mediated callbacks). Returns `true` on success.

### signInWithWallet

```dart theme={null}
Future<CrossmintWalletAuthChallenge> signInWithWallet(
  String address,
  String type,
)
```

Starts wallet-based authentication. Returns a challenge that the wallet must sign. `type` is `'evm'` or `'solana'`.

### authenticateWallet

```dart theme={null}
Future<bool> authenticateWallet(
  String address,
  String type,
  String signature,
)
```

Completes wallet-based authentication with the signed challenge.

### getSession

```dart theme={null}
Future<CrossmintAuthSession?> getSession()
```

Returns the current session (JWT + metadata), or `null` if not signed in. Does not hit the network — reads from in-memory state.

### getUser

```dart theme={null}
Future<CrossmintAuthenticatedUser?> getUser({bool forceRefresh = false})
```

Returns the authenticated user's profile. Caches the result; pass `forceRefresh: true` to bypass the cache and refetch.

### logout

```dart theme={null}
Future<void> logout()
```

Signs the user out — clears persisted storage, cached session/user, and POSTs to the Crossmint (or custom) logout endpoint.

### setJwt

```dart theme={null}
Future<void> setJwt(String? jwt)
```

Sets a custom JWT for "Bring Your Own Auth" (BYOA) flows.


# CrossmintAuthException
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-auth-exception

Flutter Final Class

**Final Class**

Thrown by authentication flows — OTP failures, OAuth callback errors, session restore issues, JWT expiry, logout failures.

```dart theme={null}
final class CrossmintAuthException extends CrossmintException
```

## Constructors

### CrossmintAuthException

```dart theme={null}
const CrossmintAuthException(
  super.message, {
  super.code = CrossmintErrorCode.unknown,
  super.cause,
})
```

Creates an auth exception.


# CrossmintAuthRejectedException
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-auth-rejected-exception

Flutter Final Class

**Final Class**

Thrown when the user cancels an OTP challenge (via `CrossmintWalletOtpController.reject` or equivalent).

```dart theme={null}
final class CrossmintAuthRejectedException extends CrossmintException
```

## Constructors

### CrossmintAuthRejectedException

```dart theme={null}
const CrossmintAuthRejectedException()
```

Creates the rejection exception. Always carries `CrossmintErrorCode.authRejected`.


# CrossmintAuthScope
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-auth-scope

Flutter Final Class

**Final Class**

Provides `CrossmintAuthClient` to descendant widgets, matching the official Crossmint RN SDK's `CrossmintAuthProvider` pattern.

```dart theme={null}
final class CrossmintAuthScope extends InheritedWidget
```

```dart theme={null}
CrossmintAuthScope(
  auth: client.auth,
  child: MyApp(),
)

// In any descendant:
final auth = CrossmintAuthScope.of(context);
```

## Constructors

### CrossmintAuthScope

```dart theme={null}
const CrossmintAuthScope({
  super.key,
  required this.auth,
  required super.child,
})
```

## Properties

### auth

```dart theme={null}
final CrossmintAuthClient auth
```

## Static Methods

### of

```dart theme={null}
static CrossmintAuthClient of(BuildContext context)
```

### maybeOf

```dart theme={null}
static CrossmintAuthClient? maybeOf(BuildContext context)
```

## Methods

### updateShouldNotify

```dart theme={null}
bool updateShouldNotify(CrossmintAuthScope oldWidget)
```


# CrossmintClient
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-client

Flutter Final Class

**Final Class**

Top-level facade for the Crossmint SDK.

```dart theme={null}
final class CrossmintClient
```

`CrossmintClient` owns every sub-client (`auth`, `wallets`, `credentials`,
`orders`, `tokens`, `users`), the shared transport, the auth session store,
and the hidden WebView signer bridge. All sub-clients share a closure that
reads the live JWT from `auth`, so token refresh works without rebuilding
the dependency graph.

## Lifecycle

1. Construct the client with a `CrossmintClientConfig`.
2. `await client.initialize()` — validates config and auto-resolves the app
   ID from platform metadata if not supplied.
3. `await client.auth.restoreSession()` — restores any persisted JWT.
4. Use sub-clients or factory helpers (`createWalletController`,
   `createEvmWallet`, etc.) for the rest of your session.
5. `await client.dispose()` when tearing down — shuts down the signer
   bridges and releases the auth client.

## Typical bootstrap

```dart theme={null}
final client = CrossmintClient(
  config: const CrossmintClientConfig(
    apiKey: 'YOUR_STAGING_API_KEY',
    appScheme: 'com.your.app',
  ),
);
await client.initialize();
await client.auth.restoreSession();

final walletController = client.createWalletController(
  const CrossmintWalletControllerConfig(showOtpSignerPrompt: true),
);
```

Named constructor parameters on the factory (`auth`, `wallets`, `transport`,
`runtimeOverrides`, etc.) are injection points primarily used by tests and
advanced integrations. Leave them null in production to get the default
HTTP transport, secure-storage-backed auth, and platform-resolved app ID.

## Constructors

### CrossmintClient

```dart theme={null}
factory CrossmintClient({
  required CrossmintClientConfig config,
  CrossmintAuthClient? auth,
  CrossmintWalletsClient? wallets,
  CrossmintCredentialsClient? credentials,
  CrossmintOrdersClient? orders,
  CrossmintTokensClient? tokens,
  CrossmintUsersClient? users,
  CrossmintTransport? transport,
  CrossmintAuthLauncher? authLauncher,
  CrossmintClientRuntimeOverrides? runtimeOverrides,
})
```

Creates a `CrossmintClient`.

## Properties

### config

```dart theme={null}
final CrossmintClientConfig config
```

The configuration this client was built with.

### auth

```dart theme={null}
final CrossmintAuthClient auth
```

Authentication sub-client — email OTP, OAuth, wallet sign-in, session persistence, JWT refresh.

### wallets

```dart theme={null}
final CrossmintWalletsClient wallets
```

Wallet sub-client — create, list, and read Crossmint-hosted wallets (EVM, Solana, Stellar) and their signers.

### credentials

```dart theme={null}
final CrossmintCredentialsClient credentials
```

Verifiable credentials sub-client — issue, query, and verify credentials.

### orders

```dart theme={null}
final CrossmintOrdersClient orders
```

Orders sub-client — checkout orders and mint/purchase flows.

### tokens

```dart theme={null}
final CrossmintTokensClient tokens
```

Tokens sub-client — metadata and balances for tokens held by wallets.

### users

```dart theme={null}
final CrossmintUsersClient users
```

Users sub-client — user profile lookups and updates.

### appId

```dart theme={null}
String? get appId
```

The effective app ID — explicit `CrossmintClientConfig.appId` if set, otherwise the value auto-resolved from platform metadata during `initialize`. May be `null` until `initialize` has completed.

### isInitialized

```dart theme={null}
bool get isInitialized
```

Whether `initialize` has completed successfully.

### isDisposed

```dart theme={null}
bool get isDisposed
```

Whether `dispose` has been called. Once disposed, the client cannot be reused — construct a new one.

### hiddenSignerBridgeController

```dart theme={null}
HiddenSignerBridgeRuntimeController get hiddenSignerBridgeController
```

The shared hidden signer bridge controller, lazily constructed on first access. Powers non-custodial email/phone signing inside a hidden WebView.

### authStorage

```dart theme={null}
CrossmintAuthStorage get authStorage
```

The auth storage adapter resolved during construction — either the one passed via `CrossmintClientConfig.authStorage` or the default `flutter_secure_storage`-backed implementation.

### transport

```dart theme={null}
CrossmintTransport get transport
```

The HTTP transport resolved during construction. Shared by every sub-client; injects the live JWT via a closure so token refresh works without rebuilding dependencies.

## Methods

### createWalletController

```dart theme={null}
CrossmintWalletController createWalletController(
  CrossmintWalletControllerConfig config,
)
```

Creates a `CrossmintWalletController` bound to this client.

### createHiddenSignerBridge

```dart theme={null}
HiddenSignerBridgeRuntimeController createHiddenSignerBridge({
  HiddenSignerBridgeConfig? config,
})
```

Builds a new `HiddenSignerBridgeRuntimeController` instance — used internally by `hiddenSignerBridgeController`. Override the bridge `config` to point at a custom signer URL (e.g. for testing).

### createExportSignerBridge

```dart theme={null}
CrossmintExportSignerBridgeRuntimeController createExportSignerBridge({
  HiddenSignerBridgeConfig? config,
})
```

Builds a new `CrossmintExportSignerBridgeRuntimeController` instance. Used internally by `exportSignerBridgeController`.

### createEvmNonCustodialSigner

```dart theme={null}
CrossmintEvmNonCustodialSigner createEvmNonCustodialSigner({
  required HiddenSignerBridge bridge,
  required String signerType,
  required String signerLocator,
  String? address,
  CrossmintSignerAuthRequiredCallback? onAuthRequired,
})
```

Builds a non-custodial EVM signer bound to an existing `HiddenSignerBridge`. Produces secp256k1 signatures inside the WebView without exposing keys to Dart.

### createSolanaNonCustodialSigner

```dart theme={null}
CrossmintSolanaNonCustodialSigner createSolanaNonCustodialSigner({
  required HiddenSignerBridge bridge,
  required String signerType,
  required String signerLocator,
  String? address,
  CrossmintSignerAuthRequiredCallback? onAuthRequired,
})
```

Builds a non-custodial Solana signer bound to an existing `HiddenSignerBridge`. Produces ed25519 signatures inside the WebView.

### createStellarNonCustodialSigner

```dart theme={null}
CrossmintStellarNonCustodialSigner createStellarNonCustodialSigner({
  required HiddenSignerBridge bridge,
  required String signerType,
  required String signerLocator,
  String? address,
  CrossmintSignerAuthRequiredCallback? onAuthRequired,
})
```

Builds a non-custodial Stellar signer bound to an existing `HiddenSignerBridge`. Produces ed25519 signatures inside the WebView.

### createEvmWallet

```dart theme={null}
CrossmintEvmWallet createEvmWallet({
  required CrossmintWallet wallet,
  CrossmintSignerConfig? recoverySigner,
  CrossmintWalletApprovalSigner? signer,
  List<CrossmintWalletApprovalSigner> additionalSigners =
      const <CrossmintWalletApprovalSigner>[],
  DeviceSignerKeyStorage? deviceSignerKeyStorage,
  CrossmintSignerAuthRequiredCallback? onAuthRequired,
})
```

Wraps a server-issued `CrossmintWallet` in a runtime `CrossmintEvmWallet`.

### createSolanaWallet

```dart theme={null}
CrossmintSolanaWallet createSolanaWallet({
  required CrossmintWallet wallet,
  CrossmintSignerConfig? recoverySigner,
  CrossmintWalletApprovalSigner? signer,
  List<CrossmintWalletApprovalSigner> additionalSigners =
      const <CrossmintWalletApprovalSigner>[],
  DeviceSignerKeyStorage? deviceSignerKeyStorage,
  CrossmintSignerAuthRequiredCallback? onAuthRequired,
})
```

Wraps a server-issued `CrossmintWallet` in a runtime `CrossmintSolanaWallet`.

### createStellarWallet

```dart theme={null}
CrossmintStellarWallet createStellarWallet({
  required CrossmintWallet wallet,
  CrossmintSignerConfig? recoverySigner,
  CrossmintWalletApprovalSigner? signer,
  List<CrossmintWalletApprovalSigner> additionalSigners =
      const <CrossmintWalletApprovalSigner>[],
  DeviceSignerKeyStorage? deviceSignerKeyStorage,
  CrossmintSignerAuthRequiredCallback? onAuthRequired,
})
```

Wraps a server-issued `CrossmintWallet` in a runtime `CrossmintStellarWallet`.

### createDeviceWalletSigner

```dart theme={null}
CrossmintDeviceWalletSigner createDeviceWalletSigner({
  required String signerLocator,
  required String address,
  DeviceSignerKeyStorage? storage,
})
```

Builds a hardware-backed device signer for an existing server signer.

### createEvmExternalWalletSigner

```dart theme={null}
CrossmintEvmExternalWalletSigner createEvmExternalWalletSigner({
  required String address,
  String? signerLocator,
  required CrossmintExternalWalletSignCallback onSign,
})
```

Builds an external-wallet EVM signer that delegates to a user-supplied `CrossmintExternalWalletSignCallback`. Use for wallets owned by the user (e.g. MetaMask, Rainbow) where the SDK only needs to request signatures.

### createSolanaExternalWalletSigner

```dart theme={null}
CrossmintSolanaExternalWalletSigner createSolanaExternalWalletSigner({
  required String address,
  String? signerLocator,
  required CrossmintExternalWalletSignCallback onSign,
})
```

Builds an external-wallet Solana signer that delegates to a user-supplied `CrossmintExternalWalletSignCallback`.

### createStellarExternalWalletSigner

```dart theme={null}
CrossmintStellarExternalWalletSigner createStellarExternalWalletSigner({
  required String address,
  String? signerLocator,
  required CrossmintExternalWalletSignCallback onSign,
})
```

Builds an external-wallet Stellar signer that delegates to a user-supplied `CrossmintExternalWalletSignCallback`.

### createPasskeyApprovalSigner

```dart theme={null}
CrossmintPasskeyApprovalSigner createPasskeyApprovalSigner({
  required String credentialId,
  required String signerLocator,
  required Future<CrossmintPasskeySignResult> Function(String message) onSign,
})
```

Builds a passkey approval signer. The caller provides `onSign` — a callback that performs the WebAuthn / platform-native passkey assertion and returns a `CrossmintPasskeySignResult`. Native platform passkey support is pending (Stage 2); today every passkey signer requires an explicit callback or `CrossmintSignerException(code: passkeyCallbackMissing)` is thrown during signing.

### dispose

```dart theme={null}
Future<void> dispose()
```

Releases the signer bridges and auth client, then marks the client as disposed. Safe to call multiple times. After disposal, construct a new `CrossmintClient` rather than reusing this one.

### initialize

```dart theme={null}
Future<void> initialize()
```

Validates configuration and prepares the client for use.


# CrossmintClientConfig
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-client-config

Flutter Final Class

**Final Class**

Configuration for `CrossmintClient`.

```dart theme={null}
final class CrossmintClientConfig extends CrossmintApiConfig
```

Extends `CrossmintApiConfig` (the shared base shape used across all
Crossmint SDK platforms) with the Flutter-specific plug-points
`authStorage`, `logger`, `refreshRoute`, and `logoutRoute`.

```dart theme={null}
const config = CrossmintClientConfig(
  apiKey: 'YOUR_STAGING_API_KEY',
  appScheme: 'com.your.app',
);
```

Use a **client key** (`ck_*`) for frontend apps — they require `origin`
for auth. Use a **server key** (`sk_*`) only in server contexts; it needs
no origin.

## Constructors

### CrossmintClientConfig

```dart theme={null}
const CrossmintClientConfig({
  required super.apiKey,
  super.appId,
  super.appScheme,
  super.origin,
  super.overrideBaseUrl,
  super.extensionId,
  this.authStorage,
  this.logger,
  this.refreshRoute,
  this.logoutRoute,
})
```

Creates a `CrossmintClientConfig`.

## Properties

### authStorage

```dart theme={null}
final CrossmintAuthStorage? authStorage
```

Custom session / token store. When null, the SDK uses `FlutterSecureStorage` under the hood.

### logger

```dart theme={null}
final CrossmintLogger? logger
```

Custom logger sink. When null, the SDK uses a no-op logger in release and a `debugPrint`-backed logger in debug.

### refreshRoute

```dart theme={null}
final Uri? refreshRoute
```

Optional custom server endpoint for token refresh.

### logoutRoute

```dart theme={null}
final Uri? logoutRoute
```

Optional custom server endpoint for logout.


# CrossmintConfigurationException
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-configuration-exception

Flutter Final Class

**Final Class**

Thrown when the client is configured incorrectly — missing API key, invalid base URL, incompatible runtime overrides, etc.

```dart theme={null}
final class CrossmintConfigurationException extends CrossmintException
```

## Constructors

### CrossmintConfigurationException

```dart theme={null}
const CrossmintConfigurationException(
  super.message, {
  super.code = CrossmintErrorCode.unknown,
  super.cause,
})
```

Creates a configuration exception.


# CrossmintCredentialsException
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-credentials-exception

Flutter Final Class

**Final Class**

Thrown by verifiable-credentials operations — malformed credential documents, verification failures, locator resolution errors.

```dart theme={null}
final class CrossmintCredentialsException extends CrossmintException
```

## Constructors

### CrossmintCredentialsException

```dart theme={null}
const CrossmintCredentialsException(
  super.message, {
  super.code = CrossmintErrorCode.unknown,
  super.cause,
})
```

Creates a credentials exception.


# CrossmintDeserializationException
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-deserialization-exception

Flutter Final Class

**Final Class**

Thrown when a JSON payload from the Crossmint API is missing a required field, contains the wrong type for a field, or otherwise cannot be parsed into a typed model. Carries the `entity` being parsed and the offending `field` so consumer code can react programmatically instead of pattern matching on the message string.

```dart theme={null}
final class CrossmintDeserializationException extends CrossmintException
```

## Constructors

### CrossmintDeserializationException

```dart theme={null}
const CrossmintDeserializationException(
  super.message, {
  this.entity,
  this.field,
  super.cause,
})
```

Creates a deserialization exception. Always carries `CrossmintErrorCode.deserializationError`.

## Properties

### entity

```dart theme={null}
final String? entity
```

The name of the model type being parsed (e.g. `"CrossmintWallet"`).

### field

```dart theme={null}
final String? field
```

The name of the field that failed to parse.


# CrossmintDeviceWalletSigner
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-device-wallet-signer

Flutter Final Class

**Final Class**

Hardware-backed approval signer — keys live in Secure Enclave (iOS) or Android Keystore, never in Dart memory.

```dart theme={null}
final class CrossmintDeviceWalletSigner implements CrossmintWalletApprovalSigner
```

Device signers are the SDK's default **delegated** signer: low-friction,
used for day-to-day transaction approvals. They are supported on EVM and
Stellar wallets. On Solana, device signer support depends on the wallet
type and is validated server-side.

The `locator` must follow the `device:<publicKeyBase64>` format. Use
`CrossmintWalletsClient.createDeviceSigner` to register a new device
signer and get a valid locator.

## Constructors

### CrossmintDeviceWalletSigner

```dart theme={null}
CrossmintDeviceWalletSigner({
  required this.address,
  required this.locator,
  DeviceSignerKeyStorage? storage,
})
```

Creates a device wallet signer bound to an existing hardware key.

## Properties

### address

```dart theme={null}
final String address
```

The wallet address associated with this signer.

### locator

```dart theme={null}
final String locator
```

### type

```dart theme={null}
String get type
```

### storage

```dart theme={null}
DeviceSignerKeyStorage get storage
```

The key-storage adapter. Defaults to the platform-native Secure Enclave / Android Keystore implementation when not overridden.

### publicKeyBase64

```dart theme={null}
String get publicKeyBase64
```

The base64-encoded public key parsed from `locator`.

## Methods

### signMessage

```dart theme={null}
Future<Object> signMessage(String message)
```

### signTransaction

```dart theme={null}
Future<Object> signTransaction(String transaction)
```

### getMappedKey

```dart theme={null}
Future<String?> getMappedKey()
```

### hasLocalKey

```dart theme={null}
Future<bool> hasLocalKey()
```

### mapCurrentKeyToAddress

```dart theme={null}
Future<void> mapCurrentKeyToAddress()
```


# CrossmintEmailOtpDialog
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-email-otp-dialog

Flutter Class

**Class**

Email OTP signer dialog matching the official Crossmint RN SDK `EmailSignersDialog` component.

```dart theme={null}
class CrossmintEmailOtpDialog extends StatefulWidget
```

## Constructors

### CrossmintEmailOtpDialog

```dart theme={null}
const CrossmintEmailOtpDialog({
  super.key,
  required this.otpController,
  this.onDismissed,
})
```

## Properties

### otpController

```dart theme={null}
final CrossmintWalletOtpController otpController
```

### onDismissed

```dart theme={null}
final VoidCallback? onDismissed
```

## Methods

### createState

```dart theme={null}
State<CrossmintEmailOtpDialog> createState()
```


# CrossmintEvmExternalWalletSigner
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-evm-external-wallet-signer

Flutter Final Class

**Final Class**

EVM variant of `CrossmintExternalWalletSigner`. Signs both arbitrary messages (via the EIP-191 personal-message path the SDK assembles) and raw transaction payloads.

```dart theme={null}
final class CrossmintEvmExternalWalletSigner extends CrossmintExternalWalletSigner
```

## Constructors

### CrossmintEvmExternalWalletSigner

```dart theme={null}
CrossmintEvmExternalWalletSigner({
  required super.address,
  super.locator,
  required super.onSign,
})
```

Creates an EVM external-wallet signer.

## Properties

### type

```dart theme={null}
String get type
```

## Methods

### signMessage

```dart theme={null}
Future<Object> signMessage(String message)
```

### signTransaction

```dart theme={null}
Future<Object> signTransaction(String transaction)
```


# CrossmintEvmNonCustodialSigner
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-evm-non-custodial-signer

Flutter Final Class

**Final Class**

EVM variant of `CrossmintNonCustodialSigner`. Signs with secp256k1 keys using hex encoding. Applies the EIP-191 personal-message prefix when signing arbitrary strings.

```dart theme={null}
final class CrossmintEvmNonCustodialSigner extends CrossmintNonCustodialSigner
```

## Constructors

### CrossmintEvmNonCustodialSigner

```dart theme={null}
CrossmintEvmNonCustodialSigner({
  required super.client,
  required super.bridge,
  required super.type,
  required super.locator,
  super.address,
  super.onAuthRequired,
  super.bridgeClient,
})
```

Creates an EVM non-custodial signer.

## Methods

### signMessage

```dart theme={null}
Future<String> signMessage(String message)
```

### signTransaction

```dart theme={null}
Future<String> signTransaction(String transaction)
```


# CrossmintEvmWallet
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-evm-wallet

Flutter Final Class

**Final Class**

Runtime wallet for EVM chains (Base, Ethereum, Polygon, Optimism, etc.).

```dart theme={null}
final class CrossmintEvmWallet extends CrossmintRuntimeWalletBase
```

Adds EVM-specific entry points on top of `CrossmintRuntimeWalletBase`:
create + sign transactions, sign arbitrary messages, and sign EIP-712
typed data. Every entry point calls `preAuthIfNeeded()` first, so
recovery flows and pending device-signer registrations are handled
automatically before the request hits the Crossmint API.

The default chain is `base-sepolia` on staging environments and `base`
on production — override per-call via `CrossmintEvmTransactionRequest.chain`.

## Constructors

### CrossmintEvmWallet

```dart theme={null}
CrossmintEvmWallet({
  required super.client,
  required super.wallet,
  super.recoverySigner,
  super.signer,
  super.additionalSigners,
  super.deviceSignerKeyStorage,
  super.onAuthRequired,
})
```

Creates a runtime EVM wallet. Use `CrossmintClient.createEvmWallet` or the wallet controller instead of constructing this directly.

## Properties

### defaultChain

```dart theme={null}
String get defaultChain
```

## Methods

### createTransaction

```dart theme={null}
Future<CrossmintTransactionDetails> createTransaction(
  CrossmintEvmTransactionRequest request,
)
```

Submits a transaction request to the Crossmint API without waiting for approval or confirmation. Use this when you want to inspect the created record before approving — most callers should use `sendTransaction`.

### sendTransaction

```dart theme={null}
Future<CrossmintTransactionDetails> sendTransaction(
  CrossmintEvmTransactionRequest request,
)
```

End-to-end: creates the transaction, approves it with the active signer, polls for confirmation (exponential backoff 1s → 8s, up to 60 attempts, with jitter), and returns the final `CrossmintTransactionDetails`.

### signMessage

```dart theme={null}
Future<String> signMessage(String message)
```

Signs an arbitrary UTF-8 string as a personal message (EIP-191). Returns the hex-encoded signature. Calls `preAuthIfNeeded()` first.

### signTypedData

```dart theme={null}
Future<String> signTypedData(CrossmintTypedData typedData)
```

Signs an EIP-712 typed data payload. Requires `domain.name`, `domain.version`, `domain.chainId`, `domain.verifyingContract`, `primaryType`, `types`, and `message`. Throws `CrossmintWalletException` on malformed input.


# CrossmintException
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-exception

Flutter Class

**Class**

Base class for every exception the Crossmint SDK throws.

```dart theme={null}
class CrossmintException implements Exception
```

Every subclass carries a `code` (`CrossmintErrorCode`) so consumer code
can `switch` on error categories instead of string-matching on `message`.
The optional `cause` preserves the original error / payload that
triggered this exception — useful for logging and programmatic handling.

## Constructors

### CrossmintException

```dart theme={null}
const CrossmintException(
  this.message, {
  this.code = CrossmintErrorCode.unknown,
  this.cause,
})
```

Creates a generic `CrossmintException`. Prefer throwing a subclass scoped to the failure domain (auth / wallet / signer / …).

## Properties

### message

```dart theme={null}
final String message
```

Human-readable message suitable for logs. Not localized — do not show this directly to end users.

### code

```dart theme={null}
final CrossmintErrorCode code
```

A machine-readable error code for programmatic `switch`/`case` handling.

### cause

```dart theme={null}
final Object? cause
```

The underlying cause — typically a lower-level exception or an API response payload. Inspect this for extra detail when diagnosing errors.

## Methods

### toString

```dart theme={null}
String toString()
```


# CrossmintExportPrivateKeyButton
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-export-private-key-button

Flutter Class

**Class**

Export private key button matching the official Crossmint RN SDK `ExportPrivateKeyButton` component.

```dart theme={null}
class CrossmintExportPrivateKeyButton extends StatefulWidget
```

Only renders when `wallet.canExportPrivateKey` is true (email/phone signers).
Returns `SizedBox.shrink` otherwise.

Headless consumers can supply a `childBuilder` to swap the Material
default button for their own widget while keeping the eligibility check
and loading state management. Pure-headless consumers can bypass this
widget entirely and call `wallet.exportPrivateKey()` directly from their
own button.

## Constructors

### CrossmintExportPrivateKeyButton

```dart theme={null}
const CrossmintExportPrivateKeyButton({
  super.key,
  required this.wallet,
  this.onExported,
  this.onError,
  this.childBuilder,
})
```

## Properties

### wallet

```dart theme={null}
final CrossmintRuntimeWalletBase wallet
```

Wallet whose private key will be exported. The button only renders when `CrossmintRuntimeWalletBase.canExportPrivateKey` is true (email/phone signer wallets).

### onExported

```dart theme={null}
final VoidCallback? onExported
```

Called after the export flow completes successfully.

### onError

```dart theme={null}
final void Function(Object error)? onError
```

Called when the export flow throws. Receives the underlying exception so consumers can surface a localized error message.

### childBuilder

```dart theme={null}
final CrossmintExportPrivateKeyButtonBuilder? childBuilder
```

Optional builder for the button visual. When `null`, falls back to the React Native parity Material `OutlinedButton` with a themed `CircularProgressIndicator` while the export is in flight. When non-null, the builder is invoked whenever the wallet is eligible to export and receives the current `isLoading` flag plus an `onExport` callback that the consumer wires to their own tap target. The `onExport` callback is `null` while loading so consumers can disable their button directly without a separate mounted check.

## Methods

### createState

```dart theme={null}
State<CrossmintExportPrivateKeyButton> createState()
```


# CrossmintExportableWalletSigner
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-exportable-wallet-signer

Flutter Abstract Interface Class

**Abstract Interface Class**

Marker interface for signers that can hand back the raw private key to the user — primarily non-custodial email and phone signers.

```dart theme={null}
abstract interface class CrossmintExportableWalletSigner
```

Non-custodial signers normally keep keys inside a hidden WebView (the
TEE/KMS runtime the Crossmint signer service manages). For recovery or
migration flows, users can request the private key via a separate,
purpose-built export bridge — that flow lives behind
`exportPrivateKey`.

## Properties

### canExportPrivateKey

```dart theme={null}
bool get canExportPrivateKey
```

Whether this signer can export its private key. Only non-custodial email/phone signers return `true`.

## Methods

### exportPrivateKey

```dart theme={null}
Future<void> exportPrivateKey(CrossmintExportSignerBridge bridge)
```

Kicks off the key-export flow via the provided export bridge. The bridge renders a Crossmint-hosted UI that the user confirms inside. Throws `CrossmintSignerException` when the signer type does not support export.


# CrossmintExternalWalletSigner
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-external-wallet-signer

Flutter Abstract Base Class

**Abstract Base Class**

Base class for external-wallet delegated signers — wallets the user owns (e.g. MetaMask, Rainbow, Phantom) where the SDK never holds keys. In Crossmint terminology, an external wallet is a flavor of delegated signer that approves operations through the user's own wallet UI.

```dart theme={null}
abstract base class CrossmintExternalWalletSigner implements CrossmintWalletApprovalSigner
```

Signing goes through `onSign`; the signer is responsible for presenting
the user whatever approval UI their wallet provides. The `locator`
defaults to `external-wallet:<address>` when not provided explicitly.

## Constructors

### CrossmintExternalWalletSigner

```dart theme={null}
CrossmintExternalWalletSigner({
  required this.address,
  String? locator,
  required this.onSign,
})
```

Creates an external-wallet signer.

## Properties

### address

```dart theme={null}
final String address
```

The wallet address the user controls.

### locator

```dart theme={null}
final String locator
```

### onSign

```dart theme={null}
final CrossmintExternalWalletSignCallback onSign
```

User-provided signing callback. Receives the chain-specific payload and returns the resulting signature string.

## Methods

### requireSignature

```dart theme={null}
Future<String> requireSignature( String payload, { required String label, })
```

Invokes `onSign` and validates the result is non-empty. Used by subclasses to share error wrapping.


# CrossmintNonCustodialSigner
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-non-custodial-signer

Flutter Abstract Base Class

**Abstract Base Class**

Base class for email / phone non-custodial signers.

```dart theme={null}
abstract base class CrossmintNonCustodialSigner implements CrossmintWalletApprovalSigner, CrossmintExportableWalletSigner
```

Signing happens inside a hidden WebView (the Crossmint signer runtime)
coordinated through `CrossmintSignerBridgeClient`. The SDK owns the
WebView's lifecycle via `CrossmintWalletHost` — if it is not mounted,
attempting to use a non-custodial signer throws
`CrossmintSignerException(code: nonCustodialBridgeHostNotMounted)`.

When authentication is needed, the signer calls `onAuthRequired` which
surfaces the OTP challenge to UI (typically via
`CrossmintWalletController.otp`). Concurrent callers are coalesced onto
the same in-flight auth future to avoid double-prompting.

Non-custodial signers are also `CrossmintExportableWalletSigner`s —
email/phone signers can export their private key via
`exportPrivateKey`.

## Constructors

### CrossmintNonCustodialSigner

```dart theme={null}
CrossmintNonCustodialSigner({
  required this.client,
  required this.bridge,
  required this.type,
  required this.locator,
  this.address,
  this.onAuthRequired,
  CrossmintSignerBridgeClient? bridgeClient,
})
```

Creates a non-custodial signer. Prefer the chain-specific factory on `CrossmintClient` (e.g. `createEvmNonCustodialSigner`) over constructing this directly.

## Properties

### client

```dart theme={null}
final CrossmintClient client
```

The client this signer belongs to.

### bridge

```dart theme={null}
final HiddenSignerBridge bridge
```

The hidden signer WebView bridge that hosts the signing runtime.

### type

```dart theme={null}
final String type
```

### locator

```dart theme={null}
final String locator
```

### address

```dart theme={null}
final String? address
```

The wallet address this signer approves for, if known at construction.

### onAuthRequired

```dart theme={null}
final CrossmintSignerAuthRequiredCallback? onAuthRequired
```

Callback invoked when an OTP challenge starts or ends. Usually wired to `CrossmintWalletController.onAuthRequired` — which in turn surfaces a reactive challenge on `CrossmintWalletController.otp`.

### needsAuth

```dart theme={null}
bool get needsAuth
```

`true` while an OTP challenge is outstanding.

### canExportPrivateKey

```dart theme={null}
bool get canExportPrivateKey
```

## Methods

### ensureAuthenticated

```dart theme={null}
Future<void> ensureAuthenticated()
```

Ensures the signer runtime has completed its authentication handshake, prompting the user via `onAuthRequired` if necessary. Concurrent callers share the same in-flight future — the user sees at most one prompt per auth cycle.

### signMessage

```dart theme={null}
Future<String> signMessage(String message)
```

### signTransaction

```dart theme={null}
Future<String> signTransaction(String transaction)
```

### sign

```dart theme={null}
Future<String> sign({
  required CrossmintSignerKeyType keyType,
  required String bytes,
  required CrossmintSignerEncoding encoding,
})
```

Low-level sign primitive — ensures auth, then invokes the signer bridge directly. Chain-specific subclasses wrap this with the encoding / key-type appropriate for their chain.

### sendOtp

```dart theme={null}
Future<void> sendOtp()
```

(Re-)sends the OTP to the signer locator (email / phone). Meant to be invoked via `CrossmintWalletOtpController.sendOtp` during an active challenge.

### exportPrivateKey

```dart theme={null}
Future<void> exportPrivateKey(CrossmintExportSignerBridge bridge)
```

### verifyOtp

```dart theme={null}
Future<void> verifyOtp(String otp)
```

Submits the OTP the user entered. Resolves the pending `ensureAuthenticated` future on success.

### reject

```dart theme={null}
void reject([Object? error])
```

Cancels the pending OTP challenge. Fails the pending `ensureAuthenticated` future with `CrossmintAuthRejectedException` when no cause is supplied.


# CrossmintOtpCodeInputStep
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-otp-code-input-step

Flutter Class

**Class**

Step 2 of the OTP signer dialog: enter verification code.

```dart theme={null}
class CrossmintOtpCodeInputStep extends StatefulWidget
```

Matches the official Crossmint RN SDK `BaseCodeInput` component.

## Constructors

### CrossmintOtpCodeInputStep

```dart theme={null}
const CrossmintOtpCodeInputStep({
  super.key,
  required this.icon,
  required this.contactInfo,
  required this.contactType,
  required this.title,
  required this.onSubmit,
  required this.onCancel,
  this.onResend,
  this.codeLength = 9,
  this.keyboardType = TextInputType.text,
  this.autofillHints,
  this.helpText,
})
```

## Properties

### icon

```dart theme={null}
final IconData icon
```

### contactInfo

```dart theme={null}
final String contactInfo
```

### contactType

```dart theme={null}
final String contactType
```

### title

```dart theme={null}
final String title
```

### codeLength

```dart theme={null}
final int codeLength
```

### keyboardType

```dart theme={null}
final TextInputType keyboardType
```

### autofillHints

```dart theme={null}
final Iterable<String>? autofillHints
```

### helpText

```dart theme={null}
final String? helpText
```

### onSubmit

```dart theme={null}
final Future<void> Function(String code) onSubmit
```

### onResend

```dart theme={null}
final Future<void> Function()? onResend
```

### onCancel

```dart theme={null}
final VoidCallback onCancel
```

## Methods

### createState

```dart theme={null}
State<CrossmintOtpCodeInputStep> createState()
```


# CrossmintOtpConfirmationStep
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-otp-confirmation-step

Flutter Class

**Class**

Step 1 of the OTP signer dialog: confirm contact info before sending code.

```dart theme={null}
class CrossmintOtpConfirmationStep extends StatefulWidget
```

Matches the official Crossmint RN SDK `BaseConfirmation` component.

## Constructors

### CrossmintOtpConfirmationStep

```dart theme={null}
const CrossmintOtpConfirmationStep({
  super.key,
  required this.icon,
  required this.contactInfo,
  required this.contactType,
  required this.onSend,
  required this.onCancel,
})
```

## Properties

### icon

```dart theme={null}
final IconData icon
```

### contactInfo

```dart theme={null}
final String contactInfo
```

### contactType

```dart theme={null}
final String contactType
```

### onSend

```dart theme={null}
final Future<void> Function() onSend
```

### onCancel

```dart theme={null}
final VoidCallback onCancel
```

## Methods

### createState

```dart theme={null}
State<CrossmintOtpConfirmationStep> createState()
```


# CrossmintOtpModalShell
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-otp-modal-shell

Flutter Class

**Class**

Shared modal shell matching the official Crossmint RN SDK modal styling.

```dart theme={null}
class CrossmintOtpModalShell extends StatelessWidget
```

* 32px padding
* Max 400px wide, max 80% screen height
* Close button top-right
* Drop shadow

## Constructors

### CrossmintOtpModalShell

```dart theme={null}
const CrossmintOtpModalShell({
  super.key,
  required this.theme,
  required this.onClose,
  required this.child,
})
```

## Properties

### theme

```dart theme={null}
final CrossmintThemeData theme
```

### onClose

```dart theme={null}
final VoidCallback onClose
```

### child

```dart theme={null}
final Widget child
```

## Methods

### build

```dart theme={null}
Widget build(BuildContext context)
```


# CrossmintPasskeyApprovalSigner
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-passkey-approval-signer

Flutter Final Class

**Final Class**

Passkey-based `CrossmintWalletApprovalSigner` that delegates signing to a caller-supplied callback.

```dart theme={null}
final class CrossmintPasskeyApprovalSigner implements CrossmintWalletApprovalSigner
```

In Stage 1, the callback is always required. In Stage 2, native platform
passkey support can be used as a fallback when no callback is provided.
Until native support ships, passing a passkey signer config without
callbacks throws `CrossmintSignerException(code: passkeyCallbackMissing)`
during wallet creation or signing.

## Constructors

### CrossmintPasskeyApprovalSigner

```dart theme={null}
CrossmintPasskeyApprovalSigner({
  required this.credentialId,
  required String locator,
  required Future<CrossmintPasskeySignResult> Function(String message) onSign,
})
```

Creates a passkey approval signer bound to a specific `credentialId` and a user-supplied `onSign` callback.

## Properties

### credentialId

```dart theme={null}
final String credentialId
```

WebAuthn credential identifier bound to this signer.

### type

```dart theme={null}
String get type
```

### locator

```dart theme={null}
String get locator
```

## Methods

### signMessage

```dart theme={null}
Future<Object> signMessage(String message)
```

### signTransaction

```dart theme={null}
Future<Object> signTransaction(String transaction)
```


# CrossmintPasskeySignerFactory
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-passkey-signer-factory

Flutter Abstract Interface Class

**Abstract Interface Class**

Experimental factory for creating a passkey signer config.

```dart theme={null}
abstract interface class CrossmintPasskeySignerFactory
```

The default implementation uses the `permissionless_passkeys` package and
is intentionally small so it can be replaced in tests.

## Methods

### createPasskeySigner

```dart theme={null}
Future<CrossmintPasskeySignerConfig> createPasskeySigner({
  required String name,
  required CrossmintPasskeyConfig config,
})
```


# CrossmintPhoneOtpDialog
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-phone-otp-dialog

Flutter Class

**Class**

Phone OTP signer dialog matching the official Crossmint RN SDK `PhoneSignersDialog` component.

```dart theme={null}
class CrossmintPhoneOtpDialog extends StatefulWidget
```

## Constructors

### CrossmintPhoneOtpDialog

```dart theme={null}
const CrossmintPhoneOtpDialog({
  super.key,
  required this.otpController,
  this.onDismissed,
})
```

## Properties

### otpController

```dart theme={null}
final CrossmintWalletOtpController otpController
```

### onDismissed

```dart theme={null}
final VoidCallback? onDismissed
```

## Methods

### createState

```dart theme={null}
State<CrossmintPhoneOtpDialog> createState()
```


# CrossmintPollingConfig
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-polling-config

Flutter Class

**Class**

Configuration for exponential-backoff polling loops used throughout the SDK.

```dart theme={null}
class CrossmintPollingConfig
```

The delay between consecutive poll attempts grows exponentially from
`initialDelay` up to `maxDelay`, with optional random jitter to prevent
thundering-herd effects when many clients poll in parallel.

The total number of attempts is capped at `maxAttempts`.

## Constructors

### CrossmintPollingConfig

```dart theme={null}
const CrossmintPollingConfig({
  this.initialDelay = const Duration(seconds: 1),
  this.maxDelay = const Duration(seconds: 8),
  this.maxAttempts = 60,
  this.jitter = true,
  this.backoffFactor = 2.0,
})
```

Creates a polling configuration.

## Properties

### initialDelay

```dart theme={null}
final Duration initialDelay
```

Delay before the first retry (doubles each attempt up to `maxDelay`).

### maxDelay

```dart theme={null}
final Duration maxDelay
```

Upper bound on the delay between attempts.

### maxAttempts

```dart theme={null}
final int maxAttempts
```

Maximum number of poll iterations before timing out.

### jitter

```dart theme={null}
final bool jitter
```

When `true`, each computed delay is multiplied by a random factor in the range `[0.5, 1.0)` to spread retries across time.

### backoffFactor

```dart theme={null}
final double backoffFactor
```

Multiplicative factor applied to the delay each iteration.

## Methods

### delayForAttempt

```dart theme={null}
Duration delayForAttempt(int attempt, [Random? random])
```

Computes the delay for a given zero-based `attempt` index.


# CrossmintRuntimeWalletBase
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-runtime-wallet-base

Flutter Abstract Base Class

**Abstract Base Class**

Base class for chain-specific runtime wallets (EVM, Solana, Stellar).

```dart theme={null}
abstract base class CrossmintRuntimeWalletBase
```

Wraps a server-issued `CrossmintWallet` with signer management,
transaction/signature approval flows, device-signer recovery, and
token operations. Use the chain subclasses (`CrossmintEvmWallet`,
`CrossmintSolanaWallet`, `CrossmintStellarWallet`) rather than this
class directly.

## Constructors

### CrossmintRuntimeWalletBase

```dart theme={null}
CrossmintRuntimeWalletBase({
  required this.client,
  required this.wallet,
  CrossmintSignerConfig? recoverySigner,
  CrossmintWalletApprovalSigner? signer,
  List<CrossmintWalletApprovalSigner> additionalSigners =
      const <CrossmintWalletApprovalSigner>[],
  this.deviceSignerKeyStorage,
  this.onAuthRequired,
})
```

## Properties

### client

```dart theme={null}
final CrossmintClient client
```

Top-level Crossmint client shared by all wallet operations.

### wallet

```dart theme={null}
final CrossmintWallet wallet
```

Server-issued wallet snapshot backing this runtime instance.

### deviceSignerKeyStorage

```dart theme={null}
final DeviceSignerKeyStorage? deviceSignerKeyStorage
```

Storage backend for hardware-backed device signer keys.

### onAuthRequired

```dart theme={null}
final CrossmintSignerAuthRequiredCallback? onAuthRequired
```

Callback invoked when a signer operation requires user authentication.

### defaultChain

```dart theme={null}
String get defaultChain
```

Chain identifier used when the wallet snapshot has no explicit chain.

### chain

```dart theme={null}
String get chain
```

Blockchain this wallet operates on (falls back to `defaultChain`).

### address

```dart theme={null}
String get address
```

On-chain address of the wallet.

### owner

```dart theme={null}
String? get owner
```

Owner identifier associated with the wallet, if any.

### recovery

```dart theme={null}
CrossmintSignerConfig? get recovery
```

Recovery (admin) signer config parsed from the wallet's backend state.

### locator

```dart theme={null}
String get locator
```

Unique wallet locator used for API calls.

### signer

```dart theme={null}
CrossmintWalletApprovalSigner? get signer
```

Currently active approval signer, or null if none is selected.

### additionalSigners

```dart theme={null}
List<CrossmintWalletApprovalSigner> get additionalSigners
```

Secondary signers available alongside the primary `signer`.

### needsRecovery

```dart theme={null}
bool get needsRecovery
```

Whether the wallet needs recovery (signer registration) before the next transaction.

### canExportPrivateKey

```dart theme={null}
bool get canExportPrivateKey
```

Whether the active signer supports private-key export.

### debugIsRecovering

```dart theme={null}
bool get debugIsRecovering
```

Test-only: true while `recover()` is in flight. Lets concurrency tests assert that concurrent callers coalesce onto a single recovery future.

## Methods

### useSigner

```dart theme={null}
Future<void> useSigner(
  CrossmintSignerConfig signer, {
  List<CrossmintSignerConfig> additionalSigners =
      const <CrossmintSignerConfig>[],
})
```

Sets the active signer for this wallet. Accepts a signer config object; the locator is inferred internally. Works for device, non-custodial, external-wallet, and passkey signers.

### balances

```dart theme={null}
Future<CrossmintWalletBalanceSnapshot> balances({
  List<String> tokens = const <String>[],
})
```

Returns the wallet balances — always includes USDC and the native token. Pass additional `tokens` to request extra token balances.

### transactions

```dart theme={null}
Future<List<CrossmintTransactionSummary>> transactions()
```

Lists transaction summaries for this wallet.

### transaction

```dart theme={null}
Future<CrossmintTransactionDetails?> transaction(String transactionId)
```

Retrieves details for a specific transaction by ID.

### approve

```dart theme={null}
Future<CrossmintWalletApproveResult> approve(
  CrossmintWalletApproveRequest request,
)
```

Approves a pending transaction or signature request.

### nfts

```dart theme={null}
Future<CrossmintWalletNftPage> nfts({int page = 1, int perPage = 50})
```

Returns the wallet's NFTs (paginated).

### fund

```dart theme={null}
Future<CrossmintWalletFundResult> fund(CrossmintWalletFundRequest request)
```

Initiates a funding (on-ramp) request for this wallet.

### transfers

```dart theme={null}
Future<List<CrossmintJsonMap>> transfers({
  int page = 1,
  int perPage = 50,
  List<String> tokens = const <String>[],
  String? status,
})
```

Reads transfer history for this wallet (unstable API).

### send

```dart theme={null}
Future<CrossmintTransactionDetails> send(
  CrossmintWalletTokenTransferRequest request,
)
```

Sends a token transfer and waits for confirmation.

### sendToken

```dart theme={null}
Future<CrossmintTransactionDetails> sendToken(
  String to,
  String token,
  String amount, {
  bool prepareOnly = false,
  String? transactionType,
})
```

Convenience wrapper around `send` for simple token transfers.

### signers

```dart theme={null}
Future<List<CrossmintWalletSigner>> signers()
```

Lists all signers registered on this wallet with their current status.

### removeSigner

```dart theme={null}
Future<void> removeSigner(String signerLocator)
```

Removes a signer from the wallet by its locator.

### signerIsRegistered

```dart theme={null}
Future<bool> signerIsRegistered(String signerLocator)
```

Checks whether a signer with the given locator is registered.

### isSignerApproved

```dart theme={null}
Future<bool> isSignerApproved(String signerLocator)
```

Checks whether a registered signer is approved and usable.

### addSigner

```dart theme={null}
Future<CrossmintWalletAddSignerResult> addSigner(
  CrossmintSignerConfig signer, {
  bool prepareOnly = false,
  bool deployImmediately = true,
})
```

Registers a new signer on the wallet and approves the registration.

### preAuthIfNeeded

```dart theme={null}
Future<void> preAuthIfNeeded()
```

Awaits any in-flight recovery; if `_needsRecovery` is set and no recovery is in-flight, starts one and awaits it. Concurrent callers coalesce onto the same future so a single recovery runs per wallet.

### recover

```dart theme={null}
Future<void> recover()
```

Runs device-signer recovery: resumes any pending operation or registers a new device signer using the recovery signer. Returns early if the device signer is already approved on-chain.

### debugRegisterRecoverySigner

```dart theme={null}
void debugRegisterRecoverySigner(CrossmintWalletApprovalSigner signer)
```

Test-only: inject a pre-assembled recovery signer, bypassing the constructor-config resolution path. Used by tests that wire a fake bridge into a non-custodial signer without exercising `hiddenSignerBridgeController`. Not part of the supported public API.

### exportPrivateKey

```dart theme={null}
Future<void> exportPrivateKey({CrossmintExportSignerBridge? bridge})
```

Exports the wallet's private key via the export signer bridge.

### approveSignatureAndWaitInternal

```dart theme={null}
Future<String> approveSignatureAndWaitInternal(String signatureId)
```

Approves a pending signature and polls until it completes.

### approveSignatureInternal

```dart theme={null}
Future<CrossmintSignatureRecord> approveSignatureInternal( String signatureId, )
```

Submits approvals for a pending signature request.

### approveTransactionAndWait

```dart theme={null}
Future<CrossmintTransactionDetails> approveTransactionAndWait(
  String transactionId, {
  CrossmintTransactionDetails? seedTransaction,
})
```

Approves a pending transaction and polls until it reaches a terminal state.

### approveTransactionInternal

```dart theme={null}
Future<CrossmintTransactionDetails> approveTransactionInternal(
  String transactionId,
)
```

Submits approvals for a pending transaction.

### transactionApprovalPayload

```dart theme={null}
String transactionApprovalPayload({
  required CrossmintTransactionDetails transaction,
  required CrossmintJsonMap pendingApproval,
  required CrossmintWalletApprovalSigner signer,
})
```

Extracts the signable payload from a pending transaction approval.

### completeApprovedTransaction

```dart theme={null}
Future<CrossmintTransactionDetails> completeApprovedTransaction(
  CrossmintTransactionDetails transaction, {
  required String transactionId,
})
```

Polls a transaction until it reaches a terminal state and attaches explorer links.

### waitForTransaction

```dart theme={null}
Future<CrossmintTransactionDetails> waitForTransaction( String transactionId, )
```

Polls a transaction by ID until it succeeds or fails.

### walletSnapshotForSigners

```dart theme={null}
Future<CrossmintWallet> walletSnapshotForSigners()
```

Fetches a fresh wallet snapshot to inspect registered signers.

### requireActiveSigner

```dart theme={null}
CrossmintWalletApprovalSigner requireActiveSigner(String operation)
```

Returns the active signer or throws if none is selected.


# CrossmintSignerException
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-signer-exception

Flutter Final Class

**Final Class**

Thrown by signer operations — missing host, rejected OTP, unsupported export, missing passkey callback, upstream signer-service errors.

```dart theme={null}
final class CrossmintSignerException extends CrossmintException
```

## Constructors

### CrossmintSignerException

```dart theme={null}
const CrossmintSignerException(
  super.message, {
  super.code = CrossmintErrorCode.unknown,
  super.cause,
})
```

Creates a signer exception.


# CrossmintSolanaExternalWalletSigner
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-solana-external-wallet-signer

Flutter Final Class

**Final Class**

Solana variant of `CrossmintExternalWalletSigner`. Signs transactions only — raw-message signing is not supported on Solana.

```dart theme={null}
final class CrossmintSolanaExternalWalletSigner extends CrossmintExternalWalletSigner
```

## Constructors

### CrossmintSolanaExternalWalletSigner

```dart theme={null}
CrossmintSolanaExternalWalletSigner({
  required super.address,
  super.locator,
  required super.onSign,
})
```

Creates a Solana external-wallet signer.

## Properties

### type

```dart theme={null}
String get type
```

## Methods

### signMessage

```dart theme={null}
Future<Object> signMessage(String message)
```

### signTransaction

```dart theme={null}
Future<Object> signTransaction(String transaction)
```


# CrossmintSolanaNonCustodialSigner
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-solana-non-custodial-signer

Flutter Final Class

**Final Class**

Solana variant of `CrossmintNonCustodialSigner`. Signs with ed25519 keys using base58 encoding. `signMessage` is intentionally unsupported — Solana only supports transaction signing.

```dart theme={null}
final class CrossmintSolanaNonCustodialSigner extends CrossmintNonCustodialSigner
```

## Constructors

### CrossmintSolanaNonCustodialSigner

```dart theme={null}
CrossmintSolanaNonCustodialSigner({
  required super.client,
  required super.bridge,
  required super.type,
  required super.locator,
  super.address,
  super.onAuthRequired,
  super.bridgeClient,
})
```

Creates a Solana non-custodial signer.

## Methods

### signMessage

```dart theme={null}
Future<String> signMessage(String message)
```

### signTransaction

```dart theme={null}
Future<String> signTransaction(String transaction)
```


# CrossmintSolanaWallet
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-solana-wallet

Flutter Final Class

**Final Class**

Runtime wallet for Solana.

```dart theme={null}
final class CrossmintSolanaWallet extends CrossmintRuntimeWalletBase
```

On Solana, device signer support depends on the wallet type and is
validated server-side; the runtime falls back to the recovery signer when
the server rejects a device signer. Non-custodial, external, and passkey
signers are also supported. Default chain is `solana`.

## Constructors

### CrossmintSolanaWallet

```dart theme={null}
CrossmintSolanaWallet({
  required super.client,
  required super.wallet,
  super.recoverySigner,
  super.signer,
  super.additionalSigners,
  super.deviceSignerKeyStorage,
  super.onAuthRequired,
})
```

Creates a runtime Solana wallet. Prefer `CrossmintClient.createSolanaWallet` or the wallet controller over constructing this directly.

## Properties

### defaultChain

```dart theme={null}
String get defaultChain
```

## Methods

### sendTransaction

```dart theme={null}
Future<CrossmintTransactionDetails> sendTransaction(
  CrossmintSolanaTransactionRequest request,
)
```

Submits, approves, and waits for confirmation of a Solana transaction. Accepts a serialized transaction (base64 or base58); the SDK applies the active signer and returns the final `CrossmintTransactionDetails`.


# CrossmintStellarExternalWalletSigner
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-stellar-external-wallet-signer

Flutter Final Class

**Final Class**

Stellar variant of `CrossmintExternalWalletSigner`. Signs transactions only — raw-message signing is not supported on Stellar.

```dart theme={null}
final class CrossmintStellarExternalWalletSigner extends CrossmintExternalWalletSigner
```

## Constructors

### CrossmintStellarExternalWalletSigner

```dart theme={null}
CrossmintStellarExternalWalletSigner({
  required super.address,
  super.locator,
  required super.onSign,
})
```

Creates a Stellar external-wallet signer.

## Properties

### type

```dart theme={null}
String get type
```

## Methods

### signMessage

```dart theme={null}
Future<Object> signMessage(String message)
```

### signTransaction

```dart theme={null}
Future<Object> signTransaction(String transaction)
```


# CrossmintStellarNonCustodialSigner
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-stellar-non-custodial-signer

Flutter Final Class

**Final Class**

Stellar variant of `CrossmintNonCustodialSigner`. Signs with ed25519 keys using base64 encoding. `signMessage` is intentionally unsupported — Stellar only supports transaction signing.

```dart theme={null}
final class CrossmintStellarNonCustodialSigner extends CrossmintNonCustodialSigner
```

## Constructors

### CrossmintStellarNonCustodialSigner

```dart theme={null}
CrossmintStellarNonCustodialSigner({
  required super.client,
  required super.bridge,
  required super.type,
  required super.locator,
  super.address,
  super.onAuthRequired,
  super.bridgeClient,
})
```

Creates a Stellar non-custodial signer.

## Methods

### signMessage

```dart theme={null}
Future<String> signMessage(String message)
```

### signTransaction

```dart theme={null}
Future<String> signTransaction(String transaction)
```


# CrossmintStellarWallet
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-stellar-wallet

Flutter Final Class

**Final Class**

Runtime wallet for Stellar — including Soroban smart-contract calls.

```dart theme={null}
final class CrossmintStellarWallet extends CrossmintRuntimeWalletBase
```

Supports device, non-custodial, external, and passkey signers. Default
chain is `stellar`. Accepts two request shapes via the
`CrossmintStellarTransactionRequest` sealed hierarchy: pre-serialized
transactions and Soroban contract calls.

## Constructors

### CrossmintStellarWallet

```dart theme={null}
CrossmintStellarWallet({
  required super.client,
  required super.wallet,
  super.recoverySigner,
  super.signer,
  super.additionalSigners,
  super.deviceSignerKeyStorage,
  super.onAuthRequired,
})
```

Creates a runtime Stellar wallet. Prefer `CrossmintClient.createStellarWallet` or the wallet controller over constructing this directly.

## Properties

### defaultChain

```dart theme={null}
String get defaultChain
```

## Methods

### sendTransaction

```dart theme={null}
Future<CrossmintTransactionDetails> sendTransaction(
  CrossmintStellarTransactionRequest request,
)
```

Submits, approves, and waits for confirmation of a Stellar transaction. Handles both serialized transactions and Soroban contract calls via the `CrossmintStellarTransactionRequest` sealed hierarchy.


# CrossmintTokensException
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-tokens-exception

Flutter Final Class

**Final Class**

Thrown by token-related operations — balance lookup failures, missing token metadata.

```dart theme={null}
final class CrossmintTokensException extends CrossmintException
```

## Constructors

### CrossmintTokensException

```dart theme={null}
const CrossmintTokensException(
  super.message, {
  super.code = CrossmintErrorCode.unknown,
  super.cause,
})
```

Creates a tokens exception.


# CrossmintUsersException
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-users-exception

Flutter Final Class

**Final Class**

Thrown by user-profile operations — user lookup failures, profile update errors.

```dart theme={null}
final class CrossmintUsersException extends CrossmintException
```

## Constructors

### CrossmintUsersException

```dart theme={null}
const CrossmintUsersException(
  super.message, {
  super.code = CrossmintErrorCode.unknown,
  super.cause,
})
```

Creates a users exception.


# CrossmintWalletAuthChallenge
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-wallet-auth-challenge

Flutter Final Class

**Final Class**

Challenge returned by `CrossmintAuthClient.signInWithWallet` that must be signed by the user's external wallet (MetaMask, Phantom, etc.).

```dart theme={null}
final class CrossmintWalletAuthChallenge
```

## Constructors

### CrossmintWalletAuthChallenge

```dart theme={null}
const CrossmintWalletAuthChallenge({
  required this.message,
  this.nonce,
  this.raw = const <String, Object?>{},
})
```

## Properties

### message

```dart theme={null}
final String message
```

The message the wallet must sign.

### nonce

```dart theme={null}
final String? nonce
```

Replay-protection nonce.

### raw

```dart theme={null}
final CrossmintJsonMap raw
```

### operator

```dart theme={null}
bool operator
```

### hashCode

```dart theme={null}
int get hashCode
```


# CrossmintWalletController
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-wallet-controller

Flutter Final Class

**Final Class**

Stateful orchestrator for Crossmint wallets in a Flutter app.

```dart theme={null}
final class CrossmintWalletController extends ChangeNotifier
```

Holds the currently-loaded `CrossmintWallet`, exposes lifecycle operations
(`getWallet`, `createWallet`, `ensureLoaded`, `refresh`, `clear`),
surfaces OTP challenges via `otp`, and provides `create*Wallet*`
convenience methods that wire a runtime wallet with a signer of your
choosing (device, non-custodial, external, passkey).

Obtain one from `CrossmintClient.createWalletController` and pair it with
`CrossmintWalletHost` (headless) or `CrossmintWalletProvider`
(opt-in Material UI) so the hidden signer bridge has a place to mount.

Extends `ChangeNotifier` — listen to the controller for wallet-state
changes. Mutations go through the controller's public API; observation
can additionally go through `state` for a narrower, read-only surface.

## Constructors

### CrossmintWalletController

```dart theme={null}
CrossmintWalletController({
  required this.client,
  required this.config,
  CrossmintWalletStateRepository? stateRepository,
})
```

Creates a wallet controller. Prefer `CrossmintClient.createWalletController` over calling this directly.

## Properties

### client

```dart theme={null}
final CrossmintClient client
```

The underlying client — exposed for code that needs direct access to sub-clients (auth, orders, credentials, etc.).

### config

```dart theme={null}
final CrossmintWalletControllerConfig config
```

The configuration this controller was built with.

### otp

```dart theme={null}
final CrossmintWalletOtpController otp
```

OTP controller for non-custodial email/phone signer challenges.

### state

```dart theme={null}
CrossmintWalletStateView get state
```

Read-only observation surface for the underlying wallet state. Advanced consumers can subscribe to wallet / status changes directly via this `Listenable` while still routing all mutations through the controller's public API (`getWallet`, `createWallet`, `refresh`, `clear`, …).

### currentWallet

```dart theme={null}
CrossmintWallet? get currentWallet
```

The currently-loaded wallet, or `null` if none is loaded.

### status

```dart theme={null}
CrossmintWalletStatus get status
```

Current wallet lifecycle status.

### onAuthRequired

```dart theme={null}
CrossmintWalletAuthRequiredCallback get onAuthRequired
```

The auth-required callback the controller wires into every signer it builds. Exposed so apps building signers manually can share the same OTP-handling path.

### pendingOtpChallenge

```dart theme={null}
CrossmintOtpChallenge? get pendingOtpChallenge
```

Shortcut to `CrossmintWalletOtpController.pendingChallenge`.

### otpChallengeListenable

```dart theme={null}
ValueListenable<CrossmintOtpChallenge?> get otpChallengeListenable
```

Shortcut to `CrossmintWalletOtpController.challengeListenable`.

### requireCurrentWallet

```dart theme={null}
CrossmintWallet get requireCurrentWallet
```

Returns the currently-loaded wallet or throws `CrossmintWalletException` when none is loaded.

## Methods

### getWallet

```dart theme={null}
Future<CrossmintWallet?> getWallet( CrossmintWalletLookupRequest request, )
```

Looks up an existing wallet and stores the result in controller state. Returns `null` when no wallet matches. Listeners fire on state changes.

### loadWallet

```dart theme={null}
Future<CrossmintWallet?> loadWallet(CrossmintWalletLookupRequest request)
```

Deprecated: use `getWallet` instead.

### createWallet

```dart theme={null}
Future<CrossmintWallet> createWallet( CrossmintWalletCreateRequest request, )
```

Creates a new wallet and stores it in controller state. Validates passkey signers up-front via `crossmintValidatePasskeySigners` and fires `CrossmintWalletLifecycleCallbacks.onWalletCreationStart` if set.

### ensureLoaded

```dart theme={null}
Future<CrossmintWallet?> ensureLoaded()
```

Ensures a wallet is loaded, creating one if configured to do so.

### refresh

```dart theme={null}
Future<CrossmintWallet?> refresh()
```

Re-fetches the currently-loaded wallet from the API. Returns `null` when nothing is loaded.

### clear

```dart theme={null}
Future<void> clear()
```

Drops the loaded wallet and any pending OTP challenge. Call during sign-out.

### sendOtp

```dart theme={null}
Future<void> sendOtp()
```

Shortcut to `CrossmintWalletOtpController.sendOtp`.

### verifyOtp

```dart theme={null}
Future<void> verifyOtp(String otpCode)
```

Shortcut to `CrossmintWalletOtpController.verifyOtp`.

### rejectOtp

```dart theme={null}
void rejectOtp([Object? error])
```

Shortcut to `CrossmintWalletOtpController.reject`.

### createEvmWallet

```dart theme={null}
CrossmintEvmWallet createEvmWallet({
  CrossmintWalletApprovalSigner? signer,
  List<CrossmintWalletApprovalSigner> additionalSigners =
      const <CrossmintWalletApprovalSigner>[],
})
```

Wraps the currently-loaded wallet as a runtime `CrossmintEvmWallet`. Throws `CrossmintWalletException` if no wallet is loaded.

### createSolanaWallet

```dart theme={null}
CrossmintSolanaWallet createSolanaWallet({
  CrossmintWalletApprovalSigner? signer,
  List<CrossmintWalletApprovalSigner> additionalSigners =
      const <CrossmintWalletApprovalSigner>[],
})
```

Wraps the currently-loaded wallet as a runtime `CrossmintSolanaWallet`. On Solana, device signer support depends on the wallet type and is validated server-side. A default device signer is not auto-injected for Solana; it is registered reactively and falls back to the recovery signer when the server rejects it.

### createStellarWallet

```dart theme={null}
CrossmintStellarWallet createStellarWallet({
  CrossmintWalletApprovalSigner? signer,
  List<CrossmintWalletApprovalSigner> additionalSigners =
      const <CrossmintWalletApprovalSigner>[],
})
```

Wraps the currently-loaded wallet as a runtime `CrossmintStellarWallet`.

### createEvmWalletWithDeviceSigner

```dart theme={null}
CrossmintEvmWallet createEvmWalletWithDeviceSigner({
  required String signerLocator,
  String? address,
  DeviceSignerKeyStorage? storage,
})
```

Builds a runtime EVM wallet backed by a hardware-backed device signer. Use for low-friction, day-to-day signing with keys in Secure Enclave / Android Keystore.

### createEvmWalletWithNonCustodialSigner

```dart theme={null}
CrossmintEvmWallet createEvmWalletWithNonCustodialSigner({
  required String signerType,
  required String signerLocator,
  String? address,
  HiddenSignerBridge? bridge,
})
```

Builds a runtime EVM wallet backed by a non-custodial email/phone signer. Requires `CrossmintWalletHost` (or `CrossmintWalletProvider`) mounted in the widget tree.

### createSolanaWalletWithNonCustodialSigner

```dart theme={null}
CrossmintSolanaWallet createSolanaWalletWithNonCustodialSigner({
  required String signerType,
  required String signerLocator,
  String? address,
  HiddenSignerBridge? bridge,
})
```

Builds a runtime Solana wallet backed by a non-custodial email/phone signer. Requires a mounted wallet host.

### createStellarWalletWithNonCustodialSigner

```dart theme={null}
CrossmintStellarWallet createStellarWalletWithNonCustodialSigner({
  required String signerType,
  required String signerLocator,
  String? address,
  HiddenSignerBridge? bridge,
})
```

Builds a runtime Stellar wallet backed by a non-custodial email/phone signer. Requires a mounted wallet host.

### createStellarWalletWithDeviceSigner

```dart theme={null}
CrossmintStellarWallet createStellarWalletWithDeviceSigner({
  required String signerLocator,
  String? address,
  DeviceSignerKeyStorage? storage,
})
```

Builds a runtime Stellar wallet backed by a hardware device signer.

### createEvmWalletWithExternalWalletSigner

```dart theme={null}
CrossmintEvmWallet createEvmWalletWithExternalWalletSigner({
  required String address,
  String? signerLocator,
  required CrossmintExternalWalletSignCallback onSign,
})
```

Builds a runtime EVM wallet backed by a user-owned external wallet (e.g. MetaMask). The caller supplies `onSign` to perform signatures.

### createSolanaWalletWithExternalWalletSigner

```dart theme={null}
CrossmintSolanaWallet createSolanaWalletWithExternalWalletSigner({
  required String address,
  String? signerLocator,
  required CrossmintExternalWalletSignCallback onSign,
})
```

Builds a runtime Solana wallet backed by a user-owned external wallet.

### createStellarWalletWithExternalWalletSigner

```dart theme={null}
CrossmintStellarWallet createStellarWalletWithExternalWalletSigner({
  required String address,
  String? signerLocator,
  required CrossmintExternalWalletSignCallback onSign,
})
```

Builds a runtime Stellar wallet backed by a user-owned external wallet.

### createEvmWalletWithPasskeySigner

```dart theme={null}
CrossmintEvmWallet createEvmWalletWithPasskeySigner({
  String? id,
  required Future<CrossmintPasskeySignResult> Function(String message) onSign,
})
```

Builds a runtime EVM wallet backed by a passkey signer.

### createSolanaWalletWithPasskeySigner

```dart theme={null}
CrossmintSolanaWallet createSolanaWalletWithPasskeySigner({
  String? id,
  required Future<CrossmintPasskeySignResult> Function(String message) onSign,
})
```

Builds a runtime Solana wallet backed by a passkey signer. See `createEvmWalletWithPasskeySigner` for passkey selection semantics.

### createStellarWalletWithPasskeySigner

```dart theme={null}
CrossmintStellarWallet createStellarWalletWithPasskeySigner({
  String? id,
  required Future<CrossmintPasskeySignResult> Function(String message) onSign,
})
```

Builds a runtime Stellar wallet backed by a passkey signer. See `createEvmWalletWithPasskeySigner` for passkey selection semantics.

### dispose

```dart theme={null}
void dispose()
```


# CrossmintWalletControllerConfig
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-wallet-controller-config

Flutter Final Class

**Final Class**

Configuration for `CrossmintWalletController`.

```dart theme={null}
final class CrossmintWalletControllerConfig
```

Pass `createOnLogin` to have the controller create (or load) a wallet
automatically when a session becomes available. Set `showOtpSignerPrompt`
to `false` if you want to drive OTP prompts entirely from your own UI
(the controller still exposes the OTP controller via
`CrossmintWalletController.otp`).

## Constructors

### CrossmintWalletControllerConfig

```dart theme={null}
const CrossmintWalletControllerConfig({
  this.createOnLogin,
  this.showOtpSignerPrompt = true,
  this.callbacks,
  this.deviceSignerKeyStorage,
})
```

Creates a controller config. All fields are optional.

## Properties

### createOnLogin

```dart theme={null}
final CrossmintCreateOnLoginConfig? createOnLogin
```

When set, the controller automatically creates (or loads) a wallet on the given chain once the user is authenticated. Fill `recovery` with the recovery signer config (e.g. `CrossmintEmailSignerConfig()`).

### showOtpSignerPrompt

```dart theme={null}
final bool showOtpSignerPrompt
```

Whether the SDK should surface the default OTP prompt automatically. Set to `false` to drive OTP UI yourself by listening to `CrossmintWalletController.otp`.

### callbacks

```dart theme={null}
final CrossmintWalletLifecycleCallbacks? callbacks
```

Optional lifecycle hooks — see `CrossmintWalletLifecycleCallbacks`.

### deviceSignerKeyStorage

```dart theme={null}
final DeviceSignerKeyStorage? deviceSignerKeyStorage
```

Storage adapter used to persist device-signer keys. Defaults to a secure-enclave / keystore-backed implementation on device.


# CrossmintWalletException
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-wallet-exception

Flutter Final Class

**Final Class**

Thrown by wallet operations — lookup failures, unsupported chain, missing wallet, malformed transaction payloads.

```dart theme={null}
final class CrossmintWalletException extends CrossmintException
```

## Constructors

### CrossmintWalletException

```dart theme={null}
const CrossmintWalletException(
  super.message, {
  super.code = CrossmintErrorCode.unknown,
  super.cause,
})
```

Creates a wallet exception.


# CrossmintWalletHost
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-wallet-host

Flutter Final Class

**Final Class**

Advanced runtime host that mounts the client/auth/wallet scopes plus the hidden bridge hosts required for signer/export flows.

```dart theme={null}
final class CrossmintWalletHost extends StatelessWidget
```

Prefer `CrossmintWalletProvider` for the recommended app-facing integration
path. This widget remains useful when the host app owns the
`CrossmintClient` and `CrossmintWalletController` lifecycle directly.

## Constructors

### CrossmintWalletHost

```dart theme={null}
const CrossmintWalletHost({
  super.key,
  required this.client,
  required this.walletController,
  required this.child,
  this.hiddenSignerBridgeController,
  this.exportSignerBridgeController,
  this.offstageHiddenSignerBridge = true,
  this.offstageExportSignerBridge = true,
})
```

Creates a host widget. Pass the `client` and `walletController` the host should expose through scopes; optionally override the bridge controllers.

## Properties

### client

```dart theme={null}
final CrossmintClient client
```

The owning `CrossmintClient`.

### walletController

```dart theme={null}
final CrossmintWalletController walletController
```

The wallet controller the scope exposes via `CrossmintWalletContext`.

### child

```dart theme={null}
final Widget child
```

The subtree wrapped by the host.

### hiddenSignerBridgeController

```dart theme={null}
final HiddenSignerBridgeRuntimeController? hiddenSignerBridgeController
```

Optional override of the client's default hidden signer bridge controller — useful for tests that inject a fake bridge.

### offstageHiddenSignerBridge

```dart theme={null}
final bool offstageHiddenSignerBridge
```

When `true` (the default) the hidden signer WebView is hidden via a 1×1 `Opacity(0.01)` + `IgnorePointer` wrapper — invisible and non-interactive but still laid out, painted, and composited. It is **not** wrapped in an `Offstage` widget (see `HiddenSignerBridgeHost` for why). Set to `false` only when debugging the bridge.

### offstageExportSignerBridge

```dart theme={null}
final bool offstageExportSignerBridge
```

When `true` (the default) the export signer WebView is hidden the same way as `offstageHiddenSignerBridge`.

## Methods

### build

```dart theme={null}
Widget build(BuildContext context)
```


# CrossmintWalletLifecycleCallbacks
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-wallet-lifecycle-callbacks

Flutter Final Class

**Final Class**

Optional lifecycle hooks invoked at key points in the wallet controller.

```dart theme={null}
final class CrossmintWalletLifecycleCallbacks
```

Useful for showing blocking UI (e.g. a spinner during wallet creation) or
pre-authorizing a transaction with the user via native UI.

## Constructors

### CrossmintWalletLifecycleCallbacks

```dart theme={null}
const CrossmintWalletLifecycleCallbacks({
  this.onWalletCreationStart,
  this.onTransactionStart,
})
```

Creates a lifecycle callback bundle.

## Properties

### onWalletCreationStart

```dart theme={null}
final Future<void> Function()? onWalletCreationStart
```

Called immediately before the controller issues a `createWallet` API call. Await the returned future to block the operation until your UI is ready.

### onTransactionStart

```dart theme={null}
final Future<void> Function()? onTransactionStart
```

Called immediately before the controller issues a create-transaction API call. Await to block until your UI is ready.


# CrossmintWalletOtpController
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-wallet-otp-controller

Flutter Final Class

**Final Class**

Drives OTP challenges raised by non-custodial email and phone signers.

```dart theme={null}
final class CrossmintWalletOtpController
```

Exposed on `CrossmintWalletController.otp`. When the signer flow requests
authentication, the controller populates `pendingChallenge` and exposes
`sendOtp` / `verifyOtp` / `reject` to drive it. UI code observes
`challengeListenable` to show a prompt.

```dart theme={null}
ValueListenableBuilder<CrossmintOtpChallenge?>(
  valueListenable: walletController.otp.challengeListenable,
  builder: (context, challenge, _) {
    if (challenge == null) return const SizedBox.shrink();
    return MyOtpDialog(
      onSubmit: walletController.otp.verifyOtp,
      onCancel: walletController.otp.reject,
    );
  },
);
```

## Properties

### needsAuth

```dart theme={null}
bool get needsAuth
```

`true` when an OTP challenge is outstanding.

### pendingChallenge

```dart theme={null}
CrossmintOtpChallenge? get pendingChallenge
```

The active challenge, or `null` when no OTP is pending.

### challengeListenable

```dart theme={null}
ValueListenable<CrossmintOtpChallenge?> get challengeListenable
```

Reactive handle on the pending challenge — subscribe to drive OTP UI.

## Methods

### onAuthRequired

```dart theme={null}
Future<void> onAuthRequired(
  String signerType,
  String signerLocator,
  bool needsAuth,
  CrossmintOtpSendCallback sendOtp,
  CrossmintOtpVerifyCallback verifyOtp,
  CrossmintOtpRejectCallback reject,
)
```

Entry point the SDK calls when a signer needs authentication. Normally invoked by the signer auto-recovery machinery — you should not need to call this yourself.

### sendOtp

```dart theme={null}
Future<void> sendOtp()
```

Requests that the Crossmint API (re-)send the OTP to the user. Throws `CrossmintSignerException` when no challenge is pending.

### verifyOtp

```dart theme={null}
Future<void> verifyOtp(String otp)
```

Submits the OTP the user entered. On success, clears the pending challenge. Throws `CrossmintSignerException` when no challenge is pending.

### reject

```dart theme={null}
void reject([Object? error])
```

Cancels the pending OTP flow, surfacing `error` (if any) to the signer request that raised the challenge.

### clear

```dart theme={null}
void clear()
```

Clears any pending challenge without notifying the signer. Prefer `verifyOtp` or `reject` to resolve a challenge cleanly.

### dispose

```dart theme={null}
void dispose()
```

Releases the underlying `ValueNotifier`. Called automatically when the parent `CrossmintWalletController` is disposed.


# CrossmintWalletProvider
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-wallet-provider

Flutter Final Class

**Final Class**

Recommended app-facing integration widget — owns client, auth, and wallet-controller lifecycle plus the hidden signer bridge host.

```dart theme={null}
final class CrossmintWalletProvider extends StatefulWidget
```

Wrap your app tree in this widget, pass a `CrossmintWalletProviderConfig`
with API key and an optional `CrossmintWalletControllerConfig.createOnLogin`,
and use `CrossmintWalletGate` to render UI based on wallet lifecycle.

Behind the scenes this widget:

1. Constructs a `CrossmintClient` and `CrossmintWalletController` from
   `config`.
2. Mounts `CrossmintClientScope`, `CrossmintAuthScope`, and
   `CrossmintWalletScope` so descendants can resolve them via
   `CrossmintWalletContext.of`.
3. Mounts `CrossmintWalletHost` — which in turn hosts the hidden signer
   WebView — unless `CrossmintWalletProviderConfig.mountBridgeHosts` is
   explicitly set to `false`.
4. Calls `restoreSession()` so any persisted JWT is applied before the
   first frame.

If you need more control over construction or want to share a client
across surfaces, use `CrossmintWalletHost` with your own pre-built
`CrossmintClient` + `CrossmintWalletController` instead.

## Constructors

### CrossmintWalletProvider

```dart theme={null}
const CrossmintWalletProvider({
  super.key,
  required this.config,
  required this.child,
})
```

Creates a provider widget.

## Properties

### config

```dart theme={null}
final CrossmintWalletProviderConfig config
```

The configuration this provider was built with.

### child

```dart theme={null}
final Widget child
```

The subtree rendered once dependencies are ready. Pair with `CrossmintWalletGate` to show a loading state until then.

## Methods

### createState

```dart theme={null}
State<CrossmintWalletProvider> createState()
```


# CrossmintWalletProviderConfig
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-wallet-provider-config

Flutter Final Class

**Final Class**

Configuration for `CrossmintWalletProvider`.

```dart theme={null}
final class CrossmintWalletProviderConfig
```

Provide either a `clientConfig` (the provider builds dependencies for
you) or a fully-formed `dependencies` bundle. Both together is invalid.

Most apps want the `clientConfig` path:

```dart theme={null}
CrossmintWalletProvider(
  config: CrossmintWalletProviderConfig(
    clientConfig: CrossmintClientConfig(
      apiKey: 'YOUR_STAGING_API_KEY',
      appScheme: 'com.your.app',
    ),
    walletControllerConfig: CrossmintWalletControllerConfig(
      createOnLogin: CrossmintCreateOnLoginConfig(
        chain: 'base-sepolia',
        recovery: const CrossmintEmailSignerConfig(),
      ),
    ),
  ),
  child: CrossmintWalletGate(...),
);
```

## Constructors

### CrossmintWalletProviderConfig

```dart theme={null}
const CrossmintWalletProviderConfig({
  this.clientConfig,
  this.walletControllerConfig = const CrossmintWalletControllerConfig(),
  this.dependencies,
  this.disposeInjectedDependencies = false,
  this.authLinkProvider,
  this.startAuthCallbackRouter = true,
  this.autoLoadWallet = true,
  this.jwt,
  this.otpPromptBuilder,
  this.mountBridgeHosts = true,
})
```

Creates a provider config. Either `clientConfig` or `dependencies` must be non-null.

## Properties

### clientConfig

```dart theme={null}
final CrossmintClientConfig? clientConfig
```

Config used to build a new `CrossmintClient`. Mutually exclusive with `dependencies`.

### walletControllerConfig

```dart theme={null}
final CrossmintWalletControllerConfig walletControllerConfig
```

Config for the wallet controller the provider creates.

### dependencies

```dart theme={null}
final CrossmintWalletProviderDependencies? dependencies
```

Pre-built dependencies — use this when you want to share a client or controller between mount points. Mutually exclusive with `clientConfig`.

### disposeInjectedDependencies

```dart theme={null}
final bool disposeInjectedDependencies
```

When the provider was handed pre-built dependencies, controls whether they are disposed alongside the provider. Defaults to `false` — the caller retains ownership.

### authLinkProvider

```dart theme={null}
final CrossmintAuthLinkProvider? authLinkProvider
```

Optional resolver for the OAuth callback URL. Leave null to use the default deep-link resolver.

### startAuthCallbackRouter

```dart theme={null}
final bool startAuthCallbackRouter
```

When `true` (default) the provider starts `CrossmintAuthCallbackRouter` automatically so OAuth redirects land correctly.

### autoLoadWallet

```dart theme={null}
final bool autoLoadWallet
```

When `true` (default) the provider triggers `ensureLoaded()` on the wallet controller once a session is detected.

### jwt

```dart theme={null}
final String? jwt
```

BYOA JWT — when supplied, the provider seeds `auth.setJwt(jwt)` on startup (Bring Your Own Auth). Apps not using BYOA can leave this null.

### otpPromptBuilder

```dart theme={null}
final CrossmintOtpPromptBuilder? otpPromptBuilder
```

Builder for the default OTP prompt UI — pass `crossmintDefaultOtpPromptBuilder` for the Material default. Leave null to drive OTP UI headlessly via `walletController.otp`.

### mountBridgeHosts

```dart theme={null}
final bool mountBridgeHosts
```

When `true` (default) the provider mounts `CrossmintWalletHost` so the hidden signer bridge has a place to run. Set to `false` only if your subtree already hosts the bridge.

## Methods

### isEquivalentTo

```dart theme={null}
bool isEquivalentTo(CrossmintWalletProviderConfig other)
```


# CrossmintWalletProviderDependencies
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-wallet-provider-dependencies

Flutter Final Class

**Final Class**

Pre-built dependency bundle accepted by `CrossmintWalletProviderConfig`.

```dart theme={null}
final class CrossmintWalletProviderDependencies
```

Pass a bundle when you already own the client/controller lifecycle (for
example, a shared client across multiple provider mount points). If you
do not need that, pass a `CrossmintClientConfig` on the config instead and
let the provider build the client for you.

## Constructors

### CrossmintWalletProviderDependencies

```dart theme={null}
const CrossmintWalletProviderDependencies({
  required this.client,
  required this.walletController,
  this.authCallbackRouter,
})
```

Creates a dependency bundle.

## Properties

### client

```dart theme={null}
final CrossmintClient client
```

An already-initialized client. The provider will not dispose this unless `CrossmintWalletProviderConfig.disposeInjectedDependencies` is `true`.

### walletController

```dart theme={null}
final CrossmintWalletController walletController
```

An already-built wallet controller bound to `client`.

### authCallbackRouter

```dart theme={null}
final CrossmintAuthCallbackRouter? authCallbackRouter
```

Optional pre-built callback router for OAuth deep links.


# CrossmintWalletScope
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-wallet-scope

Flutter Final Class

**Final Class**

Provides `CrossmintWalletController` to descendant widgets.

```dart theme={null}
final class CrossmintWalletScope extends InheritedNotifier<CrossmintWalletController>
```

Prefer `CrossmintWalletProvider` from `crossmint_flutter_ui.dart` for the
recommended app-facing wallet UI path. This scope remains available as a
lower-level compatibility helper for apps that already own client/controller
lifecycle manually.

```dart theme={null}
CrossmintWalletScope(
  controller: walletController,
  child: MyApp(),
)

// In any descendant:
final controller = CrossmintWalletScope.of(context);
final wallet = controller.currentWallet;
final status = controller.status;
```

## Constructors

### CrossmintWalletScope

```dart theme={null}
const CrossmintWalletScope({
  super.key,
  required CrossmintWalletController controller,
  required super.child,
})
```

## Properties

### controller

```dart theme={null}
CrossmintWalletController get controller
```

The wallet controller provided to descendants.

## Static Methods

### of

```dart theme={null}
static CrossmintWalletController of(BuildContext context)
```

### maybeOf

```dart theme={null}
static CrossmintWalletController? maybeOf(BuildContext context)
```


# CrossmintWalletStateRepository
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-wallet-state-repository

Flutter Final Class

**Final Class**

Single source of truth for the wallet state surfaced by `CrossmintWalletController` and the wallet provider UI layer. Holds the currently-loaded wallet, its identifier, and the lifecycle status; emits `notifyListeners()` whenever any of those change.

```dart theme={null}
final class CrossmintWalletStateRepository extends ChangeNotifier implements CrossmintWalletStateView
```

This class is deliberately small and side-effect-free: it does not fetch
wallets, call the transport layer, or touch the Crossmint API. The wallet
controller is responsible for orchestrating the API calls and pushing
results into this repository via `beginOperation`, `setWallet`,
`setError`, and `clear`.

Funnelling mutations through this type gives the SDK a clean seam to add
caching, optimistic updates, or offline persistence in the future without
touching the controller's public API.

## Constructors

### CrossmintWalletStateRepository

```dart theme={null}
CrossmintWalletStateRepository()
```

## Properties

### currentWallet

```dart theme={null}
CrossmintWallet? get currentWallet
```

### currentWalletId

```dart theme={null}
String? get currentWalletId
```

### status

```dart theme={null}
CrossmintWalletStatus get status
```

## Methods

### beginOperation

```dart theme={null}
void beginOperation()
```

Mark the beginning of a wallet operation (load / create / refresh). Transitions to `CrossmintWalletStatus.inProgress` without touching the stored wallet or wallet id, so consumers can still render stale data while a refresh runs. No-op if already in progress.

### setWallet

```dart theme={null}
void setWallet(CrossmintWallet? wallet)
```

Commit the result of a successful wallet operation. A non-null `wallet` transitions to `CrossmintWalletStatus.loaded`; a `null` wallet transitions to `CrossmintWalletStatus.notLoaded` and clears the stored id (mirroring the pre-repository controller contract — an explicit backend "not found" must not silently revive the previous wallet on the next `refresh()`).

### setError

```dart theme={null}
void setError()
```

Transition to `CrossmintWalletStatus.error` after a failed operation. The previously-loaded wallet and wallet id are preserved so consumers can still show stale data alongside the error.

### clear

```dart theme={null}
void clear()
```

Reset to the initial state. Transitions to `CrossmintWalletStatus.notLoaded` and clears both the wallet and its identifier.


# CrossmintWalletStateView
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-wallet-state-view

Flutter Abstract Interface Class

**Abstract Interface Class**

Read-only observation surface for the wallet state held by the `CrossmintWalletController`. Exposed via `CrossmintWalletController.state` so advanced consumers can subscribe to wallet / status changes directly without reaching into the controller, while still routing all mutations through the controller's public API.

```dart theme={null}
abstract interface class CrossmintWalletStateView implements Listenable
```

## Properties

### currentWallet

```dart theme={null}
CrossmintWallet? get currentWallet
```

The currently-loaded wallet, or `null` if no wallet has been loaded.

### currentWalletId

```dart theme={null}
String? get currentWalletId
```

The identifier of the most recently-loaded wallet, or `null` if the repository is in the initial / cleared state.

### status

```dart theme={null}
CrossmintWalletStatus get status
```

Current lifecycle status. See `CrossmintWalletStatus` for values.


# CrossmintWallets
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/crossmint-wallets

Flutter Final Class

**Final Class**

Stateless convenience facade for wallet operations.

```dart theme={null}
final class CrossmintWallets
```

Mirrors the `CrossmintWallets` entry point used by the TS, Kotlin, and
Swift SDKs. For reactive state management (e.g. listening to wallet changes
in a widget tree), use `CrossmintWalletController` instead.

Unlike the controller, the facade does **not** auto-resolve signer configs.
Callers must provide fully-resolved configs (e.g. include the email address
in `CrossmintEmailSignerConfig`, or pre-create a device signer via
`createDeviceSigner`). The controller's `createWallet()` auto-populates
the authenticated user's email and creates device signer keys — the facade
intentionally skips this to remain stateless.

For email/phone OTP signers, pass `onAuthRequired` to handle OTP challenges.
For device signers, pass `deviceSignerKeyStorage` to enable key creation.

## Constructors

### CrossmintWallets.from

```dart theme={null}
CrossmintWallets.from(
  this._client, {
  CrossmintSignerAuthRequiredCallback? onAuthRequired,
  DeviceSignerKeyStorage? deviceSignerKeyStorage,
})
```

Creates a `CrossmintWallets` facade backed by `client`.

## Methods

### getWallet

```dart theme={null}
Future<CrossmintRuntimeWalletBase> getWallet({
  required String chain,
  String? alias,
  List<String> plugins = const <String>[],
  CrossmintSignerConfig? recoverySigner,
})
```

Retrieves an existing wallet and returns a typed runtime wallet.

### createWallet

```dart theme={null}
Future<CrossmintRuntimeWalletBase> createWallet({
  required String chain,
  required CrossmintSignerConfig recovery,
  List<CrossmintSignerConfig> signers = const <CrossmintSignerConfig>[],
  String? owner,
  String? alias,
  List<String> plugins = const <String>[],
})
```

Creates a new wallet and returns a typed runtime wallet.

### createDeviceSigner

```dart theme={null}
Future<CrossmintDeviceSignerDescriptor> createDeviceSigner({
  DeviceSignerKeyStorage? storage,
  String? address,
})
```

Creates a device signer descriptor.

### createPasskeySigner

```dart theme={null}
Future<CrossmintPasskeySignerConfig> createPasskeySigner({
  required String name,
  required CrossmintPasskeyConfig config,
})
```

Creates a passkey signer configuration.


# DefaultCrossmintAppIdentityResolver
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/default-crossmint-app-identity-resolver

Flutter Final Class

**Final Class**

Default app identity resolver that reads the platform bundle/package ID using `PackageInfo`.

```dart theme={null}
final class DefaultCrossmintAppIdentityResolver implements CrossmintAppIdentityResolver
```

On iOS: returns the bundle identifier (e.g. `com.example.myapp`).
On Android: returns the package name (e.g. `com.example.myapp`).

This mirrors the official Crossmint RN SDK's behavior of auto-deriving
the app ID from Expo constants.

## Constructors

### DefaultCrossmintAppIdentityResolver

```dart theme={null}
const DefaultCrossmintAppIdentityResolver()
```

## Methods

### resolveAppId

```dart theme={null}
Future<String?> resolveAppId()
```


# SoftwareDeviceSignerKeyStorage
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/software-device-signer-key-storage

Flutter Final Class

**Final Class**

Software-backed device signer key storage for dev/test environments.

```dart theme={null}
final class SoftwareDeviceSignerKeyStorage implements DeviceSignerKeyStorageInternal
```

This implementation generates P-256 keys in-memory, matching the official
Crossmint RN SDK's `SoftwareDeviceSignerKeyStorage` used in Expo Go and
development builds where native hardware-backed storage is unavailable.

**Do not use in production.** Keys are stored in memory and lost when
the app process terminates.

## Methods

### isAvailable

```dart theme={null}
Future<bool> isAvailable()
```

### generateKey

```dart theme={null}
Future<String> generateKey({
  String? address,
  CrossmintBiometricPolicy biometricPolicy = CrossmintBiometricPolicy.none,
})
```

### mapAddressToKey

```dart theme={null}
Future<void> mapAddressToKey(String address, String publicKeyBase64)
```

### getKey

```dart theme={null}
Future<String?> getKey(String address)
```

### hasKey

```dart theme={null}
Future<bool> hasKey(String publicKeyBase64)
```

### signMessage

```dart theme={null}
Future<Map<String, Object?>> signMessage( String address, String message, )
```

### deleteKey

```dart theme={null}
Future<void> deleteKey(String address)
```

### deletePendingKey

```dart theme={null}
Future<void> deletePendingKey(String publicKeyBase64)
```

### getDeviceName

```dart theme={null}
Future<String?> getDeviceName()
```


# UnsupportedPasskeySignerFactory
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/unsupported-passkey-signer-factory

Flutter Final Class

**Final Class**

Fallback factory used when the Flutter runtime does not provide a concrete passkey implementation.

```dart theme={null}
final class UnsupportedPasskeySignerFactory implements CrossmintPasskeySignerFactory
```

## Constructors

### UnsupportedPasskeySignerFactory

```dart theme={null}
const UnsupportedPasskeySignerFactory()
```

## Methods

### createPasskeySigner

```dart theme={null}
Future<CrossmintPasskeySignerConfig> createPasskeySigner({
  required String name,
  required CrossmintPasskeyConfig config,
})
```


# WalletResponseParser
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/wallet-response-parser

Flutter Final Class

**Final Class**

Pure-parsing helpers that turn API envelopes into typed wallet models.

```dart theme={null}
final class WalletResponseParser
```

Methods that depend on chain-family dispatch are instance methods so they
can receive an injectable `ChainResolver`; everything else is exposed as a
static helper.

## Constructors

### WalletResponseParser

```dart theme={null}
const WalletResponseParser({
  ChainResolver chainResolver = const ChainResolver(),
})
```

## Static Methods

### walletFromMap

```dart theme={null}
static CrossmintWallet walletFromMap(
  CrossmintJsonMap map, {
  String? fallbackId,
  String? fallbackChain,
})
```

### signatureFromMap

```dart theme={null}
static CrossmintSignatureRecord signatureFromMap(CrossmintJsonMap map)
```

### transactionFromMap

```dart theme={null}
static CrossmintTransactionRecord transactionFromMap(CrossmintJsonMap map)
```

### readEnvelopeItems

```dart theme={null}
static List<CrossmintJsonMap> readEnvelopeItems(Object? body)
```

### envelopeRaw

```dart theme={null}
static CrossmintJsonMap envelopeRaw(
  Object? body, {
  required String collectionKey,
})
```

### normalizeMap

```dart theme={null}
static CrossmintJsonMap normalizeMap(Map<Object?, Object?> value)
```

### resolvedWalletChain

```dart theme={null}
static String? resolvedWalletChain(
  CrossmintJsonMap map, {
  String? fallbackChain,
})
```

### isConcreteWalletChain

```dart theme={null}
static bool isConcreteWalletChain(String? value)
```

## Methods

### walletSignerFromMap

```dart theme={null}
CrossmintWalletSigner? walletSignerFromMap(
  CrossmintJsonMap map, {
  required String chain,
})
```

### signerStatusFromMap

```dart theme={null}
String? signerStatusFromMap(CrossmintJsonMap map, {required String chain})
```

### signatureIdFromSignerRegistration

```dart theme={null}
String? signatureIdFromSignerRegistration(
  CrossmintJsonMap map, {
  required String chain,
})
```

### transactionIdFromSignerRegistration

```dart theme={null}
String? transactionIdFromSignerRegistration(
  CrossmintJsonMap map, {
  required String chain,
})
```


# WalletSerializationCodec
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/classes/wallet-serialization-codec

Flutter Final Class

**Final Class**

Centralises all wallet-API request serialisation logic.

```dart theme={null}
final class WalletSerializationCodec
```

Every method here builds a JSON payload that is sent verbatim to the
Crossmint API. The output of this codec is part of the cross-SDK wallet
parity contract — do not change field names, shapes, or conditional
inclusion semantics without a coordinated spec update.

## Constructors

### WalletSerializationCodec

```dart theme={null}
const WalletSerializationCodec({
  ChainResolver chainResolver = const ChainResolver(),
})
```

## Methods

### serializeCreateRequest

```dart theme={null}
CrossmintJsonMap serializeCreateRequest( CrossmintWalletCreateRequest request, )
```

### serializeSignerRegistrationRequest

```dart theme={null}
CrossmintJsonMap serializeSignerRegistrationRequest(
  CrossmintSignerConfig signer, {
  required String chain,
  bool deployImmediately = true,
})
```

### serializeSignerRegistrationInput

```dart theme={null}
Object serializeSignerRegistrationInput(
  CrossmintSignerConfig signer, {
  required String chainType,
})
```

### serializeDeviceSignerRegistrationInput

```dart theme={null}
Object serializeDeviceSignerRegistrationInput(
  CrossmintDeviceSignerConfig signer,
)
```

### serializeEmailSignerObject

```dart theme={null}
CrossmintJsonMap serializeEmailSignerObject(
  CrossmintEmailSignerConfig signer,
)
```

### serializePhoneSignerObject

```dart theme={null}
CrossmintJsonMap serializePhoneSignerObject(
  CrossmintPhoneSignerConfig signer,
)
```

### serializeRecoverySigner

```dart theme={null}
Object serializeRecoverySigner(CrossmintSignerConfig signer)
```

### serializeDelegatedSigner

```dart theme={null}
Object serializeDelegatedSigner(CrossmintSignerConfig signer)
```

### serializeDeviceSignerObject

```dart theme={null}
CrossmintJsonMap serializeDeviceSignerObject(
  CrossmintDeviceSignerConfig signer,
)
```

### serializePasskeySignerPayload

```dart theme={null}
CrossmintJsonMap serializePasskeySignerPayload(
  CrossmintPasskeySignerConfig signer,
)
```

### walletLocatorFromRequest

```dart theme={null}
String walletLocatorFromRequest(CrossmintWalletLookupRequest request)
```

### apiKeySignerLocator

```dart theme={null}
String apiKeySignerLocator(CrossmintApiKeySignerConfig signer)
```

### emailSignerLocator

```dart theme={null}
String emailSignerLocator(CrossmintEmailSignerConfig signer)
```

### phoneSignerLocator

```dart theme={null}
String phoneSignerLocator(CrossmintPhoneSignerConfig signer)
```

### externalWalletSignerLocator

```dart theme={null}
String externalWalletSignerLocator(
  CrossmintExternalWalletSignerConfig signer,
)
```

### serializeTransactionRequest

```dart theme={null}
CrossmintJsonMap serializeTransactionRequest(
  CrossmintEvmTransactionRequest request,
)
```

### serializeSolanaTransactionRequest

```dart theme={null}
CrossmintJsonMap serializeSolanaTransactionRequest(
  CrossmintSolanaTransactionRequest request,
)
```

### serializeStellarTransactionRequest

```dart theme={null}
CrossmintJsonMap serializeStellarTransactionRequest(
  CrossmintStellarTransactionRequest request,
)
```

### serializeTokenTransferRequest

```dart theme={null}
CrossmintJsonMap serializeTokenTransferRequest(
  CrossmintWalletTokenTransferRequest request,
)
```

### serializeTransactionCall

```dart theme={null}
CrossmintJsonMap serializeTransactionCall(CrossmintEvmTransactionCall call)
```

### recipientLocator

```dart theme={null}
String recipientLocator(Object recipient)
```

### resolveTokenLocator

```dart theme={null}
String resolveTokenLocator(CrossmintWalletTokenTransferRequest request)
```

### balanceTokensForChains

```dart theme={null}
List<String> balanceTokensForChains(
  List<String> chains, {
  required List<String> additionalTokens,
})
```

### nativeTokenForChain

```dart theme={null}
String nativeTokenForChain(String chain)
```

### dedupeStrings

```dart theme={null}
List<String> dedupeStrings(List<String> values)
```


# Controllers
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/controllers

Flutter controllers for the Flutter SDK reference for Crossmint wallets

The Flutter SDK uses `ChangeNotifier`-based controllers instead of React hooks. Controllers can be used directly (headless) or accessed through the widget tree via providers.

***

## CrossmintClient

The top-level facade for the Crossmint SDK. Provides access to auth, wallets, and all sub-clients.

### Properties

<ResponseField name="config" type="CrossmintClientConfig">
  The configuration this client was built with.

  <Expandable title="properties">
    <ResponseField name="authStorage" type="CrossmintAuthStorage?">
      Custom session / token store. When null, the SDK uses `FlutterSecureStorage` under the hood.
    </ResponseField>

    <ResponseField name="logger" type="CrossmintLogger?">
      Custom logger sink. When null, the SDK uses a no-op logger in release and a `debugPrint`-backed logger in debug.
    </ResponseField>

    <ResponseField name="refreshRoute" type="Uri?">
      Optional custom server endpoint for token refresh.
    </ResponseField>

    <ResponseField name="logoutRoute" type="Uri?">
      Optional custom server endpoint for logout.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="auth" type="CrossmintAuthClient">
  Authentication sub-client — email OTP, OAuth, wallet sign-in, session persistence, JWT refresh.
</ResponseField>

<ResponseField name="wallets" type="CrossmintWalletsClient">
  Wallet sub-client — create, list, and read Crossmint-hosted wallets (EVM, Solana, Stellar) and their signers.
</ResponseField>

<ResponseField name="credentials" type="CrossmintCredentialsClient">
  Verifiable credentials sub-client — issue, query, and verify credentials.
</ResponseField>

<ResponseField name="orders" type="CrossmintOrdersClient">
  Orders sub-client — checkout orders and mint/purchase flows.
</ResponseField>

<ResponseField name="tokens" type="CrossmintTokensClient">
  Tokens sub-client — metadata and balances for tokens held by wallets.
</ResponseField>

<ResponseField name="users" type="CrossmintUsersClient">
  Users sub-client — user profile lookups and updates.
</ResponseField>

<ResponseField name="appId" type="String?">
  The effective app ID — explicit \[CrossmintClientConfig.appId] if set, otherwise the value auto-resolved from platform metadata during \[initialize]. May be `null` until \[initialize] has completed.
</ResponseField>

<ResponseField name="isInitialized" type="bool">
  Whether \[initialize] has completed successfully.
</ResponseField>

<ResponseField name="isDisposed" type="bool">
  Whether \[dispose] has been called. Once disposed, the client cannot be reused — construct a new one.
</ResponseField>

<ResponseField name="hiddenSignerBridgeController" type="HiddenSignerBridgeRuntimeController">
  The shared hidden signer bridge controller, lazily constructed on first access. Powers non-custodial email/phone signing inside a hidden WebView.

  <Expandable title="properties">
    <ResponseField name="config" type="HiddenSignerBridgeConfig">
      <Expandable title="properties">
        <ResponseField name="uri" type="Uri" />

        <ResponseField name="javaScriptChannelName" type="String" />

        <ResponseField name="dispatchScriptBuilder" type="HiddenSignerDispatchScriptBuilder" />

        <ResponseField name="handshakeSignal" type="String" />

        <ResponseField name="handshakeTimeout" type="Duration" />

        <ResponseField name="requestTimeout" type="Duration" />

        <ResponseField name="allowedOrigins" type="Set<String>" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="authStorage" type="CrossmintAuthStorage">
  The auth storage adapter resolved during construction — either the one passed via \[CrossmintClientConfig.authStorage] or the default `flutter_secure_storage`-backed implementation.
</ResponseField>

<ResponseField name="transport" type="CrossmintTransport">
  The HTTP transport resolved during construction. Shared by every sub-client; injects the live JWT via a closure so token refresh works without rebuilding dependencies.
</ResponseField>

### Methods

<ResponseField name="createWalletController(config)" type="CrossmintWalletController">
  Creates a \[CrossmintWalletController] bound to this client.

  <Expandable title="parameters">
    <ResponseField name="config" type="CrossmintWalletControllerConfig" />
  </Expandable>
</ResponseField>

<ResponseField name="createHiddenSignerBridge(config)" type="HiddenSignerBridgeRuntimeController">
  Builds a new \[HiddenSignerBridgeRuntimeController] instance — used internally by \[hiddenSignerBridgeController]. Override the bridge `config` to point at a custom signer URL (e.g. for testing).

  <Expandable title="parameters">
    <ResponseField name="config" type="HiddenSignerBridgeConfig?" />
  </Expandable>
</ResponseField>

<ResponseField name="createExportSignerBridge(config)" type="CrossmintExportSignerBridgeRuntimeController">
  Builds a new \[CrossmintExportSignerBridgeRuntimeController] instance. Used internally by \[exportSignerBridgeController].

  <Expandable title="parameters">
    <ResponseField name="config" type="HiddenSignerBridgeConfig?" />
  </Expandable>
</ResponseField>

<ResponseField name="createEvmNonCustodialSigner(bridge, signerType, signerLocator, address, onAuthRequired)" type="CrossmintEvmNonCustodialSigner">
  Builds a non-custodial EVM signer bound to an existing \[HiddenSignerBridge]. Produces secp256k1 signatures inside the WebView without exposing keys to Dart.

  <Expandable title="parameters">
    <ResponseField name="bridge" type="HiddenSignerBridge" />

    <ResponseField name="signerType" type="String" />

    <ResponseField name="signerLocator" type="String" />

    <ResponseField name="address" type="String?" />

    <ResponseField name="onAuthRequired" type="CrossmintSignerAuthRequiredCallback?" />
  </Expandable>
</ResponseField>

<ResponseField name="createSolanaNonCustodialSigner(bridge, signerType, signerLocator, address, onAuthRequired)" type="CrossmintSolanaNonCustodialSigner">
  Builds a non-custodial Solana signer bound to an existing \[HiddenSignerBridge]. Produces ed25519 signatures inside the WebView.

  <Expandable title="parameters">
    <ResponseField name="bridge" type="HiddenSignerBridge" />

    <ResponseField name="signerType" type="String" />

    <ResponseField name="signerLocator" type="String" />

    <ResponseField name="address" type="String?" />

    <ResponseField name="onAuthRequired" type="CrossmintSignerAuthRequiredCallback?" />
  </Expandable>
</ResponseField>

<ResponseField name="createStellarNonCustodialSigner(bridge, signerType, signerLocator, address, onAuthRequired)" type="CrossmintStellarNonCustodialSigner">
  Builds a non-custodial Stellar signer bound to an existing \[HiddenSignerBridge]. Produces ed25519 signatures inside the WebView.

  <Expandable title="parameters">
    <ResponseField name="bridge" type="HiddenSignerBridge" />

    <ResponseField name="signerType" type="String" />

    <ResponseField name="signerLocator" type="String" />

    <ResponseField name="address" type="String?" />

    <ResponseField name="onAuthRequired" type="CrossmintSignerAuthRequiredCallback?" />
  </Expandable>
</ResponseField>

<ResponseField name="createEvmWallet(wallet, recoverySigner, signer, additionalSigners, deviceSignerKeyStorage, onAuthRequired)" type="CrossmintEvmWallet">
  Wraps a server-issued \[CrossmintWallet] in a runtime \[CrossmintEvmWallet].

  <Expandable title="parameters">
    <ResponseField name="wallet" type="CrossmintWallet" />

    <ResponseField name="recoverySigner" type="CrossmintSignerConfig?" />

    <ResponseField name="signer" type="CrossmintWalletApprovalSigner?" />

    <ResponseField name="additionalSigners" type="List<CrossmintWalletApprovalSigner>" />

    <ResponseField name="deviceSignerKeyStorage" type="DeviceSignerKeyStorage?" />

    <ResponseField name="onAuthRequired" type="CrossmintSignerAuthRequiredCallback?" />
  </Expandable>
</ResponseField>

<ResponseField name="createSolanaWallet(wallet, recoverySigner, signer, additionalSigners, deviceSignerKeyStorage, onAuthRequired)" type="CrossmintSolanaWallet">
  Wraps a server-issued \[CrossmintWallet] in a runtime \[CrossmintSolanaWallet].

  <Expandable title="parameters">
    <ResponseField name="wallet" type="CrossmintWallet" />

    <ResponseField name="recoverySigner" type="CrossmintSignerConfig?" />

    <ResponseField name="signer" type="CrossmintWalletApprovalSigner?" />

    <ResponseField name="additionalSigners" type="List<CrossmintWalletApprovalSigner>" />

    <ResponseField name="deviceSignerKeyStorage" type="DeviceSignerKeyStorage?" />

    <ResponseField name="onAuthRequired" type="CrossmintSignerAuthRequiredCallback?" />
  </Expandable>
</ResponseField>

<ResponseField name="createStellarWallet(wallet, recoverySigner, signer, additionalSigners, deviceSignerKeyStorage, onAuthRequired)" type="CrossmintStellarWallet">
  Wraps a server-issued \[CrossmintWallet] in a runtime \[CrossmintStellarWallet].

  <Expandable title="parameters">
    <ResponseField name="wallet" type="CrossmintWallet" />

    <ResponseField name="recoverySigner" type="CrossmintSignerConfig?" />

    <ResponseField name="signer" type="CrossmintWalletApprovalSigner?" />

    <ResponseField name="additionalSigners" type="List<CrossmintWalletApprovalSigner>" />

    <ResponseField name="deviceSignerKeyStorage" type="DeviceSignerKeyStorage?" />

    <ResponseField name="onAuthRequired" type="CrossmintSignerAuthRequiredCallback?" />
  </Expandable>
</ResponseField>

<ResponseField name="createDeviceWalletSigner(signerLocator, address, storage)" type="CrossmintDeviceWalletSigner">
  Builds a hardware-backed device signer for an existing server signer.

  <Expandable title="parameters">
    <ResponseField name="signerLocator" type="String" />

    <ResponseField name="address" type="String" />

    <ResponseField name="storage" type="DeviceSignerKeyStorage?" />
  </Expandable>
</ResponseField>

<ResponseField name="createEvmExternalWalletSigner(address, signerLocator, onSign)" type="CrossmintEvmExternalWalletSigner">
  Builds an external-wallet EVM signer that delegates to a user-supplied \[CrossmintExternalWalletSignCallback]. Use for wallets owned by the user (e.g. MetaMask, Rainbow) where the SDK only needs to request signatures.

  <Expandable title="parameters">
    <ResponseField name="address" type="String" />

    <ResponseField name="signerLocator" type="String?" />

    <ResponseField name="onSign" type="CrossmintExternalWalletSignCallback" />
  </Expandable>
</ResponseField>

<ResponseField name="createSolanaExternalWalletSigner(address, signerLocator, onSign)" type="CrossmintSolanaExternalWalletSigner">
  Builds an external-wallet Solana signer that delegates to a user-supplied \[CrossmintExternalWalletSignCallback].

  <Expandable title="parameters">
    <ResponseField name="address" type="String" />

    <ResponseField name="signerLocator" type="String?" />

    <ResponseField name="onSign" type="CrossmintExternalWalletSignCallback" />
  </Expandable>
</ResponseField>

<ResponseField name="createStellarExternalWalletSigner(address, signerLocator, onSign)" type="CrossmintStellarExternalWalletSigner">
  Builds an external-wallet Stellar signer that delegates to a user-supplied \[CrossmintExternalWalletSignCallback].

  <Expandable title="parameters">
    <ResponseField name="address" type="String" />

    <ResponseField name="signerLocator" type="String?" />

    <ResponseField name="onSign" type="CrossmintExternalWalletSignCallback" />
  </Expandable>
</ResponseField>

<ResponseField name="createPasskeyApprovalSigner(credentialId, signerLocator, onSign)" type="CrossmintPasskeyApprovalSigner">
  Builds a passkey approval signer. The caller provides `onSign` — a callback that performs the WebAuthn / platform-native passkey assertion and returns a \[CrossmintPasskeySignResult]. Native platform passkey support is pending (Stage 2); today every passkey signer requires an explicit callback or `CrossmintSignerException(code: passkeyCallbackMissing)` is thrown during signing.

  <Expandable title="parameters">
    <ResponseField name="credentialId" type="String" />

    <ResponseField name="signerLocator" type="String" />

    <ResponseField name="onSign" type="Future<CrossmintPasskeySignResult> Function(String message)" />
  </Expandable>
</ResponseField>

<ResponseField name="dispose()" type="Future<void>">
  Releases the signer bridges and auth client, then marks the client as disposed. Safe to call multiple times. After disposal, construct a new \[CrossmintClient] rather than reusing this one.
</ResponseField>

<ResponseField name="initialize()" type="Future<void>">
  Validates configuration and prepares the client for use.
</ResponseField>

### Usage

```dart theme={null}
import 'package:crossmint_flutter/crossmint_client.dart';

final client = CrossmintClient(
  config: CrossmintClientConfig(
    apiKey: 'YOUR_CLIENT_API_KEY',
    appScheme: 'myapp',
  ),
);

await client.initialize();
await client.auth.restoreSession();
```

***

## CrossmintAuthClient

Manages authentication state and login flows. Exposes state via `ValueListenable` and `Stream` for reactive UI updates. Use `setJwt()` to provide your own JWT when not using the built-in auth flows.

### Properties

<ResponseField name="state" type="CrossmintAuthState">
  The current auth state snapshot.
</ResponseField>

<ResponseField name="stateListenable" type="ValueListenable<CrossmintAuthState>">
  Reactive handle on \[state] — suitable for \[ValueListenableBuilder].
</ResponseField>

<ResponseField name="states" type="Stream<CrossmintAuthState>">
  Stream of auth-state changes. Emits on every state mutation.
</ResponseField>

### Methods

<ResponseField name="restoreSession()" type="Future<void>">
  Reads any persisted session from \[CrossmintAuthStorage] and applies it to the client. Safe to call once per app launch — prefer using the result of `CrossmintClient.initialize` which calls this internally.
</ResponseField>

<ResponseField name="loginWithOAuth(provider)" type="Future<void>">
  Opens the Crossmint-hosted OAuth flow for \[provider] (Google, Twitter, etc.). The response comes back through \[CrossmintAuthCallbackRouter] — make sure it is started before calling this.

  <Expandable title="parameters">
    <ResponseField name="provider" type="CrossmintOAuthProvider" />
  </Expandable>
</ResponseField>

<ResponseField name="sendEmailOtp(email)" type="Future<CrossmintEmailOtpChallenge>">
  Requests the Crossmint API to send an email OTP to \[email]. Returns a challenge that \[confirmEmailOtp] completes.

  <Expandable title="parameters">
    <ResponseField name="email" type="String" />
  </Expandable>
</ResponseField>

<ResponseField name="confirmEmailOtp(email, emailId, token)" type="Future<bool>">
  Submits an email OTP challenge — pass the `emailId` from the challenge and the `token` the user entered. Returns `true` on success.

  <Expandable title="parameters">
    <ResponseField name="email" type="String" />

    <ResponseField name="emailId" type="String" />

    <ResponseField name="token" type="String" />
  </Expandable>
</ResponseField>

<ResponseField name="completeOAuth(callbackUri)" type="Future<bool>">
  Completes an OAuth flow from a deep-link callback URI. Normally invoked by \[CrossmintAuthCallbackRouter]; call directly only for custom routing.

  <Expandable title="parameters">
    <ResponseField name="callbackUri" type="Uri" />
  </Expandable>
</ResponseField>

<ResponseField name="completeOAuthWithOneTimeSecret(oneTimeSecret)" type="Future<bool>">
  Completes an OAuth flow from a one-time secret (SSR / server-mediated callbacks). Returns `true` on success.

  <Expandable title="parameters">
    <ResponseField name="oneTimeSecret" type="String" />
  </Expandable>
</ResponseField>

<ResponseField name="signInWithWallet(address, type)" type="Future<CrossmintWalletAuthChallenge>">
  Starts wallet-based authentication. Returns a challenge that the wallet must sign. \[type] is `'evm'` or `'solana'`.

  <Expandable title="parameters">
    <ResponseField name="address" type="String" />

    <ResponseField name="type" type="String" />
  </Expandable>
</ResponseField>

<ResponseField name="authenticateWallet(address, type, signature)" type="Future<bool>">
  Completes wallet-based authentication with the signed challenge.

  <Expandable title="parameters">
    <ResponseField name="address" type="String" />

    <ResponseField name="type" type="String" />

    <ResponseField name="signature" type="String" />
  </Expandable>
</ResponseField>

<ResponseField name="getSession()" type="Future<CrossmintAuthSession?>">
  Returns the current session (JWT + metadata), or `null` if not signed in. Does not hit the network — reads from in-memory state.
</ResponseField>

<ResponseField name="getUser(forceRefresh)" type="Future<CrossmintAuthenticatedUser?>">
  Returns the authenticated user's profile. Caches the result; pass `forceRefresh: true` to bypass the cache and refetch.

  <Expandable title="parameters">
    <ResponseField name="forceRefresh" type="bool" />
  </Expandable>
</ResponseField>

<ResponseField name="logout()" type="Future<void>">
  Signs the user out — clears persisted storage, cached session/user, and POSTs to the Crossmint (or custom) logout endpoint.
</ResponseField>

<ResponseField name="setJwt(jwt)" type="Future<void>">
  Sets a custom JWT for "Bring Your Own Auth" (BYOA) flows.

  <Expandable title="parameters">
    <ResponseField name="jwt" type="String?" />
  </Expandable>
</ResponseField>

### Usage

```dart theme={null}
import 'package:crossmint_flutter/crossmint_flutter_auth.dart';

client.auth.stateListenable.addListener(() {
  print('Auth state: ${client.auth.state}');
});

final challenge = await client.auth.sendEmailOtp('YOUR_USER_EMAIL');
await client.auth.confirmEmailOtp(
  email: 'YOUR_USER_EMAIL',
  emailId: challenge.id,
  token: 'YOUR_OTP_CODE',
);

await client.auth.loginWithOAuth(CrossmintOAuthProvider.google);

await client.auth.logout();
```

***

## CrossmintWalletController

Manages wallet lifecycle — creation, loading, signing, and OTP flows. Extends `ChangeNotifier` for reactive UI updates.

### Properties

<ResponseField name="client" type="CrossmintClient">
  The underlying client — exposed for code that needs direct access to sub-clients (auth, orders, credentials, etc.).

  <Expandable title="properties">
    <ResponseField name="config" type="CrossmintClientConfig">
      <Expandable title="properties">
        <ResponseField name="authStorage" type="CrossmintAuthStorage?">
          Custom session / token store. When null, the SDK uses `FlutterSecureStorage` under the hood.
        </ResponseField>

        <ResponseField name="logger" type="CrossmintLogger?">
          Custom logger sink. When null, the SDK uses a no-op logger in release and a `debugPrint`-backed logger in debug.
        </ResponseField>

        <ResponseField name="refreshRoute" type="Uri?">
          Optional custom server endpoint for token refresh.
        </ResponseField>

        <ResponseField name="logoutRoute" type="Uri?">
          Optional custom server endpoint for logout.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="auth" type="CrossmintAuthClient?" />

    <ResponseField name="wallets" type="CrossmintWalletsClient?" />

    <ResponseField name="credentials" type="CrossmintCredentialsClient?" />

    <ResponseField name="orders" type="CrossmintOrdersClient?" />

    <ResponseField name="tokens" type="CrossmintTokensClient?" />

    <ResponseField name="users" type="CrossmintUsersClient?" />

    <ResponseField name="transport" type="CrossmintTransport?" />

    <ResponseField name="authLauncher" type="CrossmintAuthLauncher?" />

    <ResponseField name="runtimeOverrides" type="CrossmintClientRuntimeOverrides?">
      <Expandable title="properties">
        <ResponseField name="authStorage" type="CrossmintAuthStorage?" />

        <ResponseField name="logger" type="CrossmintLogger?" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="config" type="CrossmintWalletControllerConfig">
  The configuration this controller was built with.

  <Expandable title="properties">
    <ResponseField name="createOnLogin" type="CrossmintCreateOnLoginConfig?">
      When set, the controller automatically creates (or loads) a wallet on the given chain once the user is authenticated. Fill `recovery` with the recovery signer config (e.g. `CrossmintEmailSignerConfig()`).
    </ResponseField>

    <ResponseField name="showOtpSignerPrompt" type="bool">
      Whether the SDK should surface the default OTP prompt automatically. Set to `false` to drive OTP UI yourself by listening to \[CrossmintWalletController.otp].
    </ResponseField>

    <ResponseField name="callbacks" type="CrossmintWalletLifecycleCallbacks?">
      Optional lifecycle hooks — see \[CrossmintWalletLifecycleCallbacks].

      <Expandable title="properties">
        <ResponseField name="onWalletCreationStart" type="Future<void> Function()?">
          Called immediately before the controller issues a `createWallet` API call. Await the returned future to block the operation until your UI is ready.
        </ResponseField>

        <ResponseField name="onTransactionStart" type="Future<void> Function()?">
          Called immediately before the controller issues a create-transaction API call. Await to block until your UI is ready.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="deviceSignerKeyStorage" type="DeviceSignerKeyStorage?">
      Storage adapter used to persist device-signer keys. Defaults to a secure-enclave / keystore-backed implementation on device.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="otp" type="CrossmintWalletOtpController">
  OTP controller for non-custodial email/phone signer challenges.
</ResponseField>

<ResponseField name="state" type="CrossmintWalletStateView">
  Read-only observation surface for the underlying wallet state. Advanced consumers can subscribe to wallet / status changes directly via this \[Listenable] while still routing all mutations through the controller's public API (`getWallet`, `createWallet`, `refresh`, `clear`, …).
</ResponseField>

<ResponseField name="currentWallet" type="CrossmintWallet?">
  The currently-loaded wallet, or `null` if none is loaded.

  <Expandable title="properties">
    <ResponseField name="id" type="String" />

    <ResponseField name="chain" type="String?" />

    <ResponseField name="address" type="String?" />

    <ResponseField name="owner" type="String?" />

    <ResponseField name="raw" type="CrossmintJsonMap" />
  </Expandable>
</ResponseField>

<ResponseField name="status" type="CrossmintWalletStatus">
  Current wallet lifecycle status.
</ResponseField>

<ResponseField name="onAuthRequired" type="CrossmintWalletAuthRequiredCallback">
  The auth-required callback the controller wires into every signer it builds. Exposed so apps building signers manually can share the same OTP-handling path.
</ResponseField>

<ResponseField name="pendingOtpChallenge" type="CrossmintOtpChallenge?">
  Shortcut to \[CrossmintWalletOtpController.pendingChallenge].

  <Expandable title="properties">
    <ResponseField name="signerType" type="String" />

    <ResponseField name="signerLocator" type="String" />
  </Expandable>
</ResponseField>

<ResponseField name="otpChallengeListenable" type="ValueListenable<CrossmintOtpChallenge?>">
  Shortcut to \[CrossmintWalletOtpController.challengeListenable].
</ResponseField>

<ResponseField name="requireCurrentWallet" type="CrossmintWallet">
  Returns the currently-loaded wallet or throws \[CrossmintWalletException] when none is loaded.

  <Expandable title="properties">
    <ResponseField name="id" type="String" />

    <ResponseField name="chain" type="String?" />

    <ResponseField name="address" type="String?" />

    <ResponseField name="owner" type="String?" />

    <ResponseField name="raw" type="CrossmintJsonMap" />
  </Expandable>
</ResponseField>

### Methods

<ResponseField name="getWallet(request)" type="Future<CrossmintWallet?>">
  Looks up an existing wallet and stores the result in controller state. Returns `null` when no wallet matches. Listeners fire on state changes.

  <Expandable title="parameters">
    <ResponseField name="request" type="CrossmintWalletLookupRequest" />
  </Expandable>
</ResponseField>

<ResponseField name="loadWallet(request)" type="Future<CrossmintWallet?>">
  Deprecated: use \[getWallet] instead.

  <Expandable title="parameters">
    <ResponseField name="request" type="CrossmintWalletLookupRequest" />
  </Expandable>
</ResponseField>

<ResponseField name="createWallet(request)" type="Future<CrossmintWallet>">
  Creates a new wallet and stores it in controller state. Validates passkey signers up-front via \[crossmintValidatePasskeySigners] and fires \[CrossmintWalletLifecycleCallbacks.onWalletCreationStart] if set.

  <Expandable title="parameters">
    <ResponseField name="request" type="CrossmintWalletCreateRequest" />
  </Expandable>
</ResponseField>

<ResponseField name="ensureLoaded()" type="Future<CrossmintWallet?>">
  Ensures a wallet is loaded, creating one if configured to do so.
</ResponseField>

<ResponseField name="refresh()" type="Future<CrossmintWallet?>">
  Re-fetches the currently-loaded wallet from the API. Returns `null` when nothing is loaded.
</ResponseField>

<ResponseField name="clear()" type="Future<void>">
  Drops the loaded wallet and any pending OTP challenge. Call during sign-out.
</ResponseField>

<ResponseField name="sendOtp()" type="Future<void>">
  Shortcut to \[CrossmintWalletOtpController.sendOtp].
</ResponseField>

<ResponseField name="verifyOtp(otpCode)" type="Future<void>">
  Shortcut to \[CrossmintWalletOtpController.verifyOtp].

  <Expandable title="parameters">
    <ResponseField name="otpCode" type="String" />
  </Expandable>
</ResponseField>

<ResponseField name="rejectOtp()" type="void">
  Shortcut to \[CrossmintWalletOtpController.reject].
</ResponseField>

<ResponseField name="createEvmWallet(signer, additionalSigners)" type="CrossmintEvmWallet">
  Wraps the currently-loaded wallet as a runtime \[CrossmintEvmWallet]. Throws \[CrossmintWalletException] if no wallet is loaded.

  <Expandable title="parameters">
    <ResponseField name="signer" type="CrossmintWalletApprovalSigner?" />

    <ResponseField name="additionalSigners" type="List<CrossmintWalletApprovalSigner>" />
  </Expandable>
</ResponseField>

<ResponseField name="createSolanaWallet(signer, additionalSigners)" type="CrossmintSolanaWallet">
  Wraps the currently-loaded wallet as a runtime \[CrossmintSolanaWallet]. On Solana, device signer support depends on the wallet type and is validated server-side. A default device signer is not auto-injected for Solana; it is registered reactively and falls back to the recovery signer when the server rejects it.

  <Expandable title="parameters">
    <ResponseField name="signer" type="CrossmintWalletApprovalSigner?" />

    <ResponseField name="additionalSigners" type="List<CrossmintWalletApprovalSigner>" />
  </Expandable>
</ResponseField>

<ResponseField name="createStellarWallet(signer, additionalSigners)" type="CrossmintStellarWallet">
  Wraps the currently-loaded wallet as a runtime \[CrossmintStellarWallet].

  <Expandable title="parameters">
    <ResponseField name="signer" type="CrossmintWalletApprovalSigner?" />

    <ResponseField name="additionalSigners" type="List<CrossmintWalletApprovalSigner>" />
  </Expandable>
</ResponseField>

<ResponseField name="createEvmWalletWithDeviceSigner(signerLocator, address, storage)" type="CrossmintEvmWallet">
  Builds a runtime EVM wallet backed by a hardware-backed device signer. Use for low-friction, day-to-day signing with keys in Secure Enclave / Android Keystore.

  <Expandable title="parameters">
    <ResponseField name="signerLocator" type="String" />

    <ResponseField name="address" type="String?" />

    <ResponseField name="storage" type="DeviceSignerKeyStorage?" />
  </Expandable>
</ResponseField>

<ResponseField name="createEvmWalletWithNonCustodialSigner(signerType, signerLocator, address, bridge)" type="CrossmintEvmWallet">
  Builds a runtime EVM wallet backed by a non-custodial email/phone signer. Requires \[CrossmintWalletHost] (or `CrossmintWalletProvider`) mounted in the widget tree.

  <Expandable title="parameters">
    <ResponseField name="signerType" type="String" />

    <ResponseField name="signerLocator" type="String" />

    <ResponseField name="address" type="String?" />

    <ResponseField name="bridge" type="HiddenSignerBridge?" />
  </Expandable>
</ResponseField>

<ResponseField name="createSolanaWalletWithNonCustodialSigner(signerType, signerLocator, address, bridge)" type="CrossmintSolanaWallet">
  Builds a runtime Solana wallet backed by a non-custodial email/phone signer. Requires a mounted wallet host.

  <Expandable title="parameters">
    <ResponseField name="signerType" type="String" />

    <ResponseField name="signerLocator" type="String" />

    <ResponseField name="address" type="String?" />

    <ResponseField name="bridge" type="HiddenSignerBridge?" />
  </Expandable>
</ResponseField>

<ResponseField name="createStellarWalletWithNonCustodialSigner(signerType, signerLocator, address, bridge)" type="CrossmintStellarWallet">
  Builds a runtime Stellar wallet backed by a non-custodial email/phone signer. Requires a mounted wallet host.

  <Expandable title="parameters">
    <ResponseField name="signerType" type="String" />

    <ResponseField name="signerLocator" type="String" />

    <ResponseField name="address" type="String?" />

    <ResponseField name="bridge" type="HiddenSignerBridge?" />
  </Expandable>
</ResponseField>

<ResponseField name="createStellarWalletWithDeviceSigner(signerLocator, address, storage)" type="CrossmintStellarWallet">
  Builds a runtime Stellar wallet backed by a hardware device signer.

  <Expandable title="parameters">
    <ResponseField name="signerLocator" type="String" />

    <ResponseField name="address" type="String?" />

    <ResponseField name="storage" type="DeviceSignerKeyStorage?" />
  </Expandable>
</ResponseField>

<ResponseField name="createEvmWalletWithExternalWalletSigner(address, signerLocator, onSign)" type="CrossmintEvmWallet">
  Builds a runtime EVM wallet backed by a user-owned external wallet (e.g. MetaMask). The caller supplies \[onSign] to perform signatures.

  <Expandable title="parameters">
    <ResponseField name="address" type="String" />

    <ResponseField name="signerLocator" type="String?" />

    <ResponseField name="onSign" type="CrossmintExternalWalletSignCallback" />
  </Expandable>
</ResponseField>

<ResponseField name="createSolanaWalletWithExternalWalletSigner(address, signerLocator, onSign)" type="CrossmintSolanaWallet">
  Builds a runtime Solana wallet backed by a user-owned external wallet.

  <Expandable title="parameters">
    <ResponseField name="address" type="String" />

    <ResponseField name="signerLocator" type="String?" />

    <ResponseField name="onSign" type="CrossmintExternalWalletSignCallback" />
  </Expandable>
</ResponseField>

<ResponseField name="createStellarWalletWithExternalWalletSigner(address, signerLocator, onSign)" type="CrossmintStellarWallet">
  Builds a runtime Stellar wallet backed by a user-owned external wallet.

  <Expandable title="parameters">
    <ResponseField name="address" type="String" />

    <ResponseField name="signerLocator" type="String?" />

    <ResponseField name="onSign" type="CrossmintExternalWalletSignCallback" />
  </Expandable>
</ResponseField>

<ResponseField name="createEvmWalletWithPasskeySigner(id, onSign)" type="CrossmintEvmWallet">
  Builds a runtime EVM wallet backed by a passkey signer.

  <Expandable title="parameters">
    <ResponseField name="id" type="String?" />

    <ResponseField name="onSign" type="Future<CrossmintPasskeySignResult> Function(String message)" />
  </Expandable>
</ResponseField>

<ResponseField name="createSolanaWalletWithPasskeySigner(id, onSign)" type="CrossmintSolanaWallet">
  Builds a runtime Solana wallet backed by a passkey signer. See \[createEvmWalletWithPasskeySigner] for passkey selection semantics.

  <Expandable title="parameters">
    <ResponseField name="id" type="String?" />

    <ResponseField name="onSign" type="Future<CrossmintPasskeySignResult> Function(String message)" />
  </Expandable>
</ResponseField>

<ResponseField name="createStellarWalletWithPasskeySigner(id, onSign)" type="CrossmintStellarWallet">
  Builds a runtime Stellar wallet backed by a passkey signer. See \[createEvmWalletWithPasskeySigner] for passkey selection semantics.

  <Expandable title="parameters">
    <ResponseField name="id" type="String?" />

    <ResponseField name="onSign" type="Future<CrossmintPasskeySignResult> Function(String message)" />
  </Expandable>
</ResponseField>

<ResponseField name="dispose()" type="void" />

<Note>
  The controller also provides chain-specific convenience factories that build
  the signer for you: `createEvmWalletWithDeviceSigner`,
  `createEvmWalletWithPasskeySigner`,
  `createEvmWalletWithExternalWalletSigner`,
  `createEvmWalletWithNonCustodialSigner`, and their Solana / Stellar
  counterparts.
</Note>

### Usage

```dart theme={null}
import 'package:crossmint_flutter/crossmint_flutter_controllers.dart';

final controller = client.createWalletController(
  CrossmintWalletControllerConfig(
    createOnLogin: CrossmintCreateOnLoginConfig(
      chain: 'base-sepolia',
      recovery: const CrossmintEmailSignerConfig(),
    ),
  ),
);

// Listen to status changes
controller.addListener(() {
  print('Status: ${controller.status}');
  final wallet = controller.currentWallet;
  if (wallet != null) {
    print('Address: ${wallet.address}');
  }
});

// Manual OTP handling
controller.otp.challengeListenable.addListener(() {
  final challenge = controller.otp.challengeListenable.value;
  if (challenge != null) {
    // Show your own OTP prompt UI
    // Then call: controller.otp.verifyOtp('123456');
  }
});
```

***

## CrossmintWallets

Stateless convenience facade for wallet operations. Mirrors the `CrossmintWallets` entry point used by the TS, Kotlin, and Swift SDKs. For reactive state management (e.g. listening to wallet changes in a widget tree), use `CrossmintWalletController` instead.

Unlike the controller, the facade does **not** auto-resolve signer configs. Callers must provide fully-resolved configs (e.g. include the email address in `CrossmintEmailSignerConfig`, or pre-create a device signer via `createDeviceSigner()`).

### Constructor

<ResponseField name="CrossmintWallets.from()" type="CrossmintWallets">
  Creates a `CrossmintWallets` facade backed by `client`.
</ResponseField>

### Methods

<ResponseField name="getWallet(chain, alias, plugins, recoverySigner)" type="Future<CrossmintRuntimeWalletBase>">
  Retrieves an existing wallet and returns a typed runtime wallet.

  <Expandable title="parameters">
    <ResponseField name="chain" type="String" />

    <ResponseField name="alias" type="String?" />

    <ResponseField name="plugins" type="List<String>" />

    <ResponseField name="recoverySigner" type="CrossmintSignerConfig?" />
  </Expandable>
</ResponseField>

<ResponseField name="createWallet(chain, recovery, signers, owner, alias, plugins)" type="Future<CrossmintRuntimeWalletBase>">
  Creates a new wallet and returns a typed runtime wallet.

  <Expandable title="parameters">
    <ResponseField name="chain" type="String" />

    <ResponseField name="recovery" type="CrossmintSignerConfig" />

    <ResponseField name="signers" type="List<CrossmintSignerConfig>" />

    <ResponseField name="owner" type="String?" />

    <ResponseField name="alias" type="String?" />

    <ResponseField name="plugins" type="List<String>" />
  </Expandable>
</ResponseField>

<ResponseField name="createDeviceSigner(storage, address)" type="Future<CrossmintDeviceSignerDescriptor>">
  Creates a device signer descriptor.

  <Expandable title="parameters">
    <ResponseField name="storage" type="DeviceSignerKeyStorage?" />

    <ResponseField name="address" type="String?" />
  </Expandable>
</ResponseField>

<ResponseField name="createPasskeySigner(name, config)" type="Future<CrossmintPasskeySignerConfig>">
  Creates a passkey signer configuration.

  <Expandable title="parameters">
    <ResponseField name="name" type="String" />

    <ResponseField name="config" type="CrossmintPasskeyConfig" />
  </Expandable>
</ResponseField>

### Usage

```dart theme={null}
import 'package:crossmint_flutter/crossmint_flutter_wallets.dart';

final wallets = CrossmintWallets.from(
  client,
  onAuthRequired: (challenge) {
    // Show your OTP prompt UI, then call challenge.verify(code)
  },
);

// Get an existing wallet
final wallet = await wallets.getWallet(chain: 'base-sepolia');
print('Address: ${wallet.address}');

// Create a new wallet
final newWallet = await wallets.createWallet(
  chain: 'base-sepolia',
  recovery: CrossmintEmailSignerConfig(email: 'YOUR_USER_EMAIL'),
);

// Send tokens
final tx = await newWallet.sendToken('RECIPIENT_WALLET_ADDRESS', 'usdc', '10');
```

***

## Wallet Methods

The runtime wallet instances returned by the controller provide methods for token transfers, balances, signing, and more.

### Properties

| Property | Type | Description |
| - | - | - |
| `wallet.client` | `CrossmintClient` | Top-level Crossmint client shared by all wallet operations. |
| `wallet.wallet` | `CrossmintWallet` | Server-issued wallet snapshot backing this runtime instance. |
| `wallet.deviceSignerKeyStorage` | `DeviceSignerKeyStorage?` | Storage backend for hardware-backed device signer keys. |
| `wallet.onAuthRequired` | `CrossmintSignerAuthRequiredCallback?` | Callback invoked when a signer operation requires user authentication. |
| `wallet.defaultChain` | `String` | Chain identifier used when the wallet snapshot has no explicit chain. |
| `wallet.chain` | `String` | Blockchain this wallet operates on (falls back to \[defaultChain]). |
| `wallet.address` | `String` | On-chain address of the wallet. |
| `wallet.owner` | `String?` | Owner identifier associated with the wallet, if any. |
| `wallet.recovery` | `CrossmintSignerConfig?` | Recovery (admin) signer config parsed from the wallet's backend state. |
| `wallet.locator` | `String` | Unique wallet locator used for API calls. |
| `wallet.signer` | `CrossmintWalletApprovalSigner?` | Currently active approval signer, or null if none is selected. |
| `wallet.additionalSigners` | `List<CrossmintWalletApprovalSigner>` | Secondary signers available alongside the primary \[signer]. |
| `wallet.needsRecovery` | `bool` | Whether the wallet needs recovery (signer registration) before the next transaction. |
| `wallet.canExportPrivateKey` | `bool` | Whether the active signer supports private-key export. |

### Methods

| Method | Description |
| - | - |
| `wallet.useSigner(signer)` | Sets the active signer for this wallet. Accepts a signer config object; the locator is inferred internally. Works for device, non-custodial, external-wallet, and passkey signers. |
| `wallet.balances(tokens)` | Returns the wallet balances — always includes USDC and the native token. Pass additional \[tokens] to request extra token balances. |
| `wallet.transactions()` | Lists transaction summaries for this wallet. |
| `wallet.transaction(transactionId)` | Retrieves details for a specific transaction by ID. |
| `wallet.approve(request)` | Approves a pending transaction or signature request. |
| `wallet.nfts(page, perPage)` | Returns the wallet's NFTs (paginated). |
| `wallet.fund(request)` | Initiates a funding (on-ramp) request for this wallet. |
| `wallet.transfers(page, perPage, tokens, status)` | Reads transfer history for this wallet (unstable API). |
| `wallet.send(request)` | Sends a token transfer and waits for confirmation. |
| `wallet.sendToken(to, token, amount)` | Convenience wrapper around \[send] for simple token transfers. |
| `wallet.signers()` | Lists all signers registered on this wallet with their current status. |
| `wallet.removeSigner(signerLocator)` | Removes a signer from the wallet by its locator. |
| `wallet.signerIsRegistered(signerLocator)` | Checks whether a signer with the given locator is registered. |
| `wallet.isSignerApproved(signerLocator)` | Checks whether a registered signer is approved and usable. |
| `wallet.addSigner(signer)` | Registers a new signer on the wallet and approves the registration. |
| `wallet.preAuthIfNeeded()` | Awaits any in-flight recovery; if `_needsRecovery` is set and no recovery is in-flight, starts one and awaits it. Concurrent callers coalesce onto the same future so a single recovery runs per wallet. |
| `wallet.recover()` | Runs device-signer recovery: resumes any pending operation or registers a new device signer using the recovery signer. Returns early if the device signer is already approved on-chain. |
| `wallet.exportPrivateKey(bridge)` | Exports the wallet's private key via the export signer bridge. |
| `wallet.approveTransactionAndWait(transactionId)` | Approves a pending transaction and polls until it reaches a terminal state. |
| `wallet.transactionApprovalPayload(transaction, pendingApproval, signer)` | Extracts the signable payload from a pending transaction approval. |
| `wallet.completeApprovedTransaction(transaction)` | Polls a transaction until it reaches a terminal state and attaches explorer links. |
| `wallet.waitForTransaction(transactionId)` | Polls a transaction by ID until it succeeds or fails. |
| `wallet.walletSnapshotForSigners()` | Fetches a fresh wallet snapshot to inspect registered signers. |
| `wallet.requireActiveSigner(operation)` | Returns the active signer or throws if none is selected. |

**Chain-specific methods:**

* **`CrossmintEvmWallet`** — `sendTransaction()`, `signMessage()`, `signTypedData()`
* **`CrossmintSolanaWallet`** — `sendTransaction()`
* **`CrossmintStellarWallet`** — `sendTransaction()`

### Usage

`controller.currentWallet` holds the loaded domain model. Signing, balance, and transaction methods live on the runtime wallet returned by `controller.createEvmWallet()` (or `createSolanaWallet` / `createStellarWallet`).

```dart theme={null}
if (controller.currentWallet == null) return;

final wallet = controller.createEvmWallet();

final balances = await wallet.balances(tokens: <String>['usdc']);
print('USDC: ${balances.usdc.amount}');
print('Native: ${balances.nativeToken.amount}');

final tx = await wallet.sendToken('RECIPIENT_WALLET_ADDRESS', 'usdc', '10');
print('Transaction: ${tx.id}');

final signature = await wallet.signMessage('Hello, Web3!');
print('Signature: $signature');
```


# CrossmintChain
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/enums/crossmint-chain

Flutter Enum

**Enum**

Supported Crossmint blockchain chains.

```dart theme={null}
enum CrossmintChain
```

This enum mirrors the chain identifiers used by the Crossmint API and the
official TypeScript SDK.  Each value carries an `apiValue` string sent over
the wire, a `family` discriminator (evm / solana / stellar), and a flag
indicating whether it targets a testnet.

Environment-aware validation is available via
`CrossmintChain.validateForEnvironment`.

## Constructors

### CrossmintChain

```dart theme={null}
const CrossmintChain(this.apiValue, this.family, {this.isTestnet = false})
```

## Properties

### apiValue

```dart theme={null}
final String apiValue
```

The string value sent to the Crossmint API (e.g. `'base-sepolia'`).

### family

```dart theme={null}
final CrossmintChainFamily family
```

Top-level chain family (evm, solana, stellar).

### isTestnet

```dart theme={null}
final bool isTestnet
```

Whether this chain targets a test network.

### isEvm

```dart theme={null}
bool get isEvm
```

`true` when this chain is an EVM network.

### isSolana

```dart theme={null}
bool get isSolana
```

`true` when this chain is a Solana network.

### isStellar

```dart theme={null}
bool get isStellar
```

`true` when this chain is a Stellar network.

## Static Methods

### fromApiValue

```dart theme={null}
static CrossmintChain fromApiValue(String value)
```

Reverse-lookup from an API string (e.g. `'polygon-amoy'`).

### tryFromApiValue

```dart theme={null}
static CrossmintChain? tryFromApiValue(String value)
```

Tries to parse an API string, returning `null` on failure.

## Functions

### ethereum

```dart theme={null}
ethereum('ethereum', CrossmintChainFamily.evm),
polygon('polygon', CrossmintChainFamily.evm),
bsc('bsc', CrossmintChainFamily.evm),
optimism('optimism', CrossmintChainFamily.evm),
arbitrum('arbitrum', CrossmintChainFamily.evm),
base('base', CrossmintChainFamily.evm),
zora('zora', CrossmintChainFamily.evm),
arbitrumNova('arbitrumnova', CrossmintChainFamily.evm),
astarZkevm('astar-zkevm', CrossmintChainFamily.evm),
chiliz('chiliz', CrossmintChainFamily.evm),
story('story', CrossmintChainFamily.evm),
mode('mode', CrossmintChainFamily.evm),
shape('shape', CrossmintChainFamily.evm),
worldchain('world-chain', CrossmintChainFamily.evm),
abstract_('abstract', CrossmintChainFamily.evm),
apechain('apechain', CrossmintChainFamily.evm),
mantle('mantle', CrossmintChainFamily.evm),
scroll('scroll', CrossmintChainFamily.evm),
seiPacific1('sei-pacific-1', CrossmintChainFamily.evm),
flow('flow', CrossmintChainFamily.evm),
plume('plume', CrossmintChainFamily.evm),
tempo('tempo', CrossmintChainFamily.evm),

// ---------------------------------------------------------------------------
// EVM — Testnet
// ---------------------------------------------------------------------------
arbitrumSepolia(
  'arbitrum-sepolia',
  CrossmintChainFamily.evm,
  isTestnet: true,
),
baseSepolia('base-sepolia', CrossmintChainFamily.evm, isTestnet: true),
bscTestnet('bsc-testnet', CrossmintChainFamily.evm, isTestnet: true),
ethereumSepolia(
  'ethereum-sepolia',
  CrossmintChainFamily.evm,
  isTestnet: true,
),
polygonAmoy('polygon-amoy', CrossmintChainFamily.evm, isTestnet: true),
optimismSepolia(
  'optimism-sepolia',
  CrossmintChainFamily.evm,
  isTestnet: true,
),
zoraSepolia('zora-sepolia', CrossmintChainFamily.evm, isTestnet: true),
hypersonicTestnet(
  'hypersonic-testnet',
  CrossmintChainFamily.evm,
  isTestnet: true,
),
storyTestnet('story-testnet', CrossmintChainFamily.evm, isTestnet: true),
modeSepolia('mode-sepolia', CrossmintChainFamily.evm, isTestnet: true),
abstractTestnet(
  'abstract-testnet',
  CrossmintChainFamily.evm,
  isTestnet: true,
),
curtis('curtis', CrossmintChainFamily.evm, isTestnet: true),
mantleSepolia('mantle-sepolia', CrossmintChainFamily.evm, isTestnet: true),
scrollSepolia('scroll-sepolia', CrossmintChainFamily.evm, isTestnet: true),
seiAtlantic2Testnet(
  'sei-atlantic-2-testnet',
  CrossmintChainFamily.evm,
  isTestnet: true,
),
worldchainSepolia(
  'world-chain-sepolia',
  CrossmintChainFamily.evm,
  isTestnet: true,
),
flowTestnet('flow-testnet', CrossmintChainFamily.evm, isTestnet: true),
plumeTestnet('plume-testnet', CrossmintChainFamily.evm, isTestnet: true),
arcTestnet('arc-testnet', CrossmintChainFamily.evm, isTestnet: true),
tempoTestnet('tempo-testnet', CrossmintChainFamily.evm, isTestnet: true),

// ---------------------------------------------------------------------------
// Solana
// ---------------------------------------------------------------------------
solana('solana', CrossmintChainFamily.solana),

// ---------------------------------------------------------------------------
// Stellar
// ---------------------------------------------------------------------------
stellar('stellar', CrossmintChainFamily.stellar)
```

### validateForEnvironment

```dart theme={null}
CrossmintChain validateForEnvironment({required bool isProduction})
```

Returns the chain adjusted for the given environment.

### toString

```dart theme={null}
String toString()
```


# CrossmintChainFamily
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/enums/crossmint-chain-family

Flutter Enum

**Enum**

Top-level blockchain family discriminator.

```dart theme={null}
enum CrossmintChainFamily
```


# CrossmintErrorCode
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/enums/crossmint-error-code

Flutter Enum

**Enum**

Typed error codes for programmatic exception handling.

```dart theme={null}
enum CrossmintErrorCode
```

Consumer code can `switch` on `CrossmintException.code` instead of parsing
string messages.  Codes are grouped by domain so related errors share a
common prefix (e.g. `signer*`, `wallet*`, `auth*`).


# CrossmintWalletStatus
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/enums/crossmint-wallet-status

Flutter Enum

**Enum**

Wallet lifecycle status matching the official Crossmint RN SDK wallet context. Exposed as the status surface of both `CrossmintWalletController` (via its getter) and the underlying `CrossmintWalletStateRepository` (the SSOT that owns the field).

```dart theme={null}
enum CrossmintWalletStatus
```


# Get Started
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/get-started

Install the Crossmint Flutter SDK and set up the client and wallet controller

### Latest Flutter SDK version - <a href="https://pub.dev/packages/crossmint_flutter"><img alt="pub.dev" /></a>

The Crossmint Flutter SDK (`crossmint_flutter`) provides a headless-first SDK with optional UI widgets for integrating Crossmint wallets and authentication into your Flutter application.

## Installation

```bash theme={null}
flutter pub add crossmint_flutter
```

## Client Setup

Initialize the `CrossmintClient` and set up authentication and wallet management. The controllers barrel re-exports the client and auth surfaces, so a single import is enough:

```dart main.dart theme={null}
import 'package:crossmint_flutter/crossmint_flutter_controllers.dart';

final client = CrossmintClient(
  config: CrossmintClientConfig(
    apiKey: 'YOUR_CLIENT_API_KEY',
    appScheme: 'YOUR_APP_SCHEME',
  ),
);

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await client.initialize();
  await client.auth.restoreSession();
  runApp(const MyApp());
}
```

## Provider Setup (Optional UI)

For apps using the provider pattern, wrap your application with `CrossmintWalletProvider`. Provider mode manages its own `CrossmintClient` internally — skip the [Client Setup](#client-setup) step above if you only use the provider.

```dart main.dart theme={null}
import 'package:flutter/material.dart';
import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: CrossmintWalletProvider(
        config: CrossmintWalletProviderConfig(
          clientConfig: CrossmintClientConfig(
            apiKey: 'YOUR_CLIENT_API_KEY',
            appScheme: 'YOUR_APP_SCHEME',
          ),
          walletControllerConfig: CrossmintWalletControllerConfig(
            createOnLogin: CrossmintCreateOnLoginConfig(
              chain: 'base-sepolia',
              recovery: const CrossmintEmailSignerConfig(),
            ),
            showOtpSignerPrompt: true,
          ),
        ),
        child: const HomeScreen(),
      ),
    );
  }
}
```

## Quick Example

Once the client is set up, use the wallet controller directly (headless) to access wallet state and react to status changes via `addListener`:

```dart theme={null}
import 'package:crossmint_flutter/crossmint_flutter_controllers.dart';
import 'package:flutter/foundation.dart';
import 'package:flutter/widgets.dart';

final client = CrossmintClient(
  config: CrossmintClientConfig(
    apiKey: 'YOUR_CLIENT_API_KEY',
    appScheme: 'YOUR_APP_SCHEME',
  ),
);

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await client.initialize();
  await client.auth.restoreSession();

  final walletController = client.createWalletController(
    CrossmintWalletControllerConfig(
      createOnLogin: CrossmintCreateOnLoginConfig(
        chain: 'base-sepolia',
        recovery: const CrossmintEmailSignerConfig(),
      ),
      showOtpSignerPrompt: true,
    ),
  );

  walletController.addListener(() {
    final wallet = walletController.currentWallet;
    if (wallet != null) {
      debugPrint('Address: ${wallet.address}');
      debugPrint('Chain: ${wallet.chain}');
    }
  });
}
```

Or using the provider pattern with widgets:

```dart theme={null}
import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

class WalletInfo extends StatelessWidget {
  const WalletInfo({super.key});

  @override
  Widget build(BuildContext context) {
    return CrossmintWalletStatusBuilder(
      builder: (context, data) {
        if (data.state.walletStatus == CrossmintWalletStatus.inProgress) {
          return const CircularProgressIndicator();
        }
        final wallet = data.state.currentWallet;
        if (wallet == null) {
          return const Text('No wallet loaded');
        }
        return Column(
          children: [
            Text('Address: ${wallet.address}'),
            Text('Chain: ${wallet.chain}'),
          ],
        );
      },
    );
  }
}
```

## Headless vs UI Imports

The Flutter SDK follows a headless-first design. Most apps only need the default barrel; reach for the granular barrels when you want to narrow the surface:

| Import | Description |
| - | - |
| `crossmint_flutter.dart` | Default headless entry point — re-exports client, auth, wallets, controllers, and runtime |
| `crossmint_client.dart` | Core client and configuration |
| `crossmint_flutter_auth.dart` | Authentication client and models |
| `crossmint_flutter_wallets.dart` | Wallet models and signer configs |
| `crossmint_flutter_controllers.dart` | Wallet controller (ChangeNotifier) |
| `crossmint_flutter_runtime.dart` | Runtime wallet classes (EVM, Solana, Stellar) |
| `crossmint_flutter_ui.dart` | Optional UI widgets (pulls in Material) |

## Next Steps

* [Providers](/sdk-reference/wallets/flutter/providers) — Configure providers and scopes
* [Controllers](/sdk-reference/wallets/flutter/controllers) — Manage wallet and auth state
* [Widgets](/sdk-reference/wallets/flutter/widgets) — Optional UI widgets
* [Wallet Methods](/sdk-reference/wallets/flutter/controllers#wallet-methods) — Send tokens, check balances, sign messages


# Providers
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/providers

Flutter providers and scopes for the Flutter SDK reference for Crossmint wallets

The Flutter SDK provides widget-based providers and scopes for integrating wallet functionality into your widget tree. These are optional — the SDK is headless-first and all features can be used directly via [controllers](/sdk-reference/wallets/flutter/controllers).

1. `CrossmintWalletProvider` — All-in-one provider (recommended)
2. `CrossmintClientScope` — Low-level client scope
3. `CrossmintAuthScope` — Low-level auth scope
4. `CrossmintWalletScope` — Low-level wallet scope

***

## CrossmintWalletProvider

All-in-one provider that initializes the client, auth, and wallet controller. Handles session restoration, OAuth callback routing, and OTP prompt display automatically. This is the recommended entry point for widget-based apps.

### Props

<ResponseField name="config" type="CrossmintWalletProviderConfig">
  The configuration this provider was built with.

  <Expandable title="properties">
    <ResponseField name="clientConfig" type="CrossmintClientConfig?">
      Config used to build a new \[CrossmintClient]. Mutually exclusive with \[dependencies].

      <Expandable title="properties">
        <ResponseField name="authStorage" type="CrossmintAuthStorage?">
          Custom session / token store. When null, the SDK uses `FlutterSecureStorage` under the hood.
        </ResponseField>

        <ResponseField name="logger" type="CrossmintLogger?">
          Custom logger sink. When null, the SDK uses a no-op logger in release and a `debugPrint`-backed logger in debug.
        </ResponseField>

        <ResponseField name="refreshRoute" type="Uri?">
          Optional custom server endpoint for token refresh.
        </ResponseField>

        <ResponseField name="logoutRoute" type="Uri?">
          Optional custom server endpoint for logout.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="walletControllerConfig" type="CrossmintWalletControllerConfig">
      Config for the wallet controller the provider creates.

      <Expandable title="properties">
        <ResponseField name="createOnLogin" type="CrossmintCreateOnLoginConfig?">
          When set, the controller automatically creates (or loads) a wallet on the given chain once the user is authenticated. Fill `recovery` with the recovery signer config (e.g. `CrossmintEmailSignerConfig()`).
        </ResponseField>

        <ResponseField name="showOtpSignerPrompt" type="bool">
          Whether the SDK should surface the default OTP prompt automatically. Set to `false` to drive OTP UI yourself by listening to \[CrossmintWalletController.otp].
        </ResponseField>

        <ResponseField name="callbacks" type="CrossmintWalletLifecycleCallbacks?">
          Optional lifecycle hooks — see \[CrossmintWalletLifecycleCallbacks].
        </ResponseField>

        <ResponseField name="deviceSignerKeyStorage" type="DeviceSignerKeyStorage?">
          Storage adapter used to persist device-signer keys. Defaults to a secure-enclave / keystore-backed implementation on device.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="dependencies" type="CrossmintWalletProviderDependencies?">
      Pre-built dependencies — use this when you want to share a client or controller between mount points. Mutually exclusive with \[clientConfig].

      <Expandable title="properties">
        <ResponseField name="client" type="CrossmintClient">
          An already-initialized client. The provider will not dispose this unless \[CrossmintWalletProviderConfig.disposeInjectedDependencies] is `true`.
        </ResponseField>

        <ResponseField name="walletController" type="CrossmintWalletController">
          An already-built wallet controller bound to \[client].
        </ResponseField>

        <ResponseField name="authCallbackRouter" type="CrossmintAuthCallbackRouter?">
          Optional pre-built callback router for OAuth deep links.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="disposeInjectedDependencies" type="bool">
      When the provider was handed pre-built dependencies, controls whether they are disposed alongside the provider. Defaults to `false` — the caller retains ownership.
    </ResponseField>

    <ResponseField name="authLinkProvider" type="CrossmintAuthLinkProvider?">
      Optional resolver for the OAuth callback URL. Leave null to use the default deep-link resolver.
    </ResponseField>

    <ResponseField name="startAuthCallbackRouter" type="bool">
      When `true` (default) the provider starts \[CrossmintAuthCallbackRouter] automatically so OAuth redirects land correctly.
    </ResponseField>

    <ResponseField name="autoLoadWallet" type="bool">
      When `true` (default) the provider triggers `ensureLoaded()` on the wallet controller once a session is detected.
    </ResponseField>

    <ResponseField name="jwt" type="String?">
      BYOA JWT — when supplied, the provider seeds `auth.setJwt(jwt)` on startup (Bring Your Own Auth). Apps not using BYOA can leave this null.
    </ResponseField>

    <ResponseField name="otpPromptBuilder" type="CrossmintOtpPromptBuilder?">
      Builder for the default OTP prompt UI — pass `crossmintDefaultOtpPromptBuilder` for the Material default. Leave null to drive OTP UI headlessly via `walletController.otp`.
    </ResponseField>

    <ResponseField name="mountBridgeHosts" type="bool">
      When `true` (default) the provider mounts `CrossmintWalletHost` so the hidden signer bridge has a place to run. Set to `false` only if your subtree already hosts the bridge.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="child" type="Widget">
  The subtree rendered once dependencies are ready. Pair with \[CrossmintWalletGate] to show a loading state until then.
</ResponseField>

### Usage

```dart theme={null}
import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: CrossmintWalletProvider(
        config: CrossmintWalletProviderConfig(
          clientConfig: CrossmintClientConfig(
            apiKey: 'YOUR_CLIENT_API_KEY',
            appScheme: 'myapp',
          ),
          walletControllerConfig: CrossmintWalletControllerConfig(
            createOnLogin: CrossmintCreateOnLoginConfig(
              chain: 'base-sepolia',
              recovery: const CrossmintEmailSignerConfig(),
            ),
            showOtpSignerPrompt: true,
          ),
          otpPromptBuilder: crossmintDefaultOtpPromptBuilder,
        ),
        child: const HomeScreen(),
      ),
    );
  }
}
```

***

## CrossmintWalletControllerConfig

Configuration for the wallet controller, used by both `CrossmintWalletProvider` and the headless `CrossmintClient.createWalletController()`.

<ResponseField name="createOnLogin" type="CrossmintCreateOnLoginConfig?">
  When set, the controller automatically creates (or loads) a wallet on the given chain once the user is authenticated. Fill `recovery` with the recovery signer config (e.g. `CrossmintEmailSignerConfig()`).
</ResponseField>

<ResponseField name="showOtpSignerPrompt" type="bool">
  Whether the SDK should surface the default OTP prompt automatically. Set to `false` to drive OTP UI yourself by listening to \[CrossmintWalletController.otp].
</ResponseField>

<ResponseField name="callbacks" type="CrossmintWalletLifecycleCallbacks?">
  Optional lifecycle hooks — see \[CrossmintWalletLifecycleCallbacks].

  <Expandable title="properties">
    <ResponseField name="onWalletCreationStart" type="Future<void> Function()?">
      Called immediately before the controller issues a `createWallet` API call. Await the returned future to block the operation until your UI is ready.
    </ResponseField>

    <ResponseField name="onTransactionStart" type="Future<void> Function()?">
      Called immediately before the controller issues a create-transaction API call. Await to block until your UI is ready.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="deviceSignerKeyStorage" type="DeviceSignerKeyStorage?">
  Storage adapter used to persist device-signer keys. Defaults to a secure-enclave / keystore-backed implementation on device.
</ResponseField>

***

## CrossmintClientScope

Low-level scope that provides a `CrossmintClient` instance to the widget subtree.

Access the client from descendant widgets:

```dart theme={null}
final client = CrossmintClientScope.of(context);
```

### Usage

```dart theme={null}
import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

CrossmintClientScope(
  config: CrossmintClientConfig(
    apiKey: 'YOUR_CLIENT_API_KEY',
    appScheme: 'myapp',
  ),
  child: const MyApp(),
)
```

***

## CrossmintAuthScope

Provides the auth client to the widget subtree. Must be nested inside a `CrossmintClientScope`.

### Usage

```dart theme={null}
CrossmintClientScope(
  config: CrossmintClientConfig(apiKey: 'YOUR_CLIENT_API_KEY'),
  child: CrossmintAuthScope(
    child: const LoginScreen(),
  ),
)
```

***

## CrossmintWalletScope

Provides the wallet controller to the widget subtree. Must be nested inside a `CrossmintClientScope`.

### Usage

```dart theme={null}
CrossmintClientScope(
  config: CrossmintClientConfig(apiKey: 'YOUR_CLIENT_API_KEY'),
  child: CrossmintWalletScope(
    config: CrossmintWalletControllerConfig(
      createOnLogin: CrossmintCreateOnLoginConfig(
        chain: 'base-sepolia',
        recovery: const CrossmintEmailSignerConfig(),
      ),
    ),
    child: const WalletScreen(),
  ),
)
```

***

## CrossmintWalletGate

Status-based widget that renders different builders depending on the wallet state. Must be used within a `CrossmintWalletProvider` or `CrossmintWalletScope`.

All builders receive a `CrossmintWalletContextData` object, which provides access to the current state, auth client, wallet controller, and actions.

### Props

<ResponseField name="readyBuilder" type="CrossmintWalletGateBuilder" />

<ResponseField name="initializingBuilder" type="CrossmintWalletGateBuilder?" />

<ResponseField name="unauthenticatedBuilder" type="CrossmintWalletGateBuilder?" />

<ResponseField name="errorBuilder" type="CrossmintWalletGateBuilder?" />

### Usage

```dart theme={null}
CrossmintWalletGate(
  readyBuilder: (context, data) {
    // readyBuilder fires once authenticated — the wallet may
    // still be loading. Guard on hasWallet before accessing it.
    if (!data.state.hasWallet) {
      return const Center(child: CircularProgressIndicator());
    }
    return DashboardScreen(wallet: data.state.currentWallet!);
  },
  unauthenticatedBuilder: (context, data) => const LoginScreen(),
  initializingBuilder: (context, data) => const Center(
    child: CircularProgressIndicator(),
  ),
)
```


# CrossmintExportPrivateKeyButtonBuilder
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/type-aliases/crossmint-export-private-key-button-builder

Flutter Type Alias

**Type Alias**

Builder signature for the visual of `CrossmintExportPrivateKeyButton`. The widget owns the loading state and the eligibility check; the builder receives `isLoading` and `onExport` so the consumer can render any tap target that fits their design system. `onExport` is `null` while the export is in flight so a consumer button (e.g. `ElevatedButton`) is automatically disabled without a separate mounted check.

```dart theme={null}
typedef CrossmintExportPrivateKeyButtonBuilder = Widget Function( BuildContext context, { required bool isLoading, required VoidCallback? onExport, })
```


# CrossmintExternalWalletSignCallback
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/type-aliases/crossmint-external-wallet-sign-callback

Flutter Type Alias

**Type Alias**

Callback signature for user-owned external-wallet signers.

```dart theme={null}
typedef CrossmintExternalWalletSignCallback = Future<String> Function(String payload)
```

Receives the payload to sign (hex-encoded for EVM, base58-encoded for
Solana, base64-encoded transaction blob for Stellar) and returns the
user-produced signature in the same encoding. Implementations typically
delegate to a wallet SDK like WalletConnect, MetaMask Flask, or a
platform-native wallet adapter.


# CrossmintOtpPromptBuilder
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/type-aliases/crossmint-otp-prompt-builder

Flutter Type Alias

**Type Alias**

Builds a widget that owns the OTP signer prompt UI for the wallet provider.

```dart theme={null}
typedef CrossmintOtpPromptBuilder = Widget Function( BuildContext context, CrossmintWalletOtpController otpController, Widget child, )
```

The provider invokes this builder when its wallet controller has a pending
OTP challenge so that consumers can render the prompt with their own design
system. Pass `crossmintDefaultOtpPromptBuilder` (from
`crossmint_flutter_ui.dart`) for the Material default that mirrors the
React Native SDK; supply a custom builder for headless integrations.


# CrossmintOtpRejectCallback
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/type-aliases/crossmint-otp-reject-callback

Flutter Type Alias

**Type Alias**

Called to cancel a pending OTP challenge, optionally with an error cause.

```dart theme={null}
typedef CrossmintOtpRejectCallback = void Function([Object? error])
```


# CrossmintOtpSendCallback
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/type-aliases/crossmint-otp-send-callback

Flutter Type Alias

**Type Alias**

Called by non-custodial signers to (re-)send an OTP to the user.

```dart theme={null}
typedef CrossmintOtpSendCallback = Future<void> Function()
```


# CrossmintOtpVerifyCallback
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/type-aliases/crossmint-otp-verify-callback

Flutter Type Alias

**Type Alias**

Called by non-custodial signers to verify the OTP the user entered.

```dart theme={null}
typedef CrossmintOtpVerifyCallback = Future<void> Function(String otp)
```


# CrossmintSignerAuthRequiredCallback
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/type-aliases/crossmint-signer-auth-required-callback

Flutter Type Alias

**Type Alias**

Callback fired when a non-custodial signer needs the user to authenticate.

```dart theme={null}
typedef CrossmintSignerAuthRequiredCallback = Future<void> Function( String signerType, String signerLocator, bool needsAuth, CrossmintOtpSendCallback sendOtp, CrossmintOtpVerifyCallback verifyOtp, CrossmintOtpRejectCallback reject, )
```

The SDK passes:

* `signerType` — `"email"` or `"phone"`.
* `signerLocator` — the identifier (email or phone number in E.164 form).
* `needsAuth` — `true` when the challenge starts, `false` when it ends
  (e.g. after a successful verify).
* `sendOtp` / `verifyOtp` / `reject` — callbacks that drive the flow.

Implementers show a UI prompt, call `sendOtp` to trigger delivery, then
`verifyOtp(code)` on submission or `reject()` on cancel. The
`CrossmintWalletController.otp` controller provides a ready-made
implementation that marshalls the challenge through a
`ValueListenable` — use that unless you need bespoke wiring.


# Widgets
Source: https://docs.crossmint.com/sdk-reference/wallets/flutter/widgets

Flutter widgets for the Flutter SDK reference for Crossmint wallets

The Flutter SDK provides optional UI widgets that can be imported from `crossmint_flutter_ui.dart`. These pull in Material Design dependencies — if you prefer a fully headless approach, use the [controllers](/sdk-reference/wallets/flutter/controllers) directly.

***

## CrossmintWalletStatusBuilder

Reactive widget that rebuilds whenever the wallet status or instance changes.

### Props

<ResponseField name="builder" type="CrossmintWalletStatusWidgetBuilder" />

### Usage

```dart theme={null}
import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

CrossmintWalletStatusBuilder(
  builder: (context, data) {
    switch (data.state.walletStatus) {
      case CrossmintWalletStatus.inProgress:
        return const CircularProgressIndicator();
      case CrossmintWalletStatus.loaded:
        return Text('Address: ${data.state.currentWallet!.address}');
      default:
        return const Text('No wallet');
    }
  },
)
```

***

## CrossmintWalletConsumer

Provides access to the wallet context data from the widget tree.

### Usage

```dart theme={null}
CrossmintWalletConsumer(
  builder: (context, data) {
    return ElevatedButton(
      onPressed: () async {
        final wallet = data.state.currentWallet;
        final balances = await wallet?.balances();
        print('Balances: $balances');
      },
      child: const Text('Check Balances'),
    );
  },
)
```

***

## CrossmintOtpSignerListener

Automatically listens for OTP challenges and shows the appropriate dialog. This is a Flutter advantage over React Native — OTP prompts are handled declaratively.

### Props

<ResponseField name="otpController" type="CrossmintWalletOtpController" />

<ResponseField name="child" type="Widget" />

<ResponseField name="enabled" type="bool" />

<ResponseField name="barrierDismissible" type="bool" />

### Usage

```dart theme={null}
CrossmintOtpSignerListener(
  otpController: walletController.otp,
  child: const WalletScreen(),
)
```

***

## CrossmintExportPrivateKeyButton

Renders a button that allows the user to export their wallet's private key. Only works with email and phone signers. Will not render for passkey or external wallet signers.

### Props

<ResponseField name="wallet" type="CrossmintRuntimeWalletBase">
  Wallet whose private key will be exported. The button only renders when \[CrossmintRuntimeWalletBase.canExportPrivateKey] is true (email/phone signer wallets).

  <Expandable title="properties">
    <ResponseField name="client" type="CrossmintClient">
      Top-level Crossmint client shared by all wallet operations.

      <Expandable title="properties">
        <ResponseField name="config" type="CrossmintClientConfig" />

        <ResponseField name="auth" type="CrossmintAuthClient?" />

        <ResponseField name="wallets" type="CrossmintWalletsClient?" />

        <ResponseField name="credentials" type="CrossmintCredentialsClient?" />

        <ResponseField name="orders" type="CrossmintOrdersClient?" />

        <ResponseField name="tokens" type="CrossmintTokensClient?" />

        <ResponseField name="users" type="CrossmintUsersClient?" />

        <ResponseField name="transport" type="CrossmintTransport?" />

        <ResponseField name="authLauncher" type="CrossmintAuthLauncher?" />

        <ResponseField name="runtimeOverrides" type="CrossmintClientRuntimeOverrides?" />
      </Expandable>
    </ResponseField>

    <ResponseField name="wallet" type="CrossmintWallet">
      Server-issued wallet snapshot backing this runtime instance.

      <Expandable title="properties">
        <ResponseField name="id" type="String" />

        <ResponseField name="chain" type="String?" />

        <ResponseField name="address" type="String?" />

        <ResponseField name="owner" type="String?" />

        <ResponseField name="raw" type="CrossmintJsonMap" />
      </Expandable>
    </ResponseField>

    <ResponseField name="recoverySigner" type="CrossmintSignerConfig?" />

    <ResponseField name="signer" type="CrossmintWalletApprovalSigner?" />

    <ResponseField name="additionalSigners" type="List<CrossmintWalletApprovalSigner>" />

    <ResponseField name="deviceSignerKeyStorage" type="DeviceSignerKeyStorage?">
      Storage backend for hardware-backed device signer keys.
    </ResponseField>

    <ResponseField name="onAuthRequired" type="CrossmintSignerAuthRequiredCallback?">
      Callback invoked when a signer operation requires user authentication.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="onExported" type="VoidCallback?">
  Called after the export flow completes successfully.
</ResponseField>

<ResponseField name="onError" type="void Function(Object error)?">
  Called when the export flow throws. Receives the underlying exception so consumers can surface a localized error message.
</ResponseField>

<ResponseField name="childBuilder" type="CrossmintExportPrivateKeyButtonBuilder?">
  Optional builder for the button visual. When `null`, falls back to the React Native parity Material `OutlinedButton` with a themed `CircularProgressIndicator` while the export is in flight. When non-null, the builder is invoked whenever the wallet is eligible to export and receives the current `isLoading` flag plus an `onExport` callback that the consumer wires to their own tap target. The `onExport` callback is `null` while loading so consumers can disable their button directly without a separate mounted check.
</ResponseField>

### Usage

```dart theme={null}
import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

CrossmintExportPrivateKeyButton(
  wallet: wallet,
  onExported: () => print('Key exported'),
)
```

***

## CrossmintWalletUiState (`data.state`)

The `state` exposed on `CrossmintWalletContextData` (the second argument of every builder). Fields and convenience getters:

| Field / getter | Type | Description |
| - | - | - |
| `isInitializing` | `bool` | |
| `isLoadingWallet` | `bool` | |
| `authState` | `CrossmintAuthState` | |
| `walletStatus` | `CrossmintWalletStatus` | |
| `currentWallet` | `CrossmintWallet?` | |
| `pendingOtpChallenge` | `CrossmintOtpChallenge?` | |
| `initializationError` | `Object?` | |
| `walletError` | `Object?` | |
| `isAuthenticated` | `bool` | |
| `isLoggedOut` | `bool` | |
| `user` | `CrossmintAuthenticatedUser?` | |
| `authErrorMessage` | `String?` | |
| `error` | `Object?` | |
| `errorMessage` | `String?` | |
| `hasWallet` | `bool` | |
| `needsOtp` | `bool` | |


# AndroidCrossmintTEE
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/classes/android-crossmint-tee

Kotlin Class

**Class**

```kotlin theme={null}
class AndroidCrossmintTEE : CrossmintTEE
```

## Properties

| Property | Type | Description |
| - | - | - |
| `isHandshakeCompleted` | `Boolean` | Indicates whether the handshake with the TEE service has been completed. Handshake must be completed before performing cryptographic operations. |
| `isOTPRequired` | `StateFlow<Boolean>` | Observable state indicating whether the OTP prompt should be shown. |

## Functions

| Function | Description |
| - | - |
| `awaitReady` | Blocks continuation until a successful TEE load has completed. This method must be called before any signing operations. |
| `cancelOTP` | Cancels the signing request that waits for an OTP. The request fails with TEEError.UserCancelled. isOTPRequired changes to false. |
| `getWebView` | - |
| `performHandshake` | Performs the TEE handshake protocol. This is called automatically by load(). |
| `provideOTP` | Provides the OTP code from the user to the TEE flow. |
| `signTransaction` | - |

### awaitReady

```kotlin theme={null}
open suspend override fun awaitReady()
```

Blocks continuation until a successful TEE load has completed. This method must be called before any signing operations.

### cancelOTP

```kotlin theme={null}
open override fun cancelOTP()
```

Cancels the signing request that waits for an OTP. The request fails with TEEError.UserCancelled. isOTPRequired changes to false.

### getWebView

```kotlin theme={null}
fun getWebView(): WebView?
```

### performHandshake

```kotlin theme={null}
open suspend override fun performHandshake(): Result<Unit, TEEError>
```

Performs the TEE handshake protocol. This is called automatically by load().

### provideOTP

```kotlin theme={null}
open override fun provideOTP(code: String)
```

Provides the OTP code from the user to the TEE flow.

### signTransaction

```kotlin theme={null}
open suspend override fun signTransaction(messageBytes: String, keyType: String, encoding: String, otpAuth: String, channel: OTPDeliveryChannel?): Result<String, TEEError>
```


# AndroidPasskeyProvider
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/classes/android-passkey-provider

Kotlin Class

**Class**

```kotlin theme={null}
class AndroidPasskeyProvider(rpId: String) : PasskeyProvider
```

## Constructors

```kotlin theme={null}
constructor(rpId: String)
```

## Functions

| Function | Description |
| - | - |
| `signWithPasskey` | - |

### signWithPasskey

```kotlin theme={null}
open suspend override fun signWithPasskey(challenge: String, credentialId: String): Result<PasskeySignResult, PasskeyError>
```


# AndroidWebViewBridge
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/classes/android-web-view-bridge

Kotlin Class

**Class**

```kotlin theme={null}
class AndroidWebViewBridge(context: Context, logger: Logger = Deps.logger) : WebViewBridge
```

## Constructors

```kotlin theme={null}
constructor(context: Context, logger: Logger = Deps.logger)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `isLoaded` | `StateFlow<Boolean>` | - |
| `messages` | `SharedFlow<WebViewMessage>` | - |

## Functions

| Function | Description |
| - | - |
| `getWebView` | - |
| `loadUrl` | - |
| `sendMessage` | - |

### getWebView

```kotlin theme={null}
fun getWebView(): WebView?
```

### loadUrl

```kotlin theme={null}
open suspend override fun loadUrl(url: String, timeout: Duration)
```

### sendMessage

```kotlin theme={null}
open suspend override fun sendMessage(message: String)
```


# AuthSessionStore
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/classes/auth-session-store

Kotlin Class

**Class**

```kotlin theme={null}
class AuthSessionStore : SessionStore
```

## Constructors

```kotlin theme={null}
constructor()
```

## Functions

| Function | Description |
| - | - |
| `clear` | - |
| `token` | - |
| `update` | - |

### clear

```kotlin theme={null}
open suspend override fun clear()
```

### token

```kotlin theme={null}
open suspend override fun token(): AuthToken?
```

### update

```kotlin theme={null}
open suspend override fun update(token: AuthToken?)
```


# Crossmint
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/classes/crossmint

Kotlin Class

<Warning>Deprecated. Use CrossmintSDK.configure() and CrossmintSDK.shared instead.</Warning>

**Class**

```kotlin theme={null}
class Crossmint
```

## Constructors

```kotlin theme={null}
constructor()
```


# CrossmintAuthManager
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/classes/crossmint-auth-manager

Kotlin Class

**Class**

```kotlin theme={null}
class CrossmintAuthManager
```

## Properties

| Property | Type | Description |
| - | - | - |
| `authState` | `StateFlow<Result>` | The current authentication state, updated as the user signs in, out, or the token refreshes. |

## Functions

| Function | Description |
| - | - |
| `authenticateWithToken` | Establishes a session directly from an existing AuthToken, skipping the OTP flow. |
| `getJWT` | - |
| `logout` | - |
| `sendOtp` | Sends a one-time password to the given email to begin Crossmint-managed sign-in. |
| `setJWT` | - |
| `verifyOtp` | Verifies the code the user received and establishes a session on success. |

### authenticateWithToken

```kotlin theme={null}
suspend fun authenticateWithToken(token: Result): Result<Unit, Result>
```

Establishes a session directly from an existing AuthToken, skipping the OTP flow.

### getJWT

```kotlin theme={null}
open suspend fun getJWT(): String?
```

### logout

```kotlin theme={null}
open suspend fun logout()
```

### sendOtp

```kotlin theme={null}
suspend fun sendOtp(email: String): Result<Result, Result>
```

Sends a one-time password to the given email to begin Crossmint-managed sign-in.

### setJWT

```kotlin theme={null}
open fun setJWT(jwt: String)
```

### verifyOtp

```kotlin theme={null}
suspend fun verifyOtp(email: String, code: String): Result<Result, Result>
```

Verifies the code the user received and establishes a session on success.


# CrossmintSDK
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/classes/crossmint-sdk

Kotlin Class

**Class**

```kotlin theme={null}
class CrossmintSDK
```

## Properties

| Property | Type | Description |
| - | - | - |
| `apiKey` | `Result` | The resolved API key and environment for this instance |
| `authManager` | `Result` | Provides the current user's JWT token |
| `isOTPRequired` | `Flow<Boolean>` | Emits true whenever an email or phone signer is waiting for an OTP to be submitted. |
| `wallets` | `Result` | Entry point for all wallet operations |

## Functions

| Function | Description |
| - | - |
| `cancelTransaction` | Cancels the signing request that waits for an OTP. |
| `logout` | Signs the user out and clears all stored auth state. |
| `setJWT` | Stores an externally obtained JWT for use in all subsequent API calls. |
| `submit` | Provides the OTP entered by the user to the active email or phone signer. |

### cancelTransaction

```kotlin theme={null}
suspend fun cancelTransaction()
```

Cancels the signing request that waits for an OTP.

### logout

```kotlin theme={null}
suspend fun logout()
```

Signs the user out and clears all stored auth state.

### setJWT

```kotlin theme={null}
fun setJWT(jwt: String)
```

Stores an externally obtained JWT for use in all subsequent API calls.

### submit

```kotlin theme={null}
suspend fun submit(otp: String)
```

Provides the OTP entered by the user to the active email or phone signer.


# DelegatedSigner.PasskeyActivation
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/classes/delegated-signer-passkey-activation

Kotlin Class

**Class**

```kotlin theme={null}
class PasskeyActivation(val locator: String, val onSignWithPasskey: suspend (String) -> PasskeySignResult, val expiresAt: Long? = null) : DelegatedSigner
```

## Constructors

```kotlin theme={null}
constructor(locator: String, onSignWithPasskey: suspend (String) -> PasskeySignResult, expiresAt: Long? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `expiresAt` | `Long?` | Optional expiration timestamp in milliseconds since Unix epoch. If set, the delegated signer will expire at this time. |
| `locator` | `String` | - |
| `onSignWithPasskey` | `suspend (String) -> PasskeySignResult` | - |


# DeviceSignerStorageFactory
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/classes/device-signer-storage-factory

Kotlin Class

**Class**

```kotlin theme={null}
class DeviceSignerStorageFactory
```

## Functions

| Function | Description |
| - | - |
| `create` | - |

### create

```kotlin theme={null}
expect fun create(): DeviceSignerKeyStorage?
```

```kotlin theme={null}
fun create(context: Context): DeviceSignerKeyStorage
```


# EncryptedSharedPreferenceStorage
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/classes/encrypted-shared-preference-storage

Kotlin Class

**Class**

```kotlin theme={null}
class EncryptedSharedPreferenceStorage(context: Context) : SessionStore
```

## Constructors

```kotlin theme={null}
constructor(context: Context)
```

## Functions

| Function | Description |
| - | - |
| `clear` | - |
| `token` | - |
| `update` | - |

### clear

```kotlin theme={null}
open suspend override fun clear()
```

### token

```kotlin theme={null}
open suspend override fun token(): AuthToken?
```

### update

```kotlin theme={null}
open suspend override fun update(token: AuthToken?)
```


# EVMWallet
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/classes/evm-wallet

Kotlin Class

**Class**

```kotlin theme={null}
class EVMWallet : Wallet
```

## Properties

| Property | Type | Description |
| - | - | - |
| `address` | `String` | The blockchain address of the wallet |
| `chain` | `Chain` | The specific blockchain this wallet lives on |
| `chainType` | `ChainType` | - |
| `config` | `WalletConfig` | The wallet configuration including admin signer. WalletConfig.recoveryMethods and WalletConfig.adminSigner show the changes that you make with Wallet.addRecoveryMethod and Wallet.removeRecoveryMethod. |
| `evmChain` | `EVMChain` | The specific EVM chain this wallet lives on |
| `owner` | `Owner?` | The owner of the wallet, if available |
| `type` | `WalletType` | The type of wallet (smart wallet or MPC wallet) |

## Functions

| Function | Description |
| - | - |
| `addRecoveryMethod` | Adds a recovery method to this wallet. The function returns when the change is complete. |
| `addSigner` | Registers a new delegated signer on this wallet, choosing when it is deployed on-chain. Does not change the active signer. |
| `approve` | Signs a transaction that is in AWAITING\_APPROVAL status. |
| `balances` | Gets the wallet balances. |
| `fund` | Funds the wallet with test tokens (staging only). |
| `getSigner` | Returns the current signer for this wallet. |
| `getTransaction` | Retrieves a transaction by its ID. |
| `isSignerApproved` | Returns true if the given signer is approved on this wallet's chain. |
| `listTransactions` | Lists all transactions for this wallet. |
| `listTransfers` | Lists transfers for this wallet. |
| `localDeviceSignerLocator` | Returns the locator of the device signer that lives on this device. Returns null if this wallet has no device signer on this device. |
| `needsRecovery` | Returns true when a device signer was configured for this wallet but no matching hardware key exists on the current device. |
| `nfts` | Lists NFTs held by this wallet. Supported on EVM and Solana chains. |
| `recover` | Generates a new hardware key on this device and registers it on the wallet using the admin/recovery signer approval flow. |
| `removeRecoveryMethod` | Removes a recovery method from this wallet. The function returns when the change is complete. |
| `removeSigner` | Removes a delegated signer from this wallet. Supported types: DelegatedSigner.Email, DelegatedSigner.Phone, DelegatedSigner.ExternalWallet, DelegatedSigner.Locator, DelegatedSigner.Passkey. |
| `send` | Sends tokens to a recipient address. |
| `sendTransaction` | Submits a raw transaction and polls until it reaches a terminal state. |
| `signerIsRegistered` | Checks if the signer is registered on this wallet. |
| `signers` | Fetches the live list of signers registered on this wallet. |
| `signMessage` | Signs a message with this wallet (EIP-191). |
| `signTypedData` | Signs EIP-712 typed data with this wallet. |
| `useRecoveryMethod` | Selects the recovery method that approves changes to this wallet's signers and recovery methods. |
| `useSigner` | Sets the active signer for subsequent send and approve operations. |
| `withSigner` | Creates a new Wallet instance that uses the specified signer for transactions. |

### addRecoveryMethod

```kotlin theme={null}
suspend fun addRecoveryMethod(recoveryMethod: DelegatedSigner): Result<Unit, WalletError>
```

Adds a recovery method to this wallet. The function returns when the change is complete.

### addSigner

```kotlin theme={null}
suspend fun addSigner(signer: DelegatedSigner, deployImmediately: Boolean): Result<Unit, WalletError>
```

Registers a new delegated signer on this wallet, choosing when it is deployed on-chain. Does not change the active signer.

```kotlin theme={null}
suspend fun addSigner(signer: DelegatedSigner, approver: DelegatedSigner? = null): Result<Unit, WalletError>
```

Registers a new delegated signer on this wallet via the recovery/approval flow. Does not change the active signer.

### approve

```kotlin theme={null}
suspend fun approve(transactionId: String, signer: SignerSelection = SignerSelection.Admin): Result<Transaction, TransactionError>
```

Signs a transaction that is in AWAITING\_APPROVAL status.

### balances

```kotlin theme={null}
suspend fun balances(tokens: List<String> = emptyList()): Result<Balances, BalanceError>
```

Gets the wallet balances.

### fund

```kotlin theme={null}
suspend fun fund(token: String, amount: Int, chain: String): Result<Unit, BalanceError>
```

Funds the wallet with test tokens (staging only).

### getSigner

```kotlin theme={null}
fun getSigner(): Signer?
```

Returns the current signer for this wallet.

### getTransaction

```kotlin theme={null}
suspend fun getTransaction(transactionId: String): Result<Transaction, TransactionError>
```

Retrieves a transaction by its ID.

### isSignerApproved

```kotlin theme={null}
suspend fun isSignerApproved(locator: String): Result<Boolean, WalletError>
```

Returns true if the given signer is approved on this wallet's chain.

### listTransactions

```kotlin theme={null}
suspend fun listTransactions(): Result<List<Transaction>, TransactionError>
```

Lists all transactions for this wallet.

### listTransfers

```kotlin theme={null}
suspend fun listTransfers(tokens: List<String> = emptyList()): Result<TransferList, TransferError>
```

Lists transfers for this wallet.

### localDeviceSignerLocator

```kotlin theme={null}
suspend fun localDeviceSignerLocator(): DelegatedSignerData?
```

Returns the locator of the device signer that lives on this device. Returns null if this wallet has no device signer on this device.

### needsRecovery

```kotlin theme={null}
suspend fun needsRecovery(): Boolean
```

Returns true when a device signer was configured for this wallet but no matching hardware key exists on the current device.

### nfts

```kotlin theme={null}
suspend fun nfts(page: Int = 1, perPage: Int = 20): Result<List<NFT>, WalletError>
```

Lists NFTs held by this wallet. Supported on EVM and Solana chains.

### recover

```kotlin theme={null}
suspend fun recover(approver: DelegatedSigner? = null): Result<Unit, WalletError>
```

Generates a new hardware key on this device and registers it on the wallet using the admin/recovery signer approval flow.

### removeRecoveryMethod

```kotlin theme={null}
suspend fun removeRecoveryMethod(recoveryMethod: DelegatedSigner): Result<Unit, WalletError>
```

Removes a recovery method from this wallet. The function returns when the change is complete.

### removeSigner

```kotlin theme={null}
suspend fun removeSigner(signer: DelegatedSigner, approver: DelegatedSigner? = null): Result<Unit, WalletError>
```

Removes a delegated signer from this wallet. Supported types: DelegatedSigner.Email, DelegatedSigner.Phone, DelegatedSigner.ExternalWallet, DelegatedSigner.Locator, DelegatedSigner.Passkey.

### send

```kotlin theme={null}
suspend fun send(recipient: String, tokenLocator: String, amount: Double, idempotencyKey: String? = null, signer: SignerSelection = SignerSelection.Admin): Result<Transaction, TransactionError>
```

Sends tokens to a recipient address.

### sendTransaction

```kotlin theme={null}
suspend fun sendTransaction(params: RawTransactionParams, signer: SignerSelection = SignerSelection.Admin): Result<Transaction, TransactionError>
```

Submits a raw transaction and polls until it reaches a terminal state.

### signerIsRegistered

```kotlin theme={null}
fun signerIsRegistered(signer: DelegatedSigner): Boolean
```

Checks if the signer is registered on this wallet.

### signers

```kotlin theme={null}
suspend fun signers(): Result<List<DelegatedSignerData>, WalletError>
```

Fetches the live list of signers registered on this wallet.

### signMessage

```kotlin theme={null}
suspend fun signMessage(message: String, signer: SignerSelection = SignerSelection.Admin): Result<String, SignatureError>
```

Signs a message with this wallet (EIP-191).

### signTypedData

```kotlin theme={null}
suspend fun signTypedData(typedDataJson: String, signer: SignerSelection = SignerSelection.Admin): Result<String, SignatureError>
```

Signs EIP-712 typed data with this wallet.

### useRecoveryMethod

```kotlin theme={null}
suspend fun useRecoveryMethod(recoveryMethod: DelegatedSigner): Result<Unit, WalletError>
```

Selects the recovery method that approves changes to this wallet's signers and recovery methods.

### useSigner

```kotlin theme={null}
suspend fun useSigner(signer: DelegatedSigner): Result<Unit, WalletError>
```

Sets the active signer for subsequent send and approve operations.

### withSigner

```kotlin theme={null}
open override fun withSigner(newSigner: Signer): EVMWallet
```

Creates a new Wallet instance that uses the specified signer for transactions.

## Deprecated

### ~~signerIsRegistered~~

<Warning>Deprecated. Use signerIsRegistered(signer: DelegatedSigner) instead.</Warning>

```kotlin theme={null}
fun signerIsRegistered(locator: String): Boolean
```

Returns true if the given locator is registered as a delegated signer on this wallet.


# FallbackPolicy.InsecurePersistent
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/classes/fallback-policy-insecure-persistent

Kotlin Class

**Class**

```kotlin theme={null}
class InsecurePersistent
```

## Properties

| Property | Type | Description |
| - | - | - |
| `name` | `String` | - |
| `ordinal` | `Int` | - |


# FallbackPolicy.MemoryOnly
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/classes/fallback-policy-memory-only

Kotlin Class

**Class**

```kotlin theme={null}
class MemoryOnly
```

## Properties

| Property | Type | Description |
| - | - | - |
| `name` | `String` | - |
| `ordinal` | `Int` | - |


# InsecurePersistentSessionStore
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/classes/insecure-persistent-session-store

Kotlin Class

**Class**

```kotlin theme={null}
class InsecurePersistentSessionStore(settings: Settings = defaultSettings()) : SessionStore
```

## Constructors

```kotlin theme={null}
constructor(settings: Settings = defaultSettings())
```

## Functions

| Function | Description |
| - | - |
| `clear` | - |
| `token` | - |
| `update` | - |

### clear

```kotlin theme={null}
open suspend override fun clear()
```

### token

```kotlin theme={null}
open suspend override fun token(): AuthToken?
```

### update

```kotlin theme={null}
open suspend override fun update(token: AuthToken?)
```


# InvalidEnvironmentKeyException
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/classes/invalid-environment-key-exception

Kotlin Class

**Class**

```kotlin theme={null}
class InvalidEnvironmentKeyException : Exception
```

## Constructors

```kotlin theme={null}
constructor()
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `message` | `String?` | - |


# JvmWebViewBridge
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/classes/jvm-web-view-bridge

Kotlin Class

**Class**

```kotlin theme={null}
class JvmWebViewBridge : WebViewBridge
```

## Constructors

```kotlin theme={null}
constructor()
```

## Properties

| Property | Type | Description |
| - | - | - |
| `isLoaded` | `StateFlow<Boolean>` | - |
| `messages` | `SharedFlow<WebViewMessage>` | - |

## Functions

| Function | Description |
| - | - |
| `loadUrl` | - |
| `sendMessage` | - |

### loadUrl

```kotlin theme={null}
open suspend override fun loadUrl(url: String, timeout: Duration)
```

### sendMessage

```kotlin theme={null}
open suspend override fun sendMessage(message: String)
```


# KeystoreKeyStorage
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/classes/keystore-key-storage

Kotlin Class

**Class**

```kotlin theme={null}
class KeystoreKeyStorage(injectedContext: Context? = null) : DeviceSignerKeyStorage
```

## Constructors

```kotlin theme={null}
constructor(injectedContext: Context? = null)
```

## Functions

| Function | Description |
| - | - |
| `deleteKey` | Deletes the signing key for the given wallet address. |
| `deletePendingKey` | Deletes a pending key that was never mapped to a wallet address. |
| `generateKey` | Generates a new P-256 signing key and stores it. |
| `getDeviceName` | Returns the name of this device, for example "Pixel 10 Pro (Android)". The SDK uses this name as the display name of a device signer. If no device name is available, the function returns "Unknown Device". |
| `getKey` | Returns the base64-encoded uncompressed public key for the given wallet address, or null if not found. |
| `getSecurityLevel` | Returns a human-readable string describing the security level of the key for the given wallet address (e.g. "StrongBox", "TEE", "Software"), or null if the key is not found. |
| `hasKey` | Returns true if this storage holds a key for the given uncompressed public key (base64-encoded). Used during wallet initialization to detect whether a registered device signer belongs to this device. |
| `isAvailable` | Returns true if this storage backend is available on the current device/platform. |
| `mapAddressToKey` | Associates a previously generated pending key with a wallet address. |
| `signHexMessage` | Signs a hex-encoded message using the key for the given wallet address. |
| `signHexMessageWithPendingKey` | Signs a hex-encoded message using a pending key (not yet mapped to a wallet address). |
| `signMessage` | Signs a base64-encoded message using the key for the given wallet address. |

### deleteKey

```kotlin theme={null}
open suspend override fun deleteKey(address: String): Result<Unit>
```

Deletes the signing key for the given wallet address.

### deletePendingKey

```kotlin theme={null}
open suspend override fun deletePendingKey(publicKeyBase64: String): Result<Unit>
```

Deletes a pending key that was never mapped to a wallet address.

### generateKey

```kotlin theme={null}
open suspend override fun generateKey(address: String?): Result<String>
```

Generates a new P-256 signing key and stores it.

### getDeviceName

```kotlin theme={null}
open suspend override fun getDeviceName(): String
```

Returns the name of this device, for example "Pixel 10 Pro (Android)". The SDK uses this name as the display name of a device signer. If no device name is available, the function returns "Unknown Device".

### getKey

```kotlin theme={null}
open suspend override fun getKey(address: String): String?
```

Returns the base64-encoded uncompressed public key for the given wallet address, or null if not found.

### getSecurityLevel

```kotlin theme={null}
open suspend override fun getSecurityLevel(address: String): String?
```

Returns a human-readable string describing the security level of the key for the given wallet address (e.g. "StrongBox", "TEE", "Software"), or null if the key is not found.

### hasKey

```kotlin theme={null}
open suspend override fun hasKey(publicKeyBase64: String): Boolean
```

Returns true if this storage holds a key for the given uncompressed public key (base64-encoded). Used during wallet initialization to detect whether a registered device signer belongs to this device.

### isAvailable

```kotlin theme={null}
open suspend override fun isAvailable(): Boolean
```

Returns true if this storage backend is available on the current device/platform.

### mapAddressToKey

```kotlin theme={null}
open suspend override fun mapAddressToKey(address: String, publicKeyBase64: String): Result<Unit>
```

Associates a previously generated pending key with a wallet address.

### signHexMessage

```kotlin theme={null}
open suspend override fun signHexMessage(address: String, hexMessage: String): Result<Pair<String, String>>
```

Signs a hex-encoded message using the key for the given wallet address.

### signHexMessageWithPendingKey

```kotlin theme={null}
open suspend override fun signHexMessageWithPendingKey(publicKeyBase64: String, hexMessage: String): Result<Pair<String, String>>
```

Signs a hex-encoded message using a pending key (not yet mapped to a wallet address).

### signMessage

```kotlin theme={null}
open suspend override fun signMessage(address: String, message: String): Result<Pair<String, String>>
```

Signs a base64-encoded message using the key for the given wallet address.


# MalformedKeyException
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/classes/malformed-key-exception

Kotlin Class

**Class**

```kotlin theme={null}
class MalformedKeyException(message: String) : Exception
```

## Constructors

```kotlin theme={null}
constructor(message: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `message` | `String?` | - |


# OldKeyException
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/classes/old-key-exception

Kotlin Class

**Class**

```kotlin theme={null}
class OldKeyException : Exception
```

## Constructors

```kotlin theme={null}
constructor()
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `message` | `String?` | - |


# SolanaWallet
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/classes/solana-wallet

Kotlin Class

**Class**

```kotlin theme={null}
class SolanaWallet : Wallet
```

## Properties

| Property | Type | Description |
| - | - | - |
| `address` | `String` | The blockchain address of the wallet |
| `chain` | `Chain` | The specific blockchain this wallet lives on |
| `chainType` | `ChainType` | - |
| `config` | `WalletConfig` | The wallet configuration including admin signer. WalletConfig.recoveryMethods and WalletConfig.adminSigner show the changes that you make with Wallet.addRecoveryMethod and Wallet.removeRecoveryMethod. |
| `owner` | `Owner?` | The owner of the wallet, if available |
| `solanaChain` | `SolanaChain` | The Solana chain this wallet lives on |
| `type` | `WalletType` | The type of wallet (smart wallet or MPC wallet) |

## Functions

| Function | Description |
| - | - |
| `addRecoveryMethod` | Adds a recovery method to this wallet. The function returns when the change is complete. |
| `addSigner` | Registers a new delegated signer on this wallet via the recovery/approval flow. Does not change the active signer. |
| `approve` | Signs a transaction that is in AWAITING\_APPROVAL status. |
| `balances` | Gets the wallet balances. |
| `fund` | Funds the wallet with test tokens (staging only). |
| `getSigner` | Returns the current signer for this wallet. |
| `getTransaction` | Retrieves a transaction by its ID. |
| `isSignerApproved` | Returns true if the given signer is approved on this wallet's chain. |
| `listTransactions` | Lists all transactions for this wallet. |
| `listTransfers` | Lists transfers for this wallet. |
| `localDeviceSignerLocator` | Returns the locator of the device signer that lives on this device. Returns null if this wallet has no device signer on this device. |
| `needsRecovery` | Returns true when a device signer was configured for this wallet but no matching hardware key exists on the current device. |
| `nfts` | Lists NFTs held by this wallet. Supported on EVM and Solana chains. |
| `recover` | Generates a new hardware key on this device and registers it on the wallet using the admin/recovery signer approval flow. |
| `removeRecoveryMethod` | Removes a recovery method from this wallet. The function returns when the change is complete. |
| `removeSigner` | Removes a delegated signer from this wallet. Supported types: DelegatedSigner.Email, DelegatedSigner.Phone, DelegatedSigner.ExternalWallet, DelegatedSigner.Locator, DelegatedSigner.Passkey. |
| `send` | Sends tokens to a recipient address. |
| `sendTransaction` | Submits a raw transaction and polls until it reaches a terminal state. |
| `signerIsRegistered` | Checks if the signer is registered on this wallet. |
| `signers` | Fetches the live list of signers registered on this wallet. |
| `useRecoveryMethod` | Selects the recovery method that approves changes to this wallet's signers and recovery methods. |
| `useSigner` | Sets the active signer for subsequent send and approve operations. |
| `withSigner` | Creates a new Wallet instance that uses the specified signer for transactions. |

### addRecoveryMethod

```kotlin theme={null}
suspend fun addRecoveryMethod(recoveryMethod: DelegatedSigner): Result<Unit, WalletError>
```

Adds a recovery method to this wallet. The function returns when the change is complete.

### addSigner

```kotlin theme={null}
suspend fun addSigner(signer: DelegatedSigner, approver: DelegatedSigner? = null): Result<Unit, WalletError>
```

Registers a new delegated signer on this wallet via the recovery/approval flow. Does not change the active signer.

### approve

```kotlin theme={null}
suspend fun approve(transactionId: String, signer: SignerSelection = SignerSelection.Admin): Result<Transaction, TransactionError>
```

Signs a transaction that is in AWAITING\_APPROVAL status.

### balances

```kotlin theme={null}
suspend fun balances(tokens: List<String> = emptyList()): Result<Balances, BalanceError>
```

Gets the wallet balances.

### fund

```kotlin theme={null}
suspend fun fund(token: String, amount: Int, chain: String): Result<Unit, BalanceError>
```

Funds the wallet with test tokens (staging only).

### getSigner

```kotlin theme={null}
fun getSigner(): Signer?
```

Returns the current signer for this wallet.

### getTransaction

```kotlin theme={null}
suspend fun getTransaction(transactionId: String): Result<Transaction, TransactionError>
```

Retrieves a transaction by its ID.

### isSignerApproved

```kotlin theme={null}
suspend fun isSignerApproved(locator: String): Result<Boolean, WalletError>
```

Returns true if the given signer is approved on this wallet's chain.

### listTransactions

```kotlin theme={null}
suspend fun listTransactions(): Result<List<Transaction>, TransactionError>
```

Lists all transactions for this wallet.

### listTransfers

```kotlin theme={null}
suspend fun listTransfers(tokens: List<String> = emptyList()): Result<TransferList, TransferError>
```

Lists transfers for this wallet.

### localDeviceSignerLocator

```kotlin theme={null}
suspend fun localDeviceSignerLocator(): DelegatedSignerData?
```

Returns the locator of the device signer that lives on this device. Returns null if this wallet has no device signer on this device.

### needsRecovery

```kotlin theme={null}
suspend fun needsRecovery(): Boolean
```

Returns true when a device signer was configured for this wallet but no matching hardware key exists on the current device.

### nfts

```kotlin theme={null}
suspend fun nfts(page: Int = 1, perPage: Int = 20): Result<List<NFT>, WalletError>
```

Lists NFTs held by this wallet. Supported on EVM and Solana chains.

### recover

```kotlin theme={null}
suspend fun recover(approver: DelegatedSigner? = null): Result<Unit, WalletError>
```

Generates a new hardware key on this device and registers it on the wallet using the admin/recovery signer approval flow.

### removeRecoveryMethod

```kotlin theme={null}
suspend fun removeRecoveryMethod(recoveryMethod: DelegatedSigner): Result<Unit, WalletError>
```

Removes a recovery method from this wallet. The function returns when the change is complete.

### removeSigner

```kotlin theme={null}
suspend fun removeSigner(signer: DelegatedSigner, approver: DelegatedSigner? = null): Result<Unit, WalletError>
```

Removes a delegated signer from this wallet. Supported types: DelegatedSigner.Email, DelegatedSigner.Phone, DelegatedSigner.ExternalWallet, DelegatedSigner.Locator, DelegatedSigner.Passkey.

### send

```kotlin theme={null}
suspend fun send(recipient: String, tokenLocator: String, amount: Double, idempotencyKey: String? = null, signer: SignerSelection = SignerSelection.Admin): Result<Transaction, TransactionError>
```

Sends tokens to a recipient address.

### sendTransaction

```kotlin theme={null}
suspend fun sendTransaction(params: RawTransactionParams, signer: SignerSelection = SignerSelection.Admin): Result<Transaction, TransactionError>
```

Submits a raw transaction and polls until it reaches a terminal state.

### signerIsRegistered

```kotlin theme={null}
fun signerIsRegistered(signer: DelegatedSigner): Boolean
```

Checks if the signer is registered on this wallet.

### signers

```kotlin theme={null}
suspend fun signers(): Result<List<DelegatedSignerData>, WalletError>
```

Fetches the live list of signers registered on this wallet.

### useRecoveryMethod

```kotlin theme={null}
suspend fun useRecoveryMethod(recoveryMethod: DelegatedSigner): Result<Unit, WalletError>
```

Selects the recovery method that approves changes to this wallet's signers and recovery methods.

### useSigner

```kotlin theme={null}
suspend fun useSigner(signer: DelegatedSigner): Result<Unit, WalletError>
```

Sets the active signer for subsequent send and approve operations.

### withSigner

```kotlin theme={null}
open override fun withSigner(newSigner: Signer): SolanaWallet
```

Creates a new Wallet instance that uses the specified signer for transactions.

## Deprecated

### ~~signerIsRegistered~~

<Warning>Deprecated. Use signerIsRegistered(signer: DelegatedSigner) instead.</Warning>

```kotlin theme={null}
fun signerIsRegistered(locator: String): Boolean
```

Returns true if the given locator is registered as a delegated signer on this wallet.


# StellarWallet
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/classes/stellar-wallet

Kotlin Class

**Class**

```kotlin theme={null}
class StellarWallet : Wallet
```

## Properties

| Property | Type | Description |
| - | - | - |
| `address` | `String` | The blockchain address of the wallet |
| `chain` | `Chain` | The specific blockchain this wallet lives on |
| `chainType` | `ChainType` | - |
| `config` | `WalletConfig` | The wallet configuration including admin signer. WalletConfig.recoveryMethods and WalletConfig.adminSigner show the changes that you make with Wallet.addRecoveryMethod and Wallet.removeRecoveryMethod. |
| `owner` | `Owner?` | The owner of the wallet, if available |
| `stellarChain` | `StellarChain` | The Stellar chain this wallet lives on |
| `type` | `WalletType` | The type of wallet (smart wallet or MPC wallet) |

## Functions

| Function | Description |
| - | - |
| `addRecoveryMethod` | Adds a recovery method to this wallet. The function returns when the change is complete. |
| `addSigner` | Registers a new delegated signer on this wallet via the recovery/approval flow. Does not change the active signer. |
| `approve` | Signs a transaction that is in AWAITING\_APPROVAL status. |
| `balances` | Gets the wallet balances. |
| `fund` | Funds the wallet with test tokens (staging only). |
| `getSigner` | Returns the current signer for this wallet. |
| `getTransaction` | Retrieves a transaction by its ID. |
| `isSignerApproved` | Returns true if the given signer is approved on this wallet's chain. |
| `listTransactions` | Lists all transactions for this wallet. |
| `listTransfers` | Lists transfers for this wallet. |
| `localDeviceSignerLocator` | Returns the locator of the device signer that lives on this device. Returns null if this wallet has no device signer on this device. |
| `needsRecovery` | Returns true when a device signer was configured for this wallet but no matching hardware key exists on the current device. |
| `nfts` | Lists NFTs held by this wallet. Supported on EVM and Solana chains. |
| `recover` | Generates a new hardware key on this device and registers it on the wallet using the admin/recovery signer approval flow. |
| `removeRecoveryMethod` | Removes a recovery method from this wallet. The function returns when the change is complete. |
| `removeSigner` | Removes a delegated signer from this wallet. Supported types: DelegatedSigner.Email, DelegatedSigner.Phone, DelegatedSigner.ExternalWallet, DelegatedSigner.Locator, DelegatedSigner.Passkey. |
| `send` | Sends tokens to a recipient address. |
| `sendTransaction` | Submits a raw transaction and polls until it reaches a terminal state. |
| `signerIsRegistered` | Checks if the signer is registered on this wallet. |
| `signers` | Fetches the live list of signers registered on this wallet. |
| `useRecoveryMethod` | Selects the recovery method that approves changes to this wallet's signers and recovery methods. |
| `useSigner` | Sets the active signer for subsequent send and approve operations. |
| `withSigner` | Creates a new Wallet instance that uses the specified signer for transactions. |

### addRecoveryMethod

```kotlin theme={null}
suspend fun addRecoveryMethod(recoveryMethod: DelegatedSigner): Result<Unit, WalletError>
```

Adds a recovery method to this wallet. The function returns when the change is complete.

### addSigner

```kotlin theme={null}
suspend fun addSigner(signer: DelegatedSigner, approver: DelegatedSigner? = null): Result<Unit, WalletError>
```

Registers a new delegated signer on this wallet via the recovery/approval flow. Does not change the active signer.

### approve

```kotlin theme={null}
suspend fun approve(transactionId: String, signer: SignerSelection = SignerSelection.Admin): Result<Transaction, TransactionError>
```

Signs a transaction that is in AWAITING\_APPROVAL status.

### balances

```kotlin theme={null}
suspend fun balances(tokens: List<String> = emptyList()): Result<Balances, BalanceError>
```

Gets the wallet balances.

### fund

```kotlin theme={null}
suspend fun fund(token: String, amount: Int, chain: String): Result<Unit, BalanceError>
```

Funds the wallet with test tokens (staging only).

### getSigner

```kotlin theme={null}
fun getSigner(): Signer?
```

Returns the current signer for this wallet.

### getTransaction

```kotlin theme={null}
suspend fun getTransaction(transactionId: String): Result<Transaction, TransactionError>
```

Retrieves a transaction by its ID.

### isSignerApproved

```kotlin theme={null}
suspend fun isSignerApproved(locator: String): Result<Boolean, WalletError>
```

Returns true if the given signer is approved on this wallet's chain.

### listTransactions

```kotlin theme={null}
suspend fun listTransactions(): Result<List<Transaction>, TransactionError>
```

Lists all transactions for this wallet.

### listTransfers

```kotlin theme={null}
suspend fun listTransfers(tokens: List<String> = emptyList()): Result<TransferList, TransferError>
```

Lists transfers for this wallet.

### localDeviceSignerLocator

```kotlin theme={null}
suspend fun localDeviceSignerLocator(): DelegatedSignerData?
```

Returns the locator of the device signer that lives on this device. Returns null if this wallet has no device signer on this device.

### needsRecovery

```kotlin theme={null}
suspend fun needsRecovery(): Boolean
```

Returns true when a device signer was configured for this wallet but no matching hardware key exists on the current device.

### nfts

```kotlin theme={null}
suspend fun nfts(page: Int = 1, perPage: Int = 20): Result<List<NFT>, WalletError>
```

Lists NFTs held by this wallet. Supported on EVM and Solana chains.

### recover

```kotlin theme={null}
suspend fun recover(approver: DelegatedSigner? = null): Result<Unit, WalletError>
```

Generates a new hardware key on this device and registers it on the wallet using the admin/recovery signer approval flow.

### removeRecoveryMethod

```kotlin theme={null}
suspend fun removeRecoveryMethod(recoveryMethod: DelegatedSigner): Result<Unit, WalletError>
```

Removes a recovery method from this wallet. The function returns when the change is complete.

### removeSigner

```kotlin theme={null}
suspend fun removeSigner(signer: DelegatedSigner, approver: DelegatedSigner? = null): Result<Unit, WalletError>
```

Removes a delegated signer from this wallet. Supported types: DelegatedSigner.Email, DelegatedSigner.Phone, DelegatedSigner.ExternalWallet, DelegatedSigner.Locator, DelegatedSigner.Passkey.

### send

```kotlin theme={null}
suspend fun send(recipient: String, tokenLocator: String, amount: Double, idempotencyKey: String? = null, signer: SignerSelection = SignerSelection.Admin): Result<Transaction, TransactionError>
```

Sends tokens to a recipient address.

### sendTransaction

```kotlin theme={null}
suspend fun sendTransaction(params: RawTransactionParams, signer: SignerSelection = SignerSelection.Admin): Result<Transaction, TransactionError>
```

Submits a raw transaction and polls until it reaches a terminal state.

### signerIsRegistered

```kotlin theme={null}
fun signerIsRegistered(signer: DelegatedSigner): Boolean
```

Checks if the signer is registered on this wallet.

### signers

```kotlin theme={null}
suspend fun signers(): Result<List<DelegatedSignerData>, WalletError>
```

Fetches the live list of signers registered on this wallet.

### useRecoveryMethod

```kotlin theme={null}
suspend fun useRecoveryMethod(recoveryMethod: DelegatedSigner): Result<Unit, WalletError>
```

Selects the recovery method that approves changes to this wallet's signers and recovery methods.

### useSigner

```kotlin theme={null}
suspend fun useSigner(signer: DelegatedSigner): Result<Unit, WalletError>
```

Sets the active signer for subsequent send and approve operations.

### withSigner

```kotlin theme={null}
open override fun withSigner(newSigner: Signer): StellarWallet
```

Creates a new Wallet instance that uses the specified signer for transactions.

## Deprecated

### ~~signerIsRegistered~~

<Warning>Deprecated. Use signerIsRegistered(signer: DelegatedSigner) instead.</Warning>

```kotlin theme={null}
fun signerIsRegistered(locator: String): Boolean
```

Returns true if the given locator is registered as a delegated signer on this wallet.


# TinkSecureStorage
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/classes/tink-secure-storage

Kotlin Class

**Class**

```kotlin theme={null}
class TinkSecureStorage(context: Context, logger: Logger) : FailureAwareSessionStore
```

## Constructors

```kotlin theme={null}
constructor(context: Context, logger: Logger)
```

## Functions

| Function | Description |
| - | - |
| `clear` | - |
| `hasFailed` | Returns true if initialization has been attempted and failed. This can be used by wrapper classes to determine if fallback storage should be used. |
| `token` | - |
| `update` | - |

### clear

```kotlin theme={null}
open suspend override fun clear()
```

### hasFailed

```kotlin theme={null}
open override fun hasFailed(): Boolean
```

Returns true if initialization has been attempted and failed. This can be used by wrapper classes to determine if fallback storage should be used.

### token

```kotlin theme={null}
open suspend override fun token(): AuthToken?
```

### update

```kotlin theme={null}
open suspend override fun update(token: AuthToken?)
```


# TinkWithFallbackSessionStore
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/classes/tink-with-fallback-session-store

Kotlin Class

**Class**

```kotlin theme={null}
class TinkWithFallbackSessionStore : SessionStore
```

## Constructors

```kotlin theme={null}
constructor(context: Context, fallbackPolicy: FallbackPolicy = FallbackPolicy.MemoryOnly, logger: Logger = Deps.logger)
```

```kotlin theme={null}
Public constructor for production use.
```

## Functions

| Function | Description |
| - | - |
| `clear` | - |
| `isPersistentStorageAvailable` | Returns true if persistent storage is available. When using MemoryOnly fallback policy and fallback is active, this returns false. |
| `isUsingFallback` | Returns true if the store has fallen back to the alternative storage strategy. This can be used for logging, telemetry, or to inform users about degraded functionality. |
| `token` | - |
| `update` | - |

### clear

```kotlin theme={null}
open suspend override fun clear()
```

### isPersistentStorageAvailable

```kotlin theme={null}
fun isPersistentStorageAvailable(): Boolean
```

Returns true if persistent storage is available. When using MemoryOnly fallback policy and fallback is active, this returns false.

### isUsingFallback

```kotlin theme={null}
fun isUsingFallback(): Boolean
```

Returns true if the store has fallen back to the alternative storage strategy. This can be used for logging, telemetry, or to inform users about degraded functionality.

### token

```kotlin theme={null}
open suspend override fun token(): AuthToken?
```

### update

```kotlin theme={null}
open suspend override fun update(token: AuthToken?)
```


# Wallet
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/classes/wallet

Kotlin Class

**Class**

```kotlin theme={null}
class Wallet
```

## Properties

| Property | Type | Description |
| - | - | - |
| `address` | `String` | The blockchain address of the wallet |
| `chain` | `Chain` | The specific blockchain this wallet lives on |
| `chainType` | `ChainType` | - |
| `config` | `WalletConfig` | The wallet configuration including admin signer. WalletConfig.recoveryMethods and WalletConfig.adminSigner show the changes that you make with Wallet.addRecoveryMethod and Wallet.removeRecoveryMethod. |
| `owner` | `Owner?` | The owner of the wallet, if available |
| `type` | `WalletType` | The type of wallet (smart wallet or MPC wallet) |

## Functions

| Function | Description |
| - | - |
| `addRecoveryMethod` | Adds a recovery method to this wallet. The function returns when the change is complete. |
| `addSigner` | Registers a new delegated signer on this wallet via the recovery/approval flow. Does not change the active signer. |
| `approve` | Signs a transaction that is in AWAITING\_APPROVAL status. |
| `balances` | Gets the wallet balances. |
| `fund` | Funds the wallet with test tokens (staging only). |
| `getSigner` | Returns the current signer for this wallet. |
| `getTransaction` | Retrieves a transaction by its ID. |
| `isSignerApproved` | Returns true if the given signer is approved on this wallet's chain. |
| `listTransactions` | Lists all transactions for this wallet. |
| `listTransfers` | Lists transfers for this wallet. |
| `localDeviceSignerLocator` | Returns the locator of the device signer that lives on this device. Returns null if this wallet has no device signer on this device. |
| `needsRecovery` | Returns true when a device signer was configured for this wallet but no matching hardware key exists on the current device. |
| `nfts` | Lists NFTs held by this wallet. Supported on EVM and Solana chains. |
| `recover` | Generates a new hardware key on this device and registers it on the wallet using the admin/recovery signer approval flow. |
| `removeRecoveryMethod` | Removes a recovery method from this wallet. The function returns when the change is complete. |
| `removeSigner` | Removes a delegated signer from this wallet. Supported types: DelegatedSigner.Email, DelegatedSigner.Phone, DelegatedSigner.ExternalWallet, DelegatedSigner.Locator, DelegatedSigner.Passkey. |
| `send` | Sends tokens to a recipient address. |
| `sendTransaction` | Submits a raw transaction and polls until it reaches a terminal state. |
| `signerIsRegistered` | Checks if the signer is registered on this wallet. |
| `signers` | Fetches the live list of signers registered on this wallet. |
| `useRecoveryMethod` | Selects the recovery method that approves changes to this wallet's signers and recovery methods. |
| `useSigner` | Sets the active signer for subsequent send and approve operations. |
| `withSigner` | Creates a new Wallet instance that uses the specified signer for transactions. |

### addRecoveryMethod

```kotlin theme={null}
suspend fun addRecoveryMethod(recoveryMethod: DelegatedSigner): Result<Unit, WalletError>
```

Adds a recovery method to this wallet. The function returns when the change is complete.

### addSigner

```kotlin theme={null}
suspend fun addSigner(signer: DelegatedSigner, approver: DelegatedSigner? = null): Result<Unit, WalletError>
```

Registers a new delegated signer on this wallet via the recovery/approval flow. Does not change the active signer.

### approve

```kotlin theme={null}
suspend fun approve(transactionId: String, signer: SignerSelection = SignerSelection.Admin): Result<Transaction, TransactionError>
```

Signs a transaction that is in AWAITING\_APPROVAL status.

### balances

```kotlin theme={null}
suspend fun balances(tokens: List<String> = emptyList()): Result<Balances, BalanceError>
```

Gets the wallet balances.

### fund

```kotlin theme={null}
suspend fun fund(token: String, amount: Int, chain: String): Result<Unit, BalanceError>
```

Funds the wallet with test tokens (staging only).

### getSigner

```kotlin theme={null}
fun getSigner(): Signer?
```

Returns the current signer for this wallet.

### getTransaction

```kotlin theme={null}
suspend fun getTransaction(transactionId: String): Result<Transaction, TransactionError>
```

Retrieves a transaction by its ID.

### isSignerApproved

```kotlin theme={null}
suspend fun isSignerApproved(locator: String): Result<Boolean, WalletError>
```

Returns true if the given signer is approved on this wallet's chain.

### listTransactions

```kotlin theme={null}
suspend fun listTransactions(): Result<List<Transaction>, TransactionError>
```

Lists all transactions for this wallet.

### listTransfers

```kotlin theme={null}
suspend fun listTransfers(tokens: List<String> = emptyList()): Result<TransferList, TransferError>
```

Lists transfers for this wallet.

### localDeviceSignerLocator

```kotlin theme={null}
suspend fun localDeviceSignerLocator(): DelegatedSignerData?
```

Returns the locator of the device signer that lives on this device. Returns null if this wallet has no device signer on this device.

### needsRecovery

```kotlin theme={null}
suspend fun needsRecovery(): Boolean
```

Returns true when a device signer was configured for this wallet but no matching hardware key exists on the current device.

### nfts

```kotlin theme={null}
suspend fun nfts(page: Int = 1, perPage: Int = 20): Result<List<NFT>, WalletError>
```

Lists NFTs held by this wallet. Supported on EVM and Solana chains.

### recover

```kotlin theme={null}
suspend fun recover(approver: DelegatedSigner? = null): Result<Unit, WalletError>
```

Generates a new hardware key on this device and registers it on the wallet using the admin/recovery signer approval flow.

### removeRecoveryMethod

```kotlin theme={null}
suspend fun removeRecoveryMethod(recoveryMethod: DelegatedSigner): Result<Unit, WalletError>
```

Removes a recovery method from this wallet. The function returns when the change is complete.

### removeSigner

```kotlin theme={null}
suspend fun removeSigner(signer: DelegatedSigner, approver: DelegatedSigner? = null): Result<Unit, WalletError>
```

Removes a delegated signer from this wallet. Supported types: DelegatedSigner.Email, DelegatedSigner.Phone, DelegatedSigner.ExternalWallet, DelegatedSigner.Locator, DelegatedSigner.Passkey.

### send

```kotlin theme={null}
suspend fun send(recipient: String, tokenLocator: String, amount: Double, idempotencyKey: String? = null, signer: SignerSelection = SignerSelection.Admin): Result<Transaction, TransactionError>
```

Sends tokens to a recipient address.

### sendTransaction

```kotlin theme={null}
suspend fun sendTransaction(params: RawTransactionParams, signer: SignerSelection = SignerSelection.Admin): Result<Transaction, TransactionError>
```

Submits a raw transaction and polls until it reaches a terminal state.

### signerIsRegistered

```kotlin theme={null}
fun signerIsRegistered(signer: DelegatedSigner): Boolean
```

Checks if the signer is registered on this wallet.

### signers

```kotlin theme={null}
suspend fun signers(): Result<List<DelegatedSignerData>, WalletError>
```

Fetches the live list of signers registered on this wallet.

### useRecoveryMethod

```kotlin theme={null}
suspend fun useRecoveryMethod(recoveryMethod: DelegatedSigner): Result<Unit, WalletError>
```

Selects the recovery method that approves changes to this wallet's signers and recovery methods.

### useSigner

```kotlin theme={null}
suspend fun useSigner(signer: DelegatedSigner): Result<Unit, WalletError>
```

Sets the active signer for subsequent send and approve operations.

### withSigner

```kotlin theme={null}
open fun withSigner(newSigner: Signer): Wallet
```

Creates a new Wallet instance that uses the specified signer for transactions.

## Deprecated

### ~~signerIsRegistered~~

<Warning>Deprecated. Use signerIsRegistered(signer: DelegatedSigner) instead.</Warning>

```kotlin theme={null}
fun signerIsRegistered(locator: String): Boolean
```

Returns true if the given locator is registered as a delegated signer on this wallet.


# WebViewNotAvailableException
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/classes/web-view-not-available-exception

Kotlin Class

**Class**

```kotlin theme={null}
class WebViewNotAvailableException(message: String) : Exception
```

## Constructors

```kotlin theme={null}
constructor(message: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `message` | `String?` | - |


# CrossmintNonCustodialSignerProvider
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/composables/crossmint-non-custodial-signer-provider

Composable Function

**Composable**

```kotlin theme={null}
@Composable
fun CrossmintNonCustodialSignerProvider(content: @Composable() -> Unit)
```

Injects a hidden WebView into your Compose layout to run the Trusted Execution Environment (TEE).


# CrossmintTEEWebView
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/composables/crossmint-tee-web-view

Composable Function

**Composable**

```kotlin theme={null}
@Composable
fun CrossmintTEEWebView(tee: CrossmintTEE, modifier: Modifier = Modifier)
```


# CrossmintTEEWebViewContainer
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/composables/crossmint-tee-web-view-container

Composable Function

**Composable**

```kotlin theme={null}
@Composable
fun CrossmintTEEWebViewContainer(tee: CrossmintTEE, content: @Composable() -> Unit)
```


# PlatformSpecificProvider
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/composables/platform-specific-provider

Composable Function

**Composable**

```kotlin theme={null}
@Composable
fun PlatformSpecificProvider(apiKey: Result, authManager: Result, content: @Composable() -> Unit)
```

Platform-specific provider that can add additional capabilities like TEE on supported platforms

## Parameters

| Name | Description |
| - | - |
| sdk | The CrossmintSDK instance |
| apiKey | The API key for the SDK |
| teeOTPDialog | Optional composable invoked when TEE requires user interaction (e.g., OTP). Receives submit/dismiss callbacks. If null, TEE is disabled. |
| content | The main content to be rendered |


# ApiKey
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/api-key

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class ApiKey
```

## Properties

| Property | Type | Description |
| - | - | - |
| `apiEnvironmentPathComponent` | `String` | - |
| `environment` | `Environment` | The environment this key targets |
| `isProduction` | `Boolean` | - |
| `key` | `String` | The raw API key string |
| `type` | `ApiKey.Type` | Whether this is a client or server key |


# ApiKeyError.InvalidEnvironmentKey
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/api-key-error-invalid-environment-key

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class InvalidEnvironmentKey(val message: String = "Invalid environment key", val cause: Throwable? = null) : ApiKeyError
```

## Constructors

```kotlin theme={null}
constructor(message: String = "Invalid environment key", cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `ConfigurationErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# ApiKeyError.MalformedKey
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/api-key-error-malformed-key

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class MalformedKey(val message: String, val cause: Throwable? = null) : ApiKeyError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `ConfigurationErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# ApiKeyError.OldKey
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/api-key-error-old-key

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class OldKey(val message: String = "Old API key format detected. Please use the new key format.", val cause: Throwable? = null) : ApiKeyError
```

## Constructors

```kotlin theme={null}
constructor(message: String = "Old API key format detected. Please use the new key format.", cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `ConfigurationErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# Approval
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/approval

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Approval(val signer: String, val signature: ApprovalSignature, val metadata: ApprovalMetadata? = null)
```

## Constructors

```kotlin theme={null}
constructor(signer: String, signature: ApprovalSignature, metadata: ApprovalMetadata? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `metadata` | `ApprovalMetadata?` | - |
| `signature` | `ApprovalSignature` | - |
| `signer` | `String` | - |


# ApprovalMetadata.Passkey
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/approval-metadata-passkey

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Passkey(val authenticatorData: String, val clientDataJSON: String, val challengeIndex: Int = 23, val typeIndex: Int = 1, val userVerificationRequired: Boolean = true) : ApprovalMetadata
```

## Constructors

```kotlin theme={null}
constructor(authenticatorData: String, clientDataJSON: String, challengeIndex: Int = 23, typeIndex: Int = 1, userVerificationRequired: Boolean = true)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `authenticatorData` | `String` | - |
| `challengeIndex` | `Int` | - |
| `clientDataJSON` | `String` | - |
| `typeIndex` | `Int` | - |
| `userVerificationRequired` | `Boolean` | - |


# ApprovalSignature.Device
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/approval-signature-device

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Device(val r: String, val s: String) : ApprovalSignature
```

## Constructors

```kotlin theme={null}
constructor(r: String, s: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `r` | `String` | - |
| `s` | `String` | - |


# ApprovalSignature.Passkey
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/approval-signature-passkey

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Passkey(val r: String, val s: String) : ApprovalSignature
```

## Constructors

```kotlin theme={null}
constructor(r: String, s: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `r` | `String` | - |
| `s` | `String` | - |


# ApprovalSignature.Raw
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/approval-signature-raw

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Raw(val value: String) : ApprovalSignature
```

## Constructors

```kotlin theme={null}
constructor(value: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `value` | `String` | - |


# Approvals
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/approvals

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Approvals(val pending: List<Approvals.PendingApproval>, val submitted: List<Approvals.SubmittedApproval>)
```

## Constructors

```kotlin theme={null}
constructor(pending: List<Approvals.PendingApproval>, submitted: List<Approvals.SubmittedApproval>)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `pending` | `List<Approvals.PendingApproval>` | - |
| `submitted` | `List<Approvals.SubmittedApproval>` | - |


# Approvals.PendingApproval
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/approvals-pending-approval

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class PendingApproval(val signer: String, val message: String)
```

## Constructors

```kotlin theme={null}
constructor(signer: String, message: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `message` | `String` | The message this signer must sign to approve the transaction. |
| `signer` | `String` | Locator of the signer that must approve. |


# Approvals.SubmittedApproval
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/approvals-submitted-approval

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class SubmittedApproval(val signature: String, val submittedAt: Long, val signer: String, val message: String)
```

## Constructors

```kotlin theme={null}
constructor(signature: String, submittedAt: Long, signer: String, message: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `message` | `String` | - |
| `signature` | `String` | - |
| `signer` | `String` | - |
| `submittedAt` | `Long` | - |


# AuthError.InvalidCredentials
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/auth-error-invalid-credentials

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class InvalidCredentials(val message: String = "Invalid credentials", val cause: Throwable? = null) : AuthError
```

## Constructors

```kotlin theme={null}
constructor(message: String = "Invalid credentials", cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `AuthErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# AuthError.NotInitialized
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/auth-error-not-initialized

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class NotInitialized(val message: String = "Auth not initialized", val cause: Throwable? = null) : AuthError
```

## Constructors

```kotlin theme={null}
constructor(message: String = "Auth not initialized", cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `AuthErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# AuthError.RateLimited
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/auth-error-rate-limited

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class RateLimited(val message: String = "Rate limited", val cause: Throwable? = null) : AuthError
```

## Constructors

```kotlin theme={null}
constructor(message: String = "Rate limited", cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `AuthErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# AuthError.ServerError
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/auth-error-server-error

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class ServerError(val message: String = "Server error", val statusCode: Int? = null, val cause: Throwable? = null) : AuthError
```

## Constructors

```kotlin theme={null}
constructor(message: String = "Server error", statusCode: Int? = null, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `AuthErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |
| `statusCode` | `Int?` | - |


# AuthError.TokenExpired
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/auth-error-token-expired

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class TokenExpired(val message: String = "Token expired", val cause: Throwable? = null) : AuthError
```

## Constructors

```kotlin theme={null}
constructor(message: String = "Token expired", cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `AuthErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# AuthError.Unauthorized
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/auth-error-unauthorized

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Unauthorized(val message: String = "Unauthorized", val cause: Throwable? = null) : AuthError
```

## Constructors

```kotlin theme={null}
constructor(message: String = "Unauthorized", cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `AuthErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# BalanceError.BalanceNotFound
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/balance-error-balance-not-found

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class BalanceNotFound(val message: String, val cause: Throwable? = null) : BalanceError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `BalanceErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# BalanceError.BalanceOperationFailed
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/balance-error-balance-operation-failed

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class BalanceOperationFailed(val message: String, val cause: Throwable? = null) : BalanceError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `BalanceErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# BalanceError.Forbidden
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/balance-error-forbidden

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Forbidden(val message: String, val cause: Throwable? = null) : BalanceError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `BalanceErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# BalanceError.RateLimited
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/balance-error-rate-limited

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class RateLimited(val message: String, val cause: Throwable? = null) : BalanceError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `BalanceErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# BalanceError.ServiceNotInitialized
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/balance-error-service-not-initialized

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class ServiceNotInitialized(val message: String = "Balance service not initialized", val cause: Throwable? = null) : BalanceError
```

## Constructors

```kotlin theme={null}
constructor(message: String = "Balance service not initialized", cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `BalanceErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# BalanceError.Unauthorized
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/balance-error-unauthorized

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Unauthorized(val message: String, val cause: Throwable? = null) : BalanceError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `BalanceErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# Balances
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/balances

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Balances(val nativeToken: TokenBalance, val usdc: TokenBalance, val tokens: List<TokenBalance>)
```

## Constructors

```kotlin theme={null}
constructor(nativeToken: TokenBalance, usdc: TokenBalance, tokens: List<TokenBalance>)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `nativeToken` | `TokenBalance` | - |
| `tokens` | `List<TokenBalance>` | - |
| `usdc` | `TokenBalance` | - |


# Call
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/call

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Call(val to: String, val value: String, val data: String)
```

## Constructors

```kotlin theme={null}
constructor(to: String, value: String, data: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `data` | `String` | - |
| `to` | `String` | - |
| `value` | `String` | - |


# ChainInfo.Solana
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/chain-info-solana

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Solana(val mintHash: String?) : ChainInfo
```

## Constructors

```kotlin theme={null}
constructor(mintHash: String?)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `mintHash` | `String?` | - |


# ChainInfo.Stellar
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/chain-info-stellar

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Stellar(val contractId: String?) : ChainInfo
```

## Constructors

```kotlin theme={null}
constructor(contractId: String?)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `contractId` | `String?` | - |


# Chain.Unknown
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/chain-unknown

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Unknown(val name: String) : Chain
```

## Constructors

```kotlin theme={null}
constructor(name: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open override fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# Configuration
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/configuration

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Configuration(val apiKey: ApiKey, val appIdentifier: () -> String?)
```

## Constructors

```kotlin theme={null}
constructor(apiKey: ApiKey, appIdentifier: () -> String?)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `apiKey` | `ApiKey` | - |
| `appIdentifier` | `() -> String?` | - |
| `baseUrl` | `String` | - |


# DelegatedSigner.ApiKey
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/delegated-signer-api-key

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class ApiKey(val expiresAt: Long? = null) : DelegatedSigner
```

## Constructors

```kotlin theme={null}
constructor(expiresAt: Long? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `expiresAt` | `Long?` | Optional expiration timestamp in milliseconds since Unix epoch. If set, the delegated signer will expire at this time. |


# DelegatedSignerData
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/delegated-signer-data

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class DelegatedSignerData(val locator: String, val status: DelegatedSignerStatus = DelegatedSignerStatus.UNKNOWN, val name: String? = null)
```

## Constructors

```kotlin theme={null}
constructor(locator: String, status: DelegatedSignerStatus = DelegatedSignerStatus.UNKNOWN, name: String? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `identifier` | `String` | The signer identifier extracted from the locator (e.g. email address, phone number, wallet address). Returns the full locator if no type prefix is present. |
| `locator` | `String` | - |
| `name` | `String?` | The name of the signer, for example the name that the user gave to a passkey. This value is null when the signer has no name. |
| `status` | `DelegatedSignerStatus` | - |
| `type` | `DelegatedSignerType` | The signer type derived from the locator prefix (e.g. "device:", "email:"). Falls back to matching the whole locator when there's no colon, so an addressless API key signer (locator `"api-key"`, no identifier) still resolves to DelegatedSignerType.API\_KEY. Returns DelegatedSignerType.UNKNOWN for locators that match no known type (e.g. bare addresses). |

## Functions

| Function | Description |
| - | - |
| `toSignerData` | Converts this delegated signer data to SignerData if possible. Only email and phone signers can be converted (non-custodial, TEE-backed signers). Returns null for passkey, api-key, external-wallet, and device signers. |

### toSignerData

```kotlin theme={null}
fun toSignerData(): SignerData?
```

Converts this delegated signer data to SignerData if possible. Only email and phone signers can be converted (non-custodial, TEE-backed signers). Returns null for passkey, api-key, external-wallet, and device signers.


# DelegatedSigner.Device
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/delegated-signer-device

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Device(val expiresAt: Long? = null) : DelegatedSigner
```

## Constructors

```kotlin theme={null}
constructor(expiresAt: Long? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `expiresAt` | `Long?` | Optional expiration timestamp in milliseconds since Unix epoch. If set, the delegated signer will expire at this time. |


# DelegatedSigner.Email
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/delegated-signer-email

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Email(val email: String, val expiresAt: Long? = null) : DelegatedSigner
```

## Constructors

```kotlin theme={null}
constructor(email: String, expiresAt: Long? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `email` | `String` | - |
| `expiresAt` | `Long?` | Optional expiration timestamp in milliseconds since Unix epoch. If set, the delegated signer will expire at this time. |


# DelegatedSigner.ExternalWallet
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/delegated-signer-external-wallet

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class ExternalWallet(val address: String, val expiresAt: Long? = null) : DelegatedSigner
```

## Constructors

```kotlin theme={null}
constructor(address: String, onSign: suspend (String) -> String, expiresAt: Long? = null)
```

```kotlin theme={null}
constructor(address: String, expiresAt: Long? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `address` | `String` | - |
| `expiresAt` | `Long?` | Optional expiration timestamp in milliseconds since Unix epoch. If set, the delegated signer will expire at this time. |
| `onSign` | `suspend (String) -> String?` | Signs a message with the external wallet and returns the signature. The value is null if you create the signer without it. |


# DelegatedSigner.Locator
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/delegated-signer-locator

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Locator(val locator: String, val expiresAt: Long? = null) : DelegatedSigner
```

## Constructors

```kotlin theme={null}
constructor(locator: String, expiresAt: Long? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `expiresAt` | `Long?` | Optional expiration timestamp in milliseconds since Unix epoch. If set, the delegated signer will expire at this time. |
| `locator` | `String` | - |


# DelegatedSigner.Passkey
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/delegated-signer-passkey

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Passkey(val id: String, val name: String, val publicKeyX: String, val publicKeyY: String, val expiresAt: Long? = null) : DelegatedSigner
```

## Constructors

```kotlin theme={null}
constructor(id: String, name: String, publicKeyX: String, publicKeyY: String, expiresAt: Long? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `expiresAt` | `Long?` | Optional expiration timestamp in milliseconds since Unix epoch. If set, the delegated signer will expire at this time. |
| `id` | `String` | - |
| `name` | `String` | - |
| `publicKeyX` | `String` | - |
| `publicKeyY` | `String` | - |


# DelegatedSigner.Phone
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/delegated-signer-phone

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Phone(val phoneNumber: String, val expiresAt: Long? = null, val channel: OTPDeliveryChannel? = null) : DelegatedSigner
```

## Constructors

```kotlin theme={null}
constructor(phoneNumber: String, expiresAt: Long? = null, channel: OTPDeliveryChannel? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `channel` | `OTPDeliveryChannel?` | - |
| `expiresAt` | `Long?` | Optional expiration timestamp in milliseconds since Unix epoch. If set, the delegated signer will expire at this time. |
| `phoneNumber` | `String` | - |


# DeviceSignerError.StorageError
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/device-signer-error-storage-error

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class StorageError(val reason: String) : DeviceSignerError
```

## Constructors

```kotlin theme={null}
constructor(reason: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `message` | `String?` | - |
| `reason` | `String` | - |


# EVMTransactionParams
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/evm-transaction-params

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class EVMTransactionParams(val calls: List<Call>, val chain: EVMChain, val signer: String) : TransactionParams
```

## Constructors

```kotlin theme={null}
constructor(calls: List<Call>, chain: EVMChain, signer: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `calls` | `List<Call>` | - |
| `chain` | `EVMChain` | - |
| `signer` | `String` | - |


# FeeConfig
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/fee-config

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class FeeConfig(val feePayer: String, val amount: String)
```

## Constructors

```kotlin theme={null}
constructor(feePayer: String, amount: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `amount` | `String` | - |
| `feePayer` | `String` | - |


# IdentityVerificationError
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/identity-verification-error

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class IdentityVerificationError(val message: String, val retriable: Boolean, val code: IdentityVerificationErrorCode, val cause: Throwable? = null) : CrossmintError
```

## Constructors

```kotlin theme={null}
constructor(message: String, retriable: Boolean, code: IdentityVerificationErrorCode, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `IdentityVerificationErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |
| `retriable` | `Boolean` | - |


# NetworkError.ConnectionError
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/network-error-connection-error

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class ConnectionError(val message: String, val cause: Throwable? = null) : NetworkError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `NetworkErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# NetworkError.HttpError
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/network-error-http-error

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class HttpError(val statusCode: Int, val message: String, val cause: Throwable? = null, val body: String? = null) : NetworkError
```

## Constructors

```kotlin theme={null}
constructor(statusCode: Int, message: String, cause: Throwable? = null, body: String? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `body` | `String?` | Raw response body, when message does not already carry it verbatim. Lets callers parse stable error codes (e.g. `DEVICE_SIGNER_NOT_SUPPORTED`) without scraping message. |
| `cause` | `Throwable?` | - |
| `code` | `NetworkErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |
| `statusCode` | `Int` | - |


# NetworkError.ParseError
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/network-error-parse-error

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class ParseError(val message: String, val cause: Throwable? = null) : NetworkError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `NetworkErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# NetworkError.ServiceNotInitialized
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/network-error-service-not-initialized

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class ServiceNotInitialized(val message: String = "Service not initialized", val cause: Throwable? = null) : NetworkError
```

## Constructors

```kotlin theme={null}
constructor(message: String = "Service not initialized", cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `NetworkErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# NetworkError.TimeoutError
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/network-error-timeout-error

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class TimeoutError(val message: String, val cause: Throwable? = null) : NetworkError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `NetworkErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# NetworkError.UnknownError
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/network-error-unknown-error

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class UnknownError(val message: String, val cause: Throwable? = null) : NetworkError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `NetworkErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# OnChainData
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/on-chain-data

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class OnChainData(val userOperation: UserOperation?, val userOperationHash: String?, val explorerLink: String?, val txId: String?, val transaction: String?, val lastValidBlockHeight: Int?)
```

## Constructors

```kotlin theme={null}
constructor(userOperation: UserOperation?, userOperationHash: String?, explorerLink: String?, txId: String?, transaction: String?, lastValidBlockHeight: Int?)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `explorerLink` | `String?` | - |
| `lastValidBlockHeight` | `Int?` | - |
| `transaction` | `String?` | - |
| `txId` | `String?` | - |
| `userOperation` | `UserOperation?` | - |
| `userOperationHash` | `String?` | - |


# Owner.Address
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/owner-address

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Address(val value: String) : Owner
```

## Constructors

```kotlin theme={null}
constructor(value: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `value` | `String` | - |


# Owner.Email
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/owner-email

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Email(val value: String) : Owner
```

## Constructors

```kotlin theme={null}
constructor(value: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `value` | `String` | - |


# Owner.PhoneNumber
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/owner-phone-number

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class PhoneNumber(val value: String) : Owner
```

## Constructors

```kotlin theme={null}
constructor(value: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `value` | `String` | - |


# Owner.Twitter
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/owner-twitter

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Twitter(val value: String) : Owner
```

## Constructors

```kotlin theme={null}
constructor(value: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `value` | `String` | - |


# Owner.UserId
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/owner-user-id

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class UserId(val value: String) : Owner
```

## Constructors

```kotlin theme={null}
constructor(value: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `value` | `String` | - |


# PasskeyCredentialInfo
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/passkey-credential-info

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class PasskeyCredentialInfo(val id: String, val name: String, val publicKeyX: String, val publicKeyY: String)
```

## Constructors

```kotlin theme={null}
constructor(id: String, name: String, publicKeyX: String, publicKeyY: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `id` | `String` | - |
| `name` | `String` | - |
| `publicKeyX` | `String` | - |
| `publicKeyY` | `String` | - |


# PasskeyError.Cancelled
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/passkey-error-cancelled

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Cancelled(val message: String = "The user closed the passkey prompt", val cause: Throwable? = null) : PasskeyError
```

## Constructors

```kotlin theme={null}
constructor(message: String = "The user closed the passkey prompt", cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `PasskeyErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# PasskeyError.Failed
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/passkey-error-failed

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Failed(val message: String, val cause: Throwable? = null) : PasskeyError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `PasskeyErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# PasskeySignMetadata
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/passkey-sign-metadata

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class PasskeySignMetadata(val authenticatorData: String, val clientDataJSON: String, val challengeIndex: Int = 23, val typeIndex: Int = 1, val userVerificationRequired: Boolean = true)
```

## Constructors

```kotlin theme={null}
constructor(authenticatorData: String, clientDataJSON: String, challengeIndex: Int = 23, typeIndex: Int = 1, userVerificationRequired: Boolean = true)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `authenticatorData` | `String` | The base64url `authenticatorData` from the assertion response. |
| `clientDataJSON` | `String` | The base64url `clientDataJSON` from the assertion response. |
| `userVerificationRequired` | `Boolean` | True when the assertion needs user verification. The default is true. |

## Deprecated

### ~~challengeIndex~~

<Warning>Deprecated. Not used. Leave out this value.</Warning>

```kotlin theme={null}
val challengeIndex: Int = 23
```

Not used. Leave out this value.

### ~~typeIndex~~

<Warning>Deprecated. Not used. Leave out this value.</Warning>

```kotlin theme={null}
val typeIndex: Int = 1
```

Not used. Leave out this value.


# PasskeySignResult
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/passkey-sign-result

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class PasskeySignResult(val r: String, val s: String, val metadata: PasskeySignMetadata)
```

## Constructors

```kotlin theme={null}
constructor(r: String, s: String, metadata: PasskeySignMetadata)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `metadata` | `PasskeySignMetadata` | The WebAuthn assertion fields of the signature. |
| `r` | `String` | The r value of the P-256 signature, as `0x` hex. |
| `s` | `String` | The s value of the P-256 signature, as `0x` hex. |


# RawTransactionParams.Solana
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/raw-transaction-params-solana

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Solana(val transaction: String) : RawTransactionParams
```

## Constructors

```kotlin theme={null}
constructor(transaction: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `transaction` | `String` | - |


# RawTransactionParams.Stellar
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/raw-transaction-params-stellar

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Stellar(val contractId: String, val method: String, val args: Map<String, String>, val memo: String? = null) : RawTransactionParams
```

## Constructors

```kotlin theme={null}
constructor(contractId: String, method: String, args: Map<String, String>, memo: String? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `args` | `Map<String, String>` | - |
| `contractId` | `String` | - |
| `memo` | `String?` | - |
| `method` | `String` | - |


# RawTransactionParams.StellarSerialized
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/raw-transaction-params-stellar-serialized

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class StellarSerialized(val contractId: String, val serializedTransaction: String) : RawTransactionParams
```

## Constructors

```kotlin theme={null}
constructor(contractId: String, serializedTransaction: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `contractId` | `String` | - |
| `serializedTransaction` | `String` | - |


# RecoveryMethod
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/recovery-method

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class RecoveryMethod(val signer: SignerData, val status: DelegatedSignerStatus = DelegatedSignerStatus.UNKNOWN)
```

## Constructors

```kotlin theme={null}
constructor(signer: SignerData, status: DelegatedSignerStatus = DelegatedSignerStatus.UNKNOWN)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `signer` | `SignerData` | A signer that can recover the wallet. |
| `status` | `DelegatedSignerStatus` | The status of signer on the wallet. |


# Result.Failure
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/result-failure

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Failure<E>(val error: E) : Result<Nothing, E>
```

## Constructors

```kotlin theme={null}
constructor(error: E)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `error` | `E` | - |

## Functions

| Function | Description |
| - | - |
| `flatMap` | Chains a success through transform, which itself returns a Result. |
| `fold` | Applies onSuccess or onFailure depending on the result variant. |
| `getOrNull` | Returns the success value, or null if this is a Result.Failure. |
| `getOrThrow` | Returns the success value, or throws if this is a Result.Failure. |
| `map` | Transforms the success value using transform, leaving failures unchanged. |
| `mapError` | Transforms the error using transform, leaving successes unchanged. |

### flatMap

```kotlin theme={null}
inline fun <T, E, R> Result<T, E>.flatMap(transform: (T) -> Result<R, E>): Result<R, E>
```

Chains a success through transform, which itself returns a Result.

### fold

```kotlin theme={null}
inline fun <T, E> Result<T, E>.fold(onSuccess: (T) -> Unit, onFailure: (E) -> Unit)
```

Applies onSuccess or onFailure depending on the result variant.

### getOrNull

```kotlin theme={null}
fun <T, E> Result<T, E>.getOrNull(): T?
```

Returns the success value, or null if this is a Result.Failure.

### getOrThrow

```kotlin theme={null}
fun <T, E> Result<T, E>.getOrThrow(): T
```

Returns the success value, or throws if this is a Result.Failure.

### map

```kotlin theme={null}
inline fun <T, E, R> Result<T, E>.map(transform: (T) -> R): Result<R, E>
```

Transforms the success value using transform, leaving failures unchanged.

### mapError

```kotlin theme={null}
inline fun <T, E, F> Result<T, E>.mapError(transform: (E) -> F): Result<T, F>
```

Transforms the error using transform, leaving successes unchanged.


# Result.Success
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/result-success

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Success<T>(val value: T) : Result<T, Nothing>
```

## Constructors

```kotlin theme={null}
constructor(value: T)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `value` | `T` | - |

## Functions

| Function | Description |
| - | - |
| `flatMap` | Chains a success through transform, which itself returns a Result. |
| `fold` | Applies onSuccess or onFailure depending on the result variant. |
| `getOrNull` | Returns the success value, or null if this is a Result.Failure. |
| `getOrThrow` | Returns the success value, or throws if this is a Result.Failure. |
| `map` | Transforms the success value using transform, leaving failures unchanged. |
| `mapError` | Transforms the error using transform, leaving successes unchanged. |

### flatMap

```kotlin theme={null}
inline fun <T, E, R> Result<T, E>.flatMap(transform: (T) -> Result<R, E>): Result<R, E>
```

Chains a success through transform, which itself returns a Result.

### fold

```kotlin theme={null}
inline fun <T, E> Result<T, E>.fold(onSuccess: (T) -> Unit, onFailure: (E) -> Unit)
```

Applies onSuccess or onFailure depending on the result variant.

### getOrNull

```kotlin theme={null}
fun <T, E> Result<T, E>.getOrNull(): T?
```

Returns the success value, or null if this is a Result.Failure.

### getOrThrow

```kotlin theme={null}
fun <T, E> Result<T, E>.getOrThrow(): T
```

Returns the success value, or throws if this is a Result.Failure.

### map

```kotlin theme={null}
inline fun <T, E, R> Result<T, E>.map(transform: (T) -> R): Result<R, E>
```

Transforms the success value using transform, leaving failures unchanged.

### mapError

```kotlin theme={null}
inline fun <T, E, F> Result<T, E>.mapError(transform: (E) -> F): Result<T, F>
```

Transforms the error using transform, leaving successes unchanged.


# SignatureError.ChainNotSupported
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/signature-error-chain-not-supported

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class ChainNotSupported(val message: String = "Message signing is not supported on this chain", val cause: Throwable? = null) : SignatureError
```

## Constructors

```kotlin theme={null}
constructor(message: String = "Message signing is not supported on this chain", cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `SignatureErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# SignatureError.CreationFailed
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/signature-error-creation-failed

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class CreationFailed(val message: String, val cause: Throwable? = null) : SignatureError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `SignatureErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# SignatureError.Forbidden
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/signature-error-forbidden

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Forbidden(val message: String, val cause: Throwable? = null) : SignatureError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `SignatureErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# SignatureError.ServiceNotInitialized
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/signature-error-service-not-initialized

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class ServiceNotInitialized(val message: String, val cause: Throwable? = null) : SignatureError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `SignatureErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# SignatureError.SigningFailed
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/signature-error-signing-failed

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class SigningFailed(val message: String, val cause: Throwable? = null) : SignatureError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `SignatureErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# SignatureError.Timeout
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/signature-error-timeout

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Timeout(val message: String = "Signature polling timed out", val cause: Throwable? = null) : SignatureError
```

## Constructors

```kotlin theme={null}
constructor(message: String = "Signature polling timed out", cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `SignatureErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# SignatureError.Unauthorized
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/signature-error-unauthorized

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Unauthorized(val message: String, val cause: Throwable? = null) : SignatureError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `SignatureErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# SignatureError.Unknown
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/signature-error-unknown

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Unknown(val message: String, val cause: Throwable? = null) : SignatureError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `SignatureErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# SignatureError.UserCancelled
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/signature-error-user-cancelled

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class UserCancelled(val message: String = "The user cancelled the signature", val cause: Throwable? = null) : SignatureError
```

## Constructors

```kotlin theme={null}
constructor(message: String = "The user cancelled the signature", cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `SignatureErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# SignerData.ApiKey
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/signer-data-api-key

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class ApiKey(val address: String, val locator: String) : SignerData
```

## Constructors

```kotlin theme={null}
constructor(address: String, locator: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `address` | `String` | - |
| `locator` | `String` | - |


# SignerData.Device
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/signer-data-device

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Device(val locator: String) : SignerData
```

## Constructors

```kotlin theme={null}
constructor(locator: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `locator` | `String` | - |


# SignerData.Email
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/signer-data-email

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Email(val email: String, val locator: String = "email:") : SignerData, NonCustodialSigner
```

## Constructors

```kotlin theme={null}
constructor(email: String, locator: String = "email:")
```

## Properties

| Property | Type | Description |
| - | - | - |
| `email` | `String` | - |
| `locator` | `String` | - |


# SignerData.ExternalWallet
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/signer-data-external-wallet

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class ExternalWallet(val address: String, val locator: String = "external-wallet:") : SignerData
```

## Constructors

```kotlin theme={null}
constructor(address: String, locator: String = "external-wallet:")
```

## Properties

| Property | Type | Description |
| - | - | - |
| `address` | `String` | - |
| `locator` | `String` | - |


# SignerData.Passkey
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/signer-data-passkey

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Passkey(val id: String, val name: String, val publicKeyX: String, val publicKeyY: String, val validatorContractVersion: String?, val locator: String) : SignerData
```

## Constructors

```kotlin theme={null}
constructor(id: String, name: String, publicKeyX: String, publicKeyY: String, validatorContractVersion: String?, locator: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `id` | `String` | - |
| `locator` | `String` | - |
| `name` | `String` | - |
| `publicKeyX` | `String` | - |
| `publicKeyY` | `String` | - |
| `validatorContractVersion` | `String?` | The version of the passkey validator contract. Only EVM wallets have this value. On Solana and Stellar wallets, it is null. |


# SignerData.Phone
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/signer-data-phone

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Phone(val phone: String, val locator: String = "phone:") : SignerData, NonCustodialSigner
```

## Constructors

```kotlin theme={null}
constructor(phone: String, locator: String = "phone:")
```

## Properties

| Property | Type | Description |
| - | - | - |
| `locator` | `String` | - |
| `phone` | `String` | - |


# SignerData.Server
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/signer-data-server

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Server(val address: String, val locator: String = "server:") : SignerData
```

## Constructors

```kotlin theme={null}
constructor(address: String, locator: String = "server:")
```

## Properties

| Property | Type | Description |
| - | - | - |
| `address` | `String` | - |
| `locator` | `String` | - |


# SignerError.Generic
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/signer-error-generic

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Generic(val message: String) : SignerError
```

## Constructors

```kotlin theme={null}
constructor(message: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `message` | `String` | - |


# SignerError.SigningFailed
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/signer-error-signing-failed

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class SigningFailed(val message: String) : SignerError
```

## Constructors

```kotlin theme={null}
constructor(message: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `message` | `String` | - |


# SignerSelection.Delegated
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/signer-selection-delegated

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Delegated(val delegatedSigner: DelegatedSignerData, val channel: OTPDeliveryChannel? = null) : SignerSelection
```

## Constructors

```kotlin theme={null}
constructor(delegatedSigner: DelegatedSignerData, channel: OTPDeliveryChannel? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `channel` | `OTPDeliveryChannel?` | - |
| `delegatedSigner` | `DelegatedSignerData` | - |


# SignerType.Email
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/signer-type-email

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Email(val email: String) : SignerType
```

## Constructors

```kotlin theme={null}
constructor(email: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `email` | `String` | - |


# SignerType.ExternalWallet
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/signer-type-external-wallet

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class ExternalWallet(val address: String, val onSign: suspend (String) -> String? = null) : SignerType
```

## Constructors

```kotlin theme={null}
constructor(address: String, onSign: suspend (String) -> String? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `address` | `String` | - |
| `onSign` | `suspend (String) -> String?` | - |


# SignerType.Passkey
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/signer-type-passkey

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Passkey(val id: String, val name: String, val publicKeyX: String, val publicKeyY: String) : SignerType
```

## Constructors

```kotlin theme={null}
constructor(id: String, name: String, publicKeyX: String, publicKeyY: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `id` | `String` | - |
| `name` | `String` | - |
| `publicKeyX` | `String` | - |
| `publicKeyY` | `String` | - |


# SignerType.Phone
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/signer-type-phone

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Phone(val phoneNumber: String, val channel: OTPDeliveryChannel? = null) : SignerType
```

## Constructors

```kotlin theme={null}
constructor(phoneNumber: String, channel: OTPDeliveryChannel? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `channel` | `OTPDeliveryChannel?` | - |
| `phoneNumber` | `String` | - |


# SigningOutput.Passkey
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/signing-output-passkey

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Passkey(val result: PasskeySignResult) : SigningOutput
```

## Constructors

```kotlin theme={null}
constructor(result: PasskeySignResult)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `result` | `PasskeySignResult` | - |


# SigningOutput.Standard
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/signing-output-standard

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Standard(val value: String) : SigningOutput
```

## Constructors

```kotlin theme={null}
constructor(value: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `value` | `String` | - |


# SolanaTransactionParams
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/solana-transaction-params

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class SolanaTransactionParams(val transaction: String, val signer: String, val feeConfig: FeeConfig? = null) : TransactionParams
```

## Constructors

```kotlin theme={null}
constructor(transaction: String, signer: String, feeConfig: FeeConfig? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `feeConfig` | `FeeConfig?` | - |
| `signer` | `String` | - |
| `transaction` | `String` | - |


# StellarTransactionParams
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/stellar-transaction-params

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class StellarTransactionParams(val transaction: String, val signer: String? = null) : TransactionParams
```

## Constructors

```kotlin theme={null}
constructor(transaction: String, signer: String? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `signer` | `String?` | - |
| `transaction` | `String` | - |


# TEEError.Generic
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/tee-error-generic

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Generic(val message: String) : TEEError
```

## Constructors

```kotlin theme={null}
constructor(message: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `message` | `String` | - |


# TEEError.InvalidPayload
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/tee-error-invalid-payload

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class InvalidPayload(val message: String = "Invalid payload provided for TEE operation") : TEEError
```

## Constructors

```kotlin theme={null}
constructor(message: String = "Invalid payload provided for TEE operation")
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `message` | `String` | - |


# TokenAccountBalance
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/token-account-balance

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class TokenAccountBalance(val type: TokenAccountType, val amount: String, val rawAmount: String, val available: TokenAmount, val locked: TokenAmount)
```

## Constructors

```kotlin theme={null}
constructor(type: TokenAccountType, amount: String, rawAmount: String, available: TokenAmount, locked: TokenAmount)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `amount` | `String` | - |
| `available` | `TokenAmount` | - |
| `locked` | `TokenAmount` | - |
| `rawAmount` | `String` | - |
| `type` | `TokenAccountType` | - |


# TokenAccountType.Card
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/token-account-type-card

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Card(val provider: String) : TokenAccountType
```

## Constructors

```kotlin theme={null}
constructor(provider: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `provider` | `String` | - |


# TokenAccountType.Unknown
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/token-account-type-unknown

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Unknown(val type: String) : TokenAccountType
```

## Constructors

```kotlin theme={null}
constructor(type: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `type` | `String` | - |


# TokenAmount
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/token-amount

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class TokenAmount(val amount: String, val rawAmount: String)
```

## Constructors

```kotlin theme={null}
constructor(amount: String, rawAmount: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `amount` | `String` | - |
| `rawAmount` | `String` | - |


# TokenBalance
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/token-balance

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class TokenBalance(val symbol: String, val name: String, val decimals: Int, val amount: String, val rawAmount: String, val chainInfo: ChainInfo? = null, val available: TokenAmount? = null, val locked: TokenAmount? = null, val accounts: List<TokenAccountBalance>? = null)
```

## Constructors

```kotlin theme={null}
constructor(symbol: String, name: String, decimals: Int, amount: String, rawAmount: String, chainInfo: ChainInfo? = null, available: TokenAmount? = null, locked: TokenAmount? = null, accounts: List<TokenAccountBalance>? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `accounts` | `List<TokenAccountBalance>?` | - |
| `amount` | `String` | - |
| `available` | `TokenAmount?` | - |
| `chainInfo` | `ChainInfo?` | - |
| `decimals` | `Int` | - |
| `locked` | `TokenAmount?` | - |
| `name` | `String` | - |
| `rawAmount` | `String` | - |
| `symbol` | `String` | - |


# Transaction
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/transaction

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Transaction(val id: String, val status: TransactionStatus, val onChain: OnChainData, val params: TransactionParams, val walletType: WalletType, val createdAt: Long, val approvals: Approvals?, val error: TransactionErrorDetails?)
```

## Constructors

```kotlin theme={null}
constructor(id: String, status: TransactionStatus, onChain: OnChainData, params: TransactionParams, walletType: WalletType, createdAt: Long, approvals: Approvals?, error: TransactionErrorDetails?)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `approvals` | `Approvals?` | Approval signatures required or submitted for this transaction, if any |
| `createdAt` | `Long` | Unix epoch milliseconds when the transaction was created |
| `error` | `TransactionErrorDetails?` | Error details when status is TransactionStatus.FAILED, otherwise null |
| `id` | `String` | Unique transaction identifier |
| `onChain` | `OnChainData` | Chain-specific data available after the transaction is submitted |
| `params` | `TransactionParams` | The inputs used to construct this transaction |
| `status` | `TransactionStatus` | Current lifecycle state of the transaction |
| `walletType` | `WalletType` | The type of wallet that owns this transaction |


# TransactionErrorDetails
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/transaction-error-details

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class TransactionErrorDetails(val reason: String, val message: String, val revert: TransactionErrorDetails.Revert?)
```

## Constructors

```kotlin theme={null}
constructor(reason: String, message: String, revert: TransactionErrorDetails.Revert?)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `message` | `String` | - |
| `reason` | `String` | - |
| `revert` | `TransactionErrorDetails.Revert?` | - |


# TransactionErrorDetails.Revert
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/transaction-error-details-revert

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Revert(val type: String, val reason: String, val simulationLink: String?)
```

## Constructors

```kotlin theme={null}
constructor(type: String, reason: String, simulationLink: String?)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `reason` | `String` | - |
| `simulationLink` | `String?` | The link to a simulation of the failed transaction. |
| `type` | `String` | - |


# TransactionError.Forbidden
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/transaction-error-forbidden

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Forbidden(val message: String, val cause: Throwable? = null) : TransactionError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `TransactionErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# TransactionError.InvalidTransactionState
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/transaction-error-invalid-transaction-state

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class InvalidTransactionState(val message: String, val cause: Throwable? = null) : TransactionError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `TransactionErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# TransactionError.RateLimited
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/transaction-error-rate-limited

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class RateLimited(val message: String, val cause: Throwable? = null) : TransactionError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `TransactionErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# TransactionError.ServiceNotInitialized
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/transaction-error-service-not-initialized

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class ServiceNotInitialized(val message: String, val cause: Throwable? = null) : TransactionError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `TransactionErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# TransactionError.SigningFailed
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/transaction-error-signing-failed

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class SigningFailed(val message: String, val cause: Throwable? = null) : TransactionError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `TransactionErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# TransactionError.Timeout
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/transaction-error-timeout

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Timeout(val message: String, val cause: Throwable? = null) : TransactionError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `TransactionErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# TransactionError.TransactionCreationFailed
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/transaction-error-transaction-creation-failed

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class TransactionCreationFailed(val message: String, val cause: Throwable? = null) : TransactionError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `TransactionErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# TransactionError.TransactionFailed
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/transaction-error-transaction-failed

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class TransactionFailed(val message: String, val cause: Throwable? = null) : TransactionError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `TransactionErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# TransactionError.TransactionNotFound
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/transaction-error-transaction-not-found

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class TransactionNotFound(val message: String, val cause: Throwable? = null) : TransactionError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `TransactionErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# TransactionError.TransactionOperationFailed
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/transaction-error-transaction-operation-failed

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class TransactionOperationFailed(val message: String, val cause: Throwable? = null) : TransactionError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `TransactionErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# TransactionError.Unauthorized
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/transaction-error-unauthorized

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Unauthorized(val message: String, val cause: Throwable? = null) : TransactionError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `TransactionErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# TransactionError.UserCancelled
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/transaction-error-user-cancelled

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class UserCancelled(val message: String = "The user cancelled the signature", val cause: Throwable? = null) : TransactionError
```

## Constructors

```kotlin theme={null}
constructor(message: String = "The user cancelled the signature", cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `TransactionErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# Transfer
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/transfer

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Transfer(val id: String, val type: TransferType, val fromAddress: String, val toAddress: String, val txHash: String, val tokenSymbol: String?, val amount: String, val timestamp: Long)
```

## Constructors

```kotlin theme={null}
constructor(id: String, type: TransferType, fromAddress: String, toAddress: String, txHash: String, tokenSymbol: String?, amount: String, timestamp: Long)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `amount` | `String` | Human-readable transfer amount |
| `fromAddress` | `String` | - |
| `id` | `String` | The transfer identifier |
| `timestamp` | `Long` | Unix epoch milliseconds when the transfer occurred |
| `toAddress` | `String` | - |
| `tokenSymbol` | `String?` | Symbol of the token transferred, or null if unknown |
| `txHash` | `String` | On-chain transaction hash |
| `type` | `TransferType` | - |


# TransferError.LoadFailed
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/transfer-error-load-failed

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class LoadFailed(val message: String, val cause: Throwable? = null) : TransferError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `TransferErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# TransferError.ServiceNotInitialized
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/transfer-error-service-not-initialized

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class ServiceNotInitialized(val message: String, val cause: Throwable? = null) : TransferError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `TransferErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# TransferError.Unauthorized
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/transfer-error-unauthorized

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Unauthorized(val message: String, val cause: Throwable? = null) : TransferError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `TransferErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# TransferError.Unknown
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/transfer-error-unknown

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Unknown(val message: String, val cause: Throwable? = null) : TransferError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `TransferErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# TransferList
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/transfer-list

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class TransferList(val transfers: List<Transfer>)
```

## Constructors

```kotlin theme={null}
constructor(transfers: List<Transfer>)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `transfers` | `List<Transfer>` | - |


# UserOperation
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/user-operation

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class UserOperation(val paymaster: String?, val paymasterVerificationGasLimit: String, val preVerificationGas: String, val nonce: String, val paymasterPostOpGasLimit: String, val factoryData: String?, val factory: String?, val signature: String, val callGasLimit: String, val paymasterData: String?, val verificationGasLimit: String, val maxFeePerGas: String, val sender: String, val callData: String, val maxPriorityFeePerGas: String)
```

## Constructors

```kotlin theme={null}
constructor(paymaster: String?, paymasterVerificationGasLimit: String, preVerificationGas: String, nonce: String, paymasterPostOpGasLimit: String, factoryData: String?, factory: String?, signature: String, callGasLimit: String, paymasterData: String?, verificationGasLimit: String, maxFeePerGas: String, sender: String, callData: String, maxPriorityFeePerGas: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `callData` | `String` | - |
| `callGasLimit` | `String` | - |
| `factory` | `String?` | - |
| `factoryData` | `String?` | - |
| `maxFeePerGas` | `String` | - |
| `maxPriorityFeePerGas` | `String` | - |
| `nonce` | `String` | - |
| `paymaster` | `String?` | - |
| `paymasterData` | `String?` | - |
| `paymasterPostOpGasLimit` | `String` | - |
| `paymasterVerificationGasLimit` | `String` | - |
| `preVerificationGas` | `String` | - |
| `sender` | `String` | - |
| `signature` | `String` | - |
| `verificationGasLimit` | `String` | - |


# WalletConfig
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/wallet-config

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class WalletConfig(val adminSigner: SignerData, val delegatedSigners: List<DelegatedSignerData> = emptyList(), val recoveryMethods: List<RecoveryMethod> = listOf(RecoveryMethod(adminSigner)))
```

## Constructors

```kotlin theme={null}
constructor(adminSigner: SignerData, delegatedSigners: List<DelegatedSignerData> = emptyList(), recoveryMethods: List<RecoveryMethod> = listOf(RecoveryMethod(adminSigner)))
```

## Properties

| Property | Type | Description |
| - | - | - |
| `adminSigner` | `SignerData` | The primary recovery signer. It is the signer of the first entry in recoveryMethods. |
| `delegatedSigners` | `List<DelegatedSignerData>` | The delegated signers registered on the wallet. |
| `recoveryMethods` | `List<RecoveryMethod>` | Every recovery method of the wallet, with its status. An active recovery method can authorize on its own. A wallet with one recovery signer has one entry in this list. |


# WalletError.ChainNotSupported
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/wallet-error-chain-not-supported

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class ChainNotSupported(val message: String, val cause: Throwable? = null) : WalletError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `WalletErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# WalletError.DelegatedSignerConflict
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/wallet-error-delegated-signer-conflict

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class DelegatedSignerConflict(val message: String, val cause: Throwable? = null) : WalletError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `WalletErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# WalletError.DeviceSignerNotSupported
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/wallet-error-device-signer-not-supported

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class DeviceSignerNotSupported(val message: String, val cause: Throwable? = null) : WalletError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `WalletErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# WalletError.DuplicateRecoverySigner
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/wallet-error-duplicate-recovery-signer

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class DuplicateRecoverySigner(val message: String, val cause: Throwable? = null) : WalletError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `WalletErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# WalletError.Forbidden
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/wallet-error-forbidden

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Forbidden(val message: String, val cause: Throwable? = null) : WalletError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `WalletErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# WalletError.InvalidInput
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/wallet-error-invalid-input

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class InvalidInput(val message: String, val cause: Throwable? = null) : WalletError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `WalletErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# WalletError.InvalidRecoveryConfig
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/wallet-error-invalid-recovery-config

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class InvalidRecoveryConfig(val message: String, val cause: Throwable? = null) : WalletError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `WalletErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# WalletError.InvalidSigner
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/wallet-error-invalid-signer

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class InvalidSigner(val message: String, val cause: Throwable? = null) : WalletError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `WalletErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# WalletError.LastRecoverySigner
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/wallet-error-last-recovery-signer

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class LastRecoverySigner(val message: String, val cause: Throwable? = null) : WalletError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `WalletErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# WalletError.RateLimited
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/wallet-error-rate-limited

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class RateLimited(val message: String, val cause: Throwable? = null) : WalletError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `WalletErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# WalletError.RecoveryAdminSignerConflict
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/wallet-error-recovery-admin-signer-conflict

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class RecoveryAdminSignerConflict(val message: String, val cause: Throwable? = null) : WalletError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `WalletErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# WalletError.RecoveryNotSupportedOnApiVersion
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/wallet-error-recovery-not-supported-on-api-version

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class RecoveryNotSupportedOnApiVersion(val message: String, val cause: Throwable? = null) : WalletError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `WalletErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# WalletError.RecoveryNotSupportedOnChain
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/wallet-error-recovery-not-supported-on-chain

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class RecoveryNotSupportedOnChain(val message: String, val cause: Throwable? = null) : WalletError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `WalletErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# WalletError.RecoverySignerConflict
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/wallet-error-recovery-signer-conflict

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class RecoverySignerConflict(val message: String, val cause: Throwable? = null) : WalletError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `WalletErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# WalletError.RecoverySignerNotAllowed
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/wallet-error-recovery-signer-not-allowed

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class RecoverySignerNotAllowed(val message: String, val cause: Throwable? = null) : WalletError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `WalletErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# WalletError.ServiceNotInitialized
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/wallet-error-service-not-initialized

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class ServiceNotInitialized(val message: String = "Wallet service not initialized", val cause: Throwable? = null) : WalletError
```

## Constructors

```kotlin theme={null}
constructor(message: String = "Wallet service not initialized", cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `WalletErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# WalletError.SignerLimitExceeded
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/wallet-error-signer-limit-exceeded

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class SignerLimitExceeded(val message: String, val cause: Throwable? = null) : WalletError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `WalletErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# WalletError.SignerNotRegistered
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/wallet-error-signer-not-registered

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class SignerNotRegistered(val message: String, val cause: Throwable? = null) : WalletError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `WalletErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# WalletError.SignerRequired
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/wallet-error-signer-required

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class SignerRequired(val message: String, val cause: Throwable? = null) : WalletError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `WalletErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# WalletError.SigningError
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/wallet-error-signing-error

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class SigningError(val message: String, val cause: Throwable? = null) : WalletError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `WalletErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# WalletError.Unauthorized
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/wallet-error-unauthorized

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Unauthorized(val message: String, val cause: Throwable? = null) : WalletError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `WalletErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# WalletError.WalletNotFound
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/wallet-error-wallet-not-found

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class WalletNotFound(val message: String, val cause: Throwable? = null) : WalletError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `WalletErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# WalletError.WalletOperationFailed
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/wallet-error-wallet-operation-failed

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class WalletOperationFailed(val message: String, val cause: Throwable? = null, val statusCode: Int? = null) : WalletError
```

## Constructors

```kotlin theme={null}
constructor(message: String, cause: Throwable? = null)constructor(message: String, cause: Throwable? = null, statusCode: Int? = null)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `WalletErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |
| `statusCode` | `Int?` | - |


# WebViewMessage.Custom
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/data-classes/web-view-message-custom

Kotlin Data Class

**Data Class**

```kotlin theme={null}
data class Custom(val data: String) : WebViewMessage
```

## Constructors

```kotlin theme={null}
constructor(data: String)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `data` | `String` | - |


# ApiKey.Type
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/enums/api-key-type

Kotlin Enum Class

**Enum Class**

```kotlin theme={null}
enum Type : Enum<ApiKey.Type>
```

## Entries

| Entry | Description |
| - | - |
| `CLIENT` | - |
| `SERVER` | - |

## Properties

| Property | Type | Description |
| - | - | - |
| `entries` | `EnumEntries<ApiKey.Type>` | Returns a representation of an immutable list of all enum entries, in the order they're declared. |
| `name` | `String` | - |
| `ordinal` | `Int` | - |

## Functions

| Function | Description |
| - | - |
| `valueOf` | Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.) |
| `values` | Returns an array containing the constants of this enum type, in the order they're declared. |

### valueOf

```kotlin theme={null}
fun valueOf(value: String): ApiKey.Type
```

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

### values

```kotlin theme={null}
fun values(): Array<ApiKey.Type>
```

Returns an array containing the constants of this enum type, in the order they're declared.


# AuthErrorCode
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/enums/auth-error-code

Kotlin Enum Class

**Enum Class**

```kotlin theme={null}
enum AuthErrorCode : Enum<AuthErrorCode> , CrossmintErrorCode
```

## Entries

| Entry | Description |
| - | - |
| `INVALID_CREDENTIALS` | - |
| `TOKEN_EXPIRED` | - |
| `UNAUTHORIZED` | - |
| `SERVER_ERROR` | - |
| `RATE_LIMITED` | - |
| `NOT_INITIALIZED` | - |

## Properties

| Property | Type | Description |
| - | - | - |
| `entries` | `EnumEntries<AuthErrorCode>` | Returns a representation of an immutable list of all enum entries, in the order they're declared. |
| `name` | `String` | - |
| `ordinal` | `Int` | - |

## Functions

| Function | Description |
| - | - |
| `valueOf` | Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.) |
| `values` | Returns an array containing the constants of this enum type, in the order they're declared. |

### valueOf

```kotlin theme={null}
fun valueOf(value: String): AuthErrorCode
```

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

### values

```kotlin theme={null}
fun values(): Array<AuthErrorCode>
```

Returns an array containing the constants of this enum type, in the order they're declared.


# BalanceErrorCode
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/enums/balance-error-code

Kotlin Enum Class

**Enum Class**

```kotlin theme={null}
enum BalanceErrorCode : Enum<BalanceErrorCode> , CrossmintErrorCode
```

## Entries

| Entry | Description |
| - | - |
| `NOT_FOUND` | - |
| `UNAUTHORIZED` | - |
| `FORBIDDEN` | - |
| `RATE_LIMITED` | - |
| `OPERATION_FAILED` | - |
| `SERVICE_NOT_INITIALIZED` | - |

## Properties

| Property | Type | Description |
| - | - | - |
| `entries` | `EnumEntries<BalanceErrorCode>` | Returns a representation of an immutable list of all enum entries, in the order they're declared. |
| `name` | `String` | - |
| `ordinal` | `Int` | - |

## Functions

| Function | Description |
| - | - |
| `valueOf` | Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.) |
| `values` | Returns an array containing the constants of this enum type, in the order they're declared. |

### valueOf

```kotlin theme={null}
fun valueOf(value: String): BalanceErrorCode
```

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

### values

```kotlin theme={null}
fun values(): Array<BalanceErrorCode>
```

Returns an array containing the constants of this enum type, in the order they're declared.


# ChainType
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/enums/chain-type

Kotlin Enum Class

**Enum Class**

```kotlin theme={null}
enum ChainType : Enum<ChainType>
```

## Entries

| Entry | Description |
| - | - |
| `EVM` | Ethereum Virtual Machine compatible chains |
| `SOLANA` | Solana blockchain |
| `STELLAR` | Stellar blockchain |
| `UNKNOWN` | Unknown or unsupported chain type |

## Properties

| Property | Type | Description |
| - | - | - |
| `chainName` | `String` | - |
| `entries` | `EnumEntries<ChainType>` | Returns a representation of an immutable list of all enum entries, in the order they're declared. |
| `name` | `String` | - |
| `ordinal` | `Int` | - |

## Functions

| Function | Description |
| - | - |
| `valueOf` | Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.) |
| `values` | Returns an array containing the constants of this enum type, in the order they're declared. |

### valueOf

```kotlin theme={null}
fun valueOf(value: String): ChainType
```

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

### values

```kotlin theme={null}
fun values(): Array<ChainType>
```

Returns an array containing the constants of this enum type, in the order they're declared.


# ConfigurationErrorCode
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/enums/configuration-error-code

Kotlin Enum Class

**Enum Class**

```kotlin theme={null}
enum ConfigurationErrorCode : Enum<ConfigurationErrorCode> , CrossmintErrorCode
```

## Entries

| Entry | Description |
| - | - |
| `API_KEY_OLD_FORMAT` | - |
| `API_KEY_INVALID_ENVIRONMENT` | - |
| `API_KEY_MALFORMED` | - |

## Properties

| Property | Type | Description |
| - | - | - |
| `entries` | `EnumEntries<ConfigurationErrorCode>` | Returns a representation of an immutable list of all enum entries, in the order they're declared. |
| `name` | `String` | - |
| `ordinal` | `Int` | - |

## Functions

| Function | Description |
| - | - |
| `valueOf` | Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.) |
| `values` | Returns an array containing the constants of this enum type, in the order they're declared. |

### valueOf

```kotlin theme={null}
fun valueOf(value: String): ConfigurationErrorCode
```

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

### values

```kotlin theme={null}
fun values(): Array<ConfigurationErrorCode>
```

Returns an array containing the constants of this enum type, in the order they're declared.


# DelegatedSignerStatus
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/enums/delegated-signer-status

Kotlin Enum Class

**Enum Class**

```kotlin theme={null}
enum DelegatedSignerStatus : Enum<DelegatedSignerStatus>
```

## Entries

| Entry | Description |
| - | - |
| `ACTIVE` | - |
| `AWAITING_APPROVAL` | - |
| `PENDING` | - |
| `FAILED` | - |
| `UNKNOWN` | Fallback when the API omits the status field or returns an unrecognised value. |

## Properties

| Property | Type | Description |
| - | - | - |
| `entries` | `EnumEntries<DelegatedSignerStatus>` | Returns a representation of an immutable list of all enum entries, in the order they're declared. |
| `name` | `String` | - |
| `ordinal` | `Int` | - |
| `value` | `String` | - |

## Functions

| Function | Description |
| - | - |
| `valueOf` | Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.) |
| `values` | Returns an array containing the constants of this enum type, in the order they're declared. |

### valueOf

```kotlin theme={null}
fun valueOf(value: String): DelegatedSignerStatus
```

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

### values

```kotlin theme={null}
fun values(): Array<DelegatedSignerStatus>
```

Returns an array containing the constants of this enum type, in the order they're declared.


# DelegatedSignerType
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/enums/delegated-signer-type

Kotlin Enum Class

**Enum Class**

```kotlin theme={null}
enum DelegatedSignerType : Enum<DelegatedSignerType>
```

## Entries

| Entry | Description |
| - | - |
| `DEVICE` | - |
| `EMAIL` | - |
| `PHONE` | - |
| `EXTERNAL_WALLET` | - |
| `PASSKEY` | - |
| `API_KEY` | - |
| `UNKNOWN` | Fallback for unknown or unrecognised type values. |

## Properties

| Property | Type | Description |
| - | - | - |
| `entries` | `EnumEntries<DelegatedSignerType>` | Returns a representation of an immutable list of all enum entries, in the order they're declared. |
| `name` | `String` | - |
| `ordinal` | `Int` | - |
| `value` | `String` | - |

## Functions

| Function | Description |
| - | - |
| `valueOf` | Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.) |
| `values` | Returns an array containing the constants of this enum type, in the order they're declared. |

### valueOf

```kotlin theme={null}
fun valueOf(value: String): DelegatedSignerType
```

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

### values

```kotlin theme={null}
fun values(): Array<DelegatedSignerType>
```

Returns an array containing the constants of this enum type, in the order they're declared.


# Environment
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/enums/environment

Kotlin Enum Class

**Enum Class**

```kotlin theme={null}
enum Environment : Enum<Environment>
```

## Entries

| Entry | Description |
| - | - |
| `DEVELOPMENT` | - |
| `STAGING` | - |
| `PRODUCTION` | - |

## Properties

| Property | Type | Description |
| - | - | - |
| `entries` | `EnumEntries<Environment>` | Returns a representation of an immutable list of all enum entries, in the order they're declared. |
| `name` | `String` | - |
| `ordinal` | `Int` | - |
| `value` | `String` | - |

## Functions

| Function | Description |
| - | - |
| `valueOf` | Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.) |
| `values` | Returns an array containing the constants of this enum type, in the order they're declared. |

### valueOf

```kotlin theme={null}
fun valueOf(value: String): Environment
```

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

### values

```kotlin theme={null}
fun values(): Array<Environment>
```

Returns an array containing the constants of this enum type, in the order they're declared.


# FallbackPolicy
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/enums/fallback-policy

Kotlin Enum Class

**Enum Class**

```kotlin theme={null}
enum FallbackPolicy : Enum<FallbackPolicy>
```

## Entries

| Entry | Description |
| - | - |
| `MemoryOnly` | Fall back to in-memory storage only. Tokens will not persist across app restarts but security is maintained. |
| `InsecurePersistent` | Fall back to insecure persistent storage. Tokens will persist but are stored in plaintext. Use with caution and only when persistence is critical. |

## Properties

| Property | Type | Description |
| - | - | - |
| `entries` | `EnumEntries<FallbackPolicy>` | Returns a representation of an immutable list of all enum entries, in the order they're declared. |
| `name` | `String` | - |
| `ordinal` | `Int` | - |

## Functions

| Function | Description |
| - | - |
| `valueOf` | Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.) |
| `values` | Returns an array containing the constants of this enum type, in the order they're declared. |

### valueOf

```kotlin theme={null}
fun valueOf(value: String): FallbackPolicy
```

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

### values

```kotlin theme={null}
fun values(): Array<FallbackPolicy>
```

Returns an array containing the constants of this enum type, in the order they're declared.


# IdentityVerificationErrorCode
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/enums/identity-verification-error-code

Kotlin Enum Class

**Enum Class**

```kotlin theme={null}
enum IdentityVerificationErrorCode : Enum<IdentityVerificationErrorCode> , CrossmintErrorCode
```

## Entries

| Entry | Description |
| - | - |
| `WIDGET_UNAVAILABLE` | - |
| `INVALID_CONFIGURATION` | - |
| `INVALID_CREDENTIALS` | - |
| `PROVIDER_ERROR` | - |
| `UNKNOWN` | - |

## Properties

| Property | Type | Description |
| - | - | - |
| `entries` | `EnumEntries<IdentityVerificationErrorCode>` | Returns a representation of an immutable list of all enum entries, in the order they're declared. |
| `name` | `String` | - |
| `ordinal` | `Int` | - |

## Functions

| Function | Description |
| - | - |
| `valueOf` | Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.) |
| `values` | Returns an array containing the constants of this enum type, in the order they're declared. |

### valueOf

```kotlin theme={null}
fun valueOf(value: String): IdentityVerificationErrorCode
```

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

### values

```kotlin theme={null}
fun values(): Array<IdentityVerificationErrorCode>
```

Returns an array containing the constants of this enum type, in the order they're declared.


# LogLevel
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/enums/log-level

Kotlin Enum Class

**Enum Class**

```kotlin theme={null}
enum LogLevel : Enum<LogLevel>
```

## Entries

| Entry | Description |
| - | - |
| `DEBUG` | All SDK messages, including detailed diagnostic traces. |
| `INFO` | Lifecycle events such as initialization and auth state changes. |
| `WARN` | Recoverable issues worth attention but not fatal to the operation. |
| `ERROR` | Failures the caller should handle. |
| `SILENT` | No SDK output at all. |

## Properties

| Property | Type | Description |
| - | - | - |
| `entries` | `EnumEntries<LogLevel>` | Returns a representation of an immutable list of all enum entries, in the order they're declared. |
| `name` | `String` | - |
| `ordinal` | `Int` | - |

## Functions

| Function | Description |
| - | - |
| `valueOf` | Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.) |
| `values` | Returns an array containing the constants of this enum type, in the order they're declared. |

### valueOf

```kotlin theme={null}
fun valueOf(value: String): LogLevel
```

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

### values

```kotlin theme={null}
fun values(): Array<LogLevel>
```

Returns an array containing the constants of this enum type, in the order they're declared.


# NetworkErrorCode
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/enums/network-error-code

Kotlin Enum Class

**Enum Class**

```kotlin theme={null}
enum NetworkErrorCode : Enum<NetworkErrorCode> , CrossmintErrorCode
```

## Entries

| Entry | Description |
| - | - |
| `HTTP_ERROR` | - |
| `CONNECTION_ERROR` | - |
| `TIMEOUT_ERROR` | - |
| `PARSE_ERROR` | - |
| `UNKNOWN_ERROR` | - |
| `SERVICE_NOT_INITIALIZED` | - |

## Properties

| Property | Type | Description |
| - | - | - |
| `entries` | `EnumEntries<NetworkErrorCode>` | Returns a representation of an immutable list of all enum entries, in the order they're declared. |
| `name` | `String` | - |
| `ordinal` | `Int` | - |

## Functions

| Function | Description |
| - | - |
| `valueOf` | Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.) |
| `values` | Returns an array containing the constants of this enum type, in the order they're declared. |

### valueOf

```kotlin theme={null}
fun valueOf(value: String): NetworkErrorCode
```

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

### values

```kotlin theme={null}
fun values(): Array<NetworkErrorCode>
```

Returns an array containing the constants of this enum type, in the order they're declared.


# OTPDeliveryChannel
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/enums/otp-delivery-channel

Kotlin Enum Class

**Enum Class**

```kotlin theme={null}
enum OTPDeliveryChannel : Enum<OTPDeliveryChannel>
```

## Entries

| Entry | Description |
| - | - |
| `SMS` | A text message to the phone number. |
| `WHATSAPP` | A WhatsApp message to the phone number. |

## Properties

| Property | Type | Description |
| - | - | - |
| `entries` | `EnumEntries<OTPDeliveryChannel>` | Returns a representation of an immutable list of all enum entries, in the order they're declared. |
| `name` | `String` | - |
| `ordinal` | `Int` | - |

## Functions

| Function | Description |
| - | - |
| `valueOf` | Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.) |
| `values` | Returns an array containing the constants of this enum type, in the order they're declared. |

### valueOf

```kotlin theme={null}
fun valueOf(value: String): OTPDeliveryChannel
```

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

### values

```kotlin theme={null}
fun values(): Array<OTPDeliveryChannel>
```

Returns an array containing the constants of this enum type, in the order they're declared.


# PasskeyErrorCode
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/enums/passkey-error-code

Kotlin Enum Class

**Enum Class**

```kotlin theme={null}
enum PasskeyErrorCode : Enum<PasskeyErrorCode> , CrossmintErrorCode
```

## Entries

| Entry | Description |
| - | - |
| `CANCELLED` | - |
| `FAILED` | - |

## Properties

| Property | Type | Description |
| - | - | - |
| `entries` | `EnumEntries<PasskeyErrorCode>` | Returns a representation of an immutable list of all enum entries, in the order they're declared. |
| `name` | `String` | - |
| `ordinal` | `Int` | - |

## Functions

| Function | Description |
| - | - |
| `valueOf` | Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.) |
| `values` | Returns an array containing the constants of this enum type, in the order they're declared. |

### valueOf

```kotlin theme={null}
fun valueOf(value: String): PasskeyErrorCode
```

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

### values

```kotlin theme={null}
fun values(): Array<PasskeyErrorCode>
```

Returns an array containing the constants of this enum type, in the order they're declared.


# SignatureErrorCode
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/enums/signature-error-code

Kotlin Enum Class

**Enum Class**

```kotlin theme={null}
enum SignatureErrorCode : Enum<SignatureErrorCode> , CrossmintErrorCode
```

## Entries

| Entry | Description |
| - | - |
| `CREATION_FAILED` | - |
| `SIGNING_FAILED` | - |
| `CHAIN_NOT_SUPPORTED` | - |
| `SERVICE_NOT_INITIALIZED` | - |
| `UNAUTHORIZED` | - |
| `FORBIDDEN` | - |
| `TIMEOUT` | - |
| `UNKNOWN` | - |
| `USER_CANCELLED` | - |

## Properties

| Property | Type | Description |
| - | - | - |
| `entries` | `EnumEntries<SignatureErrorCode>` | Returns a representation of an immutable list of all enum entries, in the order they're declared. |
| `name` | `String` | - |
| `ordinal` | `Int` | - |

## Functions

| Function | Description |
| - | - |
| `valueOf` | Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.) |
| `values` | Returns an array containing the constants of this enum type, in the order they're declared. |

### valueOf

```kotlin theme={null}
fun valueOf(value: String): SignatureErrorCode
```

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

### values

```kotlin theme={null}
fun values(): Array<SignatureErrorCode>
```

Returns an array containing the constants of this enum type, in the order they're declared.


# TransactionErrorCode
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/enums/transaction-error-code

Kotlin Enum Class

**Enum Class**

```kotlin theme={null}
enum TransactionErrorCode : Enum<TransactionErrorCode> , CrossmintErrorCode
```

## Entries

| Entry | Description |
| - | - |
| `CREATION_FAILED` | - |
| `NOT_FOUND` | - |
| `SERVICE_NOT_INITIALIZED` | - |
| `UNAUTHORIZED` | - |
| `FORBIDDEN` | - |
| `RATE_LIMITED` | - |
| `SIGNING_FAILED` | - |
| `INVALID_STATE` | - |
| `TIMEOUT` | - |
| `FAILED` | - |
| `OPERATION_FAILED` | - |
| `USER_CANCELLED` | - |

## Properties

| Property | Type | Description |
| - | - | - |
| `entries` | `EnumEntries<TransactionErrorCode>` | Returns a representation of an immutable list of all enum entries, in the order they're declared. |
| `name` | `String` | - |
| `ordinal` | `Int` | - |

## Functions

| Function | Description |
| - | - |
| `valueOf` | Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.) |
| `values` | Returns an array containing the constants of this enum type, in the order they're declared. |

### valueOf

```kotlin theme={null}
fun valueOf(value: String): TransactionErrorCode
```

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

### values

```kotlin theme={null}
fun values(): Array<TransactionErrorCode>
```

Returns an array containing the constants of this enum type, in the order they're declared.


# TransactionStatus
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/enums/transaction-status

Kotlin Enum Class

**Enum Class**

```kotlin theme={null}
enum TransactionStatus : Enum<TransactionStatus>
```

## Entries

| Entry | Description |
| - | - |
| `PENDING` | Transaction created but not yet signed or submitted to the network. |
| `SUCCESS` | Transaction confirmed on-chain. |
| `FAILED` | Transaction failed on-chain or was rejected. |
| `AWAITING_APPROVAL` | Transaction is waiting for a signer to call Wallet.approve. |

## Properties

| Property | Type | Description |
| - | - | - |
| `entries` | `EnumEntries<TransactionStatus>` | Returns a representation of an immutable list of all enum entries, in the order they're declared. |
| `name` | `String` | - |
| `ordinal` | `Int` | - |

## Functions

| Function | Description |
| - | - |
| `valueOf` | Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.) |
| `values` | Returns an array containing the constants of this enum type, in the order they're declared. |

### valueOf

```kotlin theme={null}
fun valueOf(value: String): TransactionStatus
```

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

### values

```kotlin theme={null}
fun values(): Array<TransactionStatus>
```

Returns an array containing the constants of this enum type, in the order they're declared.


# TransferErrorCode
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/enums/transfer-error-code

Kotlin Enum Class

**Enum Class**

```kotlin theme={null}
enum TransferErrorCode : Enum<TransferErrorCode> , CrossmintErrorCode
```

## Entries

| Entry | Description |
| - | - |
| `LOAD_FAILED` | - |
| `UNAUTHORIZED` | - |
| `SERVICE_NOT_INITIALIZED` | - |
| `UNKNOWN` | - |

## Properties

| Property | Type | Description |
| - | - | - |
| `entries` | `EnumEntries<TransferErrorCode>` | Returns a representation of an immutable list of all enum entries, in the order they're declared. |
| `name` | `String` | - |
| `ordinal` | `Int` | - |

## Functions

| Function | Description |
| - | - |
| `valueOf` | Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.) |
| `values` | Returns an array containing the constants of this enum type, in the order they're declared. |

### valueOf

```kotlin theme={null}
fun valueOf(value: String): TransferErrorCode
```

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

### values

```kotlin theme={null}
fun values(): Array<TransferErrorCode>
```

Returns an array containing the constants of this enum type, in the order they're declared.


# TransferType
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/enums/transfer-type

Kotlin Enum Class

**Enum Class**

```kotlin theme={null}
enum TransferType : Enum<TransferType>
```

## Entries

| Entry | Description |
| - | - |
| `OUTGOING` | Token left this wallet. |
| `INCOMING` | Token arrived at this wallet. |
| `UNKNOWN` | Direction could not be determined. |

## Properties

| Property | Type | Description |
| - | - | - |
| `entries` | `EnumEntries<TransferType>` | Returns a representation of an immutable list of all enum entries, in the order they're declared. |
| `name` | `String` | - |
| `ordinal` | `Int` | - |

## Functions

| Function | Description |
| - | - |
| `valueOf` | Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.) |
| `values` | Returns an array containing the constants of this enum type, in the order they're declared. |

### valueOf

```kotlin theme={null}
fun valueOf(value: String): TransferType
```

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

### values

```kotlin theme={null}
fun values(): Array<TransferType>
```

Returns an array containing the constants of this enum type, in the order they're declared.


# WalletErrorCode
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/enums/wallet-error-code

Kotlin Enum Class

**Enum Class**

```kotlin theme={null}
enum WalletErrorCode : Enum<WalletErrorCode> , CrossmintErrorCode
```

## Entries

| Entry | Description |
| - | - |
| `INVALID_INPUT` | - |
| `UNAUTHORIZED` | - |
| `FORBIDDEN` | - |
| `NOT_FOUND` | - |
| `RATE_LIMITED` | - |
| `OPERATION_FAILED` | - |
| `SERVICE_NOT_INITIALIZED` | - |
| `INVALID_SIGNER` | - |
| `SIGNER_NOT_REGISTERED` | - |
| `DEVICE_SIGNER_NOT_SUPPORTED` | - |
| `CHAIN_NOT_SUPPORTED` | - |
| `SIGNING_ERROR` | - |
| `INVALID_RECOVERY_CONFIG` | - |
| `SIGNER_LIMIT_EXCEEDED` | - |
| `RECOVERY_DUPLICATE_SIGNER` | - |
| `RECOVERY_SIGNER_CONFLICT` | - |
| `DELEGATED_SIGNER_CONFLICT` | - |
| `SIGNER_REQUIRED` | - |
| `NOT_SUPPORTED_ON_API_VERSION` | - |
| `RECOVERY_ADMIN_SIGNER_CONFLICT` | - |
| `RECOVERY_NOT_SUPPORTED_ON_CHAIN` | - |
| `LAST_RECOVERY_SIGNER` | - |
| `RECOVERY_SIGNER_NOT_ALLOWED` | - |

## Properties

| Property | Type | Description |
| - | - | - |
| `entries` | `EnumEntries<WalletErrorCode>` | Returns a representation of an immutable list of all enum entries, in the order they're declared. |
| `name` | `String` | - |
| `ordinal` | `Int` | - |

## Functions

| Function | Description |
| - | - |
| `valueOf` | Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.) |
| `values` | Returns an array containing the constants of this enum type, in the order they're declared. |

### valueOf

```kotlin theme={null}
fun valueOf(value: String): WalletErrorCode
```

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

### values

```kotlin theme={null}
fun values(): Array<WalletErrorCode>
```

Returns an array containing the constants of this enum type, in the order they're declared.


# WalletType
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/enums/wallet-type

Kotlin Enum Class

**Enum Class**

```kotlin theme={null}
enum WalletType : Enum<WalletType>
```

## Entries

| Entry | Description |
| - | - |
| `SMART_WALLET` | Account abstraction wallet governed by an on-chain smart contract. |
| `MPC_WALLET` | Multi-party computation wallet where key shares are distributed. |

## Properties

| Property | Type | Description |
| - | - | - |
| `entries` | `EnumEntries<WalletType>` | Returns a representation of an immutable list of all enum entries, in the order they're declared. |
| `name` | `String` | - |
| `ordinal` | `Int` | - |

## Functions

| Function | Description |
| - | - |
| `valueOf` | Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.) |
| `values` | Returns an array containing the constants of this enum type, in the order they're declared. |

### valueOf

```kotlin theme={null}
fun valueOf(value: String): WalletType
```

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

### values

```kotlin theme={null}
fun values(): Array<WalletType>
```

Returns an array containing the constants of this enum type, in the order they're declared.


# configure
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/functions/configure

Kotlin Function

**Function**

```kotlin theme={null}
fun CrossmintSDK.Companion.configure(apiKey: String, appContext: Context, logLevel: LogLevel = LogLevel.WARN)
```

Configures the SDK with the given API key and Android application context. Safe to call multiple times — subsequent calls after the first are ignored.


# createAndroidTEE
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/functions/create-android-tee

Kotlin Function

**Function**

```kotlin theme={null}
fun createAndroidTEE(context: Context, apiKey: ApiKey, authManager: AuthManager, teeEncryptor: TEEEncryptor? = null): CrossmintTEE
```

Factory function to create Android TEE provider.


# createAuthManager
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/functions/create-auth-manager

Kotlin Function

**Function**

```kotlin theme={null}
fun createAuthManager(apiKey: String, secureStorage: SessionStore, appContext: Context): CrossmintAuthManager
```

Creates a CrossmintAuthManager instance for Android.


# createCrossmintWallets
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/functions/create-crossmint-wallets

Kotlin Function

**Function**

```kotlin theme={null}
fun createCrossmintWallets(service: Result): Result
```

Creates a CrossmintWallets implementation with the given service and auth manager. This function is primarily for internal SDK use. The SDK automatically creates a CrossmintWallets instance when initialized via CrossmintSDK.initialize().


# createDefaultAuthManager
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/functions/create-default-auth-manager

Kotlin Function

**Function**

```kotlin theme={null}
fun createDefaultAuthManager(configuration: Result, service: Result, sessionStore: Result, appContext: Any): Result
```

Creates an AuthManager implementation with the given service. This function is primarily for internal SDK use. The SDK automatically creates an AuthManager when initialized via CrossmintSDK.initialize().


# createDefaultSessionStore
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/functions/create-default-session-store

Kotlin Function

**Function**

```kotlin theme={null}
expect fun createDefaultSessionStore(appContext: Any): Result
```

Creates the default session store for the current platform.


# createEVMWallet
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/functions/create-evm-wallet

Kotlin Function

**Function**

```kotlin theme={null}
fun createEVMWallet(evmChain: EVMChain, address: String, type: WalletType, owner: Owner?, config: WalletConfig, transactionOperations: TransactionOperations? = null, balanceOperations: BalanceOperations? = null, signer: Signer? = null, logger: Logger, signerManagementOperations: SignerManagementOperations? = null, nftOperations: NFTOperations? = null): EVMWallet
```


# createPasskeyCredential
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/functions/create-passkey-credential

Kotlin Function

**Function**

```kotlin theme={null}
suspend fun createPasskeyCredential(name: String, activityProvider: () -> Activity, credentialManager: CredentialManager, rpId: String, rpName: String = DEFAULT_PASSKEY_RP_NAME): PasskeyCredentialInfo?
```

Creates a new passkey credential via CredentialManager and returns the public key coordinates needed to register it as a delegated signer.


# createSolanaWallet
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/functions/create-solana-wallet

Kotlin Function

**Function**

```kotlin theme={null}
fun createSolanaWallet(solanaChain: SolanaChain, address: String, type: WalletType, owner: Owner?, config: WalletConfig, transactionOperations: TransactionOperations? = null, balanceOperations: BalanceOperations? = null, signer: Signer? = null, logger: Logger, signerManagementOperations: SignerManagementOperations? = null, nftOperations: NFTOperations? = null): SolanaWallet
```


# createStellarWallet
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/functions/create-stellar-wallet

Kotlin Function

**Function**

```kotlin theme={null}
fun createStellarWallet(stellarChain: StellarChain, address: String, type: WalletType, owner: Owner?, config: WalletConfig, transactionOperations: TransactionOperations? = null, balanceOperations: BalanceOperations? = null, signer: Signer? = null, logger: Logger, signerManagementOperations: SignerManagementOperations? = null): StellarWallet
```


# createWallet
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/functions/create-wallet

Kotlin Function

**Function**

```kotlin theme={null}
fun createWallet(address: String, type: WalletType, chain: Chain, owner: Owner?, config: WalletConfig, transactionOperations: TransactionOperations? = null, balanceOperations: BalanceOperations? = null, signer: Signer? = null, logger: Logger, signerManagementOperations: SignerManagementOperations? = null, nftOperations: NFTOperations? = null): Wallet
```

Factory function to create a Wallet instance. Used by sdk-wallets module to create wallets with transaction operations.


# CrossmintTEEWebView
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/functions/crossmint-tee-web-view

Kotlin Function

**Function**

```kotlin theme={null}
fun CrossmintTEEWebView(tee: CrossmintTEE, modifier: Modifier = Modifier)
```


# flatMap
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/functions/flat-map

Kotlin Function

**Function**

```kotlin theme={null}
inline fun <T, E, R> Result<T, E>.flatMap(transform: (T) -> Result<R, E>): Result<R, E>
```

Chains a success through transform, which itself returns a Result.


# fold
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/functions/fold

Kotlin Function

**Function**

```kotlin theme={null}
inline fun <T, E> Result<T, E>.fold(onSuccess: (T) -> Unit, onFailure: (E) -> Unit)
```

Applies onSuccess or onFailure depending on the result variant.


# getOrNull
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/functions/get-or-null

Kotlin Function

**Function**

```kotlin theme={null}
fun <T, E> Result<T, E>.getOrNull(): T?
```

Returns the success value, or null if this is a Result.Failure.


# getOrThrow
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/functions/get-or-throw

Kotlin Function

**Function**

```kotlin theme={null}
fun <T, E> Result<T, E>.getOrThrow(): T
```

Returns the success value, or throws if this is a Result.Failure.


# isMainThread
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/functions/is-main-thread

Kotlin Function

**Function**

```kotlin theme={null}
expect fun isMainThread(): Boolean
```


# makePasskeySignerCallback
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/functions/make-passkey-signer-callback

Kotlin Function

**Function**

```kotlin theme={null}
fun makePasskeySignerCallback(credentialId: String, activityProvider: () -> Activity, credentialManager: CredentialManager, rpId: String): suspend (String) -> PasskeySignResult
```

Creates a signing callback for a passkey, ready to pass to DelegatedSigner.PasskeyActivation.


# map
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/functions/map

Kotlin Function

**Function**

```kotlin theme={null}
inline fun <T, E, R> Result<T, E>.map(transform: (T) -> R): Result<R, E>
```

Transforms the success value using transform, leaving failures unchanged.


# mapError
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/functions/map-error

Kotlin Function

**Function**

```kotlin theme={null}
inline fun <T, E, F> Result<T, E>.mapError(transform: (E) -> F): Result<T, F>
```

Transforms the error using transform, leaving successes unchanged.


# normalizeEmail
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/functions/normalize-email

Kotlin Function

**Function**

```kotlin theme={null}
fun normalizeEmail(email: String): String
```


# runCatching
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/functions/run-catching

Kotlin Function

**Function**

```kotlin theme={null}
suspend fun <T> runCatching(block: suspend () -> T): Result<T, Throwable>
```

Executes block and wraps the outcome in a Result.


# useSigner
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/functions/use-signer

Kotlin Function

**Function**

```kotlin theme={null}
suspend fun Wallet.useSigner(signer: DelegatedSigner.Passkey, credentialManager: CredentialManager, activityProvider: () -> Activity, rpId: String): Result<Unit, WalletError>
```

Activates a passkey signer on an EVM, Solana or Stellar wallet. On Solana, the passkey must be a delegated signer. Each time the wallet signs, the SDK calls activityProvider and shows the passkey prompt over that Activity.


# waitForMessage
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/functions/wait-for-message

Kotlin Function

**Function**

```kotlin theme={null}
inline suspend fun <T : TEEMessage> WebViewMessageHandler.waitForMessage(noinline predicate: (T) -> Boolean = { true }, timeout: Duration = 2.seconds): T
```


# Kotlin SDK Reference
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/index

API reference for the Crossmint Kotlin SDK

# Kotlin SDK Reference

## Composables

* [CrossmintNonCustodialSignerProvider](/sdk-reference/wallets/kotlin/composables/crossmint-non-custodial-signer-provider)
* [CrossmintTEEWebView](/sdk-reference/wallets/kotlin/composables/crossmint-tee-web-view)
* [CrossmintTEEWebViewContainer](/sdk-reference/wallets/kotlin/composables/crossmint-tee-web-view-container)
* [PlatformSpecificProvider](/sdk-reference/wallets/kotlin/composables/platform-specific-provider)

## Functions

* [CrossmintTEEWebView](/sdk-reference/wallets/kotlin/functions/crossmint-tee-web-view)
* [configure](/sdk-reference/wallets/kotlin/functions/configure)
* [createAndroidTEE](/sdk-reference/wallets/kotlin/functions/create-android-tee)
* [createAuthManager](/sdk-reference/wallets/kotlin/functions/create-auth-manager)
* [createCrossmintWallets](/sdk-reference/wallets/kotlin/functions/create-crossmint-wallets)
* [createDefaultAuthManager](/sdk-reference/wallets/kotlin/functions/create-default-auth-manager)
* [createDefaultSessionStore](/sdk-reference/wallets/kotlin/functions/create-default-session-store)
* [createEVMWallet](/sdk-reference/wallets/kotlin/functions/create-evm-wallet)
* [createPasskeyCredential](/sdk-reference/wallets/kotlin/functions/create-passkey-credential)
* [createSolanaWallet](/sdk-reference/wallets/kotlin/functions/create-solana-wallet)
* [createStellarWallet](/sdk-reference/wallets/kotlin/functions/create-stellar-wallet)
* [createWallet](/sdk-reference/wallets/kotlin/functions/create-wallet)
* [flatMap](/sdk-reference/wallets/kotlin/functions/flat-map)
* [fold](/sdk-reference/wallets/kotlin/functions/fold)
* [getOrNull](/sdk-reference/wallets/kotlin/functions/get-or-null)
* [getOrThrow](/sdk-reference/wallets/kotlin/functions/get-or-throw)
* [isMainThread](/sdk-reference/wallets/kotlin/functions/is-main-thread)
* [makePasskeySignerCallback](/sdk-reference/wallets/kotlin/functions/make-passkey-signer-callback)
* [map](/sdk-reference/wallets/kotlin/functions/map)
* [mapError](/sdk-reference/wallets/kotlin/functions/map-error)
* [normalizeEmail](/sdk-reference/wallets/kotlin/functions/normalize-email)
* [runCatching](/sdk-reference/wallets/kotlin/functions/run-catching)
* [useSigner](/sdk-reference/wallets/kotlin/functions/use-signer)
* [waitForMessage](/sdk-reference/wallets/kotlin/functions/wait-for-message)

## Properties

* [LocalCrossmintSDK](/sdk-reference/wallets/kotlin/properties/local-crossmint-sdk)

## Classes

* [AndroidCrossmintTEE](/sdk-reference/wallets/kotlin/classes/android-crossmint-tee)
* [AndroidPasskeyProvider](/sdk-reference/wallets/kotlin/classes/android-passkey-provider)
* [AndroidWebViewBridge](/sdk-reference/wallets/kotlin/classes/android-web-view-bridge)
* [AuthSessionStore](/sdk-reference/wallets/kotlin/classes/auth-session-store)
* [Crossmint](/sdk-reference/wallets/kotlin/classes/crossmint)
* [CrossmintAuthManager](/sdk-reference/wallets/kotlin/classes/crossmint-auth-manager)
* [CrossmintSDK](/sdk-reference/wallets/kotlin/classes/crossmint-sdk)
* [DelegatedSigner.PasskeyActivation](/sdk-reference/wallets/kotlin/classes/delegated-signer-passkey-activation)
* [DeviceSignerStorageFactory](/sdk-reference/wallets/kotlin/classes/device-signer-storage-factory)
* [EVMWallet](/sdk-reference/wallets/kotlin/classes/evm-wallet)
* [EncryptedSharedPreferenceStorage](/sdk-reference/wallets/kotlin/classes/encrypted-shared-preference-storage)
* [FallbackPolicy.InsecurePersistent](/sdk-reference/wallets/kotlin/classes/fallback-policy-insecure-persistent)
* [FallbackPolicy.MemoryOnly](/sdk-reference/wallets/kotlin/classes/fallback-policy-memory-only)
* [InsecurePersistentSessionStore](/sdk-reference/wallets/kotlin/classes/insecure-persistent-session-store)
* [InvalidEnvironmentKeyException](/sdk-reference/wallets/kotlin/classes/invalid-environment-key-exception)
* [JvmWebViewBridge](/sdk-reference/wallets/kotlin/classes/jvm-web-view-bridge)
* [KeystoreKeyStorage](/sdk-reference/wallets/kotlin/classes/keystore-key-storage)
* [MalformedKeyException](/sdk-reference/wallets/kotlin/classes/malformed-key-exception)
* [OldKeyException](/sdk-reference/wallets/kotlin/classes/old-key-exception)
* [SolanaWallet](/sdk-reference/wallets/kotlin/classes/solana-wallet)
* [StellarWallet](/sdk-reference/wallets/kotlin/classes/stellar-wallet)
* [TinkSecureStorage](/sdk-reference/wallets/kotlin/classes/tink-secure-storage)
* [TinkWithFallbackSessionStore](/sdk-reference/wallets/kotlin/classes/tink-with-fallback-session-store)
* [Wallet](/sdk-reference/wallets/kotlin/classes/wallet)
* [WebViewNotAvailableException](/sdk-reference/wallets/kotlin/classes/web-view-not-available-exception)

## Data Classes

* [ApiKey](/sdk-reference/wallets/kotlin/data-classes/api-key)
* [ApiKeyError.InvalidEnvironmentKey](/sdk-reference/wallets/kotlin/data-classes/api-key-error-invalid-environment-key)
* [ApiKeyError.MalformedKey](/sdk-reference/wallets/kotlin/data-classes/api-key-error-malformed-key)
* [ApiKeyError.OldKey](/sdk-reference/wallets/kotlin/data-classes/api-key-error-old-key)
* [Approval](/sdk-reference/wallets/kotlin/data-classes/approval)
* [ApprovalMetadata.Passkey](/sdk-reference/wallets/kotlin/data-classes/approval-metadata-passkey)
* [ApprovalSignature.Device](/sdk-reference/wallets/kotlin/data-classes/approval-signature-device)
* [ApprovalSignature.Passkey](/sdk-reference/wallets/kotlin/data-classes/approval-signature-passkey)
* [ApprovalSignature.Raw](/sdk-reference/wallets/kotlin/data-classes/approval-signature-raw)
* [Approvals](/sdk-reference/wallets/kotlin/data-classes/approvals)
* [Approvals.PendingApproval](/sdk-reference/wallets/kotlin/data-classes/approvals-pending-approval)
* [Approvals.SubmittedApproval](/sdk-reference/wallets/kotlin/data-classes/approvals-submitted-approval)
* [AuthError.InvalidCredentials](/sdk-reference/wallets/kotlin/data-classes/auth-error-invalid-credentials)
* [AuthError.NotInitialized](/sdk-reference/wallets/kotlin/data-classes/auth-error-not-initialized)
* [AuthError.RateLimited](/sdk-reference/wallets/kotlin/data-classes/auth-error-rate-limited)
* [AuthError.ServerError](/sdk-reference/wallets/kotlin/data-classes/auth-error-server-error)
* [AuthError.TokenExpired](/sdk-reference/wallets/kotlin/data-classes/auth-error-token-expired)
* [AuthError.Unauthorized](/sdk-reference/wallets/kotlin/data-classes/auth-error-unauthorized)
* [BalanceError.BalanceNotFound](/sdk-reference/wallets/kotlin/data-classes/balance-error-balance-not-found)
* [BalanceError.BalanceOperationFailed](/sdk-reference/wallets/kotlin/data-classes/balance-error-balance-operation-failed)
* [BalanceError.Forbidden](/sdk-reference/wallets/kotlin/data-classes/balance-error-forbidden)
* [BalanceError.RateLimited](/sdk-reference/wallets/kotlin/data-classes/balance-error-rate-limited)
* [BalanceError.ServiceNotInitialized](/sdk-reference/wallets/kotlin/data-classes/balance-error-service-not-initialized)
* [BalanceError.Unauthorized](/sdk-reference/wallets/kotlin/data-classes/balance-error-unauthorized)
* [Balances](/sdk-reference/wallets/kotlin/data-classes/balances)
* [Call](/sdk-reference/wallets/kotlin/data-classes/call)
* [Chain.Unknown](/sdk-reference/wallets/kotlin/data-classes/chain-unknown)
* [ChainInfo.Solana](/sdk-reference/wallets/kotlin/data-classes/chain-info-solana)
* [ChainInfo.Stellar](/sdk-reference/wallets/kotlin/data-classes/chain-info-stellar)
* [Configuration](/sdk-reference/wallets/kotlin/data-classes/configuration)
* [DelegatedSigner.ApiKey](/sdk-reference/wallets/kotlin/data-classes/delegated-signer-api-key)
* [DelegatedSigner.Device](/sdk-reference/wallets/kotlin/data-classes/delegated-signer-device)
* [DelegatedSigner.Email](/sdk-reference/wallets/kotlin/data-classes/delegated-signer-email)
* [DelegatedSigner.ExternalWallet](/sdk-reference/wallets/kotlin/data-classes/delegated-signer-external-wallet)
* [DelegatedSigner.Locator](/sdk-reference/wallets/kotlin/data-classes/delegated-signer-locator)
* [DelegatedSigner.Passkey](/sdk-reference/wallets/kotlin/data-classes/delegated-signer-passkey)
* [DelegatedSigner.Phone](/sdk-reference/wallets/kotlin/data-classes/delegated-signer-phone)
* [DelegatedSignerData](/sdk-reference/wallets/kotlin/data-classes/delegated-signer-data)
* [DeviceSignerError.StorageError](/sdk-reference/wallets/kotlin/data-classes/device-signer-error-storage-error)
* [EVMTransactionParams](/sdk-reference/wallets/kotlin/data-classes/evm-transaction-params)
* [FeeConfig](/sdk-reference/wallets/kotlin/data-classes/fee-config)
* [IdentityVerificationError](/sdk-reference/wallets/kotlin/data-classes/identity-verification-error)
* [NetworkError.ConnectionError](/sdk-reference/wallets/kotlin/data-classes/network-error-connection-error)
* [NetworkError.HttpError](/sdk-reference/wallets/kotlin/data-classes/network-error-http-error)
* [NetworkError.ParseError](/sdk-reference/wallets/kotlin/data-classes/network-error-parse-error)
* [NetworkError.ServiceNotInitialized](/sdk-reference/wallets/kotlin/data-classes/network-error-service-not-initialized)
* [NetworkError.TimeoutError](/sdk-reference/wallets/kotlin/data-classes/network-error-timeout-error)
* [NetworkError.UnknownError](/sdk-reference/wallets/kotlin/data-classes/network-error-unknown-error)
* [OnChainData](/sdk-reference/wallets/kotlin/data-classes/on-chain-data)
* [Owner.Address](/sdk-reference/wallets/kotlin/data-classes/owner-address)
* [Owner.Email](/sdk-reference/wallets/kotlin/data-classes/owner-email)
* [Owner.PhoneNumber](/sdk-reference/wallets/kotlin/data-classes/owner-phone-number)
* [Owner.Twitter](/sdk-reference/wallets/kotlin/data-classes/owner-twitter)
* [Owner.UserId](/sdk-reference/wallets/kotlin/data-classes/owner-user-id)
* [PasskeyCredentialInfo](/sdk-reference/wallets/kotlin/data-classes/passkey-credential-info)
* [PasskeyError.Cancelled](/sdk-reference/wallets/kotlin/data-classes/passkey-error-cancelled)
* [PasskeyError.Failed](/sdk-reference/wallets/kotlin/data-classes/passkey-error-failed)
* [PasskeySignMetadata](/sdk-reference/wallets/kotlin/data-classes/passkey-sign-metadata)
* [PasskeySignResult](/sdk-reference/wallets/kotlin/data-classes/passkey-sign-result)
* [RawTransactionParams.Solana](/sdk-reference/wallets/kotlin/data-classes/raw-transaction-params-solana)
* [RawTransactionParams.Stellar](/sdk-reference/wallets/kotlin/data-classes/raw-transaction-params-stellar)
* [RawTransactionParams.StellarSerialized](/sdk-reference/wallets/kotlin/data-classes/raw-transaction-params-stellar-serialized)
* [RecoveryMethod](/sdk-reference/wallets/kotlin/data-classes/recovery-method)
* [Result.Failure](/sdk-reference/wallets/kotlin/data-classes/result-failure)
* [Result.Success](/sdk-reference/wallets/kotlin/data-classes/result-success)
* [SignatureError.ChainNotSupported](/sdk-reference/wallets/kotlin/data-classes/signature-error-chain-not-supported)
* [SignatureError.CreationFailed](/sdk-reference/wallets/kotlin/data-classes/signature-error-creation-failed)
* [SignatureError.Forbidden](/sdk-reference/wallets/kotlin/data-classes/signature-error-forbidden)
* [SignatureError.ServiceNotInitialized](/sdk-reference/wallets/kotlin/data-classes/signature-error-service-not-initialized)
* [SignatureError.SigningFailed](/sdk-reference/wallets/kotlin/data-classes/signature-error-signing-failed)
* [SignatureError.Timeout](/sdk-reference/wallets/kotlin/data-classes/signature-error-timeout)
* [SignatureError.Unauthorized](/sdk-reference/wallets/kotlin/data-classes/signature-error-unauthorized)
* [SignatureError.Unknown](/sdk-reference/wallets/kotlin/data-classes/signature-error-unknown)
* [SignatureError.UserCancelled](/sdk-reference/wallets/kotlin/data-classes/signature-error-user-cancelled)
* [SignerData.ApiKey](/sdk-reference/wallets/kotlin/data-classes/signer-data-api-key)
* [SignerData.Device](/sdk-reference/wallets/kotlin/data-classes/signer-data-device)
* [SignerData.Email](/sdk-reference/wallets/kotlin/data-classes/signer-data-email)
* [SignerData.ExternalWallet](/sdk-reference/wallets/kotlin/data-classes/signer-data-external-wallet)
* [SignerData.Passkey](/sdk-reference/wallets/kotlin/data-classes/signer-data-passkey)
* [SignerData.Phone](/sdk-reference/wallets/kotlin/data-classes/signer-data-phone)
* [SignerData.Server](/sdk-reference/wallets/kotlin/data-classes/signer-data-server)
* [SignerError.Generic](/sdk-reference/wallets/kotlin/data-classes/signer-error-generic)
* [SignerError.SigningFailed](/sdk-reference/wallets/kotlin/data-classes/signer-error-signing-failed)
* [SignerSelection.Delegated](/sdk-reference/wallets/kotlin/data-classes/signer-selection-delegated)
* [SignerType.Email](/sdk-reference/wallets/kotlin/data-classes/signer-type-email)
* [SignerType.ExternalWallet](/sdk-reference/wallets/kotlin/data-classes/signer-type-external-wallet)
* [SignerType.Passkey](/sdk-reference/wallets/kotlin/data-classes/signer-type-passkey)
* [SignerType.Phone](/sdk-reference/wallets/kotlin/data-classes/signer-type-phone)
* [SigningOutput.Passkey](/sdk-reference/wallets/kotlin/data-classes/signing-output-passkey)
* [SigningOutput.Standard](/sdk-reference/wallets/kotlin/data-classes/signing-output-standard)
* [SolanaTransactionParams](/sdk-reference/wallets/kotlin/data-classes/solana-transaction-params)
* [StellarTransactionParams](/sdk-reference/wallets/kotlin/data-classes/stellar-transaction-params)
* [TEEError.Generic](/sdk-reference/wallets/kotlin/data-classes/tee-error-generic)
* [TEEError.InvalidPayload](/sdk-reference/wallets/kotlin/data-classes/tee-error-invalid-payload)
* [TokenAccountBalance](/sdk-reference/wallets/kotlin/data-classes/token-account-balance)
* [TokenAccountType.Card](/sdk-reference/wallets/kotlin/data-classes/token-account-type-card)
* [TokenAccountType.Unknown](/sdk-reference/wallets/kotlin/data-classes/token-account-type-unknown)
* [TokenAmount](/sdk-reference/wallets/kotlin/data-classes/token-amount)
* [TokenBalance](/sdk-reference/wallets/kotlin/data-classes/token-balance)
* [Transaction](/sdk-reference/wallets/kotlin/data-classes/transaction)
* [TransactionError.Forbidden](/sdk-reference/wallets/kotlin/data-classes/transaction-error-forbidden)
* [TransactionError.InvalidTransactionState](/sdk-reference/wallets/kotlin/data-classes/transaction-error-invalid-transaction-state)
* [TransactionError.RateLimited](/sdk-reference/wallets/kotlin/data-classes/transaction-error-rate-limited)
* [TransactionError.ServiceNotInitialized](/sdk-reference/wallets/kotlin/data-classes/transaction-error-service-not-initialized)
* [TransactionError.SigningFailed](/sdk-reference/wallets/kotlin/data-classes/transaction-error-signing-failed)
* [TransactionError.Timeout](/sdk-reference/wallets/kotlin/data-classes/transaction-error-timeout)
* [TransactionError.TransactionCreationFailed](/sdk-reference/wallets/kotlin/data-classes/transaction-error-transaction-creation-failed)
* [TransactionError.TransactionFailed](/sdk-reference/wallets/kotlin/data-classes/transaction-error-transaction-failed)
* [TransactionError.TransactionNotFound](/sdk-reference/wallets/kotlin/data-classes/transaction-error-transaction-not-found)
* [TransactionError.TransactionOperationFailed](/sdk-reference/wallets/kotlin/data-classes/transaction-error-transaction-operation-failed)
* [TransactionError.Unauthorized](/sdk-reference/wallets/kotlin/data-classes/transaction-error-unauthorized)
* [TransactionError.UserCancelled](/sdk-reference/wallets/kotlin/data-classes/transaction-error-user-cancelled)
* [TransactionErrorDetails](/sdk-reference/wallets/kotlin/data-classes/transaction-error-details)
* [TransactionErrorDetails.Revert](/sdk-reference/wallets/kotlin/data-classes/transaction-error-details-revert)
* [Transfer](/sdk-reference/wallets/kotlin/data-classes/transfer)
* [TransferError.LoadFailed](/sdk-reference/wallets/kotlin/data-classes/transfer-error-load-failed)
* [TransferError.ServiceNotInitialized](/sdk-reference/wallets/kotlin/data-classes/transfer-error-service-not-initialized)
* [TransferError.Unauthorized](/sdk-reference/wallets/kotlin/data-classes/transfer-error-unauthorized)
* [TransferError.Unknown](/sdk-reference/wallets/kotlin/data-classes/transfer-error-unknown)
* [TransferList](/sdk-reference/wallets/kotlin/data-classes/transfer-list)
* [UserOperation](/sdk-reference/wallets/kotlin/data-classes/user-operation)
* [WalletConfig](/sdk-reference/wallets/kotlin/data-classes/wallet-config)
* [WalletError.ChainNotSupported](/sdk-reference/wallets/kotlin/data-classes/wallet-error-chain-not-supported)
* [WalletError.DelegatedSignerConflict](/sdk-reference/wallets/kotlin/data-classes/wallet-error-delegated-signer-conflict)
* [WalletError.DeviceSignerNotSupported](/sdk-reference/wallets/kotlin/data-classes/wallet-error-device-signer-not-supported)
* [WalletError.DuplicateRecoverySigner](/sdk-reference/wallets/kotlin/data-classes/wallet-error-duplicate-recovery-signer)
* [WalletError.Forbidden](/sdk-reference/wallets/kotlin/data-classes/wallet-error-forbidden)
* [WalletError.InvalidInput](/sdk-reference/wallets/kotlin/data-classes/wallet-error-invalid-input)
* [WalletError.InvalidRecoveryConfig](/sdk-reference/wallets/kotlin/data-classes/wallet-error-invalid-recovery-config)
* [WalletError.InvalidSigner](/sdk-reference/wallets/kotlin/data-classes/wallet-error-invalid-signer)
* [WalletError.LastRecoverySigner](/sdk-reference/wallets/kotlin/data-classes/wallet-error-last-recovery-signer)
* [WalletError.RateLimited](/sdk-reference/wallets/kotlin/data-classes/wallet-error-rate-limited)
* [WalletError.RecoveryAdminSignerConflict](/sdk-reference/wallets/kotlin/data-classes/wallet-error-recovery-admin-signer-conflict)
* [WalletError.RecoveryNotSupportedOnApiVersion](/sdk-reference/wallets/kotlin/data-classes/wallet-error-recovery-not-supported-on-api-version)
* [WalletError.RecoveryNotSupportedOnChain](/sdk-reference/wallets/kotlin/data-classes/wallet-error-recovery-not-supported-on-chain)
* [WalletError.RecoverySignerConflict](/sdk-reference/wallets/kotlin/data-classes/wallet-error-recovery-signer-conflict)
* [WalletError.RecoverySignerNotAllowed](/sdk-reference/wallets/kotlin/data-classes/wallet-error-recovery-signer-not-allowed)
* [WalletError.ServiceNotInitialized](/sdk-reference/wallets/kotlin/data-classes/wallet-error-service-not-initialized)
* [WalletError.SignerLimitExceeded](/sdk-reference/wallets/kotlin/data-classes/wallet-error-signer-limit-exceeded)
* [WalletError.SignerNotRegistered](/sdk-reference/wallets/kotlin/data-classes/wallet-error-signer-not-registered)
* [WalletError.SignerRequired](/sdk-reference/wallets/kotlin/data-classes/wallet-error-signer-required)
* [WalletError.SigningError](/sdk-reference/wallets/kotlin/data-classes/wallet-error-signing-error)
* [WalletError.Unauthorized](/sdk-reference/wallets/kotlin/data-classes/wallet-error-unauthorized)
* [WalletError.WalletNotFound](/sdk-reference/wallets/kotlin/data-classes/wallet-error-wallet-not-found)
* [WalletError.WalletOperationFailed](/sdk-reference/wallets/kotlin/data-classes/wallet-error-wallet-operation-failed)
* [WebViewMessage.Custom](/sdk-reference/wallets/kotlin/data-classes/web-view-message-custom)

## Sealed Classes

* [ApprovalMetadata](/sdk-reference/wallets/kotlin/sealed-classes/approval-metadata)
* [ApprovalSignature](/sdk-reference/wallets/kotlin/sealed-classes/approval-signature)
* [DelegatedSigner](/sdk-reference/wallets/kotlin/sealed-classes/delegated-signer)
* [DeviceSignerError](/sdk-reference/wallets/kotlin/sealed-classes/device-signer-error)
* [Owner](/sdk-reference/wallets/kotlin/sealed-classes/owner)
* [RawTransactionParams](/sdk-reference/wallets/kotlin/sealed-classes/raw-transaction-params)
* [SignerData](/sdk-reference/wallets/kotlin/sealed-classes/signer-data)
* [SignerError](/sdk-reference/wallets/kotlin/sealed-classes/signer-error)
* [SignerSelection](/sdk-reference/wallets/kotlin/sealed-classes/signer-selection)
* [SignerType](/sdk-reference/wallets/kotlin/sealed-classes/signer-type)
* [SigningOutput](/sdk-reference/wallets/kotlin/sealed-classes/signing-output)
* [TEEError](/sdk-reference/wallets/kotlin/sealed-classes/tee-error)

## Sealed Interfaces

* [ApiKeyError](/sdk-reference/wallets/kotlin/sealed-interfaces/api-key-error)
* [AuthError](/sdk-reference/wallets/kotlin/sealed-interfaces/auth-error)
* [BalanceError](/sdk-reference/wallets/kotlin/sealed-interfaces/balance-error)
* [Chain](/sdk-reference/wallets/kotlin/sealed-interfaces/chain)
* [ChainInfo](/sdk-reference/wallets/kotlin/sealed-interfaces/chain-info)
* [ConfigurationError](/sdk-reference/wallets/kotlin/sealed-interfaces/configuration-error)
* [CrossmintError](/sdk-reference/wallets/kotlin/sealed-interfaces/crossmint-error)
* [CrossmintErrorCode](/sdk-reference/wallets/kotlin/sealed-interfaces/crossmint-error-code)
* [EVMChain](/sdk-reference/wallets/kotlin/sealed-interfaces/evm-chain)
* [NetworkError](/sdk-reference/wallets/kotlin/sealed-interfaces/network-error)
* [PasskeyError](/sdk-reference/wallets/kotlin/sealed-interfaces/passkey-error)
* [Result](/sdk-reference/wallets/kotlin/sealed-interfaces/result)
* [SignatureError](/sdk-reference/wallets/kotlin/sealed-interfaces/signature-error)
* [SolanaChain](/sdk-reference/wallets/kotlin/sealed-interfaces/solana-chain)
* [StellarChain](/sdk-reference/wallets/kotlin/sealed-interfaces/stellar-chain)
* [SupportedChain](/sdk-reference/wallets/kotlin/sealed-interfaces/supported-chain)
* [TokenAccountType](/sdk-reference/wallets/kotlin/sealed-interfaces/token-account-type)
* [TransactionError](/sdk-reference/wallets/kotlin/sealed-interfaces/transaction-error)
* [TransactionParams](/sdk-reference/wallets/kotlin/sealed-interfaces/transaction-params)
* [TransferError](/sdk-reference/wallets/kotlin/sealed-interfaces/transfer-error)
* [WalletError](/sdk-reference/wallets/kotlin/sealed-interfaces/wallet-error)

## Interfaces

* [AuthManager](/sdk-reference/wallets/kotlin/interfaces/auth-manager)
* [AuthService](/sdk-reference/wallets/kotlin/interfaces/auth-service)
* [BalanceOperations](/sdk-reference/wallets/kotlin/interfaces/balance-operations)
* [CrossmintTEE](/sdk-reference/wallets/kotlin/interfaces/crossmint-tee)
* [CrossmintWallets](/sdk-reference/wallets/kotlin/interfaces/crossmint-wallets)
* [DeviceSignerKeyStorage](/sdk-reference/wallets/kotlin/interfaces/device-signer-key-storage)
* [EmailSigner](/sdk-reference/wallets/kotlin/interfaces/email-signer)
* [FailureAwareSessionStore](/sdk-reference/wallets/kotlin/interfaces/failure-aware-session-store)
* [NFTOperations](/sdk-reference/wallets/kotlin/interfaces/nft-operations)
* [NonCustodialSigner](/sdk-reference/wallets/kotlin/interfaces/non-custodial-signer)
* [PasskeyProvider](/sdk-reference/wallets/kotlin/interfaces/passkey-provider)
* [SessionStore](/sdk-reference/wallets/kotlin/interfaces/session-store)
* [Signer](/sdk-reference/wallets/kotlin/interfaces/signer)
* [SignerManagementOperations](/sdk-reference/wallets/kotlin/interfaces/signer-management-operations)
* [TransactionOperations](/sdk-reference/wallets/kotlin/interfaces/transaction-operations)

## Enums

* [ApiKey.Type](/sdk-reference/wallets/kotlin/enums/api-key-type)
* [AuthErrorCode](/sdk-reference/wallets/kotlin/enums/auth-error-code)
* [BalanceErrorCode](/sdk-reference/wallets/kotlin/enums/balance-error-code)
* [ChainType](/sdk-reference/wallets/kotlin/enums/chain-type)
* [ConfigurationErrorCode](/sdk-reference/wallets/kotlin/enums/configuration-error-code)
* [DelegatedSignerStatus](/sdk-reference/wallets/kotlin/enums/delegated-signer-status)
* [DelegatedSignerType](/sdk-reference/wallets/kotlin/enums/delegated-signer-type)
* [Environment](/sdk-reference/wallets/kotlin/enums/environment)
* [FallbackPolicy](/sdk-reference/wallets/kotlin/enums/fallback-policy)
* [IdentityVerificationErrorCode](/sdk-reference/wallets/kotlin/enums/identity-verification-error-code)
* [LogLevel](/sdk-reference/wallets/kotlin/enums/log-level)
* [NetworkErrorCode](/sdk-reference/wallets/kotlin/enums/network-error-code)
* [OTPDeliveryChannel](/sdk-reference/wallets/kotlin/enums/otp-delivery-channel)
* [PasskeyErrorCode](/sdk-reference/wallets/kotlin/enums/passkey-error-code)
* [SignatureErrorCode](/sdk-reference/wallets/kotlin/enums/signature-error-code)
* [TransactionErrorCode](/sdk-reference/wallets/kotlin/enums/transaction-error-code)
* [TransactionStatus](/sdk-reference/wallets/kotlin/enums/transaction-status)
* [TransferErrorCode](/sdk-reference/wallets/kotlin/enums/transfer-error-code)
* [TransferType](/sdk-reference/wallets/kotlin/enums/transfer-type)
* [WalletErrorCode](/sdk-reference/wallets/kotlin/enums/wallet-error-code)
* [WalletType](/sdk-reference/wallets/kotlin/enums/wallet-type)

## Objects

* [ApiKey.Companion](/sdk-reference/wallets/kotlin/objects/api-key-companion)
* [Chain.Companion](/sdk-reference/wallets/kotlin/objects/chain-companion)
* [Configuration.Companion](/sdk-reference/wallets/kotlin/objects/configuration-companion)
* [Crossmint.Companion](/sdk-reference/wallets/kotlin/objects/crossmint-companion)
* [CrossmintAuthManager.Companion](/sdk-reference/wallets/kotlin/objects/crossmint-auth-manager-companion)
* [CrossmintSDK.Companion](/sdk-reference/wallets/kotlin/objects/crossmint-sdk-companion)
* [DelegatedSignerStatus.Companion](/sdk-reference/wallets/kotlin/objects/delegated-signer-status-companion)
* [DelegatedSignerType.Companion](/sdk-reference/wallets/kotlin/objects/delegated-signer-type-companion)
* [DeviceSignerError.HardwareUnavailable](/sdk-reference/wallets/kotlin/objects/device-signer-error-hardware-unavailable)
* [DeviceSignerError.InvalidMessage](/sdk-reference/wallets/kotlin/objects/device-signer-error-invalid-message)
* [DeviceSignerError.KeyGenerationFailed](/sdk-reference/wallets/kotlin/objects/device-signer-error-key-generation-failed)
* [DeviceSignerError.KeyNotFound](/sdk-reference/wallets/kotlin/objects/device-signer-error-key-not-found)
* [DeviceSignerError.SigningFailed](/sdk-reference/wallets/kotlin/objects/device-signer-error-signing-failed)
* [EVMChain.Apechain](/sdk-reference/wallets/kotlin/objects/evm-chain-apechain)
* [EVMChain.Apex](/sdk-reference/wallets/kotlin/objects/evm-chain-apex)
* [EVMChain.Arbitrum](/sdk-reference/wallets/kotlin/objects/evm-chain-arbitrum)
* [EVMChain.ArbitrumNova](/sdk-reference/wallets/kotlin/objects/evm-chain-arbitrum-nova)
* [EVMChain.ArbitrumSepolia](/sdk-reference/wallets/kotlin/objects/evm-chain-arbitrum-sepolia)
* [EVMChain.AstarZkEVM](/sdk-reference/wallets/kotlin/objects/evm-chain-astar-zk-evm)
* [EVMChain.Avalanche](/sdk-reference/wallets/kotlin/objects/evm-chain-avalanche)
* [EVMChain.AvalancheFuji](/sdk-reference/wallets/kotlin/objects/evm-chain-avalanche-fuji)
* [EVMChain.BSCTestnet](/sdk-reference/wallets/kotlin/objects/evm-chain-bsc-testnet)
* [EVMChain.BarretTestnet](/sdk-reference/wallets/kotlin/objects/evm-chain-barret-testnet)
* [EVMChain.Base](/sdk-reference/wallets/kotlin/objects/evm-chain-base)
* [EVMChain.BaseGoerli](/sdk-reference/wallets/kotlin/objects/evm-chain-base-goerli)
* [EVMChain.BaseSepolia](/sdk-reference/wallets/kotlin/objects/evm-chain-base-sepolia)
* [EVMChain.Boss](/sdk-reference/wallets/kotlin/objects/evm-chain-boss)
* [EVMChain.Chiliz](/sdk-reference/wallets/kotlin/objects/evm-chain-chiliz)
* [EVMChain.ChilizSpicyTestnet](/sdk-reference/wallets/kotlin/objects/evm-chain-chiliz-spicy-testnet)
* [EVMChain.Coti](/sdk-reference/wallets/kotlin/objects/evm-chain-coti)
* [EVMChain.CotiTestnet](/sdk-reference/wallets/kotlin/objects/evm-chain-coti-testnet)
* [EVMChain.Curtis](/sdk-reference/wallets/kotlin/objects/evm-chain-curtis)
* [EVMChain.Ethereum](/sdk-reference/wallets/kotlin/objects/evm-chain-ethereum)
* [EVMChain.EthereumGoerli](/sdk-reference/wallets/kotlin/objects/evm-chain-ethereum-goerli)
* [EVMChain.EthereumSepolia](/sdk-reference/wallets/kotlin/objects/evm-chain-ethereum-sepolia)
* [EVMChain.HypersonicTestnet](/sdk-reference/wallets/kotlin/objects/evm-chain-hypersonic-testnet)
* [EVMChain.Lightlink](/sdk-reference/wallets/kotlin/objects/evm-chain-lightlink)
* [EVMChain.LightlinkPegasus](/sdk-reference/wallets/kotlin/objects/evm-chain-lightlink-pegasus)
* [EVMChain.Mode](/sdk-reference/wallets/kotlin/objects/evm-chain-mode)
* [EVMChain.ModeSepolia](/sdk-reference/wallets/kotlin/objects/evm-chain-mode-sepolia)
* [EVMChain.Optimism](/sdk-reference/wallets/kotlin/objects/evm-chain-optimism)
* [EVMChain.OptimismGoerli](/sdk-reference/wallets/kotlin/objects/evm-chain-optimism-goerli)
* [EVMChain.OptimismSepolia](/sdk-reference/wallets/kotlin/objects/evm-chain-optimism-sepolia)
* [EVMChain.Polygon](/sdk-reference/wallets/kotlin/objects/evm-chain-polygon)
* [EVMChain.PolygonAmoy](/sdk-reference/wallets/kotlin/objects/evm-chain-polygon-amoy)
* [EVMChain.PolygonMumbai](/sdk-reference/wallets/kotlin/objects/evm-chain-polygon-mumbai)
* [EVMChain.Rari](/sdk-reference/wallets/kotlin/objects/evm-chain-rari)
* [EVMChain.RariTestnet](/sdk-reference/wallets/kotlin/objects/evm-chain-rari-testnet)
* [EVMChain.Scroll](/sdk-reference/wallets/kotlin/objects/evm-chain-scroll)
* [EVMChain.ScrollSepolia](/sdk-reference/wallets/kotlin/objects/evm-chain-scroll-sepolia)
* [EVMChain.SeiAtlantic2Testnet](/sdk-reference/wallets/kotlin/objects/evm-chain-sei-atlantic2testnet)
* [EVMChain.SeiPacific1](/sdk-reference/wallets/kotlin/objects/evm-chain-sei-pacific1)
* [EVMChain.Shape](/sdk-reference/wallets/kotlin/objects/evm-chain-shape)
* [EVMChain.ShapeSepolia](/sdk-reference/wallets/kotlin/objects/evm-chain-shape-sepolia)
* [EVMChain.SkaleNebula](/sdk-reference/wallets/kotlin/objects/evm-chain-skale-nebula)
* [EVMChain.SkaleNebulaTestnet](/sdk-reference/wallets/kotlin/objects/evm-chain-skale-nebula-testnet)
* [EVMChain.Soneium](/sdk-reference/wallets/kotlin/objects/evm-chain-soneium)
* [EVMChain.SoneiumMinatoTestnet](/sdk-reference/wallets/kotlin/objects/evm-chain-soneium-minato-testnet)
* [EVMChain.Space](/sdk-reference/wallets/kotlin/objects/evm-chain-space)
* [EVMChain.SpaceTestnet](/sdk-reference/wallets/kotlin/objects/evm-chain-space-testnet)
* [EVMChain.Story](/sdk-reference/wallets/kotlin/objects/evm-chain-story)
* [EVMChain.StoryTestnet](/sdk-reference/wallets/kotlin/objects/evm-chain-story-testnet)
* [EVMChain.VerifyTestnet](/sdk-reference/wallets/kotlin/objects/evm-chain-verify-testnet)
* [EVMChain.Viction](/sdk-reference/wallets/kotlin/objects/evm-chain-viction)
* [EVMChain.VictionTestnet](/sdk-reference/wallets/kotlin/objects/evm-chain-viction-testnet)
* [EVMChain.Xai](/sdk-reference/wallets/kotlin/objects/evm-chain-xai)
* [EVMChain.XaiSepoliaTestnet](/sdk-reference/wallets/kotlin/objects/evm-chain-xai-sepolia-testnet)
* [EVMChain.ZenchainTestnet](/sdk-reference/wallets/kotlin/objects/evm-chain-zenchain-testnet)
* [EVMChain.Zkatana](/sdk-reference/wallets/kotlin/objects/evm-chain-zkatana)
* [EVMChain.Zkyoto](/sdk-reference/wallets/kotlin/objects/evm-chain-zkyoto)
* [EVMChain.Zora](/sdk-reference/wallets/kotlin/objects/evm-chain-zora)
* [EVMChain.ZoraGoerli](/sdk-reference/wallets/kotlin/objects/evm-chain-zora-goerli)
* [EVMChain.ZoraSepolia](/sdk-reference/wallets/kotlin/objects/evm-chain-zora-sepolia)
* [EncryptedSharedPreferenceStorage.Companion](/sdk-reference/wallets/kotlin/objects/encrypted-shared-preference-storage-companion)
* [InsecurePersistentSessionStore.Companion](/sdk-reference/wallets/kotlin/objects/insecure-persistent-session-store-companion)
* [KeystoreKeyStorage.Companion](/sdk-reference/wallets/kotlin/objects/keystore-key-storage-companion)
* [SignerError.Cancelled](/sdk-reference/wallets/kotlin/objects/signer-error-cancelled)
* [SignerError.InvalidEmail](/sdk-reference/wallets/kotlin/objects/signer-error-invalid-email)
* [SignerError.NotInitialized](/sdk-reference/wallets/kotlin/objects/signer-error-not-initialized)
* [SignerError.NotStarted](/sdk-reference/wallets/kotlin/objects/signer-error-not-started)
* [SignerError.TeeNotStarted](/sdk-reference/wallets/kotlin/objects/signer-error-tee-not-started)
* [SignerSelection.Admin](/sdk-reference/wallets/kotlin/objects/signer-selection-admin)
* [SignerType.ApiKey](/sdk-reference/wallets/kotlin/objects/signer-type-api-key)
* [SolanaChain.Solana](/sdk-reference/wallets/kotlin/objects/solana-chain-solana)
* [StellarChain.Stellar](/sdk-reference/wallets/kotlin/objects/stellar-chain-stellar)
* [TEEError.EncryptionUnavailable](/sdk-reference/wallets/kotlin/objects/tee-error-encryption-unavailable)
* [TEEError.ErrorLoadingService](/sdk-reference/wallets/kotlin/objects/tee-error-error-loading-service)
* [TEEError.HandshakeFailed](/sdk-reference/wallets/kotlin/objects/tee-error-handshake-failed)
* [TEEError.HandshakeRequired](/sdk-reference/wallets/kotlin/objects/tee-error-handshake-required)
* [TEEError.InvalidSignature](/sdk-reference/wallets/kotlin/objects/tee-error-invalid-signature)
* [TEEError.JWTRequired](/sdk-reference/wallets/kotlin/objects/tee-error-jwt-required)
* [TEEError.SignerStatusUnavailable](/sdk-reference/wallets/kotlin/objects/tee-error-signer-status-unavailable)
* [TEEError.Timeout](/sdk-reference/wallets/kotlin/objects/tee-error-timeout)
* [TEEError.UserCancelled](/sdk-reference/wallets/kotlin/objects/tee-error-user-cancelled)
* [TinkSecureStorage.Companion](/sdk-reference/wallets/kotlin/objects/tink-secure-storage-companion)
* [TinkWithFallbackSessionStore.Companion](/sdk-reference/wallets/kotlin/objects/tink-with-fallback-session-store-companion)
* [TokenAccountType.Wallet](/sdk-reference/wallets/kotlin/objects/token-account-type-wallet)


# AuthManager
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/interfaces/auth-manager

Kotlin Interface

**Interface**

```kotlin theme={null}
interface AuthManager
```

## Functions

| Function | Description |
| - | - |
| `getJWT` | Returns the current JWT for use as a Bearer token in API calls, or null if not authenticated. |
| `logout` | Signs the user out and clears all stored auth state. |
| `setJWT` | Stores an externally obtained JWT for use in API calls. |

### getJWT

```kotlin theme={null}
abstract suspend fun getJWT(): String?
```

Returns the current JWT for use as a Bearer token in API calls, or null if not authenticated.

### logout

```kotlin theme={null}
abstract suspend fun logout()
```

Signs the user out and clears all stored auth state.

### setJWT

```kotlin theme={null}
abstract fun setJWT(jwt: String)
```

Stores an externally obtained JWT for use in API calls.


# AuthService
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/interfaces/auth-service

Kotlin Interface

**Interface**

```kotlin theme={null}
interface AuthService
```

## Functions

| Function | Description |
| - | - |
| `logout` | - |
| `refreshToken` | - |
| `sendOtp` | - |
| `verifyOtp` | - |

### logout

```kotlin theme={null}
abstract suspend fun logout(refreshToken: String): Result<Unit, AuthError>
```

### refreshToken

```kotlin theme={null}
abstract suspend fun refreshToken(oneTimeSecret: String): Result<AuthToken, AuthError>
```

### sendOtp

```kotlin theme={null}
abstract suspend fun sendOtp(email: String): Result<SendOtpResponse, AuthError>
```

### verifyOtp

```kotlin theme={null}
abstract suspend fun verifyOtp(email: String, code: String, state: String): Result<VerifyOtpResponse, AuthError>
```


# BalanceOperations
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/interfaces/balance-operations

Kotlin Interface

**Interface**

```kotlin theme={null}
interface BalanceOperations
```

## Functions

| Function | Description |
| - | - |
| `fund` | Funds the wallet with test tokens (staging only). |
| `getBalances` | Gets the wallet balances. |

### fund

```kotlin theme={null}
abstract suspend fun fund(token: String, amount: Int, chain: String): Result<Unit, BalanceError>
```

Funds the wallet with test tokens (staging only).

### getBalances

```kotlin theme={null}
abstract suspend fun getBalances(tokens: List<String>): Result<Balances, BalanceError>
```

Gets the wallet balances.


# CrossmintTEE
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/interfaces/crossmint-tee

Kotlin Interface

**Interface**

```kotlin theme={null}
interface CrossmintTEE
```

## Properties

| Property | Type | Description |
| - | - | - |
| `isHandshakeCompleted` | `Boolean` | Indicates whether the handshake with the TEE service has been completed. Handshake must be completed before performing cryptographic operations. |
| `isOTPRequired` | `StateFlow<Boolean>` | Observable state indicating whether the OTP prompt should be shown. |

## Functions

| Function | Description |
| - | - |
| `awaitReady` | Blocks continuation until a successful TEE load has completed. This method must be called before any signing operations. |
| `cancelOTP` | Cancels the signing request that waits for an OTP. The request fails with TEEError.UserCancelled. isOTPRequired changes to false. |
| `performHandshake` | Performs the TEE handshake protocol. This is called automatically by load(). |
| `provideOTP` | Provides the OTP code from the user to the TEE flow. |
| `signTransaction` | - |

### awaitReady

```kotlin theme={null}
abstract suspend fun awaitReady()
```

Blocks continuation until a successful TEE load has completed. This method must be called before any signing operations.

### cancelOTP

```kotlin theme={null}
abstract fun cancelOTP()
```

Cancels the signing request that waits for an OTP. The request fails with TEEError.UserCancelled. isOTPRequired changes to false.

### performHandshake

```kotlin theme={null}
abstract suspend fun performHandshake(): Result<Unit, TEEError>
```

Performs the TEE handshake protocol. This is called automatically by load().

### provideOTP

```kotlin theme={null}
abstract fun provideOTP(code: String)
```

Provides the OTP code from the user to the TEE flow.

### signTransaction

```kotlin theme={null}
abstract suspend fun signTransaction(messageBytes: String, keyType: String, encoding: String, otpAuth: String, channel: Result? = null): Result<String, TEEError>
```


# CrossmintWallets
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/interfaces/crossmint-wallets

Kotlin Interface

**Interface**

```kotlin theme={null}
interface CrossmintWallets
```

## Functions

| Function | Description |
| - | - |
| `addSigner` | Adds a delegated signer to the current wallet on the given chain. Supported types: Email, Phone, ExternalWallet, Locator, Passkey. |
| `createWallet` | Creates a wallet from a list of recovery methods on the given chain. |
| `getDeviceSignerSecurityLevel` | Returns the hardware security level of the device signer key for the given wallet address. Possible values: "StrongBox", "TEE", "Hardware-backed", "Software", or null if not available. |
| `getWallet` | Returns the wallet of the current user on the given chain. |
| `removeSigner` | Removes a delegated signer from the current wallet on the given chain. Supported types: Email, Phone, ExternalWallet, Locator, Passkey. |

### addSigner

```kotlin theme={null}
abstract suspend fun addSigner(signer: DelegatedSigner, chain: Chain, deployImmediately: Boolean = true, approver: DelegatedSigner? = null): Result<Unit, WalletError>
```

Adds a delegated signer to the current wallet on the given chain. Supported types: Email, Phone, ExternalWallet, Locator, Passkey.

### createWallet

```kotlin theme={null}
open suspend fun createWallet(chain: Chain, recoveryMethods: List<SignerType>, signers: List<DelegatedSigner> = emptyList(), owner: String? = null, alias: String? = null, deviceSigner: Boolean = false): Result<Wallet, WalletError>
```

Creates a wallet from a list of recovery methods on the given chain.

```kotlin theme={null}
abstract suspend fun <W : Wallet> createWallet(chain: SupportedChain<W>, recoveryMethods: List<SignerType>, signers: List<DelegatedSigner> = emptyList(), owner: String? = null, alias: String? = null, deviceSigner: Boolean = false): Result<W, WalletError>
```

Creates a wallet from a list of recovery methods.

```kotlin theme={null}
abstract suspend fun <W : Wallet> createWallet(chain: SupportedChain<W>, recoveryMethods: List<SignerType>, signers: List<DelegatedSigner> = emptyList(), owner: String? = null, alias: String? = null, deviceSigner: Boolean = false, passkeyProvider: PasskeyProvider): Result<W, WalletError>
```

Creates a wallet from a list of recovery methods. The wallet signs with its passkeys through passkeyProvider.

### getDeviceSignerSecurityLevel

```kotlin theme={null}
abstract suspend fun getDeviceSignerSecurityLevel(walletAddress: String): String?
```

Returns the hardware security level of the device signer key for the given wallet address. Possible values: "StrongBox", "TEE", "Hardware-backed", "Software", or null if not available.

### getWallet

```kotlin theme={null}
open suspend fun getWallet(chain: Chain): Result<Wallet, WalletError>
```

```kotlin theme={null}
abstract suspend fun <W : Wallet> getWallet(chain: SupportedChain<W>): Result<W, WalletError>
```

```kotlin theme={null}
abstract suspend fun <W : Wallet> getWallet(chain: SupportedChain<W>, passkeyProvider: PasskeyProvider): Result<W, WalletError>
```

Returns the wallet of the current user on the given chain.

### removeSigner

```kotlin theme={null}
abstract suspend fun removeSigner(signer: DelegatedSigner, chain: Chain, approver: DelegatedSigner? = null): Result<Unit, WalletError>
```

Removes a delegated signer from the current wallet on the given chain. Supported types: Email, Phone, ExternalWallet, Locator, Passkey.

## Deprecated

### ~~createWallet~~

<Warning>Deprecated. Use createWallet with recoveryMethods.</Warning>

```kotlin theme={null}
open suspend fun createWallet(chain: Chain, recovery: SignerType, signers: List<DelegatedSigner> = emptyList(), owner: String? = null, alias: String? = null, deviceSigner: Boolean = false): Result<Wallet, WalletError>
```

Creates a wallet with one recovery signer on the given chain.

```kotlin theme={null}
abstract suspend fun <W : Wallet> createWallet(chain: SupportedChain<W>, recovery: SignerType, signers: List<DelegatedSigner> = emptyList(), owner: String? = null, alias: String? = null, deviceSigner: Boolean = false): Result<W, WalletError>
```

Creates a wallet with one recovery signer.


# DeviceSignerKeyStorage
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/interfaces/device-signer-key-storage

Kotlin Interface

**Interface**

```kotlin theme={null}
interface DeviceSignerKeyStorage
```

## Functions

| Function | Description |
| - | - |
| `deleteKey` | Deletes the signing key for the given wallet address. |
| `deletePendingKey` | Deletes a pending key that was never mapped to a wallet address. |
| `generateKey` | Generates a new P-256 signing key and stores it. |
| `getDeviceName` | Returns the name of this device, for example "Pixel 10 Pro (Android)". The SDK uses this name as the display name of a device signer. If no device name is available, the function returns "Unknown Device". |
| `getKey` | Returns the base64-encoded uncompressed public key for the given wallet address, or null if not found. |
| `getSecurityLevel` | Returns a human-readable string describing the security level of the key for the given wallet address (e.g. "StrongBox", "TEE", "Software"), or null if the key is not found. |
| `hasKey` | Returns true if this storage holds a key for the given uncompressed public key (base64-encoded). Used during wallet initialization to detect whether a registered device signer belongs to this device. |
| `isAvailable` | Returns true if this storage backend is available on the current device/platform. |
| `mapAddressToKey` | Associates a previously generated pending key with a wallet address. |
| `signHexMessage` | Signs a hex-encoded message using the key for the given wallet address. |
| `signHexMessageWithPendingKey` | Signs a hex-encoded message using a pending key (not yet mapped to a wallet address). |
| `signMessage` | Signs a base64-encoded message using the key for the given wallet address. |

### deleteKey

```kotlin theme={null}
abstract suspend fun deleteKey(address: String): Result<Unit>
```

Deletes the signing key for the given wallet address.

### deletePendingKey

```kotlin theme={null}
abstract suspend fun deletePendingKey(publicKeyBase64: String): Result<Unit>
```

Deletes a pending key that was never mapped to a wallet address.

### generateKey

```kotlin theme={null}
abstract suspend fun generateKey(address: String?): Result<String>
```

Generates a new P-256 signing key and stores it.

### getDeviceName

```kotlin theme={null}
open suspend fun getDeviceName(): String
```

Returns the name of this device, for example "Pixel 10 Pro (Android)". The SDK uses this name as the display name of a device signer. If no device name is available, the function returns "Unknown Device".

### getKey

```kotlin theme={null}
abstract suspend fun getKey(address: String): String?
```

Returns the base64-encoded uncompressed public key for the given wallet address, or null if not found.

### getSecurityLevel

```kotlin theme={null}
abstract suspend fun getSecurityLevel(address: String): String?
```

Returns a human-readable string describing the security level of the key for the given wallet address (e.g. "StrongBox", "TEE", "Software"), or null if the key is not found.

### hasKey

```kotlin theme={null}
abstract suspend fun hasKey(publicKeyBase64: String): Boolean
```

Returns true if this storage holds a key for the given uncompressed public key (base64-encoded). Used during wallet initialization to detect whether a registered device signer belongs to this device.

### isAvailable

```kotlin theme={null}
abstract suspend fun isAvailable(): Boolean
```

Returns true if this storage backend is available on the current device/platform.

### mapAddressToKey

```kotlin theme={null}
abstract suspend fun mapAddressToKey(address: String, publicKeyBase64: String): Result<Unit>
```

Associates a previously generated pending key with a wallet address.

### signHexMessage

```kotlin theme={null}
abstract suspend fun signHexMessage(address: String, hexMessage: String): Result<Pair<String, String>>
```

Signs a hex-encoded message using the key for the given wallet address.

### signHexMessageWithPendingKey

```kotlin theme={null}
abstract suspend fun signHexMessageWithPendingKey(publicKeyBase64: String, hexMessage: String): Result<Pair<String, String>>
```

Signs a hex-encoded message using a pending key (not yet mapped to a wallet address).

### signMessage

```kotlin theme={null}
abstract suspend fun signMessage(address: String, message: String): Result<Pair<String, String>>
```

Signs a base64-encoded message using the key for the given wallet address.


# EmailSigner
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/interfaces/email-signer

Kotlin Interface

**Interface**

```kotlin theme={null}
interface EmailSigner : Signer
```

## Properties

| Property | Type | Description |
| - | - | - |
| `signerData` | `SignerData` | The admin signer data associated with this signer. Contains signer-specific information (email, public key, etc.) |

## Functions

| Function | Description |
| - | - |
| `getEncoding` | The encoding format for signatures. |
| `getKeyType` | The cryptographic key type used for signing. |
| `initialize` | Initializes the signer with necessary service context. Must be called before sign() operations. |
| `locator` | - |
| `processMessage` | Allows platform-specific preprocessing of the message before signing. |
| `sign` | Signs a message and returns the signature. |
| `signForApproval` | Signs a message and returns typed output suitable for building an approval. The default implementation wraps sign as SigningOutput.Standard. Override to return SigningOutput.Passkey for passkey-based signers. |

### getEncoding

```kotlin theme={null}
abstract suspend fun getEncoding(): String
```

The encoding format for signatures.

### getKeyType

```kotlin theme={null}
abstract suspend fun getKeyType(): String
```

The cryptographic key type used for signing.

### initialize

```kotlin theme={null}
abstract suspend fun initialize(service: CrossmintService?)
```

Initializes the signer with necessary service context. Must be called before sign() operations.

### locator

```kotlin theme={null}
open fun locator(): String
```

### processMessage

```kotlin theme={null}
abstract fun processMessage(message: String): String
```

Allows platform-specific preprocessing of the message before signing.

### sign

```kotlin theme={null}
abstract suspend fun sign(message: String): Result<String, SignerError>
```

Signs a message and returns the signature.

### signForApproval

```kotlin theme={null}
open suspend fun signForApproval(message: String): Result<SigningOutput, SignerError>
```

Signs a message and returns typed output suitable for building an approval. The default implementation wraps sign as SigningOutput.Standard. Override to return SigningOutput.Passkey for passkey-based signers.


# FailureAwareSessionStore
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/interfaces/failure-aware-session-store

Kotlin Interface

**Interface**

```kotlin theme={null}
interface FailureAwareSessionStore : SessionStore
```

## Functions

| Function | Description |
| - | - |
| `clear` | - |
| `hasFailed` | Returns true if this store has encountered a failure and should no longer be used. Once this returns true, it should continue to return true for the lifetime of the instance. |
| `token` | - |
| `update` | - |

### clear

```kotlin theme={null}
abstract suspend fun clear()
```

### hasFailed

```kotlin theme={null}
abstract fun hasFailed(): Boolean
```

Returns true if this store has encountered a failure and should no longer be used. Once this returns true, it should continue to return true for the lifetime of the instance.

### token

```kotlin theme={null}
abstract suspend fun token(): AuthToken?
```

### update

```kotlin theme={null}
abstract suspend fun update(token: AuthToken?)
```


# NFTOperations
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/interfaces/nft-operations

Kotlin Interface

**Interface**

```kotlin theme={null}
interface NFTOperations
```

## Functions

| Function | Description |
| - | - |
| `getNFTs` | - |

### getNFTs

```kotlin theme={null}
abstract suspend fun getNFTs(page: Int, perPage: Int): Result<List<NFT>, WalletError>
```


# NonCustodialSigner
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/interfaces/non-custodial-signer

Kotlin Interface

**Interface**

```kotlin theme={null}
interface NonCustodialSigner
```

## Properties

| Property | Type | Description |
| - | - | - |
| `locator` | `String` | - |


# PasskeyProvider
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/interfaces/passkey-provider

Kotlin Interface

**Interface**

```kotlin theme={null}
interface PasskeyProvider
```

## Functions

| Function | Description |
| - | - |
| `signWithPasskey` | Shows the passkey prompt and signs challenge with the passkey credentialId. |

### signWithPasskey

```kotlin theme={null}
abstract suspend fun signWithPasskey(challenge: String, credentialId: String): Result<PasskeySignResult, PasskeyError>
```

Shows the passkey prompt and signs challenge with the passkey credentialId.


# SessionStore
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/interfaces/session-store

Kotlin Interface

**Interface**

```kotlin theme={null}
interface SessionStore
```

## Functions

| Function | Description |
| - | - |
| `clear` | - |
| `token` | - |
| `update` | - |

### clear

```kotlin theme={null}
abstract suspend fun clear()
```

### token

```kotlin theme={null}
abstract suspend fun token(): AuthToken?
```

### update

```kotlin theme={null}
abstract suspend fun update(token: AuthToken?)
```


# Signer
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/interfaces/signer

Kotlin Interface

**Interface**

```kotlin theme={null}
interface Signer
```

## Properties

| Property | Type | Description |
| - | - | - |
| `signerData` | `SignerData` | The admin signer data associated with this signer. Contains signer-specific information (email, public key, etc.) |

## Functions

| Function | Description |
| - | - |
| `initialize` | Initializes the signer with necessary service context. Must be called before sign() operations. |
| `locator` | - |
| `sign` | Signs a message and returns the signature. |
| `signForApproval` | Signs a message and returns typed output suitable for building an approval. The default implementation wraps sign as SigningOutput.Standard. Override to return SigningOutput.Passkey for passkey-based signers. |

### initialize

```kotlin theme={null}
abstract suspend fun initialize(service: CrossmintService?)
```

Initializes the signer with necessary service context. Must be called before sign() operations.

### locator

```kotlin theme={null}
open fun locator(): String
```

### sign

```kotlin theme={null}
abstract suspend fun sign(message: String): Result<String, SignerError>
```

Signs a message and returns the signature.

### signForApproval

```kotlin theme={null}
open suspend fun signForApproval(message: String): Result<SigningOutput, SignerError>
```

Signs a message and returns typed output suitable for building an approval. The default implementation wraps sign as SigningOutput.Standard. Override to return SigningOutput.Passkey for passkey-based signers.


# SignerManagementOperations
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/interfaces/signer-management-operations

Kotlin Interface

**Interface**

```kotlin theme={null}
interface SignerManagementOperations
```

## Properties

| Property | Type | Description |
| - | - | - |
| `recoveryMethods` | `List<RecoveryMethod>` | The recovery methods of the wallet, with the changes made by addRecoveryMethod and removeRecoveryMethod. |

## Functions

| Function | Description |
| - | - |
| `addRecoveryMethod` | Adds a recovery method to the wallet. See Wallet.addRecoveryMethod. |
| `addSigner` | Registers a new delegated signer on the wallet via the recovery/approval flow. Does not change the active signer. |
| `isSignerApproved` | Returns true if the given signer is approved on this wallet's chain. |
| `localDeviceSignerLocator` | Returns the locator of the device signer that lives on this device. Returns null if this wallet has no device signer on this device. |
| `needsRecovery` | Returns true when a device signer was configured for this wallet but no matching hardware key exists on the current device. |
| `recover` | Generates a new hardware key on this device and registers it on the wallet using the admin/recovery signer approval flow. |
| `removeRecoveryMethod` | Removes a recovery method from the wallet. See Wallet.removeRecoveryMethod. |
| `removeSigner` | Removes a delegated signer from the wallet. Supported types: DelegatedSigner.Email, DelegatedSigner.Phone, DelegatedSigner.ExternalWallet, DelegatedSigner.Locator, DelegatedSigner.Passkey. |
| `signerIsRegistered` | Checks if the signer is registered on this wallet. |
| `signers` | Fetches the live list of signers registered on this wallet from the API. |
| `useRecoveryMethod` | Selects the recovery method that approves signer changes. See Wallet.useRecoveryMethod. |
| `useSigner` | Sets the active signer for subsequent wallet operations. |

### addRecoveryMethod

```kotlin theme={null}
abstract suspend fun addRecoveryMethod(recoveryMethod: DelegatedSigner): Result<Unit, WalletError>
```

Adds a recovery method to the wallet. See Wallet.addRecoveryMethod.

### addSigner

```kotlin theme={null}
abstract suspend fun addSigner(signer: DelegatedSigner, deployImmediately: Boolean, approver: DelegatedSigner? = null): Result<Unit, WalletError>
```

Registers a new delegated signer on the wallet via the recovery/approval flow. Does not change the active signer.

### isSignerApproved

```kotlin theme={null}
abstract suspend fun isSignerApproved(locator: String): Result<Boolean, WalletError>
```

Returns true if the given signer is approved on this wallet's chain.

### localDeviceSignerLocator

```kotlin theme={null}
abstract suspend fun localDeviceSignerLocator(): DelegatedSignerData?
```

Returns the locator of the device signer that lives on this device. Returns null if this wallet has no device signer on this device.

### needsRecovery

```kotlin theme={null}
abstract suspend fun needsRecovery(): Boolean
```

Returns true when a device signer was configured for this wallet but no matching hardware key exists on the current device.

### recover

```kotlin theme={null}
abstract suspend fun recover(approver: DelegatedSigner? = null): Result<Unit, WalletError>
```

Generates a new hardware key on this device and registers it on the wallet using the admin/recovery signer approval flow.

### removeRecoveryMethod

```kotlin theme={null}
abstract suspend fun removeRecoveryMethod(recoveryMethod: DelegatedSigner): Result<Unit, WalletError>
```

Removes a recovery method from the wallet. See Wallet.removeRecoveryMethod.

### removeSigner

```kotlin theme={null}
abstract suspend fun removeSigner(signer: DelegatedSigner, approver: DelegatedSigner? = null): Result<Unit, WalletError>
```

Removes a delegated signer from the wallet. Supported types: DelegatedSigner.Email, DelegatedSigner.Phone, DelegatedSigner.ExternalWallet, DelegatedSigner.Locator, DelegatedSigner.Passkey.

### signerIsRegistered

```kotlin theme={null}
abstract fun signerIsRegistered(signer: DelegatedSigner): Boolean
```

Checks if the signer is registered on this wallet.

### signers

```kotlin theme={null}
abstract suspend fun signers(): Result<List<DelegatedSignerData>, WalletError>
```

Fetches the live list of signers registered on this wallet from the API.

### useRecoveryMethod

```kotlin theme={null}
abstract suspend fun useRecoveryMethod(recoveryMethod: DelegatedSigner): Result<Unit, WalletError>
```

Selects the recovery method that approves signer changes. See Wallet.useRecoveryMethod.

### useSigner

```kotlin theme={null}
abstract suspend fun useSigner(signer: DelegatedSigner): Result<Unit, WalletError>
```

Sets the active signer for subsequent wallet operations.

## Deprecated

### ~~signerIsRegistered~~

<Warning>Deprecated. Use signerIsRegistered(signer: DelegatedSigner) instead.</Warning>

```kotlin theme={null}
abstract fun signerIsRegistered(locator: String): Boolean
```

Returns true if the given locator is registered as a delegated signer on this wallet.


# TransactionOperations
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/interfaces/transaction-operations

Kotlin Interface

**Interface**

```kotlin theme={null}
interface TransactionOperations
```

## Functions

| Function | Description |
| - | - |
| `getTransaction` | - |
| `listTransactions` | - |
| `listTransfers` | - |
| `send` | Sends tokens to a recipient address. |
| `sendRawTransaction` | - |
| `signAndSubmitTransaction` | - |
| `signMessage` | - |
| `signTypedData` | - |

### getTransaction

```kotlin theme={null}
abstract suspend fun getTransaction(transactionId: String): Result<Transaction, TransactionError>
```

### listTransactions

```kotlin theme={null}
abstract suspend fun listTransactions(): Result<List<Transaction>, TransactionError>
```

### listTransfers

```kotlin theme={null}
abstract suspend fun listTransfers(tokens: List<String>): Result<TransferList, TransferError>
```

### send

```kotlin theme={null}
abstract suspend fun send(recipient: String, tokenLocator: String, amount: Double, idempotencyKey: String? = null, signer: SignerSelection = SignerSelection.Admin): Result<Transaction, TransactionError>
```

Sends tokens to a recipient address.

### sendRawTransaction

```kotlin theme={null}
abstract suspend fun sendRawTransaction(params: RawTransactionParams, signer: SignerSelection = SignerSelection.Admin): Result<Transaction, TransactionError>
```

### signAndSubmitTransaction

```kotlin theme={null}
abstract suspend fun signAndSubmitTransaction(transactionId: String, signer: SignerSelection = SignerSelection.Admin): Result<Transaction, TransactionError>
```

### signMessage

```kotlin theme={null}
abstract suspend fun signMessage(message: String, signer: SignerSelection): Result<String, SignatureError>
```

### signTypedData

```kotlin theme={null}
abstract suspend fun signTypedData(typedDataJson: String, signer: SignerSelection): Result<String, SignatureError>
```


# ApiKey.Companion
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/api-key-companion

Kotlin Object

**Object**

```kotlin theme={null}
companion object
```

## Functions

| Function | Description |
| - | - |
| `fromString` | - |

### fromString

```kotlin theme={null}
fun fromString(key: String): ApiKey
```


# Chain.Companion
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/chain-companion

Kotlin Object

**Object**

```kotlin theme={null}
companion object
```

## Properties

| Property | Type | Description |
| - | - | - |
| `all` | `Map<String, Chain>` | - |

## Functions

| Function | Description |
| - | - |
| `fromName` | Resolves a chain from its string identifier. |

### fromName

```kotlin theme={null}
fun fromName(chainName: String): Chain
```

Resolves a chain from its string identifier.


# Configuration.Companion
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/configuration-companion

Kotlin Object

**Object**

```kotlin theme={null}
companion object
```

## Functions

| Function | Description |
| - | - |
| `create` | - |

### create

```kotlin theme={null}
fun create(apiKeyString: String, appIdentifierProvider: () -> String?): Configuration
```


# CrossmintAuthManager.Companion
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/crossmint-auth-manager-companion

Kotlin Object

**Object**

```kotlin theme={null}
companion object
```

## Properties

| Property | Type | Description |
| - | - | - |
| `initialized` | `Result` | - |


# Crossmint.Companion
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/crossmint-companion

Kotlin Object

**Object**

```kotlin theme={null}
companion object
```

## Properties

| Property | Type | Description |
| - | - | - |
| `instance` | `CrossmintSDK` | - |


# CrossmintSDK.Companion
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/crossmint-sdk-companion

Kotlin Object

**Object**

```kotlin theme={null}
companion object
```

## Properties

| Property | Type | Description |
| - | - | - |
| `shared` | `CrossmintSDK` | Returns the configured SDK instance. |

## Functions

| Function | Description |
| - | - |
| `configure` | Configures the SDK with the given API key. Safe to call multiple times — subsequent calls after the first are ignored. |

### configure

```kotlin theme={null}
fun configure(apiKey: String, logLevel: Result = LogLevel.WARN)
```

Configures the SDK with the given API key. Safe to call multiple times — subsequent calls after the first are ignored.

```kotlin theme={null}
fun CrossmintSDK.Companion.configure(apiKey: String, appContext: Context, logLevel: LogLevel = LogLevel.WARN)
```

Configures the SDK with the given API key and Android application context. Safe to call multiple times — subsequent calls after the first are ignored.


# DelegatedSignerStatus.Companion
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/delegated-signer-status-companion

Kotlin Object

**Object**

```kotlin theme={null}
companion object
```

## Functions

| Function | Description |
| - | - |
| `from` | - |

### from

```kotlin theme={null}
fun from(value: String?): DelegatedSignerStatus
```


# DelegatedSignerType.Companion
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/delegated-signer-type-companion

Kotlin Object

**Object**

```kotlin theme={null}
companion object
```

## Functions

| Function | Description |
| - | - |
| `from` | - |

### from

```kotlin theme={null}
fun from(value: String?): DelegatedSignerType
```


# DeviceSignerError.HardwareUnavailable
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/device-signer-error-hardware-unavailable

Kotlin Object

**Object**

```kotlin theme={null}
data object HardwareUnavailable : DeviceSignerError
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `message` | `String?` | - |


# DeviceSignerError.InvalidMessage
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/device-signer-error-invalid-message

Kotlin Object

**Object**

```kotlin theme={null}
data object InvalidMessage : DeviceSignerError
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `message` | `String?` | - |


# DeviceSignerError.KeyGenerationFailed
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/device-signer-error-key-generation-failed

Kotlin Object

**Object**

```kotlin theme={null}
data object KeyGenerationFailed : DeviceSignerError
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `message` | `String?` | - |


# DeviceSignerError.KeyNotFound
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/device-signer-error-key-not-found

Kotlin Object

**Object**

```kotlin theme={null}
data object KeyNotFound : DeviceSignerError
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `message` | `String?` | - |


# DeviceSignerError.SigningFailed
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/device-signer-error-signing-failed

Kotlin Object

**Object**

```kotlin theme={null}
data object SigningFailed : DeviceSignerError
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `message` | `String?` | - |


# EncryptedSharedPreferenceStorage.Companion
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/encrypted-shared-preference-storage-companion

Kotlin Object

**Object**

```kotlin theme={null}
companion object
```


# EVMChain.Apechain
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-apechain

Kotlin Object

**Object**

```kotlin theme={null}
data object Apechain : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.Apex
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-apex

Kotlin Object

**Object**

```kotlin theme={null}
data object Apex : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.Arbitrum
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-arbitrum

Kotlin Object

**Object**

```kotlin theme={null}
data object Arbitrum : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.ArbitrumNova
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-arbitrum-nova

Kotlin Object

**Object**

```kotlin theme={null}
data object ArbitrumNova : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.ArbitrumSepolia
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-arbitrum-sepolia

Kotlin Object

**Object**

```kotlin theme={null}
data object ArbitrumSepolia : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.AstarZkEVM
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-astar-zk-evm

Kotlin Object

**Object**

```kotlin theme={null}
data object AstarZkEVM : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.Avalanche
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-avalanche

Kotlin Object

**Object**

```kotlin theme={null}
data object Avalanche : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.AvalancheFuji
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-avalanche-fuji

Kotlin Object

**Object**

```kotlin theme={null}
data object AvalancheFuji : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.BarretTestnet
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-barret-testnet

Kotlin Object

**Object**

```kotlin theme={null}
data object BarretTestnet : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.Base
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-base

Kotlin Object

**Object**

```kotlin theme={null}
data object Base : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.BaseGoerli
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-base-goerli

Kotlin Object

**Object**

```kotlin theme={null}
data object BaseGoerli : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.BaseSepolia
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-base-sepolia

Kotlin Object

**Object**

```kotlin theme={null}
data object BaseSepolia : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.Boss
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-boss

Kotlin Object

**Object**

```kotlin theme={null}
data object Boss : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.BSCTestnet
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-bsc-testnet

Kotlin Object

**Object**

```kotlin theme={null}
data object BSCTestnet : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.Chiliz
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-chiliz

Kotlin Object

**Object**

```kotlin theme={null}
data object Chiliz : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.ChilizSpicyTestnet
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-chiliz-spicy-testnet

Kotlin Object

**Object**

```kotlin theme={null}
data object ChilizSpicyTestnet : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.Coti
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-coti

Kotlin Object

**Object**

```kotlin theme={null}
data object Coti : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.CotiTestnet
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-coti-testnet

Kotlin Object

**Object**

```kotlin theme={null}
data object CotiTestnet : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.Curtis
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-curtis

Kotlin Object

**Object**

```kotlin theme={null}
data object Curtis : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.Ethereum
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-ethereum

Kotlin Object

**Object**

```kotlin theme={null}
data object Ethereum : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.EthereumGoerli
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-ethereum-goerli

Kotlin Object

**Object**

```kotlin theme={null}
data object EthereumGoerli : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.EthereumSepolia
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-ethereum-sepolia

Kotlin Object

**Object**

```kotlin theme={null}
data object EthereumSepolia : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.HypersonicTestnet
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-hypersonic-testnet

Kotlin Object

**Object**

```kotlin theme={null}
data object HypersonicTestnet : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.Lightlink
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-lightlink

Kotlin Object

**Object**

```kotlin theme={null}
data object Lightlink : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.LightlinkPegasus
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-lightlink-pegasus

Kotlin Object

**Object**

```kotlin theme={null}
data object LightlinkPegasus : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.Mode
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-mode

Kotlin Object

**Object**

```kotlin theme={null}
data object Mode : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.ModeSepolia
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-mode-sepolia

Kotlin Object

**Object**

```kotlin theme={null}
data object ModeSepolia : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.Optimism
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-optimism

Kotlin Object

**Object**

```kotlin theme={null}
data object Optimism : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.OptimismGoerli
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-optimism-goerli

Kotlin Object

**Object**

```kotlin theme={null}
data object OptimismGoerli : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.OptimismSepolia
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-optimism-sepolia

Kotlin Object

**Object**

```kotlin theme={null}
data object OptimismSepolia : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.Polygon
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-polygon

Kotlin Object

**Object**

```kotlin theme={null}
data object Polygon : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.PolygonAmoy
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-polygon-amoy

Kotlin Object

**Object**

```kotlin theme={null}
data object PolygonAmoy : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.PolygonMumbai
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-polygon-mumbai

Kotlin Object

**Object**

```kotlin theme={null}
data object PolygonMumbai : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.Rari
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-rari

Kotlin Object

**Object**

```kotlin theme={null}
data object Rari : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.RariTestnet
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-rari-testnet

Kotlin Object

**Object**

```kotlin theme={null}
data object RariTestnet : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.Scroll
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-scroll

Kotlin Object

**Object**

```kotlin theme={null}
data object Scroll : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.ScrollSepolia
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-scroll-sepolia

Kotlin Object

**Object**

```kotlin theme={null}
data object ScrollSepolia : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.SeiAtlantic2Testnet
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-sei-atlantic2testnet

Kotlin Object

**Object**

```kotlin theme={null}
data object SeiAtlantic2Testnet : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.SeiPacific1
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-sei-pacific1

Kotlin Object

**Object**

```kotlin theme={null}
data object SeiPacific1 : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.Shape
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-shape

Kotlin Object

**Object**

```kotlin theme={null}
data object Shape : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.ShapeSepolia
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-shape-sepolia

Kotlin Object

**Object**

```kotlin theme={null}
data object ShapeSepolia : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.SkaleNebula
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-skale-nebula

Kotlin Object

**Object**

```kotlin theme={null}
data object SkaleNebula : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.SkaleNebulaTestnet
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-skale-nebula-testnet

Kotlin Object

**Object**

```kotlin theme={null}
data object SkaleNebulaTestnet : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.Soneium
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-soneium

Kotlin Object

**Object**

```kotlin theme={null}
data object Soneium : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.SoneiumMinatoTestnet
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-soneium-minato-testnet

Kotlin Object

**Object**

```kotlin theme={null}
data object SoneiumMinatoTestnet : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.Space
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-space

Kotlin Object

**Object**

```kotlin theme={null}
data object Space : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.SpaceTestnet
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-space-testnet

Kotlin Object

**Object**

```kotlin theme={null}
data object SpaceTestnet : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.Story
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-story

Kotlin Object

**Object**

```kotlin theme={null}
data object Story : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.StoryTestnet
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-story-testnet

Kotlin Object

**Object**

```kotlin theme={null}
data object StoryTestnet : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.VerifyTestnet
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-verify-testnet

Kotlin Object

**Object**

```kotlin theme={null}
data object VerifyTestnet : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.Viction
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-viction

Kotlin Object

**Object**

```kotlin theme={null}
data object Viction : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.VictionTestnet
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-viction-testnet

Kotlin Object

**Object**

```kotlin theme={null}
data object VictionTestnet : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.Xai
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-xai

Kotlin Object

**Object**

```kotlin theme={null}
data object Xai : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.XaiSepoliaTestnet
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-xai-sepolia-testnet

Kotlin Object

**Object**

```kotlin theme={null}
data object XaiSepoliaTestnet : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.ZenchainTestnet
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-zenchain-testnet

Kotlin Object

**Object**

```kotlin theme={null}
data object ZenchainTestnet : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.Zkatana
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-zkatana

Kotlin Object

**Object**

```kotlin theme={null}
data object Zkatana : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.Zkyoto
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-zkyoto

Kotlin Object

**Object**

```kotlin theme={null}
data object Zkyoto : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.Zora
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-zora

Kotlin Object

**Object**

```kotlin theme={null}
data object Zora : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.ZoraGoerli
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-zora-goerli

Kotlin Object

**Object**

```kotlin theme={null}
data object ZoraGoerli : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# EVMChain.ZoraSepolia
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/evm-chain-zora-sepolia

Kotlin Object

**Object**

```kotlin theme={null}
data object ZoraSepolia : EVMChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# InsecurePersistentSessionStore.Companion
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/insecure-persistent-session-store-companion

Kotlin Object

**Object**

```kotlin theme={null}
companion object
```

## Properties

| Property | Type | Description |
| - | - | - |
| `settingsFactory` | `() -> Settings` | - |


# KeystoreKeyStorage.Companion
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/keystore-key-storage-companion

Kotlin Object

**Object**

```kotlin theme={null}
companion object
```


# SignerError.Cancelled
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/signer-error-cancelled

Kotlin Object

**Object**

```kotlin theme={null}
data object Cancelled : SignerError
```


# SignerError.InvalidEmail
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/signer-error-invalid-email

Kotlin Object

**Object**

```kotlin theme={null}
data object InvalidEmail : SignerError
```


# SignerError.NotInitialized
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/signer-error-not-initialized

Kotlin Object

**Object**

```kotlin theme={null}
data object NotInitialized : SignerError
```


# SignerError.NotStarted
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/signer-error-not-started

Kotlin Object

**Object**

```kotlin theme={null}
data object NotStarted : SignerError
```


# SignerError.TeeNotStarted
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/signer-error-tee-not-started

Kotlin Object

**Object**

```kotlin theme={null}
data object TeeNotStarted : SignerError
```


# SignerSelection.Admin
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/signer-selection-admin

Kotlin Object

**Object**

```kotlin theme={null}
object Admin : SignerSelection
```


# SignerType.ApiKey
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/signer-type-api-key

Kotlin Object

**Object**

```kotlin theme={null}
data object ApiKey : SignerType
```


# SolanaChain.Solana
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/solana-chain-solana

Kotlin Object

**Object**

```kotlin theme={null}
data object Solana : SolanaChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open override fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# StellarChain.Stellar
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/stellar-chain-stellar

Kotlin Object

**Object**

```kotlin theme={null}
data object Stellar : StellarChain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open override fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# TEEError.EncryptionUnavailable
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/tee-error-encryption-unavailable

Kotlin Object

**Object**

```kotlin theme={null}
object EncryptionUnavailable : TEEError
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `message` | `String` | - |


# TEEError.ErrorLoadingService
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/tee-error-error-loading-service

Kotlin Object

**Object**

```kotlin theme={null}
object ErrorLoadingService : TEEError
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `message` | `String` | - |


# TEEError.HandshakeFailed
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/tee-error-handshake-failed

Kotlin Object

**Object**

```kotlin theme={null}
object HandshakeFailed : TEEError
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `message` | `String` | - |


# TEEError.HandshakeRequired
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/tee-error-handshake-required

Kotlin Object

**Object**

```kotlin theme={null}
object HandshakeRequired : TEEError
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `message` | `String` | - |


# TEEError.InvalidSignature
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/tee-error-invalid-signature

Kotlin Object

**Object**

```kotlin theme={null}
object InvalidSignature : TEEError
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `message` | `String` | - |


# TEEError.JWTRequired
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/tee-error-jwt-required

Kotlin Object

**Object**

```kotlin theme={null}
object JWTRequired : TEEError
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `message` | `String` | - |


# TEEError.SignerStatusUnavailable
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/tee-error-signer-status-unavailable

Kotlin Object

**Object**

```kotlin theme={null}
object SignerStatusUnavailable : TEEError
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `message` | `String` | - |


# TEEError.Timeout
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/tee-error-timeout

Kotlin Object

**Object**

```kotlin theme={null}
object Timeout : TEEError
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `message` | `String` | - |


# TEEError.UserCancelled
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/tee-error-user-cancelled

Kotlin Object

**Object**

```kotlin theme={null}
object UserCancelled : TEEError
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `message` | `String` | - |


# TinkSecureStorage.Companion
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/tink-secure-storage-companion

Kotlin Object

**Object**

```kotlin theme={null}
companion object
```


# TinkWithFallbackSessionStore.Companion
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/tink-with-fallback-session-store-companion

Kotlin Object

**Object**

```kotlin theme={null}
companion object
```


# TokenAccountType.Wallet
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/objects/token-account-type-wallet

Kotlin Object

**Object**

```kotlin theme={null}
data object Wallet : TokenAccountType
```


# LocalCrossmintSDK
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/properties/local-crossmint-sdk

Kotlin Property

**Property**

```kotlin theme={null}
val LocalCrossmintSDK: ProvidableCompositionLocal<Result>
```

CompositionLocal for providing CrossmintSDK instance to the composition tree.


# ApprovalMetadata
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/sealed-classes/approval-metadata

Kotlin Sealed Class

**Sealed Class**

```kotlin theme={null}
sealed class ApprovalMetadata
```


# ApprovalSignature
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/sealed-classes/approval-signature

Kotlin Sealed Class

**Sealed Class**

```kotlin theme={null}
sealed class ApprovalSignature
```


# DelegatedSigner
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/sealed-classes/delegated-signer

Kotlin Sealed Class

**Sealed Class**

```kotlin theme={null}
sealed class DelegatedSigner
```

## Properties

| Property | Type | Description |
| - | - | - |
| `expiresAt` | `Long?` | Optional expiration timestamp in milliseconds since Unix epoch. If set, the delegated signer will expire at this time. |


# DeviceSignerError
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/sealed-classes/device-signer-error

Kotlin Sealed Class

**Sealed Class**

```kotlin theme={null}
sealed class DeviceSignerError : Exception
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `message` | `String?` | - |


# Owner
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/sealed-classes/owner

Kotlin Sealed Class

**Sealed Class**

```kotlin theme={null}
sealed class Owner
```


# RawTransactionParams
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/sealed-classes/raw-transaction-params

Kotlin Sealed Class

**Sealed Class**

```kotlin theme={null}
sealed class RawTransactionParams
```


# SignerData
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/sealed-classes/signer-data

Kotlin Sealed Class

**Sealed Class**

```kotlin theme={null}
sealed class SignerData
```

## Properties

| Property | Type | Description |
| - | - | - |
| `locator` | `String` | - |


# SignerError
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/sealed-classes/signer-error

Kotlin Sealed Class

**Sealed Class**

```kotlin theme={null}
sealed class SignerError
```


# SignerSelection
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/sealed-classes/signer-selection

Kotlin Sealed Class

**Sealed Class**

```kotlin theme={null}
sealed class SignerSelection
```


# SignerType
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/sealed-classes/signer-type

Kotlin Sealed Class

**Sealed Class**

```kotlin theme={null}
sealed class SignerType
```


# SigningOutput
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/sealed-classes/signing-output

Kotlin Sealed Class

**Sealed Class**

```kotlin theme={null}
sealed class SigningOutput
```


# TEEError
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/sealed-classes/tee-error

Kotlin Sealed Class

**Sealed Class**

```kotlin theme={null}
sealed class TEEError : Exception
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `message` | `String?` | - |


# ApiKeyError
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/sealed-interfaces/api-key-error

Kotlin Sealed Interface

**Sealed Interface**

```kotlin theme={null}
sealed interface ApiKeyError : ConfigurationError
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `ConfigurationErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# AuthError
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/sealed-interfaces/auth-error

Kotlin Sealed Interface

**Sealed Interface**

```kotlin theme={null}
sealed interface AuthError : CrossmintError
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `AuthErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# BalanceError
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/sealed-interfaces/balance-error

Kotlin Sealed Interface

**Sealed Interface**

```kotlin theme={null}
sealed interface BalanceError : CrossmintError
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `BalanceErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# Chain
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/sealed-interfaces/chain

Kotlin Sealed Interface

**Sealed Interface**

```kotlin theme={null}
sealed interface Chain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# ChainInfo
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/sealed-interfaces/chain-info

Kotlin Sealed Interface

**Sealed Interface**

```kotlin theme={null}
sealed interface ChainInfo
```


# ConfigurationError
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/sealed-interfaces/configuration-error

Kotlin Sealed Interface

**Sealed Interface**

```kotlin theme={null}
sealed interface ConfigurationError : CrossmintError
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `ConfigurationErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# CrossmintError
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/sealed-interfaces/crossmint-error

Kotlin Sealed Interface

**Sealed Interface**

```kotlin theme={null}
sealed interface CrossmintError
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `CrossmintErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# CrossmintErrorCode
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/sealed-interfaces/crossmint-error-code

Kotlin Sealed Interface

**Sealed Interface**

```kotlin theme={null}
sealed interface CrossmintErrorCode
```


# EVMChain
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/sealed-interfaces/evm-chain

Kotlin Sealed Interface

**Sealed Interface**

```kotlin theme={null}
sealed interface EVMChain : SupportedChain<EVMWallet>
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# NetworkError
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/sealed-interfaces/network-error

Kotlin Sealed Interface

**Sealed Interface**

```kotlin theme={null}
sealed interface NetworkError : CrossmintError
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `NetworkErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# PasskeyError
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/sealed-interfaces/passkey-error

Kotlin Sealed Interface

**Sealed Interface**

```kotlin theme={null}
sealed interface PasskeyError : CrossmintError
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `PasskeyErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# Result
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/sealed-interfaces/result

Kotlin Sealed Interface

**Sealed Interface**

```kotlin theme={null}
sealed interface Result<out T, out E>
```

## Functions

| Function | Description |
| - | - |
| `flatMap` | Chains a success through transform, which itself returns a Result. |
| `fold` | Applies onSuccess or onFailure depending on the result variant. |
| `getOrNull` | Returns the success value, or null if this is a Result.Failure. |
| `getOrThrow` | Returns the success value, or throws if this is a Result.Failure. |
| `map` | Transforms the success value using transform, leaving failures unchanged. |
| `mapError` | Transforms the error using transform, leaving successes unchanged. |

### flatMap

```kotlin theme={null}
inline fun <T, E, R> Result<T, E>.flatMap(transform: (T) -> Result<R, E>): Result<R, E>
```

Chains a success through transform, which itself returns a Result.

### fold

```kotlin theme={null}
inline fun <T, E> Result<T, E>.fold(onSuccess: (T) -> Unit, onFailure: (E) -> Unit)
```

Applies onSuccess or onFailure depending on the result variant.

### getOrNull

```kotlin theme={null}
fun <T, E> Result<T, E>.getOrNull(): T?
```

Returns the success value, or null if this is a Result.Failure.

### getOrThrow

```kotlin theme={null}
fun <T, E> Result<T, E>.getOrThrow(): T
```

Returns the success value, or throws if this is a Result.Failure.

### map

```kotlin theme={null}
inline fun <T, E, R> Result<T, E>.map(transform: (T) -> R): Result<R, E>
```

Transforms the success value using transform, leaving failures unchanged.

### mapError

```kotlin theme={null}
inline fun <T, E, F> Result<T, E>.mapError(transform: (E) -> F): Result<T, F>
```

Transforms the error using transform, leaving successes unchanged.


# SignatureError
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/sealed-interfaces/signature-error

Kotlin Sealed Interface

**Sealed Interface**

```kotlin theme={null}
sealed interface SignatureError : CrossmintError
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `SignatureErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# SolanaChain
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/sealed-interfaces/solana-chain

Kotlin Sealed Interface

**Sealed Interface**

```kotlin theme={null}
sealed interface SolanaChain : SupportedChain<SolanaWallet>
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# StellarChain
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/sealed-interfaces/stellar-chain

Kotlin Sealed Interface

**Sealed Interface**

```kotlin theme={null}
sealed interface StellarChain : SupportedChain<StellarWallet>
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# SupportedChain
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/sealed-interfaces/supported-chain

Kotlin Sealed Interface

**Sealed Interface**

```kotlin theme={null}
sealed interface SupportedChain<W : Wallet> : Chain
```

## Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | The technology family this chain belongs to |
| `isTestnet` | `Boolean` | True if this is a test network |
| `name` | `String` | The canonical lowercase string identifier for this chain (e.g. "ethereum", "base-sepolia") |

## Functions

| Function | Description |
| - | - |
| `isValid` | Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise). |

### isValid

```kotlin theme={null}
open fun isValid(isProductionEnvironment: Boolean): Boolean
```

Returns true if this chain should be used in the given environment (mainnet chains for production, testnets otherwise).


# TokenAccountType
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/sealed-interfaces/token-account-type

Kotlin Sealed Interface

**Sealed Interface**

```kotlin theme={null}
sealed interface TokenAccountType
```


# TransactionError
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/sealed-interfaces/transaction-error

Kotlin Sealed Interface

**Sealed Interface**

```kotlin theme={null}
sealed interface TransactionError : CrossmintError
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `TransactionErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# TransactionParams
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/sealed-interfaces/transaction-params

Kotlin Sealed Interface

**Sealed Interface**

```kotlin theme={null}
sealed interface TransactionParams
```

## Properties

| Property | Type | Description |
| - | - | - |
| `signer` | `String?` | - |


# TransferError
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/sealed-interfaces/transfer-error

Kotlin Sealed Interface

**Sealed Interface**

```kotlin theme={null}
sealed interface TransferError : CrossmintError
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `TransferErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# WalletError
Source: https://docs.crossmint.com/sdk-reference/wallets/kotlin/sealed-interfaces/wallet-error

Kotlin Sealed Interface

**Sealed Interface**

```kotlin theme={null}
sealed interface WalletError : CrossmintError
```

## Properties

| Property | Type | Description |
| - | - | - |
| `cause` | `Throwable?` | - |
| `code` | `WalletErrorCode` | Stable, machine-readable identifier for this error. |
| `message` | `String` | - |


# Components
Source: https://docs.crossmint.com/sdk-reference/wallets/react-native/components

React Native components for React Native SDK reference for Crossmint wallets

## ExportPrivateKeyButton

Renders a button that allows the user to export their wallet's private key. Only works with email and phone signers. Will not render for passkey or external wallet signers.

### Props

<ResponseField name="appearance" type="UIConfig">
  Optional appearance configuration for styling the export button.

  <Expandable title="properties">
    <ResponseField name="borderRadius" type="string" />

    <ResponseField name="colors" type="UiConfigColors">
      <Expandable title="properties">
        <ResponseField name="accent" type="string" />

        <ResponseField name="background" type="string" />

        <ResponseField name="backgroundSecondary" type="string" />

        <ResponseField name="backgroundTertiary" type="string" />

        <ResponseField name="border" type="string" />

        <ResponseField name="buttonBackground" type="string" />

        <ResponseField name="danger" type="string" />

        <ResponseField name="inputBackground" type="string" />

        <ResponseField name="textLink" type="string" />

        <ResponseField name="textPrimary" type="string" />

        <ResponseField name="textSecondary" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="fonts" type="UiConfigFonts">
      <Expandable title="properties">
        <ResponseField name="cssSrc" type="string" />

        <ResponseField name="family" type="string" />

        <ResponseField name="display" type="string" />

        <ResponseField name="src" type="string" />

        <ResponseField name="style" type="&#x22;normal&#x22; | &#x22;italic&#x22; | &#x22;oblique&#x22;" />

        <ResponseField name="weight" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="fontSizeBase" type="string" />

    <ResponseField name="fontWeightPrimary" type="string" />

    <ResponseField name="fontWeightSecondary" type="string" />

    <ResponseField name="hideCardForm" type="boolean" />

    <ResponseField name="spacingUnit" type="string" />
  </Expandable>
</ResponseField>

<ResponseField name="onExport" type="() => void | Promise<void>">
  Optional callback invoked after the user successfully exports (copies) their private key.
</ResponseField>

### Usage

```tsx theme={null}
import { ExportPrivateKeyButton } from "@crossmint/client-sdk-react-native-ui";
import { View, Text } from "react-native";

function WalletSettings() {
    return (
        <View>
            <Text>Export Private Key</Text>
            <ExportPrivateKeyButton
                appearance={{
                    colors: { border: "#e2e8f0" },
                    borderRadius: "12px",
                }}
            />
        </View>
    );
}
```

> **Note:** Only works with email and phone signers. Will not render for passkey or external wallet signers.


# Get Started
Source: https://docs.crossmint.com/sdk-reference/wallets/react-native/get-started

Installation and setup for the React Native SDK reference for Crossmint wallets

### Latest React Native SDK version - <a href="https://www.npmjs.com/package/@crossmint/client-sdk-react-native-ui"><img alt="npm" /></a>

The Crossmint React Native SDK (`@crossmint/client-sdk-react-native-ui`) provides React Native components and hooks for integrating Crossmint wallets into your mobile application.

## Installation

<Snippet />

## Provider Setup

Wrap your application with the required providers:

```tsx theme={null}
import {
    CrossmintProvider,
    CrossmintWalletProvider,
} from "@crossmint/client-sdk-react-native-ui";

function App() {
    return (
        <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
            <CrossmintWalletProvider
                createOnLogin={{
                    chain: "base-sepolia",
                    recovery: { type: "email" },
                }}
            >
                {/* Your app components */}
            </CrossmintWalletProvider>
        </CrossmintProvider>
    );
}
```

## Quick Example

Once providers are set up, use hooks to access wallet state:

```tsx theme={null}
import { useWallet } from "@crossmint/client-sdk-react-native-ui";
import { View, Text } from "react-native";

function WalletInfo() {
    const { wallet, status } = useWallet();

    if (status === "in-progress") return <Text>Loading wallet...</Text>;
    if (!wallet) return <Text>No wallet connected</Text>;

    return (
        <View>
            <Text>Address: {wallet.address}</Text>
            <Text>Chain: {wallet.chain}</Text>
        </View>
    );
}
```

## Next Steps

* [Providers](/sdk-reference/wallets/react-native/providers) — Configure providers and their options
* [Hooks](/sdk-reference/wallets/react-native/hooks) — Access SDK state via React hooks
* [Components](/sdk-reference/wallets/react-native/components) — Drop-in UI components
* [Wallets SDK Reference](/sdk-reference/wallets/typescript/classes/Wallet) — Complete wallet method documentation


# Hooks
Source: https://docs.crossmint.com/sdk-reference/wallets/react-native/hooks

React Native hooks for React Native SDK reference for Crossmint wallets

## useWallet()

### Returns

<ResponseField name="createDeviceSigner" type="(address: string) => Promise<DeviceSignerConfig> | undefined">
  Creates a Device Signer
</ResponseField>

<ResponseField name="createPasskeySigner" type="(passkeyName: string) => Promise<RegisterSignerPasskeyParams>">
  Creates a Passkey Signer
</ResponseField>

<ResponseField name="createWallet" type="(props: ClientSideWalletCreateArgs<C>) => Promise<Wallet | undefined>">
  Creates a new wallet.

  <Expandable title="parameters">
    <ResponseField name="chain" type="Chain">
      The blockchain to create the wallet on (e.g. "base-sepolia").
    </ResponseField>

    <ResponseField name="recovery" type="SignerConfigForChain">
      A single recovery method configuration (e.g. `{ type: "email" }`). Used for wallet recovery and adding new signers.
    </ResponseField>

    <ResponseField name="recoveryMethods" type="SignerConfigForChain[]">
      Recovery methods, each able to authorize on its own. Only Solana and Stellar accept more than one.
    </ResponseField>

    <ResponseField name="signers" type="SignerConfigForChain[]">
      Optional array of operational signers. Defaults to a device signer if omitted (e.g. `[{ type: "device" }]`).
    </ResponseField>

    <ResponseField name="alias" type="string">
      Optional wallet alias.
    </ResponseField>

    <ResponseField name="plugins" type="WalletPlugin[]">
      Optional array of wallet plugins.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="error" type="WalletContextError | null">
  Detail about the last failure, or null when there is no error.
</ResponseField>

<ResponseField name="getWallet" type="(props: Pick<ClientSideWalletArgsFor<C>, &#x22;chain&#x22; | &#x22;alias&#x22;>) => Promise<Wallet | undefined>">
  Retrieves an existing wallet.

  <Expandable title="parameters">
    <ResponseField name="chain" type="Chain">
      The blockchain of the wallet to retrieve (e.g. "base-sepolia").
    </ResponseField>

    <ResponseField name="alias" type="string">
      Optional wallet alias to look up.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="status" type="&#x22;not-loaded&#x22; | &#x22;in-progress&#x22; | &#x22;loaded&#x22; | &#x22;error&#x22;">
  Current wallet status.
</ResponseField>

<ResponseField name="wallet" type="Wallet<Chain> | undefined">
  The current wallet instance, or undefined if no wallet is loaded.

  <Expandable title="parameters">
    <ResponseField name="constructor" type="unknown" />

    <ResponseField name="address" type="string" />

    <ResponseField name="alias" type="string" />

    <ResponseField name="chain" type="C" />

    <ResponseField name="owner" type="string" />

    <ResponseField name="apiClient" type="unknown" />

    <ResponseField name="recovery" type="unknown" />

    <ResponseField name="recoveryMethods" type="unknown" />

    <ResponseField name="signer" type="unknown" />

    <ResponseField name="addRecoveryMethod" type="unknown" />

    <ResponseField name="addSigner" type="unknown" />

    <ResponseField name="approve" type="unknown" />

    <ResponseField name="approveTransaction" type="unknown" />

    <ResponseField name="balances" type="unknown" />

    <ResponseField name="isSignerApproved" type="unknown" />

    <ResponseField name="needsRecovery" type="unknown" />

    <ResponseField name="nfts" type="unknown" />

    <ResponseField name="recover" type="unknown" />

    <ResponseField name="removeRecoveryMethod" type="unknown" />

    <ResponseField name="removeSigner" type="unknown" />

    <ResponseField name="send" type="unknown" />

    <ResponseField name="signerIsRegistered" type="unknown" />

    <ResponseField name="signers" type="unknown" />

    <ResponseField name="stagingFund" type="unknown" />

    <ResponseField name="transaction" type="unknown" />

    <ResponseField name="transactions" type="unknown" />

    <ResponseField name="transfers" type="unknown" />

    <ResponseField name="useRecoveryMethod" type="unknown" />

    <ResponseField name="useSigner" type="unknown" />

    <ResponseField name="waitForInit" type="unknown" />
  </Expandable>
</ResponseField>

### Usage

```tsx theme={null}
import { useWallet } from "@crossmint/client-sdk-react-native-ui";
import { View, Text, TouchableOpacity } from "react-native";

function WalletActions() {
    const { wallet, status } = useWallet();

    if (status === "in-progress") return <Text>Loading wallet...</Text>;
    if (!wallet) return <Text>No wallet</Text>;

    const handleSend = async () => {
        const tx = await wallet.send("0x...", "usdc", "10");
        console.log("Transaction:", tx.explorerLink);
    };

    const handleBalances = async () => {
        const balances = await wallet.balances();
        console.log("USDC:", balances.usdc.amount);
        console.log("Native:", balances.nativeToken.amount);
    };

    return (
        <View>
            <Text>Wallet: {wallet.address}</Text>
            <TouchableOpacity onPress={handleBalances}>
                <Text>Check Balances</Text>
            </TouchableOpacity>
            <TouchableOpacity onPress={handleSend}>
                <Text>Send USDC</Text>
            </TouchableOpacity>
        </View>
    );
}
```

***

## useWalletOtpSigner()

Hook for managing OTP-based signer authentication flows. Provides OTP send/verify functions for wallets using an email or phone signer. Must be used within a CrossmintWalletProvider.

### Returns

<ResponseField name="needsAuth" type="boolean">
  Whether the OTP signer currently requires authentication (OTP verification).
</ResponseField>

<ResponseField name="reject" type="(error: Error) => void">
  Rejects the current authentication request with an error.
</ResponseField>

<ResponseField name="sendOtp" type="() => Promise<void>">
  Sends a one-time password to the user (via email or phone, depending on the signer type).
</ResponseField>

<ResponseField name="verifyOtp" type="(otp: string) => Promise<void>">
  Verifies the one-time password entered by the user.
</ResponseField>

### Usage

```tsx theme={null}
import { useWalletOtpSigner } from "@crossmint/client-sdk-react-native-ui";
import { View, Text, TextInput, TouchableOpacity } from "react-native";
import { useState } from "react";

function OtpSignerFlow() {
    const { needsAuth, sendOtp, verifyOtp, reject } = useWalletOtpSigner();
    const [otp, setOtp] = useState("");

    if (!needsAuth) return null;

    return (
        <View>
            <Text>OTP verification required</Text>
            <TouchableOpacity onPress={sendOtp}>
                <Text>Send OTP</Text>
            </TouchableOpacity>
            <TextInput value={otp} onChangeText={setOtp} placeholder="Enter OTP" />
            <TouchableOpacity onPress={() => verifyOtp(otp)}>
                <Text>Verify</Text>
            </TouchableOpacity>
            <TouchableOpacity onPress={() => reject(new Error("User cancelled"))}>
                <Text>Cancel</Text>
            </TouchableOpacity>
        </View>
    );
}
```

***

## Wallet Methods

The `wallet` instance returned by `useWallet()` provides methods for token transfers, balances, signing, and more.

Since the React Native SDK wraps the Wallets SDK, see the **[Wallets SDK Reference](/sdk-reference/wallets/typescript/classes/Wallet)** for complete documentation.

| Method | Description |
| - | - |
| [`wallet.addRecoveryMethod()`](/sdk-reference/wallets/typescript/classes/Wallet#addrecoverymethod) | Add a recovery method to the wallet. Supported on Solana and Stellar only. Always uses one of the existing recovery methods to approve the change, selected as in addSigner. |
| [`wallet.addSigner()`](/sdk-reference/wallets/typescript/classes/Wallet#addsigner) | Add a signer to the wallet. Always uses a recovery method internally to approve the registration: the one selected via useRecoveryMethod, else the active signer when it is one of the recovery methods, else the wallet's single recovery method. Wallets with several recovery methods must select one first; an operational signer cannot authorize this. If the signer being added is the current operational signer, it will be reassembled with the new locator. Otherwise, the original signer is restored after the operation. |
| [`wallet.balances()`](/sdk-reference/wallets/typescript/classes/Wallet#balances) | Get the wallet balances - always includes USDC and native token (ETH/SOL) |
| [`wallet.isSignerApproved()`](/sdk-reference/wallets/typescript/classes/Wallet#issignerapproved) | Check if a signer is approved and usable for the current wallet chain. |
| [`wallet.needsRecovery()`](/sdk-reference/wallets/typescript/classes/Wallet#needsrecovery) | Whether the wallet needs recovery (signer registration) before the next transaction. |
| [`wallet.nfts()`](/sdk-reference/wallets/typescript/classes/Wallet#nfts) | Get the wallet NFTs |
| [`wallet.recover()`](/sdk-reference/wallets/typescript/classes/Wallet#recover) | Register a device signer with the wallet using the recovery signer. Generates a new device key and registers it on-chain. Returns early if the device signer's locator is already approved on-chain. |
| [`wallet.removeRecoveryMethod()`](/sdk-reference/wallets/typescript/classes/Wallet#removerecoverymethod) | Remove a recovery method from the wallet. Supported on Solana and Stellar only. Always uses one of the remaining recovery methods to approve the change, selected as in addSigner. |
| [`wallet.removeSigner()`](/sdk-reference/wallets/typescript/classes/Wallet#removesigner) | Remove a signer from the wallet. Always uses a recovery method internally to approve the removal, selected as in addSigner. |
| [`wallet.send()`](/sdk-reference/wallets/typescript/classes/Wallet#send) | Send a token to a wallet or user locator |
| [`wallet.signerIsRegistered()`](/sdk-reference/wallets/typescript/classes/Wallet#signerisregistered) | Check if a signer is registered in this wallet. |
| [`wallet.signers()`](/sdk-reference/wallets/typescript/classes/Wallet#signers) | List the signers for this wallet. Returns full signer objects with status. For EVM wallets, only signers with an approval (pending or completed) for the wallet's chain are included. |
| [`wallet.stagingFund()`](/sdk-reference/wallets/typescript/classes/Wallet#stagingfund) | Funds the wallet with Crossmint's stablecoin (USDXM).  **Note:** This method is only available in staging environments and exclusively supports USDXM tokens. It cannot be used in production environments. |
| [`wallet.transaction()`](/sdk-reference/wallets/typescript/classes/Wallet#transaction) | Get a transaction by id |
| [`wallet.transactions()`](/sdk-reference/wallets/typescript/classes/Wallet#transactions) | Get the wallet transactions |
| [`wallet.transfers()`](/sdk-reference/wallets/typescript/classes/Wallet#transfers) | Get the wallet transfers |
| [`wallet.useRecoveryMethod()`](/sdk-reference/wallets/typescript/classes/Wallet#userecoverymethod) | Select which of the wallet's recovery methods authorizes admin operations (addSigner, removeSigner, addRecoveryMethod, removeRecoveryMethod). Unlike useSigner, this does not change the active signer used for transactions and signatures.  The config must refer to one of recoveryMethods; pass the fuller form when the method needs it to operate (an `onSign` callback for external wallets, the `secret` for server signers). |
| [`wallet.useSigner()`](/sdk-reference/wallets/typescript/classes/Wallet#usesigner) | Set the active signer for this wallet. Accepts a signer config object. The locator is inferred internally. Works for both registered signers and the recovery signer.  For passkey signers: if no `id` is provided, the wallet will auto-select the passkey if exactly one passkey signer is registered. If multiple passkeys exist, an `id` must be specified.  For device signers: if no device key is found locally, the signer will be created automatically during the next transaction (via recovery).  For external-wallet signers: the config object must include an onSign callback (applies to both registered and recovery signers). |
| [`wallet.waitForInit()`](/sdk-reference/wallets/typescript/classes/Wallet#waitforinit) | Wait for the wallet's internal signer initialization to complete. After this resolves, `needsRecovery()` reflects the true state. |

**Chain-specific:**

* [`EVMWallet`](/sdk-reference/wallets/typescript/classes/EVMWallet) — `getViemClient()`, `sendTransaction()`, `signMessage()`, `signTypedData()`
* [`SolanaWallet`](/sdk-reference/wallets/typescript/classes/SolanaWallet) — `sendTransaction()`
* [`StellarWallet`](/sdk-reference/wallets/typescript/classes/StellarWallet) — `migrate()`, `sendTransaction()`, `upgrade()`


# Providers
Source: https://docs.crossmint.com/sdk-reference/wallets/react-native/providers

React Native context providers for React Native SDK reference for Crossmint wallets

1. `CrossmintProvider` — SDK initialization (required for all Crossmint features)
2. `CrossmintWalletProvider` — Wallet creation and management

## CrossmintProvider

Root provider for the Crossmint SDK. Must wrap your entire application. Initializes the SDK with your API key and sets up logging.

### Props

<ResponseField name="apiKey" type="string">
  Your Crossmint client-side API key.
</ResponseField>

<ResponseField name="appId" type="string">
  Application identifier, sent as `x-app-identifier` header.
</ResponseField>

<ResponseField name="consoleLogLevel" type="ConsoleLogLevel">
  Minimum log level for console output (or "silent" to suppress all output). Logs below this level will not be written to the console. Set to "silent" to completely suppress console output. Defaults to "debug" (all logs shown) for backward compatibility.
</ResponseField>

<ResponseField name="overrideBaseUrl" type="string">
  Override the base API URL.
</ResponseField>

### Usage

```tsx theme={null}
import { CrossmintProvider } from "@crossmint/client-sdk-react-native-ui";

function App() {
    return (
        <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
            {/* Your app content */}
        </CrossmintProvider>
    );
}
```

***

## CrossmintWalletProvider

Provider for wallet creation and management. Must be nested inside CrossmintProvider. Handles secure communication with the Crossmint signer via a hidden WebView.

### Props

<ResponseField name="appearance" type="UIConfig">
  Optional appearance configuration for styling built-in UI components.

  <Expandable title="properties">
    <ResponseField name="borderRadius" type="string" />

    <ResponseField name="colors" type="UiConfigColors">
      <Expandable title="properties">
        <ResponseField name="accent" type="string" />

        <ResponseField name="background" type="string" />

        <ResponseField name="backgroundSecondary" type="string" />

        <ResponseField name="backgroundTertiary" type="string" />

        <ResponseField name="border" type="string" />

        <ResponseField name="buttonBackground" type="string" />

        <ResponseField name="danger" type="string" />

        <ResponseField name="inputBackground" type="string" />

        <ResponseField name="textLink" type="string" />

        <ResponseField name="textPrimary" type="string" />

        <ResponseField name="textSecondary" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="fonts" type="UiConfigFonts">
      <Expandable title="properties">
        <ResponseField name="cssSrc" type="string" />

        <ResponseField name="family" type="string" />

        <ResponseField name="display" type="string" />

        <ResponseField name="src" type="string" />

        <ResponseField name="style" type="&#x22;normal&#x22; | &#x22;italic&#x22; | &#x22;oblique&#x22;" />

        <ResponseField name="weight" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="fontSizeBase" type="string" />

    <ResponseField name="fontWeightPrimary" type="string" />

    <ResponseField name="fontWeightSecondary" type="string" />

    <ResponseField name="hideCardForm" type="boolean" />

    <ResponseField name="spacingUnit" type="string" />
  </Expandable>
</ResponseField>

<ResponseField name="callbacks" type="{ onTransactionStart?: () => Promise<void>; onWalletCreationStart?: () => Promise<void> }">
  Optional lifecycle callbacks invoked during wallet creation and transaction signing.

  <Expandable title="properties">
    <ResponseField name="onTransactionStart" type="() => Promise<void>">
      Called when a transaction signing flow begins.
    </ResponseField>

    <ResponseField name="onWalletCreationStart" type="() => Promise<void>">
      Called when a wallet creation flow begins.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="createOnLogin" type="CreateOnLogin">
  Wallet configuration for automatic creation on user login. Defines the chain and signer type for the wallet.

  <Expandable title="properties">
    <ResponseField name="chain" type="Chain">
      The blockchain to create the wallet on (e.g. "base-sepolia").
    </ResponseField>

    <ResponseField name="recovery" type="SignerConfigForChain">
      A single recovery method configuration (e.g. `{ type: "email" }`). Used for wallet recovery and adding new signers.
    </ResponseField>

    <ResponseField name="recoveryMethods" type="SignerConfigForChain[]">
      Recovery methods, each able to authorize on its own. Only Solana and Stellar accept more than one.
    </ResponseField>

    <ResponseField name="signers" type="SignerConfigForChain[]">
      Optional array of operational signers. Defaults to a device signer if omitted (e.g. `[{ type: "device" }]`).
    </ResponseField>

    <ResponseField name="alias" type="string">
      Optional wallet alias.
    </ResponseField>

    <ResponseField name="plugins" type="WalletPlugin[]">
      Optional array of wallet plugins.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="deviceSignerKeyStorage" type="DeviceSignerKeyStorage">
  Storage implementation for device signer keys. Defaults to `NativeDeviceSignerKeyStorage` (Secure Enclave on iOS, Android Keystore on Android). Override for testing or custom storage.
</ResponseField>

<ResponseField name="showOtpSignerPrompt" type="boolean">
  When true (default), built-in OTP signer UI prompts are shown during signing flows. When false, signing flows must be handled manually via the useWalletOtpSigner hook.
</ResponseField>

### Usage

```tsx theme={null}
import {
    CrossmintProvider,
    CrossmintWalletProvider,
} from "@crossmint/client-sdk-react-native-ui";

function App() {
    return (
        <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
            <CrossmintWalletProvider
                createOnLogin={{
                    chain: "base-sepolia",
                    recovery: { type: "email" },
                }}
            >
                {/* Your app content */}
            </CrossmintWalletProvider>
        </CrossmintProvider>
    );
}
```

> **Note:** CrossmintWalletProvider must be nested inside CrossmintProvider. showOtpSignerPrompt defaults to true in React Native, showing built-in OTP dialogs automatically. Set to false to handle signing flows manually via the useWalletOtpSigner hook.


# Components
Source: https://docs.crossmint.com/sdk-reference/wallets/react/components

React components for React SDK reference for Crossmint wallets

## ExportPrivateKeyButton

### Props

<ResponseField name="appearance" type="UIConfig">
  Optional appearance configuration for styling the export button.

  <Expandable title="properties">
    <ResponseField name="borderRadius" type="string" />

    <ResponseField name="colors" type="UiConfigColors">
      <Expandable title="properties">
        <ResponseField name="accent" type="string" />

        <ResponseField name="background" type="string" />

        <ResponseField name="backgroundSecondary" type="string" />

        <ResponseField name="backgroundTertiary" type="string" />

        <ResponseField name="border" type="string" />

        <ResponseField name="buttonBackground" type="string" />

        <ResponseField name="danger" type="string" />

        <ResponseField name="inputBackground" type="string" />

        <ResponseField name="textLink" type="string" />

        <ResponseField name="textPrimary" type="string" />

        <ResponseField name="textSecondary" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="fonts" type="UiConfigFonts">
      <Expandable title="properties">
        <ResponseField name="cssSrc" type="string" />

        <ResponseField name="family" type="string" />

        <ResponseField name="display" type="string" />

        <ResponseField name="src" type="string" />

        <ResponseField name="style" type="&#x22;normal&#x22; | &#x22;italic&#x22; | &#x22;oblique&#x22;" />

        <ResponseField name="weight" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="fontSizeBase" type="string" />

    <ResponseField name="fontWeightPrimary" type="string" />

    <ResponseField name="fontWeightSecondary" type="string" />

    <ResponseField name="hideCardForm" type="boolean" />

    <ResponseField name="spacingUnit" type="string" />
  </Expandable>
</ResponseField>

<ResponseField name="onExport" type="() => void | Promise<void>">
  Optional callback invoked after the user successfully exports (copies) their private key.
</ResponseField>

### Usage

```tsx theme={null}
import { ExportPrivateKeyButton } from "@crossmint/client-sdk-react-ui";

function WalletSettings() {
    return (
        <div>
            <h3>Export Private Key</h3>
            <ExportPrivateKeyButton
                appearance={{
                    colors: { border: "#e2e8f0" },
                    borderRadius: "12px",
                }}
            />
        </div>
    );
}
```

> **Note:** Only works with email and phone signers. Will not render for passkey or external wallet signers.


# Get Started
Source: https://docs.crossmint.com/sdk-reference/wallets/react/get-started

Installation and setup for the React SDK reference for Crossmint wallets

### Latest React SDK version - <a href="https://www.npmjs.com/package/@crossmint/client-sdk-react-ui"><img alt="npm" /></a>

The Crossmint React SDK (`@crossmint/client-sdk-react-ui`) provides React components and hooks for integrating Crossmint wallets into your application.

## Installation

<Snippet />

## Provider Setup

Wrap your application with the required providers:

```tsx theme={null}
import {
    CrossmintProvider,
    CrossmintWalletProvider,
} from "@crossmint/client-sdk-react-ui";

function App() {
    return (
        <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
            <CrossmintWalletProvider
                createOnLogin={{
                    chain: "base-sepolia",
                    recovery: { type: "email" },
                }}
            >
                {/* Your app components */}
            </CrossmintWalletProvider>
        </CrossmintProvider>
    );
}
```

## Quick Example

Once providers are set up, use hooks to access wallet state:

```tsx theme={null}
import { useWallet } from "@crossmint/client-sdk-react-ui";

function WalletInfo() {
    const { wallet, status } = useWallet();

    if (status === "in-progress") return <p>Loading wallet...</p>;
    if (!wallet) return <p>No wallet connected</p>;

    return (
        <div>
            <p>Address: {wallet.address}</p>
            <p>Chain: {wallet.chain}</p>
        </div>
    );
}
```

## Next Steps

* [Providers](/sdk-reference/wallets/react/providers) — Configure providers and their options
* [Hooks](/sdk-reference/wallets/react/hooks) — Access SDK state via React hooks
* [Components](/sdk-reference/wallets/react/components) — Drop-in UI components
* [Wallets SDK Reference](/sdk-reference/wallets/typescript/classes/Wallet) — Complete wallet method documentation


# Hooks
Source: https://docs.crossmint.com/sdk-reference/wallets/react/hooks

React hooks for React SDK reference for Crossmint wallets

## useWallet()

### Returns

<ResponseField name="createDeviceSigner" type="(address: string) => Promise<DeviceSignerConfig> | undefined">
  Creates a Device Signer
</ResponseField>

<ResponseField name="createPasskeySigner" type="(passkeyName: string) => Promise<RegisterSignerPasskeyParams>">
  Creates a Passkey Signer
</ResponseField>

<ResponseField name="createWallet" type="(props: ClientSideWalletCreateArgs<C>) => Promise<Wallet | undefined>">
  Creates a new wallet.

  <Expandable title="parameters">
    <ResponseField name="chain" type="Chain">
      The blockchain to create the wallet on (e.g. "base-sepolia").
    </ResponseField>

    <ResponseField name="recovery" type="SignerConfigForChain">
      A single recovery method configuration (e.g. `{ type: "email" }`). Used for wallet recovery and adding new signers.
    </ResponseField>

    <ResponseField name="recoveryMethods" type="SignerConfigForChain[]">
      Recovery methods, each able to authorize on its own. Only Solana and Stellar accept more than one.
    </ResponseField>

    <ResponseField name="signers" type="SignerConfigForChain[]">
      Optional array of operational signers. Defaults to a device signer if omitted (e.g. `[{ type: "device" }]`).
    </ResponseField>

    <ResponseField name="alias" type="string">
      Optional wallet alias.
    </ResponseField>

    <ResponseField name="plugins" type="WalletPlugin[]">
      Optional array of wallet plugins.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="error" type="WalletContextError | null">
  Detail about the last failure, or null when there is no error.
</ResponseField>

<ResponseField name="getWallet" type="(props: Pick<ClientSideWalletArgsFor<C>, &#x22;chain&#x22; | &#x22;alias&#x22;>) => Promise<Wallet | undefined>">
  Retrieves an existing wallet.

  <Expandable title="parameters">
    <ResponseField name="chain" type="Chain">
      The blockchain of the wallet to retrieve (e.g. "base-sepolia").
    </ResponseField>

    <ResponseField name="alias" type="string">
      Optional wallet alias to look up.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="status" type="&#x22;not-loaded&#x22; | &#x22;in-progress&#x22; | &#x22;loaded&#x22; | &#x22;error&#x22;">
  Current wallet status.
</ResponseField>

<ResponseField name="wallet" type="Wallet<Chain> | undefined">
  The current wallet instance, or undefined if no wallet is loaded.

  <Expandable title="parameters">
    <ResponseField name="constructor" type="unknown" />

    <ResponseField name="address" type="string" />

    <ResponseField name="alias" type="string" />

    <ResponseField name="chain" type="C" />

    <ResponseField name="owner" type="string" />

    <ResponseField name="apiClient" type="unknown" />

    <ResponseField name="recovery" type="unknown" />

    <ResponseField name="recoveryMethods" type="unknown" />

    <ResponseField name="signer" type="unknown" />

    <ResponseField name="addRecoveryMethod" type="unknown" />

    <ResponseField name="addSigner" type="unknown" />

    <ResponseField name="approve" type="unknown" />

    <ResponseField name="approveTransaction" type="unknown" />

    <ResponseField name="balances" type="unknown" />

    <ResponseField name="isSignerApproved" type="unknown" />

    <ResponseField name="needsRecovery" type="unknown" />

    <ResponseField name="nfts" type="unknown" />

    <ResponseField name="recover" type="unknown" />

    <ResponseField name="removeRecoveryMethod" type="unknown" />

    <ResponseField name="removeSigner" type="unknown" />

    <ResponseField name="send" type="unknown" />

    <ResponseField name="signerIsRegistered" type="unknown" />

    <ResponseField name="signers" type="unknown" />

    <ResponseField name="stagingFund" type="unknown" />

    <ResponseField name="transaction" type="unknown" />

    <ResponseField name="transactions" type="unknown" />

    <ResponseField name="transfers" type="unknown" />

    <ResponseField name="useRecoveryMethod" type="unknown" />

    <ResponseField name="useSigner" type="unknown" />

    <ResponseField name="waitForInit" type="unknown" />
  </Expandable>
</ResponseField>

### Usage

```tsx theme={null}
import { useWallet } from "@crossmint/client-sdk-react-ui";

function WalletActions() {
    const { wallet, status } = useWallet();

    if (status === "in-progress") return <p>Loading wallet...</p>;
    if (!wallet) return <p>No wallet</p>;

    const handleSend = async () => {
        const tx = await wallet.send("0x...", "usdc", "10");
        console.log("Transaction:", tx.explorerLink);
    };

    const handleBalances = async () => {
        const balances = await wallet.balances();
        console.log("USDC:", balances.usdc.amount);
        console.log("Native:", balances.nativeToken.amount);
    };

    return (
        <div>
            <p>Wallet: {wallet.address}</p>
            <button onClick={handleBalances}>Check Balances</button>
            <button onClick={handleSend}>Send USDC</button>
        </div>
    );
}
```

***

## Wallet Methods

The `wallet` instance returned by `useWallet()` provides methods for token transfers, balances, signing, and more.

Since the React SDK wraps the Wallets SDK, see the **[Wallets SDK Reference](/sdk-reference/wallets/typescript/classes/Wallet)** for complete documentation.

| Method | Description |
| - | - |
| [`wallet.addRecoveryMethod()`](/sdk-reference/wallets/typescript/classes/Wallet#addrecoverymethod) | Add a recovery method to the wallet. Supported on Solana and Stellar only. Always uses one of the existing recovery methods to approve the change, selected as in addSigner. |
| [`wallet.addSigner()`](/sdk-reference/wallets/typescript/classes/Wallet#addsigner) | Add a signer to the wallet. Always uses a recovery method internally to approve the registration: the one selected via useRecoveryMethod, else the active signer when it is one of the recovery methods, else the wallet's single recovery method. Wallets with several recovery methods must select one first; an operational signer cannot authorize this. If the signer being added is the current operational signer, it will be reassembled with the new locator. Otherwise, the original signer is restored after the operation. |
| [`wallet.balances()`](/sdk-reference/wallets/typescript/classes/Wallet#balances) | Get the wallet balances - always includes USDC and native token (ETH/SOL) |
| [`wallet.isSignerApproved()`](/sdk-reference/wallets/typescript/classes/Wallet#issignerapproved) | Check if a signer is approved and usable for the current wallet chain. |
| [`wallet.needsRecovery()`](/sdk-reference/wallets/typescript/classes/Wallet#needsrecovery) | Whether the wallet needs recovery (signer registration) before the next transaction. |
| [`wallet.nfts()`](/sdk-reference/wallets/typescript/classes/Wallet#nfts) | Get the wallet NFTs |
| [`wallet.recover()`](/sdk-reference/wallets/typescript/classes/Wallet#recover) | Register a device signer with the wallet using the recovery signer. Generates a new device key and registers it on-chain. Returns early if the device signer's locator is already approved on-chain. |
| [`wallet.removeRecoveryMethod()`](/sdk-reference/wallets/typescript/classes/Wallet#removerecoverymethod) | Remove a recovery method from the wallet. Supported on Solana and Stellar only. Always uses one of the remaining recovery methods to approve the change, selected as in addSigner. |
| [`wallet.removeSigner()`](/sdk-reference/wallets/typescript/classes/Wallet#removesigner) | Remove a signer from the wallet. Always uses a recovery method internally to approve the removal, selected as in addSigner. |
| [`wallet.send()`](/sdk-reference/wallets/typescript/classes/Wallet#send) | Send a token to a wallet or user locator |
| [`wallet.signerIsRegistered()`](/sdk-reference/wallets/typescript/classes/Wallet#signerisregistered) | Check if a signer is registered in this wallet. |
| [`wallet.signers()`](/sdk-reference/wallets/typescript/classes/Wallet#signers) | List the signers for this wallet. Returns full signer objects with status. For EVM wallets, only signers with an approval (pending or completed) for the wallet's chain are included. |
| [`wallet.stagingFund()`](/sdk-reference/wallets/typescript/classes/Wallet#stagingfund) | Funds the wallet with Crossmint's stablecoin (USDXM).  **Note:** This method is only available in staging environments and exclusively supports USDXM tokens. It cannot be used in production environments. |
| [`wallet.transaction()`](/sdk-reference/wallets/typescript/classes/Wallet#transaction) | Get a transaction by id |
| [`wallet.transactions()`](/sdk-reference/wallets/typescript/classes/Wallet#transactions) | Get the wallet transactions |
| [`wallet.transfers()`](/sdk-reference/wallets/typescript/classes/Wallet#transfers) | Get the wallet transfers |
| [`wallet.useRecoveryMethod()`](/sdk-reference/wallets/typescript/classes/Wallet#userecoverymethod) | Select which of the wallet's recovery methods authorizes admin operations (addSigner, removeSigner, addRecoveryMethod, removeRecoveryMethod). Unlike useSigner, this does not change the active signer used for transactions and signatures.  The config must refer to one of recoveryMethods; pass the fuller form when the method needs it to operate (an `onSign` callback for external wallets, the `secret` for server signers). |
| [`wallet.useSigner()`](/sdk-reference/wallets/typescript/classes/Wallet#usesigner) | Set the active signer for this wallet. Accepts a signer config object. The locator is inferred internally. Works for both registered signers and the recovery signer.  For passkey signers: if no `id` is provided, the wallet will auto-select the passkey if exactly one passkey signer is registered. If multiple passkeys exist, an `id` must be specified.  For device signers: if no device key is found locally, the signer will be created automatically during the next transaction (via recovery).  For external-wallet signers: the config object must include an onSign callback (applies to both registered and recovery signers). |
| [`wallet.waitForInit()`](/sdk-reference/wallets/typescript/classes/Wallet#waitforinit) | Wait for the wallet's internal signer initialization to complete. After this resolves, `needsRecovery()` reflects the true state. |

**Chain-specific:**

* [`EVMWallet`](/sdk-reference/wallets/typescript/classes/EVMWallet) — `getViemClient()`, `sendTransaction()`, `signMessage()`, `signTypedData()`
* [`SolanaWallet`](/sdk-reference/wallets/typescript/classes/SolanaWallet) — `sendTransaction()`
* [`StellarWallet`](/sdk-reference/wallets/typescript/classes/StellarWallet) — `migrate()`, `sendTransaction()`, `upgrade()`


# Providers
Source: https://docs.crossmint.com/sdk-reference/wallets/react/providers

React context providers for React SDK reference for Crossmint wallets

1. `CrossmintProvider` — SDK initialization (required for all Crossmint features)
2. `CrossmintWalletProvider` — Wallet creation and management

## CrossmintProvider

### Props

<ResponseField name="apiKey" type="string">
  Your Crossmint client-side API key.
</ResponseField>

<ResponseField name="appId" type="string">
  Application identifier, sent as `x-app-identifier` header.
</ResponseField>

<ResponseField name="consoleLogLevel" type="ConsoleLogLevel">
  Minimum log level for console output (or "silent" to suppress all output). Logs below this level will not be written to the console. Set to "silent" to completely suppress console output. Defaults to "debug" (all logs shown) for backward compatibility.
</ResponseField>

<ResponseField name="extensionId" type="string">
  Extension identifier, sent as `x-extension-id` header.
</ResponseField>

<ResponseField name="jwt" type="string">
  JWT token for authentication.
</ResponseField>

<ResponseField name="overrideBaseUrl" type="string">
  Override the base API URL.
</ResponseField>

### Usage

```tsx theme={null}
import { CrossmintProvider } from "@crossmint/client-sdk-react-ui";

function App() {
    return (
        <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
            {/* Your app content */}
        </CrossmintProvider>
    );
}
```

***

## CrossmintWalletProvider

### Props

<ResponseField name="appearance" type="UIConfig">
  Appearance configuration for wallet UI components.

  <Expandable title="properties">
    <ResponseField name="borderRadius" type="string" />

    <ResponseField name="colors" type="UiConfigColors">
      <Expandable title="properties">
        <ResponseField name="accent" type="string" />

        <ResponseField name="background" type="string" />

        <ResponseField name="backgroundSecondary" type="string" />

        <ResponseField name="backgroundTertiary" type="string" />

        <ResponseField name="border" type="string" />

        <ResponseField name="buttonBackground" type="string" />

        <ResponseField name="danger" type="string" />

        <ResponseField name="inputBackground" type="string" />

        <ResponseField name="textLink" type="string" />

        <ResponseField name="textPrimary" type="string" />

        <ResponseField name="textSecondary" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="fonts" type="UiConfigFonts">
      <Expandable title="properties">
        <ResponseField name="cssSrc" type="string" />

        <ResponseField name="family" type="string" />

        <ResponseField name="display" type="string" />

        <ResponseField name="src" type="string" />

        <ResponseField name="style" type="&#x22;normal&#x22; | &#x22;italic&#x22; | &#x22;oblique&#x22;" />

        <ResponseField name="weight" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="fontSizeBase" type="string" />

    <ResponseField name="fontWeightPrimary" type="string" />

    <ResponseField name="fontWeightSecondary" type="string" />

    <ResponseField name="hideCardForm" type="boolean" />

    <ResponseField name="spacingUnit" type="string" />
  </Expandable>
</ResponseField>

<ResponseField name="callbacks" type="{ onTransactionStart?: () => Promise<void>; onWalletCreationStart?: () => Promise<void> }">
  Lifecycle callbacks for wallet creation and transaction events.

  <Expandable title="properties">
    <ResponseField name="onTransactionStart" type="() => Promise<void>" />

    <ResponseField name="onWalletCreationStart" type="() => Promise<void>" />
  </Expandable>
</ResponseField>

<ResponseField name="createOnLogin" type="CreateOnLogin">
  Configuration for automatic wallet creation on login.

  <Expandable title="properties">
    <ResponseField name="chain" type="Chain">
      The blockchain to create the wallet on (e.g. "base-sepolia").
    </ResponseField>

    <ResponseField name="recovery" type="SignerConfigForChain">
      A single recovery method configuration (e.g. `{ type: "email" }`). Used for wallet recovery and adding new signers.
    </ResponseField>

    <ResponseField name="recoveryMethods" type="SignerConfigForChain[]">
      Recovery methods, each able to authorize on its own. Only Solana and Stellar accept more than one.
    </ResponseField>

    <ResponseField name="signers" type="SignerConfigForChain[]">
      Optional array of operational signers. Defaults to a device signer if omitted (e.g. `[{ type: "device" }]`).
    </ResponseField>

    <ResponseField name="alias" type="string">
      Optional wallet alias.
    </ResponseField>

    <ResponseField name="plugins" type="WalletPlugin[]">
      Optional array of wallet plugins.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="showOtpSignerPrompt" type="boolean">
  When true (default), built-in OTP signer UI prompts are shown during signing flows. When false, signing flows must be handled manually via the useWalletOtpSigner hook. Default: true.
</ResponseField>

<ResponseField name="showPasskeyHelpers" type="boolean">
  Whether to show passkey helper UI. Default: true.
</ResponseField>

### Usage

```tsx theme={null}
import {
    CrossmintProvider,
    CrossmintWalletProvider,
} from "@crossmint/client-sdk-react-ui";

function App() {
    return (
        <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
            <CrossmintWalletProvider
                createOnLogin={{
                    chain: "base-sepolia",
                    recovery: { type: "email" },
                }}
            >
                {/* Your app content */}
            </CrossmintWalletProvider>
        </CrossmintProvider>
    );
}
```

> **Note:** CrossmintWalletProvider must be nested inside CrossmintProvider.


# ABI
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/classes/abi

Swift Class

**Class**

```swift theme={null}
class ABI
```

## Enumerations

### ABI.Argument

```swift theme={null}
enum Argument
```

### ABI.Error

```swift theme={null}
enum Error
```


# ApiKeySigner
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/classes/apikeysigner

Swift Class

**Class**

```swift theme={null}
class ApiKeySigner
```

## Initializers

### init(adminSigner:)

```swift theme={null}
init(adminSigner: ApiKeySignerData)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `adminSigner` | `ApiKeySignerData` | Inherited from `Signer.adminSigner`. |
| `signerType` | `SignerType` | Inherited from `Signer.signerType`. |

## Instance Methods

### approvals(withSignature:)

Inherited from `Signer.approvals(withSignature:)`.

```swift theme={null}
func approvals(withSignature signature: String) async throws(SignerError) -> [SignRequestApi.Approval]
```

### initialize(\_:)

Inherited from `ApprovalSigner.initialize(_:)`.

```swift theme={null}
func initialize(_ service: (any SmartWalletService)?) async throws(SignerError)
```

### sign(message:)

Inherited from `Signer.sign(message:)`.

```swift theme={null}
func sign(message: String) async throws(SignerError) -> String
```

## Type Aliases

### ApiKeySigner.AdminType

Inherited from `Signer.AdminType`.

```swift theme={null}
typealias AdminType = ApiKeySignerData
```


# CrossmintAuthManager
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/classes/crossmintauthmanager

Swift Class

**Class**

Built-in `AuthManager` that authenticates users via email OTP.

```swift theme={null}
actor CrossmintAuthManager
```

## OTP flow

```swift theme={null}
let auth = CrossmintSDK.shared.authManager

try await auth.sendEmailOtp(email: "user@example.com")
// ... user enters the code from their inbox ...
let status = try await auth.confirmEmailOtp(email: "user@example.com", code: userInput)
if status.isAuthenticated {
    print("Signed in as", status.email ?? "")
}
```

The JWT is refreshed automatically before expiry; no app-level polling is required.

## Initializers

### init(apiKey:)

```swift theme={null}
convenience init(apiKey apiKeyString: String) throws
```

### init(authService:secureStorage:)

```swift theme={null}
init(authService: any AuthService, secureStorage: any SecureStorage)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `authenticationStatus` | `AuthenticationStatus` | - |
| `email` | `String?` | - |
| `jwt` | `String?` | Inherited from `AuthManager.jwt`. |

## Instance Methods

### confirmEmailOtp(email:code:)

Validates the OTP code and, on success, establishes an authenticated session.

```swift theme={null}
func confirmEmailOtp(email: String, code: String) async throws(AuthManagerError) -> OTPAuthenticationStatus
```

#### Discussion

Must be called after `sendEmailOtp(email:)` with the same email address. Throws `AuthManagerError.noPendingOTP` if no email has been sent yet.

### logout()

Invalidates the server-side refresh token and clears the local session.

```swift theme={null}
func logout() async throws(AuthManagerError) -> OTPAuthenticationStatus
```

#### Discussion

Has no effect if the user is not currently authenticated.

### oneTimeSecretAuthentication(oneTimeSecret:)

```swift theme={null}
func oneTimeSecretAuthentication(oneTimeSecret: String) async throws(AuthManagerError) -> OTPAuthenticationStatus
```

### reset()

Clears the local session state without contacting the server.

```swift theme={null}
func reset() async -> OTPAuthenticationStatus
```

#### Discussion

Use this when the server session is already gone (e.g. the refresh token expired or was revoked externally) and you just need to reset local state. Prefer `logout()` when the session is still valid and you want to revoke the server-side token as well.

### sendEmailOtp(email:)

Sends a one-time password to the given email address. Call `confirmEmailOtp(email:code:)` next.

```swift theme={null}
func sendEmailOtp(email: String) async throws(AuthManagerError)
```

### setJWT(\_:)

Inherited from `AuthManager.setJWT(_:)`.

```swift theme={null}
func setJWT(_ jwt: String) async
```


# CrossmintSDK
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/classes/crossmintsdk

Swift Class

**Class**

Entry point for the Crossmint SDK.

```swift theme={null}
@MainActor final class CrossmintSDK
```

## Overview

Call `configure(apiKey:logLevel:)` once at app startup before accessing `shared`. Accessing `shared` before configuring causes a `fatalError`.
When using an email or phone OTP signer, observe `isOTPRequired` to know when to display an OTP input, then call `submit(otp:)` with the code the user enters.

## Example

```swift theme={null}
@main
struct MyApp: App {
    init() {
        CrossmintSDK.configure(apiKey: "ck_development_...", logLevel: .warn)
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
                .environmentObject(CrossmintSDK.shared)
        }
    }
}
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `authClient` | `AuthClient` | Standalone auth client for explicit OTP lifecycle management. See `AuthClient`. |
| `authManager` | `CrossmintAuthManager` | Authentication manager for the email OTP flow. See `CrossmintAuthManager`. |
| `crossmintService` | `CrossmintService` | Low-level Crossmint service for direct API access. |
| `crossmintWallets` | `CrossmintWallets` | Factory for creating and retrieving smart wallets. See `CrossmintWallets`. |
| `isOTPRequired` | `Published<Bool>.Publisher` | Emits `true` when a pending transaction is waiting for the user to enter an email or phone OTP. |
| `isProductionEnvironment` | `Bool` | Whether the SDK is running against the Crossmint production environment. |

## Instance Methods

### cancelTransaction()

Cancels the pending transaction waiting for an OTP.

```swift theme={null}
@MainActor func cancelTransaction()
```

### logout()

Invalidates the server-side refresh token, clears the local session, and resets OTP state.

```swift theme={null}
@MainActor func logout() async
```

### setJWT(\_:)

Sets a JWT for authentication. Use this when authenticating with an externally obtained token rather than through the built-in OTP flow.

```swift theme={null}
@MainActor func setJWT(_ jwt: String) async
```

#### Discussion

> **Note**: Unlike the TypeScript SDK’s synchronous `setJwt`, this is `async` because it updates actor-isolated state on `CrossmintAuthManager`.

### submit(otp:)

Provides the OTP entered by the user to unblock the pending transaction.

```swift theme={null}
@MainActor func submit(otp: String)
```

## Type Properties

| Property | Type | Description |
| - | - | - |
| `shared` | `CrossmintSDK` | The configured SDK instance. Access after calling `configure(apiKey:logLevel:)`. |

## Type Methods

### configure(apiKey:logLevel:)

Configures the SDK. Must be called once before accessing `shared`.

```swift theme={null}
@MainActor static func configure(apiKey: String, logLevel: LogLevel = .error)
```

#### Discussion

Subsequent calls are silently ignored — the SDK can only be configured once per process.

#### Parameters

| Parameter | Description |
| - | - |
| `apiKey` | A client API key (prefixed `ck_`). |
| `logLevel` | Controls SDK log verbosity. Defaults to `.error`. |


# DefaultAuthClient
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/classes/defaultauthclient

Swift Class

**Class**

Built-in `AuthClient` implementation that routes through `CrossmintAuthManager`.

```swift theme={null}
actor DefaultAuthClient
```

## Overview

Obtain via `CrossmintSDK/authClient` — do not instantiate directly.

## Instance Methods

### logout()

Inherited from `AuthClient.logout()`.

```swift theme={null}
func logout() async
```

### sendOTP(to:)

Inherited from `AuthClient.sendOTP(to:)`.

```swift theme={null}
func sendOTP(to email: String) async throws(AuthError) -> OTPRequest
```

### verifyOTP(code:requestId:)

Inherited from `AuthClient.verifyOTP(code:requestId:)`.

```swift theme={null}
func verifyOTP(code: String, requestId: String) async throws(AuthError) -> AuthSession
```


# DefaultAuthService
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/classes/defaultauthservice

Swift Class

**Class**

```swift theme={null}
final class DefaultAuthService
```

## Initializers

### init(crossmintService:jsonCoder:)

```swift theme={null}
init(crossmintService: any CrossmintService, jsonCoder: any JSONCoder = DefaultJSONCoder())
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `jsonCoder` | `any JSONCoder` | - |

## Instance Methods

### logout(\_:)

Inherited from `AuthService.logout(_:)`.

```swift theme={null}
func logout(_ logoutRequest: LogoutRequest) async throws(AuthError)
```

### refreshJWT(\_:)

Inherited from `AuthService.refreshJWT(_:)`.

```swift theme={null}
func refreshJWT(_ refreshJWTRequest: RefreshJWTRequest) async throws(AuthError) -> RefreshJWTResponse
```

### validateEmail(\_:)

Inherited from `AuthService.validateEmail(_:)`.

```swift theme={null}
func validateEmail(_ validateEmailRequest: ValidateEmailRequest) async throws(AuthError) -> ValidateEmailResponse
```

### validateToken(\_:)

Inherited from `AuthService.validateToken(_:)`.

```swift theme={null}
func validateToken(_ validateTokenRequest: ValidateTokenRequest) async throws(AuthError) -> ValidateTokenResponse
```


# DefaultCrossmintWallets
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/classes/defaultcrossmintwallets

Swift Class

**Class**

```swift theme={null}
final class DefaultCrossmintWallets
```

## Initializers

### init(service:secureWalletStorage:deviceSignerKeyStorage:)

```swift theme={null}
init(service: any SmartWalletService, secureWalletStorage: any SecureWalletStorage, deviceSignerKeyStorage: any DeviceSignerKeyStorage)
```

## Instance Methods

### createWallet(chain:recovery:options:)

Inherited from `CrossmintWallets.createWallet(chain:recovery:options:)`.

```swift theme={null}
func createWallet(chain: Chain, recovery: any Signer, options: WalletOptions? = nil) async throws(WalletError) -> Wallet
```

### createWallet(chain:recoveryMethods:options:)

Inherited from `CrossmintWallets.createWallet(chain:recoveryMethods:options:)`.

```swift theme={null}
func createWallet(chain: Chain, recoveryMethods: [any Signer], options: WalletOptions? = nil) async throws(WalletError) -> Wallet
```

### createWallet(chain:recoveryMethods:signers:options:)

Inherited from `CrossmintWallets.createWallet(chain:recoveryMethods:signers:options:)`.

```swift theme={null}
func createWallet(chain: Chain, recoveryMethods: [any Signer], signers: [SignerConfig], options: WalletOptions? = nil) async throws(WalletError) -> Wallet
```

### getWallet(chain:options:)

Inherited from `CrossmintWallets.getWallet(chain:options:)`.

```swift theme={null}
func getWallet(chain: Chain, options: WalletOptions? = nil) async throws(WalletError) -> Wallet?
```

### getWallet(chain:recovery:options:)

Inherited from `CrossmintWallets.getWallet(chain:recovery:options:)`.

```swift theme={null}
func getWallet(chain: Chain, recovery: any Signer, options: WalletOptions? = nil) async throws(WalletError) -> Wallet?
```


# DefaultSmartWalletService
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/classes/defaultsmartwalletservice

Swift Class

**Class**

```swift theme={null}
final class DefaultSmartWalletService
```

## Initializers

### init(crossmintService:authManager:jsonCoder:)

```swift theme={null}
init(crossmintService: any CrossmintService, authManager: any AuthManager, jsonCoder: any JSONCoder = DefaultJSONCoder())
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `isProductionEnvironment` | `Bool` | Inherited from `WalletService.isProductionEnvironment`. |

## Instance Methods

### addRecoveryMethod(\_:chainType:approver:)

Inherited from `WalletService.addRecoveryMethod(_:chainType:approver:)`.

```swift theme={null}
func addRecoveryMethod(_ recoveryMethod: any AdminSignerData, chainType: ChainType, approver: SignerLocator) async throws(WalletError) -> any TransactionApiModel
```

### addSigner(\_:chainType:chainName:deployImmediately:)

Inherited from `WalletService.addSigner(_:chainType:chainName:deployImmediately:)`.

```swift theme={null}
func addSigner(_ entry: DelegatedSignerEntry, chainType: ChainType, chainName: String, deployImmediately: Bool?) async throws(WalletError) -> AddDelegatedSignerResponse
```

### addSigner(\_:chainType:chainName:deployImmediately:approver:)

Inherited from `WalletService.addSigner(_:chainType:chainName:deployImmediately:approver:)`.

```swift theme={null}
func addSigner(_ entry: DelegatedSignerEntry, chainType: ChainType, chainName: String, deployImmediately: Bool?, approver: SignerLocator?) async throws(WalletError) -> AddDelegatedSignerResponse
```

### approveSignature(\_:)

Inherited from `SignatureService.approveSignature(_:)`.

```swift theme={null}
func approveSignature(_ request: SignRequest) async throws(SignatureError)
```

### createSignature(\_:)

Inherited from `SignatureService.createSignature(_:)`.

```swift theme={null}
func createSignature(_ request: CreateSignatureRequest) async throws(SignatureError) -> any SignatureApiModel
```

### createTransaction(\_:)

Inherited from `TransactionService.createTransaction(_:)`.

```swift theme={null}
func createTransaction(_ request: CreateTransactionRequest) async throws(TransactionError) -> any TransactionApiModel
```

### createWallet(\_:)

Inherited from `WalletService.createWallet(_:)`.

```swift theme={null}
func createWallet(_ request: CreateWalletParams) async throws(WalletError) -> WalletApiModel
```

### fetchSignature(\_:chainType:)

Inherited from `SignatureService.fetchSignature(_:chainType:)`.

```swift theme={null}
func fetchSignature(_ signatureId: String, chainType: ChainType) async throws(SignatureError) -> any SignatureApiModel
```

### fetchTransaction(\_:)

Inherited from `TransactionService.fetchTransaction(_:)`.

```swift theme={null}
func fetchTransaction(_ request: FetchTransactionRequest) async throws(TransactionError) -> any TransactionApiModel
```

### fund(\_:)

Inherited from `WalletService.fund(_:)`.

```swift theme={null}
func fund(_ request: FundWalletRequest) async throws(WalletError)
```

### getBalance(\_:)

Inherited from `BalanceService.getBalance(_:)`.

```swift theme={null}
func getBalance(_ params: GetBalanceQueryParams) async throws(WalletError) -> Balances
```

### getNFTs(\_:)

Inherited from `NFTService.getNFTs(_:)`.

```swift theme={null}
func getNFTs(_ params: GetNTFQueryParams) async throws(WalletError) -> [NFT]
```

### getSigner(\_:chainType:)

Inherited from `WalletService.getSigner(_:chainType:)`.

```swift theme={null}
func getSigner(_ signerLocator: String, chainType: ChainType) async throws(WalletError) -> AddDelegatedSignerResponse?
```

### getWallet(\_:)

Inherited from `WalletService.getWallet(_:)`.

```swift theme={null}
func getWallet(_ request: GetMeWalletRequest) async throws(WalletError) -> WalletApiModel
```

### listTransactions(\_:)

Inherited from `TransactionService.listTransactions(_:)`.

```swift theme={null}
func listTransactions(_ request: ListTransactionsRequest) async throws(TransactionError) -> [Transaction]
```

### listTransfers(\_:)

Inherited from `TransferService.listTransfers(_:)`.

```swift theme={null}
func listTransfers(_ params: ListTransfersQueryParams) async throws(WalletError) -> TransferListResult
```

### registerTypedSigner(\_:chainType:chainName:deployImmediately:)

Inherited from `WalletService.registerTypedSigner(_:chainType:chainName:deployImmediately:)`.

```swift theme={null}
func registerTypedSigner(_ signer: any AdminSignerData, chainType: ChainType, chainName: String, deployImmediately: Bool?) async throws(WalletError) -> AddDelegatedSignerResponse
```

### registerTypedSigner(\_:chainType:chainName:deployImmediately:approver:)

Inherited from `WalletService.registerTypedSigner(_:chainType:chainName:deployImmediately:approver:)`.

```swift theme={null}
func registerTypedSigner(_ signer: any AdminSignerData, chainType: ChainType, chainName: String, deployImmediately: Bool?, approver: SignerLocator?) async throws(WalletError) -> AddDelegatedSignerResponse
```

### removeRecoveryMethod(\_:chainType:approver:)

Inherited from `WalletService.removeRecoveryMethod(_:chainType:approver:)`.

```swift theme={null}
func removeRecoveryMethod(_ locator: SignerLocator, chainType: ChainType, approver: SignerLocator) async throws(WalletError) -> any TransactionApiModel
```

### removeSigner(\_:chainType:chainName:)

Inherited from `WalletService.removeSigner(_:chainType:chainName:)`.

```swift theme={null}
func removeSigner(_ signerLocator: String, chainType: ChainType, chainName: String) async throws(TransactionError) -> any TransactionApiModel
```

### removeSigner(\_:chainType:chainName:approver:)

Inherited from `WalletService.removeSigner(_:chainType:chainName:approver:)`.

```swift theme={null}
func removeSigner(_ signerLocator: String, chainType: ChainType, chainName: String, approver: SignerLocator?) async throws(TransactionError) -> any TransactionApiModel
```

### signTransaction(\_:)

Inherited from `TransactionService.signTransaction(_:)`.

```swift theme={null}
func signTransaction(_ request: SignRequest) async throws(TransactionError) -> any TransactionApiModel
```

### transferToken(\_:)

Inherited from `TransferService.transferToken(_:)`.

```swift theme={null}
func transferToken(_ request: TransferTokenRequest) async throws(TransactionError) -> any TransactionApiModel
```


# EVMEmailSigner
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/classes/evmemailsigner

Swift Class

**Class**

```swift theme={null}
final class EVMEmailSigner
```

## Initializers

### init(email:crossmintTEE:)

```swift theme={null}
init(email: String, crossmintTEE: CrossmintTEE?)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `adminSigner` | `EmailSignerData` | Inherited from `Signer.adminSigner`. |
| `email` | `String` | - |
| `encoding` | `String` | - |
| `keyType` | `String` | - |
| `signerType` | `SignerType` | Inherited from `Signer.signerType`. |

## Type Aliases

### EVMEmailSigner.AdminType

Inherited from `Signer.AdminType`.

```swift theme={null}
typealias AdminType = EmailSignerData
```


# EVMKeyPairSigner
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/classes/evmkeypairsigner

Swift Class

**Class**

```swift theme={null}
final class EVMKeyPairSigner
```

## Initializers

### init(privateKey:)

```swift theme={null}
init(privateKey: String) throws(SignerError)
```

### init(privateKeyData:)

```swift theme={null}
init(privateKeyData: [UInt8]? = nil) throws(SignerError)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `adminSigner` | `ExternalWalletSignerData` | Inherited from `Signer.adminSigner`. |
| `evmAddress` | `EVMAddress` | - |
| `privateKey` | `String` | - |
| `publicKey` | `String` | - |
| `signerType` | `SignerType` | Inherited from `Signer.signerType`. |

## Instance Methods

### approvals(withSignature:)

Inherited from `Signer.approvals(withSignature:)`.

```swift theme={null}
func approvals(withSignature signature: String) async throws(SignerError) -> [SignRequestApi.Approval]
```

### initialize(\_:)

Inherited from `ApprovalSigner.initialize(_:)`.

```swift theme={null}
func initialize(_ service: (any SmartWalletService)?) async throws(SignerError)
```

### sign(message:)

Inherited from `Signer.sign(message:)`.

```swift theme={null}
func sign(message: String) async throws(SignerError) -> String
```

## Type Aliases

### EVMKeyPairSigner.AdminType

Inherited from `Signer.AdminType`.

```swift theme={null}
typealias AdminType = ExternalWalletSignerData
```


# EVMWallet
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/classes/evmwallet

Swift Class

**Class**

A Crossmint smart wallet on an EVM-compatible chain.

```swift theme={null}
class EVMWallet
```

## Overview

Obtain an instance via `getWallet(chain:options:)` or `createWallet(chain:recoveryMethods:options:)`.

## Instance Methods

### addSigner(\_:deployImmediately:)

Registers a new signer on this wallet, choosing how the registration gets approved.

```swift theme={null}
func addSigner(_ config: SignerConfig, deployImmediately: Bool) async throws(WalletError)
```

#### Discussion

> **Throws**: `WalletError` if registration fails.

#### Parameters

| Parameter | Description |
| - | - |
| `config` | The signer configuration to register. |
| `deployImmediately` | Whether the registration is approved through an on-chain transaction rather than the lazy signature-request flow. |

### sendTransaction(to:data:value:chain:)

```swift theme={null}
func sendTransaction(to address: EVMAddress, data: String?, value: BigInt?, chain: EVMChain) async throws(TransactionError) -> Transaction
```

### sendTransaction(to:value:data:chain:)

Sends a raw EVM transaction and polls until it is confirmed on-chain.

```swift theme={null}
func sendTransaction(to address: String, value: String?, data: String?, chain: EVMChain? = nil) async throws(TransactionError) -> TransactionSummary
```

#### Example

```swift theme={null}
// Transfer 0.001 ETH
let summary = try await evmWallet.sendTransaction(
    to: "0xRecipient...",
    value: "1000000000000000",
    data: nil
)
print("Confirmed:", summary.explorerLink)
```

#### Parameters

| Parameter | Description |
| - | - |
| `address` | Recipient contract or EOA address (checksummed or lowercase hex). |
| `value` | Native token value in wei as a decimal string, e.g. `"1000000000000000"`. Pass `nil` or `"0"` for contract calls that transfer no ETH. |
| `data` | ABI-encoded call data as a `0x`-prefixed hex string. Pass `nil` or `"0x"` for plain ETH transfers. |
| `chain` | Target chain. Defaults to the chain the wallet was opened on. |

### signMessage(\_:signer:isSmartWalletSignature:)

Signs an arbitrary message with this wallet.

```swift theme={null}
func signMessage(_ message: String, signer: (any AdminSignerData)? = nil, isSmartWalletSignature: Bool = true) async throws(SignatureError) -> String
```

#### Example

```swift theme={null}
let signature = try await evmWallet.signMessage("Hello, Crossmint!")
```

#### Parameters

| Parameter | Description |
| - | - |
| `message` | The plain-text message to sign. |
| `signer` | Override which signer produces the signature. Defaults to the wallet’s recovery signer. |
| `isSmartWalletSignature` | When `true` (default), produces an EIP-6492 smart-wallet-compatible signature. Set to `false` to produce a standard EOA signature instead. |

### signTypedData(\_:signer:isSmartWalletSignature:)

Signs EIP-712 typed structured data with this wallet.

```swift theme={null}
func signTypedData(_ typedData: EIP712.TypedData, signer: (any AdminSignerData)? = nil, isSmartWalletSignature: Bool = true) async throws(SignatureError) -> String
```

#### Parameters

| Parameter | Description |
| - | - |
| `typedData` | The structured data to sign, conforming to EIP-712. |
| `signer` | Override which signer produces the signature. Defaults to the wallet’s recovery signer. |
| `isSmartWalletSignature` | See `signMessage(_:signer:isSmartWalletSignature:)` for semantics. |

## Type Aliases

### EVMWallet.SpecificChain

Inherited from `WalletOnChain.SpecificChain`.

```swift theme={null}
typealias SpecificChain = EVMChain
```

## Type Methods

### from(wallet:)

Casts a generic `Wallet` to `EVMWallet`.

```swift theme={null}
static func from(wallet: Wallet) throws(WalletError) -> EVMWallet
```

#### Discussion

Useful when you have a `Wallet` reference and need EVM-specific methods. Throws `WalletError` if the wallet is not an EVM wallet.


# PasskeySigner
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/classes/passkeysigner

Swift Class

**Class**

```swift theme={null}
final class PasskeySigner
```

## Initializers

### init(name:host:)

```swift theme={null}
init(name: String, host: String)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `adminSigner` | `PasskeySignerData` | Inherited from `Signer.adminSigner`. |
| `signerType` | `SignerType` | Inherited from `Signer.signerType`. |

## Instance Methods

### approvals(withSignature:)

Inherited from `Signer.approvals(withSignature:)`.

```swift theme={null}
func approvals(withSignature signature: String) async throws(SignerError) -> [SignRequestApi.Approval]
```

### initialize(\_:)

Inherited from `ApprovalSigner.initialize(_:)`.

```swift theme={null}
func initialize(_ service: (any SmartWalletService)?) async throws(SignerError)
```

### sign(message:)

Inherited from `Signer.sign(message:)`.

```swift theme={null}
func sign(message: String) async throws(SignerError) -> String
```

### updateAdminSigner(\_:)

```swift theme={null}
func updateAdminSigner(_ adminSigner: PasskeySignerData) async -> any Signer
```

## Type Aliases

### PasskeySigner.AdminType

Inherited from `Signer.AdminType`.

```swift theme={null}
typealias AdminType = PasskeySignerData
```


# PhoneSigner
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/classes/phonesigner

Swift Class

**Class**

A phone (SMS or WhatsApp) OTP signer.

```swift theme={null}
final class PhoneSigner
```

## Overview

One class covers every chain because all three differ only in the key type, the signature encoding, and whether the message carries a hex prefix.

## Initializers

### init(phone:channel:chainType:crossmintTEE:)

```swift theme={null}
init(phone: String, channel: OTPDeliveryChannel?, chainType: ChainType, crossmintTEE: CrossmintTEE?)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `adminSigner` | `PhoneSignerData` | Inherited from `Signer.adminSigner`. |
| `channel` | `OTPDeliveryChannel?` | - |
| `encoding` | `String` | - |
| `keyType` | `String` | - |
| `phone` | `String` | In E.164 format, e.g. `"+15551234567"`. |
| `signerType` | `SignerType` | Inherited from `Signer.signerType`. |

## Type Aliases

### PhoneSigner.AdminType

Inherited from `Signer.AdminType`.

```swift theme={null}
typealias AdminType = PhoneSignerData
```


# SolanaEmailSigner
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/classes/solanaemailsigner

Swift Class

**Class**

```swift theme={null}
final class SolanaEmailSigner
```

## Initializers

### init(email:crossmintTEE:)

```swift theme={null}
init(email: String, crossmintTEE: CrossmintTEE?)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `adminSigner` | `EmailSignerData` | Inherited from `Signer.adminSigner`. |
| `email` | `String` | - |
| `encoding` | `String` | - |
| `keyType` | `String` | - |
| `signerType` | `SignerType` | Inherited from `Signer.signerType`. |

## Type Aliases

### SolanaEmailSigner.AdminType

Inherited from `Signer.AdminType`.

```swift theme={null}
typealias AdminType = EmailSignerData
```


# SolanaWallet
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/classes/solanawallet

Swift Class

**Class**

A Crossmint smart wallet on the Solana chain.

```swift theme={null}
final class SolanaWallet
```

## Overview

Obtain an instance via `getWallet(chain:options:)` or `createWallet(chain:recoveryMethods:options:)`.

## Instance Methods

### sendTransaction(transaction:)

Submits a serialized Solana transaction and polls until it is confirmed on-chain.

```swift theme={null}
func sendTransaction(transaction: String) async throws(TransactionError) -> TransactionSummary
```

#### Example

```swift theme={null}
let summary = try await solanaWallet.sendTransaction(transaction: base64EncodedTx)
print("Signature:", summary.hash)
```

#### Parameters

| Parameter | Description |
| - | - |
| `transaction` | A base64-encoded, serialized Solana transaction. |

### sendTransaction(transaction:)

```swift theme={null}
func sendTransaction(transaction: String) async throws(TransactionError) -> Transaction
```

## Type Aliases

### SolanaWallet.SpecificChain

Inherited from `WalletOnChain.SpecificChain`.

```swift theme={null}
typealias SpecificChain = SolanaChain
```

## Type Methods

### from(wallet:)

```swift theme={null}
static func from(wallet: Wallet) throws(WalletError) -> SolanaWallet
```


# StellarEmailSigner
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/classes/stellaremailsigner

Swift Class

**Class**

```swift theme={null}
final class StellarEmailSigner
```

## Initializers

### init(email:crossmintTEE:)

```swift theme={null}
init(email: String, crossmintTEE: CrossmintTEE?)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `adminSigner` | `EmailSignerData` | Inherited from `Signer.adminSigner`. |
| `email` | `String` | - |
| `encoding` | `String` | - |
| `keyType` | `String` | - |
| `signerType` | `SignerType` | Inherited from `Signer.signerType`. |

## Type Aliases

### StellarEmailSigner.AdminType

Inherited from `Signer.AdminType`.

```swift theme={null}
typealias AdminType = EmailSignerData
```


# StellarWallet
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/classes/stellarwallet

Swift Class

**Class**

```swift theme={null}
final class StellarWallet
```

## Instance Methods

### sendTransaction(transaction:)

```swift theme={null}
func sendTransaction(transaction: String) async throws(TransactionError) -> TransactionSummary
```

## Type Aliases

### StellarWallet.SpecificChain

Inherited from `WalletOnChain.SpecificChain`.

```swift theme={null}
typealias SpecificChain = StellarChain
```

## Type Methods

### from(wallet:)

```swift theme={null}
static func from(wallet: Wallet) throws(WalletError) -> StellarWallet
```


# Wallet
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/classes/wallet

Swift Class

**Class**

```swift theme={null}
class Wallet
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `address` | `String` | - |
| `recoveryMethods` | `[RecoveryMethod]` | Every recovery method of this wallet, with its install status. The list reflects the wallet at load time. `addRecoveryMethod(_:)` and `removeRecoveryMethod(locator:)` update it after a successful change. |

## Instance Methods

### addRecoveryMethod(\_:)

Adds a recovery method to the wallet.

```swift theme={null}
@discardableResult func addRecoveryMethod(_ method: SignerConfig) async throws(WalletError) -> Transaction
```

#### Return Value

The completed `Transaction`.

#### Discussion

Solana and Stellar wallets only. A recovery method of the wallet approves the change. To select it, see `useRecoveryMethod(_:)`.

> **Throws**: `WalletError.recoveryConfigRejected(code:message:)` with one of these codes:
>
> * `WalletError.RecoveryConfigCode.notSupportedOnChain` if the wallet is an EVM wallet.
> * `WalletError.RecoveryConfigCode.signerNotAllowed` if `method` is a passkey and the wallet is a Solana wallet.

#### Example

```swift theme={null}
let transaction = try await wallet.addRecoveryMethod(.email("backup@example.com"))
```

#### Parameters

| Parameter | Description |
| - | - |
| `method` | An email, phone, external wallet or passkey signer. For a passkey, the SDK shows the system prompt to create a new passkey. A Solana wallet does not accept a passkey as a recovery method. |

### addSigner(\_:)

Registers a new signer on this wallet.

```swift theme={null}
func addSigner(_ config: SignerConfig) async throws(WalletError)
```

#### Discussion

> **Throws**: `WalletError` if registration fails.

#### Parameters

| Parameter | Description |
| - | - |
| `config` | The signer configuration to register. |

### approve(transactionId:)

Approves and submits a pending transaction on behalf of the current signer.

```swift theme={null}
func approve(transactionId id: String) async throws(TransactionError) -> Transaction
```

#### Discussion

Use this when a transaction was created externally (e.g. via the Crossmint API) and shows `TransactionStatus.awaitingApproval`. The SDK signs the approval message and polls until the transaction reaches a terminal state.

#### Parameters

| Parameter | Description |
| - | - |
| `id` | The transaction ID returned by the Crossmint API. |

### balance(of:)

```swift theme={null}
func balance(of tokens: [CryptoCurrency] = []) async throws(WalletError) -> Balances
```

### balances(\_:\_:)

Returns balances for the requested tokens, always including the chain’s native token and USDC.

```swift theme={null}
func balances(_ tokens: [CryptoCurrency] = [], _ chains: [Chain] = []) async throws(WalletError) -> Balance
```

#### Parameters

| Parameter | Description |
| - | - |
| `tokens` | Additional tokens to include. Native token and USDC are always fetched. |
| `chains` | Additional chains to query. The wallet’s own chain is always included. |

### fund(token:amount:)

Funds the wallet with test tokens from the Crossmint faucet.

```swift theme={null}
func fund(token: CryptoCurrency, amount: Int) async throws(WalletError)
```

#### Discussion

Only available in staging/development environments; throws in production.

#### Parameters

| Parameter | Description |
| - | - |
| `token` | The token to fund. |
| `amount` | Amount in the token’s smallest unit (e.g. lamports for SOL, wei for ETH). |

### getTransaction(id:)

Fetches a transaction by its ID.

```swift theme={null}
func getTransaction(id: String) async throws(TransactionError) -> Transaction
```

#### Return Value

The `Transaction` matching the given ID.

#### Discussion

Use this to check the current status of a transaction, including its `TransactionStatus`, on-chain data, and any pending or submitted approvals.

> **Throws**: `TransactionError` if the transaction cannot be retrieved or decoded.

#### Example

```swift theme={null}
let transaction = try await wallet.getTransaction(id: "42bbb192-...")
if transaction.status == .success {
    print("Confirmed:", transaction.onChain.txId ?? "")
}
```

#### Parameters

| Parameter | Description |
| - | - |
| `id` | The transaction ID returned by the Crossmint API. |

### isSignerApproved(\_:)

Returns whether the given signer is approved and usable on this wallet’s chain.

```swift theme={null}
func isSignerApproved(_ locator: String) async throws(WalletError) -> Bool
```

#### Discussion

A freshly registered signer can need approval before it can sign. Call `addSigner(_:)` to register a signer. This method returns `false` when the signer is not registered on this wallet.

> **Throws**: `WalletError` if the request fails, or `WalletError.signerLocatorError(_:)` when the locator string does not parse as a `SignerLocator`.

#### Parameters

| Parameter | Description |
| - | - |
| `locator` | A signer locator string, for example `"email:user@example.com"`, `"phone:+15551234567"`, `"device:<pubkey>"`, `"api-key"`, or `"passkey:<id>"`. |

### isSignerApproved(\_:)

Returns whether the given signer is approved and usable on this wallet’s chain.

```swift theme={null}
func isSignerApproved(_ locator: SignerLocator) async throws(WalletError) -> Bool
```

#### Discussion

A freshly registered signer can need approval before it can sign. Call `addSigner(_:)` to register a signer. This method returns `false` when the signer is not registered on this wallet.

> **Throws**: `WalletError` if the request fails.

#### Parameters

| Parameter | Description |
| - | - |
| `locator` | The locator of the signer to check. |

### listTransactions(page:transactionsPerPage:)

Fetches a page of the transaction history for this wallet, ordered most recent first.

```swift theme={null}
func listTransactions(page: Int, transactionsPerPage: Int) async throws(TransactionError) -> [Transaction]
```

#### Return Value

The wallet’s `Transaction` list for the requested page.

#### Discussion

> **Throws**: `TransactionError` if the request fails.

#### Example

```swift theme={null}
let transactions = try await wallet.listTransactions(page: 1, transactionsPerPage: 20)

for transaction in transactions {
    print("\(transaction.id): \(transaction.status)")
}
```

#### Parameters

| Parameter | Description |
| - | - |
| `page` | One-based page index. |
| `transactionsPerPage` | Number of transactions per page. |

### listTransfers(tokens:)

Fetches the transfer history for this wallet.

```swift theme={null}
func listTransfers(tokens: [CryptoCurrency]) async throws(WalletError) -> TransferListResult
```

#### Return Value

A `TransferListResult` containing the transfer events sorted by timestamp (most recent first).

#### Discussion

Returns a list of incoming and outgoing transfers for the specified tokens. Use this method to display transaction history in your application.

> **Throws**: `WalletError` if the request fails.

#### Example

```swift theme={null}
// Fetch ETH and USDC transfers
let result = try await wallet.listTransfers(tokens: [.eth, .usdc])

for transfer in result.transfers {
    switch transfer.type {
    case .outgoing:
        print("Sent \(transfer.amount) \(transfer.tokenSymbol ?? "tokens")")
    case .incoming:
        print("Received \(transfer.amount) \(transfer.tokenSymbol ?? "tokens")")
    case .unknown:
        break
    }
}
```

#### Parameters

| Parameter | Description |
| - | - |
| `tokens` | The cryptocurrency tokens to fetch transfers for. Common values include `.eth`, `.usdc`, `.sol`, etc. |

### localDeviceSigner()

Returns the locator of the device signer whose private key is on this device. Returns `nil` if this wallet has no such signer.

```swift theme={null}
func localDeviceSigner() async -> SignerLocator?
```

#### Discussion

A wallet can have `device:` delegated signers registered from other devices. This method only returns a locator when the matching key is present in local secure storage.

### localDeviceSignerLocator()

Returns the locator string of the device signer whose private key is on this device. Returns `nil` if this wallet has no such signer.

```swift theme={null}
func localDeviceSignerLocator() async -> String?
```

### needsRecovery()

Returns whether this wallet needs recovery on the current device.

```swift theme={null}
func needsRecovery() async -> Bool
```

#### Discussion

A wallet needs recovery when a device signer is configured but the signing key for this wallet is not present on the current device. Call `recover()` to re-register.

> **Note**: This method awaits the background signer-initialization task that runs at wallet creation, so the first call may take a moment on slow networks.

### nfts(page:nftsPerPage:)

Returns a page of NFTs owned by this wallet.

```swift theme={null}
func nfts(page: Int, nftsPerPage: Int) async throws(WalletError) -> [NFT]
```

#### Parameters

| Parameter | Description |
| - | - |
| `page` | Zero-based page index. |
| `nftsPerPage` | Number of NFTs per page. |

### recover()

Re-registers the device signer on this device.

```swift theme={null}
func recover() async throws(WalletError)
```

#### Discussion

Call this when `needsRecovery()` returns `true` — i.e. the wallet has a device signer registered but the private key is missing on the current device. This generates a new key, registers it with Crossmint, and awaits approval from the existing admin signer.
If the wallet’s provider does not support device signers, this returns without error and signing stays on the recovery signer; the rejection is remembered so registration is not retried for this wallet instance.

> **Throws**: `WalletError` if recovery fails or there is no device signer configured.

### removeRecoveryMethod(locator:)

Removes a recovery method from the wallet.

```swift theme={null}
@discardableResult func removeRecoveryMethod(locator: SignerLocator) async throws(WalletError) -> Transaction
```

#### Return Value

The completed `Transaction`.

#### Discussion

Solana and Stellar wallets only. A different recovery method of the wallet approves the change. To select it, see `useRecoveryMethod(_:)`. If you selected the removed recovery method, the SDK clears the selection.
To remove a signer that you added with `addSigner(_:)`, use `removeSigner(locator:)`.

> **Throws**: `WalletError.recoveryConfigRejected(code:message:)` with one of these codes:
>
> * `WalletError.RecoveryConfigCode.notSupportedOnChain` on an EVM wallet.
> * `WalletError.RecoveryConfigCode.lastSigner` if the wallet has no other recovery method.

#### Example

```swift theme={null}
let transaction = try await wallet.removeRecoveryMethod(locator: .email("old@example.com"))
```

#### Parameters

| Parameter | Description |
| - | - |
| `locator` | The recovery method to remove. |

### removeSigner(locator:)

Removes an assigned signer from this wallet.

```swift theme={null}
func removeSigner(locator: String) async throws(TransactionError) -> Transaction
```

#### Return Value

The completed `Transaction` once the signer has been removed on-chain.

#### Discussion

This method submits a remove-signer transaction on-chain. If the transaction needs approval, the current signer signs it. The method then polls until the transaction completes.

#### Parameters

| Parameter | Description |
| - | - |
| `locator` | The signer locator string that identifies the signer to remove, for example `"device:ABC123..."` or `"external-wallet:0x456..."`. |

### removeSigner(locator:)

Removes an assigned signer from this wallet.

```swift theme={null}
func removeSigner(locator: SignerLocator) async throws(TransactionError) -> Transaction
```

#### Return Value

The completed `Transaction` once the signer has been removed on-chain.

#### Discussion

This method submits a remove-signer transaction on-chain. If the transaction needs approval, the current signer signs it. The method then polls until the transaction completes.
Use `removeRecoveryMethod(locator:)` to remove a recovery method.

#### Parameters

| Parameter | Description |
| - | - |
| `locator` | The locator that identifies the signer to remove. |

### send(\_:\_:\_:idempotencyKey:)

Transfers tokens to another wallet and polls until the transaction is confirmed on-chain.

```swift theme={null}
func send(_ walletLocator: String, _ tokenLocator: String, _ amount: Double, idempotencyKey: String? = nil) async throws(TransactionError) -> TransactionSummary
```

#### Return Value

A `TransactionSummary` with the on-chain hash and explorer link once confirmed.

#### Example

```swift theme={null}
let summary = try await wallet.send(
    "0xRecipient...",
    "base-sepolia:usdc",
    5.0
)
print("Sent. Explorer:", summary.explorerLink)
```

#### Parameters

| Parameter | Description |
| - | - |
| `walletLocator` | Recipient address (e.g. `"0xABC..."` or a Solana public key). |
| `tokenLocator` | `"{chain}:{token}"`, e.g. `"base-sepolia:eth"` or `"solana:usdc"`. |
| `amount` | Amount as a human-readable decimal (e.g. `0.01` for 0.01 ETH). |
| `idempotencyKey` | Pass a stable key to prevent duplicate transactions on retry; omit to generate one automatically. |

### send(token:recipient:amount:)

```swift theme={null}
func send(token: CryptoCurrency, recipient: TransferTokenRecipient, amount: String) async throws(TransactionError) -> Transaction
```

### signerIsRegistered(\_:)

Returns true if the locator is a signer on this wallet.

```swift theme={null}
func signerIsRegistered(_ locator: SignerLocator) async -> Bool
```

#### Discussion

This method sends a request to the server. It returns `false` if the request fails.

### signerIsRegistered(\_:)

Returns true if the locator is a signer on this wallet.

```swift theme={null}
func signerIsRegistered(_ locator: String) async -> Bool
```

#### Discussion

This method sends a request to the server. It returns `false` if the request fails. It also returns `false` if the locator string is not valid.

#### Parameters

| Parameter | Description |
| - | - |
| `locator` | A signer locator string, for example `"email:user@example.com"`, `"phone:+15551234567"`, `"device:<pubkey>"`, `"api-key"`, or `"passkey:<id>"`. |

### signers()

Fetches the current list of signers from the API.

```swift theme={null}
func signers() async throws(WalletError) -> [WalletSigner]
```

#### Discussion

Each `WalletSigner` includes its registration `status` on this wallet’s chain. On EVM wallets, signers without a registration entry (pending or completed) for the wallet’s chain are omitted. A signer whose state lookup fails is returned with `SignerStatus.unknown` rather than dropped.
Always returns fresh data — safe to call after `addSigner(_:)` or `removeSigner(locator:)`.

### transferToken(tokenId:recipient:amount:)

Transfers an NFT or fungible token to a recipient.

```swift theme={null}
func transferToken(tokenId: String? = nil, recipient: TransferTokenRecipient, amount: String) async throws(TransactionError) -> Transaction
```

#### Parameters

| Parameter | Description |
| - | - |
| `tokenId` | NFT token ID to transfer; omit for fungible token transfers. |
| `recipient` | Recipient address or wallet locator. |
| `amount` | Amount as a string (e.g. `"1"` for one NFT, or a fungible amount). |

### useRecoveryMethod(\_:)

Selects the recovery method that approves changes to signers and recovery methods.

```swift theme={null}
func useRecoveryMethod(_ method: SignerConfig) async throws(WalletError)
```

#### Discussion

The signer for transactions and messages does not change. To change it, use `useSigner(_:)`.
If you do not select a recovery method, the SDK uses one of these:

1. The only recovery method of the wallet.
2. The active signer, if it is a recovery method.
   If neither applies, the change fails with `WalletError.RecoveryConfigCode.signerRequired`.

> **Throws**: `WalletError.recoveryConfigRejected(code:message:)` with `WalletError.RecoveryConfigCode.invalidConfig` if `method` is not in `recoveryMethods`, or if `method` is a passkey with no `id` and the wallet has more than one passkey recovery method. The SDK throws `WalletError.walletGeneric(_:)` for a different signer type.

#### Example

```swift theme={null}
try await wallet.useRecoveryMethod(.phone("+14155552671"))
let transaction = try await wallet.removeRecoveryMethod(locator: .email("old@example.com"))
```

#### Parameters

| Parameter | Description |
| - | - |
| `method` | An email, phone, API key or passkey recovery method of the wallet. For a passkey, the SDK selects the passkey in `recoveryMethods` that has the `id` you give. If `id` is `nil`, the wallet must have only one passkey recovery method. The SDK does not create a new passkey. |

### useSigner(\_:)

Sets the signer for the send and sign operations of this wallet.

```swift theme={null}
func useSigner(_ config: SignerConfig) async throws(WalletError)
```

#### Discussion

The signer replaces the admin signer. The signer must be registered on this wallet. To register a new signer, call `addSigner(_:)` first.
To select the recovery method that approves signer changes, use `useRecoveryMethod(_:)`.

> **Throws**: - `WalletError.signerNotRegistered(_:)` if the signer is not registered on this wallet.
>
> * The `WalletError` of the failed request if the API does not return the wallet signers. The active signer does not change. You can try again.
> * `WalletError.walletGeneric(_:)` if `config` is `SignerConfig.externalWallet(_:onSign:)` and `onSign` is `nil`.
> * `WalletError.walletGeneric(_:)` if `config` is `SignerConfig.passkey(name:host:id:)` with no `id` and the wallet has more than one passkey signer.
> * `WalletError.deviceSignerNotSupported(_:)` if you select `.device` and the wallet provider does not accept device signers.

#### Parameters

| Parameter | Description |
| - | - |
| `config` | The signer to use. |


# Address
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/address

Swift Enumeration

**Enumeration**

```swift theme={null}
enum Address
```

## Enumeration Cases

| Case | Description |
| - | - |
| `evm(_:)` | - |
| `solana(_:)` | - |
| `stellar(_:)` | - |

## Initializers

### init(address:)

Inherited from `BlockchainAddress.init(address:)`.

```swift theme={null}
init(address: String) throws(BlockchainAddressError)
```

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `description` | `String` | Inherited from `CustomStringConvertible.description`. |
| `hiddenPublicKeyAddress` | `String` | - |

## Instance Methods

### encode(to:)

Inherited from `Encodable.encode(to:)`.

```swift theme={null}
func encode(to encoder: any Encoder) throws
```

## Type Methods

### validateAddressAndReturnAddress(\_:chain:)

```swift theme={null}
static func validateAddressAndReturnAddress(_ address: String, chain: Chain? = nil) -> Address?
```


# AdminSignerDataType
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/adminsignerdatatype

Swift Enumeration

**Enumeration**

```swift theme={null}
enum AdminSignerDataType
```

## Enumeration Cases

| Case | Description |
| - | - |
| `apiKey` | - |
| `email` | - |
| `externalWallet` | - |
| `passkey` | - |
| `phone` | - |
| `server` | - |

## Initializers

### init(rawValue:)

Inherited from `RawRepresentable.init(rawValue:)`.

```swift theme={null}
init?(rawValue: String)
```


# AuthenticationStatus
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/authenticationstatus

Swift Enumeration

**Enumeration**

The authentication state of the current session.

```swift theme={null}
enum AuthenticationStatus
```

## Enumeration Cases

| Case | Description |
| - | - |
| `authenticated(email:jwt:secret:)` | The user has a valid JWT. The `secret` is an opaque refresh token managed by the SDK. |
| `authenticating` | A stored refresh token is being exchanged for a JWT (transient state at startup). |
| `nonAuthenticated` | No session exists. |

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `isAuthenticated` | `Bool` | - |


# AuthError
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/autherror

Swift Enumeration

**Enumeration**

An error thrown by `AuthClient` and `CrossmintAuthManager` operations.

```swift theme={null}
enum AuthError
```

## Enumeration Cases

| Case | Description |
| - | - |
| `generic(_:)` | An unexpected error with a descriptive message. |
| `serviceError(_:)` | A Crossmint API or network error. Inspect the associated `CrossmintServiceError` for details. |
| `signInRequired` | The session has expired or the operation requires authentication. Call `sendOTP(to:)` to sign in again. |

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `code` | `String` | Inherited from `CrossmintError.code`. |
| `message` | `String` | Inherited from `CrossmintError.message`. |
| `recoverySuggestion` | `String?` | Inherited from `CrossmintError.recoverySuggestion`. |
| `underlyingError` | `(any Error)?` | Inherited from `CrossmintError.underlyingError`. |


# AuthManagerError
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/authmanagererror

Swift Enumeration

**Enumeration**

```swift theme={null}
enum AuthManagerError
```

## Enumeration Cases

| Case | Description |
| - | - |
| `invalidEmail` | The email address is not a valid format. |
| `invalidInput(_:)` | The caller supplied a value that failed validation (e.g. an empty OTP code). |
| `noPendingOTP` | `confirmEmailOtp(email:code:)` was called before `sendEmailOtp(email:)`. |
| `serviceError(_:)` | - |
| `unknown(_:)` | - |

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `code` | `String` | Inherited from `CrossmintError.code`. |
| `message` | `String` | Inherited from `CrossmintError.message`. |
| `recoverySuggestion` | `String?` | Inherited from `CrossmintError.recoverySuggestion`. |


# BlockchainAddressError
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/blockchainaddresserror

Swift Enumeration

**Enumeration**

```swift theme={null}
enum BlockchainAddressError
```

## Enumeration Cases

| Case | Description |
| - | - |
| `chainNotSupported(_:)` | - |
| `invalidAptosAddress(_:)` | - |
| `invalidCardanoAddress(_:)` | - |
| `invalidEVMAddress(_:)` | - |
| `invalidSolanaAddress(_:)` | - |
| `invalidStellarAddress(_:)` | - |
| `invalidSuiAddress(_:)` | - |


# BlockchainExplorerLinkType
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/blockchainexplorerlinktype

Swift Enumeration

**Enumeration**

```swift theme={null}
enum BlockchainExplorerLinkType
```

## Enumeration Cases

| Case | Description |
| - | - |
| `address(_:)` | - |


# Chain
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/chain

Swift Enumeration

**Enumeration**

```swift theme={null}
enum Chain
```

## Enumeration Cases

| Case | Description |
| - | - |
| `apechain` | - |
| `apex` | - |
| `arbitrum` | - |
| `arbitrumSepolia` | - |
| `arbitrumnova` | - |
| `astarZkevm` | - |
| `avalanche` | - |
| `avalancheFuji` | - |
| `barretTestnet` | - |
| `base` | - |
| `baseGoerli` | - |
| `baseSepolia` | - |
| `boss` | - |
| `bsc` | - |
| `bscTestnet` | - |
| `chiliz` | - |
| `chilizSpicyTestnet` | - |
| `coti` | - |
| `cotiTestnet` | - |
| `curtis` | - |
| `ethereum` | - |
| `ethereumGoerli` | - |
| `ethereumSepolia` | - |
| `hypersonicTestnet` | - |
| `lightlink` | - |
| `lightlinkPegasus` | - |
| `mode` | - |
| `modeSepolia` | - |
| `optimism` | - |
| `optimismGoerli` | - |
| `optimismSepolia` | - |
| `polygon` | - |
| `polygonAmoy` | - |
| `polygonMumbai` | - |
| `rari` | - |
| `rariTestnet` | - |
| `scroll` | - |
| `scrollSepolia` | - |
| `seiAtlantic2Testnet` | - |
| `seiPacific1` | - |
| `shape` | - |
| `shapeSepolia` | - |
| `skaleNebula` | - |
| `skaleNebulaTestnet` | - |
| `solana` | - |
| `soneium` | - |
| `soneiumMinatoTestnet` | - |
| `space` | - |
| `spaceTestnet` | - |
| `stellar` | - |
| `story` | - |
| `storyTestnet` | - |
| `unknown(name:)` | - |
| `verifyTestnet` | - |
| `viction` | - |
| `victionTestnet` | - |
| `xai` | - |
| `xaiSepoliaTestnet` | - |
| `zenchainTestnet` | - |
| `zkatana` | - |
| `zkyoto` | - |
| `zora` | - |
| `zoraGoerli` | - |
| `zoraSepolia` | - |

## Initializers

### init(\_:)

```swift theme={null}
init(_ from: String)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | Inherited from `AnyChain.chainType`. |
| `name` | `String` | Inherited from `AnyChain.name`. |

## Instance Methods

### isValid(isProductionEnvironment:)

Inherited from `AnyChain.isValid(isProductionEnvironment:)`.

```swift theme={null}
func isValid(isProductionEnvironment: Bool) -> Bool
```

## Type Methods

### fromName(\_:)

```swift theme={null}
static func fromName(_ name: String) -> Chain?
```


# ChainAndAddress
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/chainandaddress

Swift Enumeration

**Enumeration**

```swift theme={null}
enum ChainAndAddress
```

## Enumeration Cases

| Case | Description |
| - | - |
| `evm(_:_:)` | - |
| `solana(_:)` | - |
| `stellar(_:)` | - |

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `blockchainAddress` | `any BlockchainAddress` | - |
| `chain` | `Chain` | - |
| `description` | `String` | Inherited from `CustomStringConvertible.description`. |


# ChainType
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/chaintype

Swift Enumeration

**Enumeration**

```swift theme={null}
enum ChainType
```

## Enumeration Cases

| Case | Description |
| - | - |
| `evm` | - |
| `solana` | - |
| `stellar` | - |
| `unknown` | - |

## Initializers

### init(rawValue:)

Inherited from `RawRepresentable.init(rawValue:)`.

```swift theme={null}
init?(rawValue: String)
```


# CryptoCurrency
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/cryptocurrency

Swift Enumeration

**Enumeration**

```swift theme={null}
enum CryptoCurrency
```

## Operators

### \<(\_:\_:)

Inherited from `Comparable.<(_:_:)`.

```swift theme={null}
static func < (lhs: CryptoCurrency, rhs: CryptoCurrency) -> Bool
```

## Enumeration Cases

| Case | Description |
| - | - |
| `ada` | - |
| `ape` | - |
| `apt` | - |
| `avax` | - |
| `bnb` | - |
| `bonk` | - |
| `brett` | - |
| `busd` | - |
| `chz` | - |
| `degen` | - |
| `eth` | - |
| `eurc` | - |
| `fuel` | - |
| `ip` | - |
| `matic` | - |
| `mother` | - |
| `pol` | - |
| `sei` | - |
| `sfuel` | - |
| `sol` | - |
| `sui` | - |
| `superverse` | - |
| `toshi` | - |
| `unknown(_:)` | - |
| `usdc` | - |
| `usdce` | - |
| `usdxm` | - |
| `vic` | - |
| `weth` | - |
| `wif` | - |
| `xai` | - |
| `xlm` | - |

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

### init(name:)

```swift theme={null}
init(name: String)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `name` | `String` | - |

## Instance Methods

### contains(\_:)

Inherited from `RangeExpression.contains(_:)`.

```swift theme={null}
func contains(_ element: CryptoCurrency) -> Bool
```

### getNumericPriceDecimalsPerCurrency(defaultValue:)

```swift theme={null}
func getNumericPriceDecimalsPerCurrency(defaultValue: Int = 5) -> Int
```

### relative(to:)

```swift theme={null}
func relative<C>(to collection: C) -> Range<C.Index> where C : Collection
```

### relative(to:)

Inherited from `RangeExpression.relative(to:)`.

```swift theme={null}
func relative<C>(to collection: C) -> Range<CryptoCurrency> where C : Collection, C.Index == CryptoCurrency
```

## Type Properties

| Property | Type | Description |
| - | - | - |
| `allCases` | `[CryptoCurrency]` | Inherited from `CaseIterable.allCases`. |


# CryptoPaymentFailureCode
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/cryptopaymentfailurecode

Swift Enumeration

**Enumeration**

```swift theme={null}
enum CryptoPaymentFailureCode
```

## Enumeration Cases

| Case | Description |
| - | - |
| `insufficientFunds` | - |
| `txIdNotFound` | - |
| `unknown` | - |

## Initializers

### init(rawValue:)

Inherited from `RawRepresentable.init(rawValue:)`.

```swift theme={null}
init?(rawValue: String)
```


# EIP712
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/eip712

Swift Enumeration

**Enumeration**

```swift theme={null}
enum EIP712
```

## Classes

### EIP712.Builder

```swift theme={null}
class Builder
```

### EIP712.FieldBuilder

```swift theme={null}
class FieldBuilder
```

## Structures

### EIP712.Domain

```swift theme={null}
struct Domain
```

### EIP712.Field

```swift theme={null}
struct Field
```

### EIP712.TypedData

```swift theme={null}
struct TypedData
```

## Enumerations

### EIP712.CommonPatterns

```swift theme={null}
enum CommonPatterns
```

### EIP712.TypeString

```swift theme={null}
enum TypeString
```


# EVMChain
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/evmchain

Swift Enumeration

**Enumeration**

```swift theme={null}
enum EVMChain
```

## Enumeration Cases

| Case | Description |
| - | - |
| `apechain` | - |
| `apex` | - |
| `arbitrum` | - |
| `arbitrumSepolia` | - |
| `arbitrumnova` | - |
| `astarZkevm` | - |
| `avalanche` | - |
| `avalancheFuji` | - |
| `barretTestnet` | - |
| `base` | - |
| `baseGoerli` | - |
| `baseSepolia` | - |
| `boss` | - |
| `bsc` | - |
| `bscTestnet` | - |
| `chiliz` | - |
| `chilizSpicyTestnet` | - |
| `coti` | - |
| `cotiTestnet` | - |
| `curtis` | - |
| `ethereum` | - |
| `ethereumGoerli` | - |
| `ethereumSepolia` | - |
| `hypersonicTestnet` | - |
| `lightlink` | - |
| `lightlinkPegasus` | - |
| `mode` | - |
| `modeSepolia` | - |
| `optimism` | - |
| `optimismGoerli` | - |
| `optimismSepolia` | - |
| `polygon` | - |
| `polygonAmoy` | - |
| `polygonMumbai` | - |
| `rari` | - |
| `rariTestnet` | - |
| `scroll` | - |
| `scrollSepolia` | - |
| `seiAtlantic2Testnet` | - |
| `seiPacific1` | - |
| `shape` | - |
| `shapeSepolia` | - |
| `skaleNebula` | - |
| `skaleNebulaTestnet` | - |
| `soneium` | - |
| `soneiumMinatoTestnet` | - |
| `space` | - |
| `spaceTestnet` | - |
| `story` | - |
| `storyTestnet` | - |
| `verifyTestnet` | - |
| `viction` | - |
| `victionTestnet` | - |
| `xai` | - |
| `xaiSepoliaTestnet` | - |
| `zenchainTestnet` | - |
| `zkatana` | - |
| `zkyoto` | - |
| `zora` | - |
| `zoraGoerli` | - |
| `zoraSepolia` | - |

## Initializers

### init(\_:)

Inherited from `SpecificChain.init(_:)`.

```swift theme={null}
init?(_ from: String)
```

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `chain` | `Chain` | Inherited from `SpecificChain.chain`. |
| `chainType` | `ChainType` | Inherited from `AnyChain.chainType`. |
| `name` | `String` | Inherited from `AnyChain.name`. |

## Instance Methods

### isValid(isProductionEnvironment:)

Inherited from `AnyChain.isValid(isProductionEnvironment:)`.

```swift theme={null}
func isValid(isProductionEnvironment: Bool) -> Bool
```


# EVMSigners
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/evmsigners

Swift Enumeration

**Enumeration**

```swift theme={null}
enum EVMSigners
```

## Enumeration Cases

| Case | Description |
| - | - |
| `apiKey` | - |
| `email(_:)` | - |
| `passkey(name:host:)` | - |
| `phone(_:channel:)` | - |

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `signer` | `any Signer` | Inherited from `SignerProvider.signer`. |


# EVMSmartWalletMapping
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/evmsmartwalletmapping

Swift Enumeration

**Enumeration**

```swift theme={null}
enum EVMSmartWalletMapping
```

## Type Aliases

### EVMSmartWalletMapping.APIModel

Inherited from `WalletTypeTransactionMapping.APIModel`.

```swift theme={null}
typealias APIModel = EVMTransactionApiModel
```

## Type Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | Inherited from `WalletTypeTransactionMapping.chainType`. |


# FiatCurrency
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/fiatcurrency

Swift Enumeration

**Enumeration**

```swift theme={null}
enum FiatCurrency
```

## Operators

### \<(\_:\_:)

Inherited from `Comparable.<(_:_:)`.

```swift theme={null}
static func < (lhs: FiatCurrency, rhs: FiatCurrency) -> Bool
```

## Enumeration Cases

| Case | Description |
| - | - |
| `aud` | - |
| `eur` | - |
| `gbp` | - |
| `hkd` | - |
| `inr` | - |
| `jpy` | - |
| `krw` | - |
| `sgd` | - |
| `unknown(_:)` | - |
| `usd` | - |
| `vnd` | - |

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

### init(name:)

```swift theme={null}
init(name: String)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `isPaymentEnabledFiatCurrency` | `Bool` | - |
| `name` | `String` | - |

## Instance Methods

### contains(\_:)

Inherited from `RangeExpression.contains(_:)`.

```swift theme={null}
func contains(_ element: FiatCurrency) -> Bool
```

### encode(to:)

Inherited from `Encodable.encode(to:)`.

```swift theme={null}
func encode(to encoder: any Encoder) throws
```

### relative(to:)

Inherited from `RangeExpression.relative(to:)`.

```swift theme={null}
func relative<C>(to collection: C) -> Range<FiatCurrency> where C : Collection, C.Index == FiatCurrency
```

### relative(to:)

```swift theme={null}
func relative<C>(to collection: C) -> Range<C.Index> where C : Collection
```


# LinkedUserError
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/linkedusererror

Swift Enumeration

**Enumeration**

```swift theme={null}
enum LinkedUserError
```

## Enumeration Cases

| Case | Description |
| - | - |
| `invalidLocator(_:)` | - |
| `unknownType(_:)` | - |

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `errorDescription` | `String?` | Inherited from `LocalizedError.errorDescription`. |


# NonCustodialSignerError
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/noncustodialsignererror

Swift Enumeration

**Enumeration**

```swift theme={null}
enum NonCustodialSignerError
```

## Enumeration Cases

| Case | Description |
| - | - |
| `generic(_:)` | - |
| `nonAvailable` | - |
| `teeNotStarted` | - |


# OTPAuthenticationStatus
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/otpauthenticationstatus

Swift Enumeration

**Enumeration**

Returned by OTP flow methods to indicate either session state or a pending email.

```swift theme={null}
enum OTPAuthenticationStatus
```

## Enumeration Cases

| Case | Description |
| - | - |
| `authenticationStatus(_:)` | Wraps the underlying `AuthenticationStatus`. |
| `emailSent(email:emailId:)` | An OTP email has been sent; `confirmEmailOtp(email:code:)` is now expected. |

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `email` | `String?` | - |
| `isAuthenticated` | `Bool` | - |


# OTPDeliveryChannel
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/otpdeliverychannel

Swift Enumeration

**Enumeration**

How a phone signer’s one-time password reaches the user.

```swift theme={null}
enum OTPDeliveryChannel
```

## Overview

The channel is sent with every onboarding request. The signer service falls back to SMS when none is requested, and it does not persist the choice, so it must be supplied again each time.

## Enumeration Cases

| Case | Description |
| - | - |
| `sms` | - |
| `whatsapp` | - |

## Initializers

### init(rawValue:)

Inherited from `RawRepresentable.init(rawValue:)`.

```swift theme={null}
init?(rawValue: String)
```


# Owner
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/owner

Swift Enumeration

**Enumeration**

```swift theme={null}
enum Owner
```

## Enumeration Cases

| Case | Description |
| - | - |
| `email(_:)` | - |
| `phoneNumber(_:)` | - |
| `twitter(_:)` | - |
| `userId(_:)` | - |
| `x(_:)` | - |

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

### init(from:)

```swift theme={null}
init(from locator: String) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `description` | `String` | Inherited from `CustomStringConvertible.description`. |

## Instance Methods

### encode(to:)

Inherited from `Encodable.encode(to:)`.

```swift theme={null}
func encode(to encoder: any Encoder) throws
```


# SignatureError
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/signatureerror

Swift Enumeration

**Enumeration**

```swift theme={null}
enum SignatureError
```

## Enumeration Cases

| Case | Description |
| - | - |
| `approvalFailed` | - |
| `creationFailed` | - |
| `decodingError` | - |
| `networkError` | - |
| `serviceError(_:)` | - |
| `signingFailed(underlyingError:)` | - |
| `unknown` | - |
| `userCancelled` | - |

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `code` | `String` | Inherited from `CrossmintError.code`. |
| `message` | `String` | Inherited from `CrossmintError.message`. |
| `underlyingError` | `(any Error)?` | Inherited from `CrossmintError.underlyingError`. |


# SignerConfig
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/signerconfig

Swift Enumeration

**Enumeration**

Describes which signer to use for wallet operations.

```swift theme={null}
enum SignerConfig
```

## Overview

Pass a `SignerConfig` to `useSigner(_:)` to set the active signer, or to `addSigner(_:)` to register a new signer on the wallet.

## Enumeration Cases

| Case | Description |
| - | - |
| `apiKey` | The API key signer (server-side / custodial). |
| `device` | The device’s Secure Enclave (or software fallback) as the signer. Created lazily on first transaction if no local key exists. |
| `email(_:)` | An email OTP signer. |
| `externalWallet(_:onSign:)` | A signer that uses an external wallet, for example a wallet app or a hardware wallet. |
| `passkey(name:host:id:)` | A passkey signer. |
| `phone(_:channel:)` | A phone OTP signer. The phone number must be in E.164 format (e.g. `"+15551234567"`). |


# SignerError
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/signererror

Swift Enumeration

**Enumeration**

```swift theme={null}
enum SignerError
```

## Enumeration Cases

| Case | Description |
| - | - |
| `cancelled` | - |
| `device(_:)` | The device signer key could not sign. The `DeviceSignerError` gives the cause. |
| `invalidAddress` | - |
| `invalidEmail` | - |
| `invalidMessage` | - |
| `invalidPrivateKey` | - |
| `invalidSigner` | - |
| `notStarted` | - |
| `passkey(_:)` | - |
| `signingFailed` | - |

## Enumerations

### SignerError.PasskeyError

```swift theme={null}
enum PasskeyError
```


# SignerLocator
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/signerlocator

Swift Enumeration

**Enumeration**

Identifies a signer registered on a wallet.

```swift theme={null}
enum SignerLocator
```

## Operators

### ==(\_:\_:)

Inherited from `Equatable.==(_:_:)`.

```swift theme={null}
static func == (lhs: SignerLocator, rhs: SignerLocator) -> Bool
```

## Enumeration Cases

| Case | Description |
| - | - |
| `apiKey(address:)` | - |
| `device(publicKey:)` | - |
| `email(_:)` | - |
| `externalWallet(address:)` | - |
| `passkey(credentialId:)` | - |
| `phone(_:)` | - |
| `server(address:)` | - |
| `unknown(_:)` | - |

## Initializers

### init(from:)

```swift theme={null}
init(from locator: String) throws(WalletError)
```

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `isDevice` | `Bool` | Whether this locator refers to a device signer, regardless of its public key. |
| `isPasskey` | `Bool` | Whether this locator refers to a passkey signer, regardless of its credential ID. |
| `value` | `String` | - |

## Instance Methods

### encode(to:)

Inherited from `Encodable.encode(to:)`.

```swift theme={null}
func encode(to encoder: any Encoder) throws
```

### hash(into:)

Inherited from `Hashable.hash(into:)`.

```swift theme={null}
func hash(into hasher: inout Hasher)
```


# Signers
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/signers

Swift Enumeration

**Enumeration**

```swift theme={null}
enum Signers
```

## Enumeration Cases

| Case | Description |
| - | - |
| `evmEmailSigner(email:)` | - |
| `evmFireblocksSigner` | - |
| `passkeySigner(name:host:)` | - |
| `solanaEmailSigner(email:)` | - |
| `solanaFireblocksSigner` | - |

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `signer` | `any Signer` | - |


# SignerStatus
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/signerstatus

Swift Enumeration

**Enumeration**

The registration state of a signer as it moves through approval.

```swift theme={null}
enum SignerStatus
```

## Enumeration Cases

| Case | Description |
| - | - |
| `active` | Registered and usable. |
| `awaitingApproval` | Waiting for one or more approvals before it becomes active. |
| `failed` | Rejected or reverted. |
| `pending` | Submitted but not yet routed for approval. |
| `unknown` | The backend returned a status this SDK doesn’t recognize, or omitted it. |

## Initializers

### init(rawValue:)

Inherited from `RawRepresentable.init(rawValue:)`.

```swift theme={null}
init?(rawValue: String)
```

## Type Methods

### from(\_:)

Parses a raw status string, treating the legacy `"success"` response as `SignerStatus.active` and falling back to `SignerStatus.unknown` for anything `nil` or unrecognized.

```swift theme={null}
static func from(_ rawValue: String?) -> SignerStatus
```


# SignerType
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/signertype

Swift Enumeration

**Enumeration**

```swift theme={null}
enum SignerType
```

## Enumeration Cases

| Case | Description |
| - | - |
| `apiKey` | - |
| `email` | - |
| `externalWallet` | - |
| `passkey` | - |
| `phone` | - |

## Initializers

### init(rawValue:)

Inherited from `RawRepresentable.init(rawValue:)`.

```swift theme={null}
init?(rawValue: String)
```


# SolanaChain
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/solanachain

Swift Enumeration

**Enumeration**

```swift theme={null}
enum SolanaChain
```

## Enumeration Cases

| Case | Description |
| - | - |
| `solana` | - |

## Initializers

### init(\_:)

Inherited from `SpecificChain.init(_:)`.

```swift theme={null}
init?(_ from: String)
```

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `chain` | `Chain` | Inherited from `SpecificChain.chain`. |
| `chainType` | `ChainType` | Inherited from `AnyChain.chainType`. |
| `name` | `String` | Inherited from `AnyChain.name`. |

## Instance Methods

### isValid(isProductionEnvironment:)

Inherited from `AnyChain.isValid(isProductionEnvironment:)`.

```swift theme={null}
func isValid(isProductionEnvironment: Bool) -> Bool
```


# SolanaSigners
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/solanasigners

Swift Enumeration

**Enumeration**

The recovery signers for a Solana wallet.

```swift theme={null}
enum SolanaSigners
```

## Overview

A passkey cannot be a recovery signer on Solana. To add a passkey to a Solana wallet, use `addSigner(_:)` with `SignerConfig.passkey(name:host:id:)`.

## Enumeration Cases

| Case | Description |
| - | - |
| `apiKey` | - |
| `email(_:)` | - |
| `phone(_:channel:)` | - |

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `signer` | `any Signer` | Inherited from `SignerProvider.signer`. |


# SolanaSmartWalletMapping
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/solanasmartwalletmapping

Swift Enumeration

**Enumeration**

```swift theme={null}
enum SolanaSmartWalletMapping
```

## Type Aliases

### SolanaSmartWalletMapping.APIModel

Inherited from `WalletTypeTransactionMapping.APIModel`.

```swift theme={null}
typealias APIModel = SolanaTransactionApiModel
```

## Type Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | Inherited from `WalletTypeTransactionMapping.chainType`. |


# SolanaSupportedToken
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/solanasupportedtoken

Swift Enumeration

**Enumeration**

```swift theme={null}
enum SolanaSupportedToken
```

## Enumeration Cases

| Case | Description |
| - | - |
| `sol` | - |
| `usdc` | - |

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `asCryptoCurrency` | `CryptoCurrency` | - |
| `name` | `String` | - |

## Type Methods

### toSolanaSupportedToken(\_:)

```swift theme={null}
static func toSolanaSupportedToken(_ cryptoCurrency: CryptoCurrency?) -> SolanaSupportedToken?
```


# StellarChain
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/stellarchain

Swift Enumeration

**Enumeration**

```swift theme={null}
enum StellarChain
```

## Enumeration Cases

| Case | Description |
| - | - |
| `stellar` | - |

## Initializers

### init(\_:)

Inherited from `SpecificChain.init(_:)`.

```swift theme={null}
init?(_ from: String)
```

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `chain` | `Chain` | Inherited from `SpecificChain.chain`. |
| `chainType` | `ChainType` | Inherited from `AnyChain.chainType`. |
| `name` | `String` | Inherited from `AnyChain.name`. |

## Instance Methods

### isValid(isProductionEnvironment:)

Inherited from `AnyChain.isValid(isProductionEnvironment:)`.

```swift theme={null}
func isValid(isProductionEnvironment: Bool) -> Bool
```


# StellarSigners
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/stellarsigners

Swift Enumeration

**Enumeration**

```swift theme={null}
enum StellarSigners
```

## Enumeration Cases

| Case | Description |
| - | - |
| `apiKey` | - |
| `email(_:)` | - |
| `passkey(name:host:)` | - |
| `phone(_:channel:)` | - |

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `signer` | `any Signer` | Inherited from `SignerProvider.signer`. |


# StellarSmartWalletMapping
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/stellarsmartwalletmapping

Swift Enumeration

**Enumeration**

```swift theme={null}
enum StellarSmartWalletMapping
```

## Type Aliases

### StellarSmartWalletMapping.APIModel

Inherited from `WalletTypeTransactionMapping.APIModel`.

```swift theme={null}
typealias APIModel = StellarTransactionApiModel
```

## Type Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | Inherited from `WalletTypeTransactionMapping.chainType`. |


# StellarSupportedToken
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/stellarsupportedtoken

Swift Enumeration

**Enumeration**

```swift theme={null}
enum StellarSupportedToken
```

## Enumeration Cases

| Case | Description |
| - | - |
| `usdxm` | - |
| `xlm` | - |

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `asCryptoCurrency` | `CryptoCurrency` | - |
| `name` | `String` | - |

## Type Methods

### toStellarSupportedToken(\_:)

```swift theme={null}
static func toStellarSupportedToken(_ cryptoCurrency: CryptoCurrency?) -> StellarSupportedToken?
```


# TokenAccountType
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/tokenaccounttype

Swift Enumeration

**Enumeration**

```swift theme={null}
enum TokenAccountType
```

## Enumeration Cases

| Case | Description |
| - | - |
| `card(provider:)` | - |
| `unknown(_:)` | An account type that this version of the SDK does not know. The value is the type name that the API sent. |
| `wallet` | - |


# TransactionError
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/transactionerror

Swift Enumeration

**Enumeration**

```swift theme={null}
enum TransactionError
```

## Enumeration Cases

| Case | Description |
| - | - |
| `invalidApprovals(expected:actual:)` | - |
| `serviceError(_:)` | - |
| `transactionCreationFailed` | - |
| `transactionCreationFailedNoSigner` | - |
| `transactionGeneric(_:)` | - |
| `transactionNotFound` | - |
| `transactionSigningFailed(_:)` | - |
| `transactionSigningFailedInvalidKey` | - |
| `transactionSigningFailedNoMessage` | - |
| `transactionSigningFailedNoSigner` | - |
| `userCancelled` | - |

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `code` | `String` | Inherited from `CrossmintError.code`. |
| `message` | `String` | Inherited from `CrossmintError.message`. |
| `recoverySuggestion` | `String?` | Inherited from `CrossmintError.recoverySuggestion`. |
| `underlyingError` | `(any Error)?` | Inherited from `CrossmintError.underlyingError`. |


# TransactionStatus
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/transactionstatus

Swift Enumeration

**Enumeration**

The lifecycle state of a transaction submitted through the Crossmint API.

```swift theme={null}
enum TransactionStatus
```

## Enumeration Cases

| Case | Description |
| - | - |
| `awaitingApproval` | Waiting for one or more signers to approve before it can be submitted. |
| `failed` | Rejected or reverted on-chain. |
| `pending` | Submitted to the API but not yet broadcast to the network. |
| `success` | Confirmed on-chain. |

## Initializers

### init(rawValue:)

Inherited from `RawRepresentable.init(rawValue:)`.

```swift theme={null}
init?(rawValue: String)
```


# TransactionStatusApiModel
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/transactionstatusapimodel

Swift Enumeration

**Enumeration**

```swift theme={null}
enum TransactionStatusApiModel
```

## Enumeration Cases

| Case | Description |
| - | - |
| `awaitingApproval` | - |
| `failed` | - |
| `pending` | - |
| `success` | - |

## Initializers

### init(rawValue:)

Inherited from `RawRepresentable.init(rawValue:)`.

```swift theme={null}
init?(rawValue: String)
```


# TransferTokenLocator
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/transfertokenlocator

Swift Enumeration

**Enumeration**

```swift theme={null}
enum TransferTokenLocator
```

## Operators

### !=(\_:\_:)

```swift theme={null}
static func != (lhs: TransferTokenLocator, rhs: String) -> Bool
```

### !=(\_:\_:)

```swift theme={null}
static func != (lhs: String, rhs: TransferTokenLocator) -> Bool
```

### ==(\_:\_:)

```swift theme={null}
static func == (lhs: TransferTokenLocator, rhs: String) -> Bool
```

### ==(\_:\_:)

```swift theme={null}
static func == (lhs: String, rhs: TransferTokenLocator) -> Bool
```

## Enumeration Cases

| Case | Description |
| - | - |
| `address(_:)` | - |
| `currency(_:)` | - |
| `tokenId(_:tokenId:)` | - |

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `description` | `String` | Inherited from `CustomStringConvertible.description`. |

## Instance Methods

### matches(\_:)

```swift theme={null}
func matches(_ string: String) -> Bool
```

## Enumerations

### TransferTokenLocator.CurrencyData

```swift theme={null}
enum CurrencyData
```


# TransferTokenRecipient
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/transfertokenrecipient

Swift Enumeration

**Enumeration**

```swift theme={null}
enum TransferTokenRecipient
```

## Operators

### !=(\_:\_:)

```swift theme={null}
static func != (lhs: TransferTokenRecipient, rhs: NonEmptyString) -> Bool
```

### !=(\_:\_:)

```swift theme={null}
static func != (lhs: TransferTokenRecipient, rhs: String) -> Bool
```

### !=(\_:\_:)

```swift theme={null}
static func != (lhs: String, rhs: TransferTokenRecipient) -> Bool
```

### !=(\_:\_:)

```swift theme={null}
static func != (lhs: NonEmptyString, rhs: TransferTokenRecipient) -> Bool
```

### ==(\_:\_:)

```swift theme={null}
static func == (lhs: String, rhs: TransferTokenRecipient) -> Bool
```

### ==(\_:\_:)

```swift theme={null}
static func == (lhs: NonEmptyString, rhs: TransferTokenRecipient) -> Bool
```

### ==(\_:\_:)

```swift theme={null}
static func == (lhs: TransferTokenRecipient, rhs: String) -> Bool
```

### ==(\_:\_:)

```swift theme={null}
static func == (lhs: TransferTokenRecipient, rhs: NonEmptyString) -> Bool
```

## Enumeration Cases

| Case | Description |
| - | - |
| `address(_:)` | - |
| `email(_:)` | - |
| `phoneNumber(_:)` | - |
| `twitter(_:)` | - |
| `userId(_:)` | - |
| `x(_:)` | - |

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `description` | `String` | Inherited from `CustomStringConvertible.description`. |

## Instance Methods

### encode(to:)

Inherited from `Encodable.encode(to:)`.

```swift theme={null}
func encode(to encoder: any Encoder) throws
```

### matches(\_:)

```swift theme={null}
func matches(_ string: String) -> Bool
```

## Enumerations

### TransferTokenRecipient.OptionalChain

```swift theme={null}
enum OptionalChain
```


# TransferType
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/transfertype

Swift Enumeration

**Enumeration**

The direction of a transfer relative to the wallet.

```swift theme={null}
enum TransferType
```

## Enumeration Cases

| Case | Description |
| - | - |
| `incoming` | The transfer was received by the wallet. |
| `outgoing` | The transfer was sent from the wallet. |

## Initializers

### init(rawValue:)

Inherited from `RawRepresentable.init(rawValue:)`.

```swift theme={null}
init?(rawValue: String)
```


# UnknownChain
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/unknownchain

Swift Enumeration

**Enumeration**

```swift theme={null}
enum UnknownChain
```

## Enumeration Cases

| Case | Description |
| - | - |
| `unknown(name:)` | - |

## Initializers

### init(\_:)

Inherited from `SpecificChain.init(_:)`.

```swift theme={null}
init?(_ from: String)
```

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `chain` | `Chain` | Inherited from `SpecificChain.chain`. |
| `chainType` | `ChainType` | Inherited from `AnyChain.chainType`. |
| `name` | `String` | Inherited from `AnyChain.name`. |

## Instance Methods

### isValid(isProductionEnvironment:)

Inherited from `AnyChain.isValid(isProductionEnvironment:)`.

```swift theme={null}
func isValid(isProductionEnvironment: Bool) -> Bool
```


# WalletError
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/walleterror

Swift Enumeration

**Enumeration**

```swift theme={null}
enum WalletError
```

## Enumeration Cases

| Case | Description |
| - | - |
| `deviceSignerNotSupported(_:)` | The wallet’s underlying provider does not support device signers, surfaced from the backend’s stable `DEVICE_SIGNER_NOT_SUPPORTED` error code. `recover()` catches it and falls back to the recovery signer. |
| `invalidChain(chain:)` | - |
| `invalidToken(token:)` | - |
| `recoveryConfigRejected(code:message:)` | The SDK or Crossmint rejected the recovery method list. `message` explains the rejection. |
| `serviceError(_:)` | - |
| `signerLocatorError(_:)` | - |
| `signerNotRegistered(_:)` | - |
| `transactionNotFound` | - |
| `walletCreationCancelled` | - |
| `walletCreationFailed(_:)` | - |
| `walletGeneric(_:)` | - |
| `walletInvalidCredentials` | - |
| `walletInvalidSignerProvided` | - |
| `walletInvalidType(_:)` | - |
| `walletLocatorError(_:)` | - |
| `walletNotFound` | - |

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `code` | `String` | Inherited from `CrossmintError.code`. |
| `message` | `String` | Inherited from `CrossmintError.message`. |
| `recoverySuggestion` | `String?` | Inherited from `CrossmintError.recoverySuggestion`. |
| `underlyingError` | `(any Error)?` | Inherited from `CrossmintError.underlyingError`. |

## Enumerations

### WalletError.RecoveryConfigCode

The reason the SDK or Crossmint rejected a recovery method list.

```swift theme={null}
enum RecoveryConfigCode
```


# WalletLocator
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/walletlocator

Swift Enumeration

**Enumeration**

```swift theme={null}
enum WalletLocator
```

## Enumeration Cases

| Case | Description |
| - | - |
| `address(_:)` | - |
| `externalWallet(_:_:)` | - |
| `owner(_:_:)` | - |
| `ownerWithChain(_:_:)` | - |

## Initializers

### init(from:)

```swift theme={null}
init(from locator: String) throws
```

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `value` | `String` | - |

## Instance Methods

### encode(to:)

Inherited from `Encodable.encode(to:)`.

```swift theme={null}
func encode(to encoder: any Encoder) throws
```


# WalletType
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/enums/wallettype

Swift Enumeration

**Enumeration**

```swift theme={null}
enum WalletType
```

## Enumeration Cases

| Case | Description |
| - | - |
| `mpc` | - |
| `smart` | - |

## Initializers

### init(rawValue:)

Inherited from `RawRepresentable.init(rawValue:)`.

```swift theme={null}
init?(rawValue: String)
```


# Logger
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/extensions/logger

Swift Extended Module

**Extended Module**

## Extended Structures

### Logger

```swift theme={null}
extension Logger
```


# SwiftUICore
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/extensions/swiftuicore

Swift Extended Module

**Extended Module**

## Extended Protocols

### View

```swift theme={null}
extension View
```


# getBlockchainExplorerURL(for:)
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/functions/getblockchainexplorerurl-for

Swift Function

**Function**

```swift theme={null}
func getBlockchainExplorerURL(for link: BlockchainExplorerLinkType) -> String
```


# AdminSignerApiModel
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/protocols/adminsignerapimodel

Swift Protocol

**Protocol**

```swift theme={null}
protocol AdminSignerApiModel : Decodable, Encodable
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `toDomain` | `any AdminSignerData` | - |
| `type` | `AdminSignerDataType` | - |


# AdminSignerData
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/protocols/adminsignerdata

Swift Protocol

**Protocol**

```swift theme={null}
protocol AdminSignerData : Sendable
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `locator` | `String` | - |
| `locatorId` | `String` | - |
| `type` | `AdminSignerDataType` | - |


# AnyChain
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/protocols/anychain

Swift Protocol

**Protocol**

```swift theme={null}
protocol AnyChain : Sendable
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | - |
| `name` | `String` | - |

## Instance Methods

### isValid(isProductionEnvironment:)

```swift theme={null}
func isValid(isProductionEnvironment: Bool) -> Bool
```


# ApprovalSigner
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/protocols/approvalsigner

Swift Protocol

**Protocol**

A signer that can approve a transaction or a signature request. Every `Signer` is an `ApprovalSigner`. The device signer conforms to this protocol only.

```swift theme={null}
protocol ApprovalSigner : Sendable
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `locator` | `SignerLocator?` | The locator that the Crossmint API uses for this signer. `nil` when the signer does not have a locator yet, for example a device signer with no key. |

## Instance Methods

### approvals(for:)

Signs `message`. Returns the approvals to send for this message.

```swift theme={null}
func approvals(for message: String) async throws(SignerError) -> [SignRequestApi.Approval]
```

### initialize()

```swift theme={null}
func initialize() async throws(SignerError)
```

### initialize(\_:)

Makes the signer ready to approve through `service`. A signer with no setup step does nothing.

```swift theme={null}
func initialize(_ service: (any SmartWalletService)?) async throws(SignerError)
```


# AuthClient
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/protocols/authclient

Swift Protocol

**Protocol**

Standalone authentication client for apps that manage auth independently of wallet operations.

```swift theme={null}
protocol AuthClient : Sendable
```

## Overview

Access via `CrossmintSDK/authClient`. For most apps the built-in email OTP flow through `CrossmintAuthManager` is sufficient; use `AuthClient` when you need explicit control over the OTP lifecycle (e.g. custom UI, headless flows).

## Example

```swift theme={null}
let client = CrossmintSDK.shared.authClient

let request = try await client.sendOTP(to: "user@example.com")
// ... show OTP input to user ...
let session = try await client.verifyOTP(code: userInput, requestId: request.requestId)
print("Signed in:", session.user.email)
```

## Instance Methods

### logout()

Invalidates the current session.

```swift theme={null}
func logout() async
```

### sendOTP(to:)

Sends an OTP to the given email address.

```swift theme={null}
func sendOTP(to email: String) async throws(AuthError) -> OTPRequest
```

#### Return Value

An `OTPRequest` whose `requestId` is required by `verifyOTP(code:requestId:)`.

### verifyOTP(code:requestId:)

Validates the OTP and establishes a session.

```swift theme={null}
func verifyOTP(code: String, requestId: String) async throws(AuthError) -> AuthSession
```

#### Parameters

| Parameter | Description |
| - | - |
| `code` | The code the user entered. |
| `requestId` | The value from the `OTPRequest` returned by `sendOTP(to:)`. |


# AuthManager
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/protocols/authmanager

Swift Protocol

**Protocol**

Provides the current user’s JWT to the SDK for authenticated requests.

```swift theme={null}
protocol AuthManager : Sendable
```

## Overview

The built-in implementation is `CrossmintAuthManager`, which handles email OTP sessions. Provide a custom conformance to integrate an existing auth system — only `jwt` and `setJWT(_:)` are required.

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `jwt` | `String?` | The current session JWT, or `nil` when the user is not authenticated. |

## Instance Methods

### setJWT(\_:)

Injects an externally-obtained JWT into the SDK session.

```swift theme={null}
func setJWT(_ jwt: String) async
```


# AuthService
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/protocols/authservice

Swift Protocol

**Protocol**

```swift theme={null}
protocol AuthService : Sendable
```

## Instance Methods

### logout(\_:)

```swift theme={null}
func logout(_ logoutRequest: LogoutRequest) async throws(AuthError)
```

### refreshJWT(\_:)

```swift theme={null}
func refreshJWT(_ refreshJWTRequest: RefreshJWTRequest) async throws(AuthError) -> RefreshJWTResponse
```

### validateEmail(\_:)

```swift theme={null}
func validateEmail(_ validateEmailRequest: ValidateEmailRequest) async throws(AuthError) -> ValidateEmailResponse
```

### validateToken(\_:)

```swift theme={null}
func validateToken(_ validateTokenRequest: ValidateTokenRequest) async throws(AuthError) -> ValidateTokenResponse
```


# BalanceService
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/protocols/balanceservice

Swift Protocol

**Protocol**

```swift theme={null}
protocol BalanceService : Sendable
```

## Instance Methods

### getBalance(\_:)

```swift theme={null}
func getBalance(_ params: GetBalanceQueryParams) async throws(WalletError) -> Balances
```


# BlockchainAddress
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/protocols/blockchainaddress

Swift Protocol

**Protocol**

```swift theme={null}
protocol BlockchainAddress : CustomStringConvertible, Decodable, Encodable, Hashable, Sendable
```

## Initializers

### init(address:)

```swift theme={null}
init(address: String) throws(BlockchainAddressError)
```


# ChainWithSigners
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/protocols/chainwithsigners

Swift Protocol

**Protocol**

Protocol that associates a `SpecificChain` with its corresponding `SignerProvider`.

```swift theme={null}
protocol ChainWithSigners : SpecificChain
```

## Overview

This protocol extends `SpecificChain` to add the signer provider association, enabling generic wallet creation methods that work across all chains without requiring separate method overloads per chain type.

## Associated Types

### SpecificSigner

```swift theme={null}
associatedtype SpecificSigner : SignerProvider
```

### WalletType

```swift theme={null}
associatedtype WalletType : Wallet
```


# CrossmintWallets
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/protocols/crossmintwallets

Swift Protocol

**Protocol**

Factory for obtaining and creating Crossmint smart wallets.

```swift theme={null}
protocol CrossmintWallets : Sendable
```

## Overview

Obtain an instance from `ClientSDK/crossmintWallets()` or `CrossmintSDK/crossmintWallets`. Prefer the chain-specific overloads (e.g. `getWallet(chain:options:)`) over the generic ones so you get a typed wallet back without an additional cast.

## Example

```swift theme={null}
let wallets = CrossmintSDK.shared.crossmintWallets

// Get or create an EVM wallet with email recovery
if let wallet = try await wallets.getWallet(chain: .baseMainnet) {
    print("Existing wallet:", wallet.address)
} else {
    let wallet = try await wallets.createWallet(
        chain: .baseMainnet,
        recoveryMethods: [.email("user@example.com")]
    )
    print("New wallet:", wallet.address)
}

// Solana and Stellar accept several recovery signers. Each one can authorize on its own.
let solanaWallet = try await wallets.createWallet(
    chain: .solana,
    recoveryMethods: [.email("user@example.com"), .phone("+15551234567")]
)
```

## Instance Methods

### createWallet(chain:recovery:options:)

Creates a new smart wallet for the authenticated user on the given chain.

```swift theme={null}
func createWallet(chain: Chain, recovery: any Signer, options: WalletOptions?) async throws(WalletError) -> Wallet
```

#### Parameters

| Parameter | Description |
| - | - |
| `chain` | The blockchain to deploy to. |
| `recovery` | The signer that can authorize recovery operations for this wallet. |
| `options` | Optional configuration, such as enabling a device signer. |

### createWallet(chain:recoveryMethods:options:)

Creates a new smart wallet for the authenticated user on the given chain.

```swift theme={null}
func createWallet(chain: Chain, recoveryMethods: [any Signer], options: WalletOptions?) async throws(WalletError) -> Wallet
```

#### Discussion

Deploys the wallet contract on-chain. Calling this when a wallet already exists returns the existing wallet rather than creating a duplicate.
Each recovery signer can authorize on its own. The wallet stays usable when the user loses one of them. Only Solana and Stellar accept more than one recovery signer. The wallet’s first recovery signer, as the API reports it, is the active signer until `useSigner(_:)` selects another one.

> **Throws**: `WalletError.recoveryConfigRejected(code:message:)` in these conditions:
>
> * The list is empty.
> * The list has more than one signer, and the chain accepts only one.
> * The list has a passkey, and the chain is Solana.

#### Parameters

| Parameter | Description |
| - | - |
| `chain` | The blockchain to deploy to. |
| `recoveryMethods` | The signers that can each authorize recovery operations for this wallet. To use an external wallet as a recovery signer, pass an `ExternalWalletSigner`. |
| `options` | Optional configuration, such as enabling a device signer. |

### createWallet(chain:recoveryMethods:signers:options:)

Creates a new smart wallet for the authenticated user, with more signers on the wallet.

```swift theme={null}
func createWallet(chain: Chain, recoveryMethods: [any Signer], signers: [SignerConfig], options: WalletOptions?) async throws(WalletError) -> Wallet
```

#### Discussion

The SDK adds the signers when it creates the wallet. The recovery method does not approve them.

> **Throws**: `WalletError.recoveryConfigRejected(code:message:)` if the recovery list is empty. The SDK also throws this error if the list has more than one signer on a chain that accepts one. `WalletError.walletCreationCancelled` if the user cancels the passkey creation.

#### Parameters

| Parameter | Description |
| - | - |
| `chain` | The blockchain to deploy to. |
| `recoveryMethods` | The signers that can each authorize recovery operations for this wallet. |
| `signers` | The signers to add to the wallet. For `SignerConfig/passkey(name:host:)`, the SDK asks the user to create the passkey first. `SignerConfig.device` has the same effect as `deviceSigner`. |
| `options` | Optional configuration, such as enabling a device signer. |

### getWallet(chain:options:)

Returns the wallet of the authenticated user on the given chain. Returns `nil` if the wallet does not exist.

```swift theme={null}
func getWallet(chain: Chain, options: WalletOptions?) async throws(WalletError) -> Wallet?
```

#### Discussion

The SDK selects the signer for transactions:

* If `signers()` has only one signer, the SDK uses that signer. This applies to email, phone, API key, and passkey signers.
* If not, the SDK uses the first recovery method of the wallet.
  To use a different signer, call `useSigner(_:)`.
  To sign with a passkey, set `passkeyHost` in `options`. To sign with an external wallet, call `useSigner(_:)` before you send a transaction.

#### Parameters

| Parameter | Description |
| - | - |
| `chain` | The blockchain to look up. |
| `options` | Optional configuration, such as enabling a device signer. |

### getWallet(chain:recovery:options:)

Returns the wallet for the authenticated user on the given chain, or `nil` if none exists yet.

```swift theme={null}
func getWallet(chain: Chain, recovery: any Signer, options: WalletOptions?) async throws(WalletError) -> Wallet?
```

#### Parameters

| Parameter | Description |
| - | - |
| `chain` | The blockchain to look up. |
| `recovery` | The signer that can authorize recovery operations for this wallet. |
| `options` | Optional configuration, such as enabling a device signer. |


# EVMCompatibleSigner
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/protocols/evmcompatiblesigner

Swift Protocol

**Protocol**

```swift theme={null}
protocol EVMCompatibleSigner : Sendable
```


# NFTService
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/protocols/nftservice

Swift Protocol

**Protocol**

```swift theme={null}
protocol NFTService : Sendable
```

## Instance Methods

### getNFTs(\_:)

```swift theme={null}
func getNFTs(_ params: GetNTFQueryParams) async throws(WalletError) -> [NFT]
```


# SignatureApiModel
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/protocols/signatureapimodel

Swift Protocol

**Protocol**

```swift theme={null}
protocol SignatureApiModel : Decodable
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `approvals` | `Approvals` | - |
| `chainType` | `String?` | - |
| `createdAt` | `Date` | - |
| `id` | `String` | - |
| `status` | `String` | - |
| `type` | `String` | - |
| `walletType` | `String?` | - |


# SignatureService
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/protocols/signatureservice

Swift Protocol

**Protocol**

```swift theme={null}
protocol SignatureService : Sendable
```

## Instance Methods

### approveSignature(\_:)

```swift theme={null}
func approveSignature(_ request: SignRequest) async throws(SignatureError)
```

### createSignature(\_:)

```swift theme={null}
func createSignature(_ request: CreateSignatureRequest) async throws(SignatureError) -> any SignatureApiModel
```

### fetchSignature(\_:chainType:)

```swift theme={null}
func fetchSignature(_ signatureId: String, chainType: ChainType) async throws(SignatureError) -> any SignatureApiModel
```


# Signer
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/protocols/signer

Swift Protocol

**Protocol**

```swift theme={null}
protocol Signer<AdminType> : ApprovalSigner
```

## Associated Types

### AdminType

```swift theme={null}
associatedtype AdminType : AdminSignerData
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `adminSigner` | `Self.AdminType` | - |
| `signerType` | `SignerType` | - |

## Instance Methods

### approvals(withSignature:)

```swift theme={null}
func approvals(withSignature signature: String) async throws(SignerError) -> [SignRequestApi.Approval]
```

### sign(message:)

```swift theme={null}
func sign(message: String) async throws(SignerError) -> String
```


# SignerProvider
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/protocols/signerprovider

Swift Protocol

**Protocol**

```swift theme={null}
protocol SignerProvider : Sendable
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `signer` | `any Signer` | - |


# SmartWalletCreationQueryParams
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/protocols/smartwalletcreationqueryparams

Swift Protocol

**Protocol**

```swift theme={null}
protocol SmartWalletCreationQueryParams : Encodable, Sendable
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `type` | `WalletType` | - |


# SmartWalletService
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/protocols/smartwalletservice

Swift Protocol

**Protocol**

```swift theme={null}
protocol SmartWalletService : BalanceService, NFTService, SignatureService, TransactionService, TransferService, WalletService
```


# SolanaCompatibleSigner
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/protocols/solanacompatiblesigner

Swift Protocol

**Protocol**

```swift theme={null}
protocol SolanaCompatibleSigner : Sendable
```


# SpecificChain
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/protocols/specificchain

Swift Protocol

**Protocol**

```swift theme={null}
protocol SpecificChain : AnyChain, Decodable, Encodable, Hashable
```

## Operators

### !=(\_:\_:)

```swift theme={null}
static func != (lhs: Chain, rhs: Self) -> Bool
```

### !=(\_:\_:)

```swift theme={null}
static func != (lhs: Self, rhs: Chain) -> Bool
```

## Initializers

### init(\_:)

```swift theme={null}
init?(_ from: String)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `chain` | `Chain` | - |


# StellarCompatibleSigner
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/protocols/stellarcompatiblesigner

Swift Protocol

**Protocol**

```swift theme={null}
protocol StellarCompatibleSigner : Sendable
```


# TransactionApiModel
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/protocols/transactionapimodel

Swift Protocol

**Protocol**

```swift theme={null}
protocol TransactionApiModel : Decodable, Identifiable
```

## Instance Methods

### toDomain()

```swift theme={null}
func toDomain() -> Transaction
```


# TransactionRequest
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/protocols/transactionrequest

Swift Protocol

**Protocol**

```swift theme={null}
protocol TransactionRequest : Encodable, Sendable
```


# TransactionService
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/protocols/transactionservice

Swift Protocol

**Protocol**

```swift theme={null}
protocol TransactionService : Sendable
```

## Instance Methods

### createTransaction(\_:)

```swift theme={null}
func createTransaction(_ request: CreateTransactionRequest) async throws(TransactionError) -> any TransactionApiModel
```

### fetchTransaction(\_:)

```swift theme={null}
func fetchTransaction(_ request: FetchTransactionRequest) async throws(TransactionError) -> any TransactionApiModel
```

### listTransactions(\_:)

```swift theme={null}
func listTransactions(_ request: ListTransactionsRequest) async throws(TransactionError) -> [Transaction]
```

### signTransaction(\_:)

```swift theme={null}
func signTransaction(_ request: SignRequest) async throws(TransactionError) -> any TransactionApiModel
```


# TransferService
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/protocols/transferservice

Swift Protocol

**Protocol**

```swift theme={null}
protocol TransferService : Sendable
```

## Instance Methods

### listTransfers(\_:)

```swift theme={null}
func listTransfers(_ params: ListTransfersQueryParams) async throws(WalletError) -> TransferListResult
```

### transferToken(\_:)

```swift theme={null}
func transferToken(_ request: TransferTokenRequest) async throws(TransactionError) -> any TransactionApiModel
```


# WalletOnChain
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/protocols/walletonchain

Swift Protocol

**Protocol**

```swift theme={null}
protocol WalletOnChain
```

## Associated Types

### SpecificChain

```swift theme={null}
associatedtype SpecificChain : AnyChain
```

## Instance Methods

### fund(token:amount:on:)

```swift theme={null}
func fund(token: CryptoCurrency, amount: Int, on chain: Self.SpecificChain) async throws(WalletError)
```

### nfts(page:nftsPerPage:on:)

```swift theme={null}
func nfts(page: Int, nftsPerPage: Int, on chain: Self.SpecificChain) async throws(WalletError) -> [NFT]
```


# WalletService
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/protocols/walletservice

Swift Protocol

**Protocol**

```swift theme={null}
protocol WalletService : Sendable
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `isProductionEnvironment` | `Bool` | - |

## Instance Methods

### addRecoveryMethod(\_:chainType:approver:)

```swift theme={null}
func addRecoveryMethod(_ recoveryMethod: any AdminSignerData, chainType: ChainType, approver: SignerLocator) async throws(WalletError) -> any TransactionApiModel
```

### addSigner(\_:chainType:chainName:deployImmediately:)

```swift theme={null}
func addSigner(_ entry: DelegatedSignerEntry, chainType: ChainType, chainName: String, deployImmediately: Bool?) async throws(WalletError) -> AddDelegatedSignerResponse
```

### addSigner(\_:chainType:chainName:deployImmediately:approver:)

```swift theme={null}
func addSigner(_ entry: DelegatedSignerEntry, chainType: ChainType, chainName: String, deployImmediately: Bool?, approver: SignerLocator?) async throws(WalletError) -> AddDelegatedSignerResponse
```

### createWallet(\_:)

```swift theme={null}
func createWallet(_ request: CreateWalletParams) async throws(WalletError) -> WalletApiModel
```

### fund(\_:)

```swift theme={null}
func fund(_ request: FundWalletRequest) async throws(WalletError)
```

### getSigner(\_:chainType:)

```swift theme={null}
func getSigner(_ signerLocator: String, chainType: ChainType) async throws(WalletError) -> AddDelegatedSignerResponse?
```

### getWallet(\_:)

```swift theme={null}
func getWallet(_ request: GetMeWalletRequest) async throws(WalletError) -> WalletApiModel
```

### registerTypedSigner(\_:chainType:chainName:deployImmediately:)

```swift theme={null}
func registerTypedSigner(_ signer: any AdminSignerData, chainType: ChainType, chainName: String, deployImmediately: Bool?) async throws(WalletError) -> AddDelegatedSignerResponse
```

### registerTypedSigner(\_:chainType:chainName:deployImmediately:approver:)

```swift theme={null}
func registerTypedSigner(_ signer: any AdminSignerData, chainType: ChainType, chainName: String, deployImmediately: Bool?, approver: SignerLocator?) async throws(WalletError) -> AddDelegatedSignerResponse
```

### removeRecoveryMethod(\_:chainType:approver:)

```swift theme={null}
func removeRecoveryMethod(_ locator: SignerLocator, chainType: ChainType, approver: SignerLocator) async throws(WalletError) -> any TransactionApiModel
```

### removeSigner(\_:chainType:chainName:)

```swift theme={null}
func removeSigner(_ signerLocator: String, chainType: ChainType, chainName: String) async throws(TransactionError) -> any TransactionApiModel
```

### removeSigner(\_:chainType:chainName:approver:)

```swift theme={null}
func removeSigner(_ signerLocator: String, chainType: ChainType, chainName: String, approver: SignerLocator?) async throws(TransactionError) -> any TransactionApiModel
```


# WalletTypeTransactionMapping
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/protocols/wallettypetransactionmapping

Swift Protocol

**Protocol**

```swift theme={null}
protocol WalletTypeTransactionMapping
```

## Associated Types

### APIModel

```swift theme={null}
associatedtype APIModel : TransactionApiModel
```

## Type Properties

| Property | Type | Description |
| - | - | - |
| `chainType` | `ChainType` | - |


# ABIAddress
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/abiaddress

Swift Structure

**Structure**

```swift theme={null}
struct ABIAddress
```

## Initializers

### init(address:)

```swift theme={null}
init(address: String)
```


# ABIUInt64
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/abiuint64

Swift Structure

**Structure**

```swift theme={null}
struct ABIUInt64
```

## Initializers

### init(uint:)

```swift theme={null}
init(uint: UInt64)
```


# AddDelegatedSignerResponse
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/adddelegatedsignerresponse

Swift Structure

**Structure**

```swift theme={null}
struct AddDelegatedSignerResponse
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `chains` | `[String : ChainRegistrationEntry]?` | - |
| `transaction` | `RegistrationTransaction?` | - |


# ApiKeySignerApiModel
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/apikeysignerapimodel

Swift Structure

**Structure**

```swift theme={null}
struct ApiKeySignerApiModel
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `address` | `String` | - |
| `locator` | `String` | - |
| `toDomain` | `any AdminSignerData` | Inherited from `AdminSignerApiModel.toDomain`. |
| `type` | `AdminSignerDataType` | Inherited from `AdminSignerApiModel.type`. |


# ApiKeySignerData
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/apikeysignerdata

Swift Structure

**Structure**

```swift theme={null}
struct ApiKeySignerData
```

## Initializers

### init(address:)

```swift theme={null}
init(address: String? = nil)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `address` | `String?` | - |
| `locator` | `String` | Inherited from `AdminSignerData.locator`. |
| `locatorId` | `String` | Inherited from `AdminSignerData.locatorId`. |
| `type` | `AdminSignerDataType` | Inherited from `AdminSignerData.type`. |


# ApprovalEntry
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/approvalentry

Swift Structure

**Structure**

```swift theme={null}
struct ApprovalEntry
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```


# Approvals
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/approvals

Swift Structure

**Structure**

```swift theme={null}
struct Approvals
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```


# AuthSession
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/authsession

Swift Structure

**Structure**

The authenticated session returned after a successful OTP verification.

```swift theme={null}
struct AuthSession
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `jwt` | `String` | A short-lived JWT for authorizing requests to Crossmint APIs. |
| `user` | `AuthUser` | Details about the authenticated user. |


# AuthUser
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/authuser

Swift Structure

**Structure**

Identifies the authenticated user within an `AuthSession`.

```swift theme={null}
struct AuthUser
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `email` | `String` | - |


# Balance
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/balance

Swift Structure

**Structure**

```swift theme={null}
struct Balance
```

## Initializers

### init(nativeToken:usdc:tokens:)

```swift theme={null}
init(nativeToken: TokenBalance, usdc: TokenBalance, tokens: [TokenBalance])
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `nativeToken` | `TokenBalance` | - |
| `tokens` | `[TokenBalance]` | - |
| `usdc` | `TokenBalance` | - |


# Balances
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/balances

Swift Structure

**Structure**

```swift theme={null}
struct Balances
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `isEmpty` | `Bool` | - |
| `tokens` | `[CryptoCurrency]` | - |

## Instance Methods

### filter(\_:)

```swift theme={null}
func filter(_ isIncluded: (CryptoCurrency, ChainBalances) -> Bool) -> Balances
```

### nonZeroBalances()

```swift theme={null}
func nonZeroBalances() -> Balances
```

## Subscripts

### subscript(\_:)

```swift theme={null}
subscript(currency: CryptoCurrency) -> ChainBalances? { get }
```


# BlockchainAddressLink
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/blockchainaddresslink

Swift Structure

**Structure**

```swift theme={null}
struct BlockchainAddressLink
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `address` | `String` | - |
| `chain` | `Chain` | - |


# BlockchainTokenLink
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/blockchaintokenlink

Swift Structure

**Structure**

```swift theme={null}
struct BlockchainTokenLink
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `options` | `TokenLinkOptions?` | - |
| `tokenLocator` | `String` | - |


# BlockchainTransactionLink
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/blockchaintransactionlink

Swift Structure

**Structure**

```swift theme={null}
struct BlockchainTransactionLink
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `chain` | `Chain` | - |
| `txId` | `String` | - |


# ChainBalances
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/chainbalances

Swift Structure

**Structure**

```swift theme={null}
struct ChainBalances
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `chainBalances` | `[Chain : Decimal]` | - |
| `decimals` | `Int` | - |
| `total` | `Decimal` | - |

## Instance Methods

### convertToBaseUnits(\_:)

```swift theme={null}
func convertToBaseUnits(_ value: String) -> String?
```

## Subscripts

### subscript(\_:)

```swift theme={null}
subscript(chain: Chain) -> Decimal { get }
```


# ChainRegistrationEntry
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/chainregistrationentry

Swift Structure

**Structure**

```swift theme={null}
struct ChainRegistrationEntry
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `approvals` | `RegistrationApprovals?` | - |
| `id` | `String?` | - |
| `onChain` | `ChainRegistrationOnChain?` | - |
| `status` | `SignerStatus` | - |


# ChainRegistrationOnChain
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/chainregistrationonchain

Swift Structure

**Structure**

Marker for an on-chain (transaction) registration entry. When present, approval goes through the transaction flow instead of the signature flow.

```swift theme={null}
struct ChainRegistrationOnChain
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```


# CreateEVMTransactionRequest
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/createevmtransactionrequest

Swift Structure

**Structure**

```swift theme={null}
struct CreateEVMTransactionRequest
```

## Instance Methods

### encode(to:)

Inherited from `Encodable.encode(to:)`.

```swift theme={null}
func encode(to encoder: any Encoder) throws
```


# CreateSignatureRequest
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/createsignaturerequest

Swift Structure

**Structure**

```swift theme={null}
struct CreateSignatureRequest
```

## Initializers

### init(signMessageRequest:chainType:)

```swift theme={null}
init(signMessageRequest: SignMessageRequest, chainType: ChainType)
```

### init(signTypedDataRequest:chainType:)

```swift theme={null}
init(signTypedDataRequest: SignTypedDataRequest, chainType: ChainType)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `body` | `CreateSignatureRequest.Body` | - |
| `chainType` | `ChainType` | - |

## Enumerations

### CreateSignatureRequest.Body

```swift theme={null}
enum Body
```


# CreateSolanaTransactionRequest
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/createsolanatransactionrequest

Swift Structure

**Structure**

```swift theme={null}
struct CreateSolanaTransactionRequest
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

### init(transaction:signer:)

```swift theme={null}
init(transaction: String, signer: String? = nil)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `signer` | `String?` | Locator of the signer that authorizes the transaction. When `nil`, the wallet’s first recovery signer authorizes it. |
| `transaction` | `String` | - |

## Instance Methods

### encode(to:)

Inherited from `Encodable.encode(to:)`.

```swift theme={null}
func encode(to encoder: any Encoder) throws
```


# CreateStellarTransactionRequest
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/createstellartransactionrequest

Swift Structure

**Structure**

```swift theme={null}
struct CreateStellarTransactionRequest
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

### init(transaction:signer:)

```swift theme={null}
init(transaction: String, signer: String? = nil)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `signer` | `String?` | Locator of the signer that authorizes the transaction. When `nil`, the wallet’s first recovery signer authorizes it. |
| `transaction` | `String` | - |

## Instance Methods

### encode(to:)

Inherited from `Encodable.encode(to:)`.

```swift theme={null}
func encode(to encoder: any Encoder) throws
```


# CreateTransactionRequest
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/createtransactionrequest

Swift Structure

**Structure**

```swift theme={null}
struct CreateTransactionRequest
```


# CreateWalletParams
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/createwalletparams

Swift Structure

**Structure**

```swift theme={null}
struct CreateWalletParams
```


# DelegatedSignerEntry
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/delegatedsignerentry

Swift Structure

**Structure**

```swift theme={null}
struct DelegatedSignerEntry
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `signer` | `DelegatedSignerEntry.Signer` | - |

## Enumerations

### DelegatedSignerEntry.Signer

```swift theme={null}
enum Signer
```


# DevicePublicKey
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/devicepublickey

Swift Structure

**Structure**

```swift theme={null}
struct DevicePublicKey
```

## Initializers

### init(publicKeyBase64:)

Splits a base64-encoded 65-byte uncompressed P-256 public key (0x04 ‖ x ‖ y) into its `0x`-prefixed hex coordinates. Fails when the key is not in that format.

```swift theme={null}
init?(publicKeyBase64: String)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `x` | `String` | - |
| `y` | `String` | - |


# EmailSignerApiModel
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/emailsignerapimodel

Swift Structure

**Structure**

```swift theme={null}
struct EmailSignerApiModel
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `email` | `String` | - |
| `locator` | `String` | - |
| `toDomain` | `any AdminSignerData` | Inherited from `AdminSignerApiModel.toDomain`. |
| `type` | `AdminSignerDataType` | Inherited from `AdminSignerApiModel.type`. |


# EmailSignerData
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/emailsignerdata

Swift Structure

**Structure**

```swift theme={null}
struct EmailSignerData
```

## Initializers

### init(email:)

```swift theme={null}
init(email: String)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `email` | `String` | - |
| `locatorId` | `String` | Inherited from `AdminSignerData.locatorId`. |
| `type` | `AdminSignerDataType` | Inherited from `AdminSignerData.type`. |


# ERC20Encoder
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/erc20encoder

Swift Structure

**Structure**

```swift theme={null}
struct ERC20Encoder
```

## Type Methods

### encode(functionName:arguments:)

```swift theme={null}
static func encode(functionName: String, arguments: [ABI.Argument]) throws(ERC20Encoder.Error) -> String
```

## Enumerations

### ERC20Encoder.Error

```swift theme={null}
enum Error
```


# EVMAddress
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/evmaddress

Swift Structure

**Structure**

```swift theme={null}
struct EVMAddress
```

## Initializers

### init(address:)

Inherited from `BlockchainAddress.init(address:)`.

```swift theme={null}
init(address: String) throws(BlockchainAddressError)
```

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `address` | `String` | - |
| `description` | `String` | Inherited from `CustomStringConvertible.description`. |

## Instance Methods

### encode(to:)

Inherited from `Encodable.encode(to:)`.

```swift theme={null}
func encode(to encoder: any Encoder) throws
```


# EvmPasskeySignerApiModel
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/evmpasskeysignerapimodel

Swift Structure

**Structure**

```swift theme={null}
struct EvmPasskeySignerApiModel
```

## Structures

### EvmPasskeySignerApiModel.PublicKey

```swift theme={null}
struct PublicKey
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `id` | `String` | - |
| `locator` | `String` | - |
| `name` | `String` | - |
| `publicKey` | `EvmPasskeySignerApiModel.PublicKey` | - |
| `toDomain` | `any AdminSignerData` | Inherited from `AdminSignerApiModel.toDomain`. |
| `type` | `AdminSignerDataType` | Inherited from `AdminSignerApiModel.type`. |
| `validatorContractVersion` | `String?` | - |


# EVMTransactionApiModel
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/evmtransactionapimodel

Swift Structure

**Structure**

```swift theme={null}
struct EVMTransactionApiModel
```

## Structures

### EVMTransactionApiModel.Call

```swift theme={null}
struct Call
```

### EVMTransactionApiModel.OnChainData

```swift theme={null}
struct OnChainData
```

### EVMTransactionApiModel.Params

```swift theme={null}
struct Params
```

### EVMTransactionApiModel.UserOperation

```swift theme={null}
struct UserOperation
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `approvals` | `Approvals?` | - |
| `createdAt` | `Date` | - |
| `error` | `TransactionErrorApiModel?` | - |
| `id` | `String` | Inherited from `Identifiable.id`. |
| `onChain` | `EVMTransactionApiModel.OnChainData` | - |
| `params` | `EVMTransactionApiModel.Params` | - |
| `status` | `TransactionStatusApiModel` | - |
| `walletType` | `WalletType` | - |

## Instance Methods

### toDomain()

Inherited from `TransactionApiModel.toDomain()`.

```swift theme={null}
func toDomain() -> Transaction
```


# ExternalWalletSigner
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/externalwalletsigner

Swift Structure

**Structure**

A signer that uses an external wallet, for example a wallet app or a hardware wallet.

```swift theme={null}
struct ExternalWalletSigner
```

## Overview

To use the external wallet as a recovery signer, pass this signer in `recoveryMethods` to `createWallet(chain:recoveryMethods:options:)`. To sign with the external wallet, pass `SignerConfig.externalWallet(_:onSign:)` to `useSigner(_:)`.
For the message that `onSign` receives and the signature that it returns, see `SignerConfig.externalWallet(_:onSign:)`.

## Initializers

### init(address:onSign:)

Makes a signer for the external wallet at `address`.

```swift theme={null}
init(address: String, onSign: @escaping @Sendable (String) async throws -> String)
```

#### Parameters

| Parameter | Description |
| - | - |
| `address` | The address of the external wallet. |
| `onSign` | Signs a message with the external wallet and returns the signature. See `SignerConfig.externalWallet(_:onSign:)`. |

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `adminSigner` | `ExternalWalletSignerData` | Inherited from `Signer.adminSigner`. |
| `signerType` | `SignerType` | Inherited from `Signer.signerType`. |

## Instance Methods

### approvals(withSignature:)

Inherited from `Signer.approvals(withSignature:)`.

```swift theme={null}
func approvals(withSignature signature: String) async throws(SignerError) -> [SignRequestApi.Approval]
```

### initialize(\_:)

Inherited from `ApprovalSigner.initialize(_:)`.

```swift theme={null}
func initialize(_ service: (any SmartWalletService)?) async throws(SignerError)
```

### sign(message:)

Inherited from `Signer.sign(message:)`.

```swift theme={null}
func sign(message: String) async throws(SignerError) -> String
```

## Type Aliases

### ExternalWalletSigner.AdminType

Inherited from `Signer.AdminType`.

```swift theme={null}
typealias AdminType = ExternalWalletSignerData
```


# ExternalWalletSignerApiModel
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/externalwalletsignerapimodel

Swift Structure

**Structure**

```swift theme={null}
struct ExternalWalletSignerApiModel
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `address` | `String` | - |
| `locator` | `String` | - |
| `toDomain` | `any AdminSignerData` | Inherited from `AdminSignerApiModel.toDomain`. |
| `type` | `AdminSignerDataType` | Inherited from `AdminSignerApiModel.type`. |


# ExternalWalletSignerData
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/externalwalletsignerdata

Swift Structure

**Structure**

```swift theme={null}
struct ExternalWalletSignerData
```

## Initializers

### init(address:)

```swift theme={null}
init(address: String)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `address` | `String` | - |
| `locatorId` | `String` | Inherited from `AdminSignerData.locatorId`. |
| `type` | `AdminSignerDataType` | Inherited from `AdminSignerData.type`. |


# FetchTransactionRequest
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/fetchtransactionrequest

Swift Structure

**Structure**

```swift theme={null}
struct FetchTransactionRequest
```


# FundWalletApiRequest
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/fundwalletapirequest

Swift Structure

**Structure**

```swift theme={null}
struct FundWalletApiRequest
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

### init(token:amount:chain:)

```swift theme={null}
init(token: String, amount: Int, chain: String)
```


# FundWalletRequest
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/fundwalletrequest

Swift Structure

**Structure**

```swift theme={null}
struct FundWalletRequest
```


# GetBalanceQueryParams
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/getbalancequeryparams

Swift Structure

**Structure**

```swift theme={null}
struct GetBalanceQueryParams
```

## Initializers

### init(walletLocator:token:chain:)

```swift theme={null}
init(walletLocator: WalletLocator, token: CryptoCurrency, chain: Chain)
```

### init(walletLocator:tokens:chains:)

```swift theme={null}
init(walletLocator: WalletLocator, tokens: [CryptoCurrency], chains: [any AnyChain] = [])
```


# GetMeWalletRequest
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/getmewalletrequest

Swift Structure

**Structure**

```swift theme={null}
struct GetMeWalletRequest
```

## Initializers

### init(chainType:)

```swift theme={null}
init(chainType: ChainType)
```


# GetNTFQueryParams
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/getntfqueryparams

Swift Structure

**Structure**

```swift theme={null}
struct GetNTFQueryParams
```

## Initializers

### init(walletLocator:chain:page:perPage:)

```swift theme={null}
init(walletLocator: WalletLocator, chain: any AnyChain, page: Int, perPage: Int)
```


# GetTransationQueryParams
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/gettransationqueryparams

Swift Structure

**Structure**

```swift theme={null}
struct GetTransationQueryParams
```

## Initializers

### init(walletLocator:transactionId:)

```swift theme={null}
init(walletLocator: WalletLocator, transactionId: String)
```


# ListTransactionsRequest
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/listtransactionsrequest

Swift Structure

**Structure**

```swift theme={null}
struct ListTransactionsRequest
```


# ListTransfersQueryParams
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/listtransfersqueryparams

Swift Structure

**Structure**

Query parameters for listing wallet activity.

```swift theme={null}
struct ListTransfersQueryParams
```

## Initializers

### init(walletLocator:chain:tokens:)

```swift theme={null}
init(walletLocator: WalletLocator, chain: Chain, tokens: [CryptoCurrency])
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `chain` | `Chain` | The blockchain to query activity from. |
| `tokens` | `[CryptoCurrency]` | The tokens to filter activity by. |
| `walletLocator` | `WalletLocator` | The wallet locator to fetch activity for. |


# LogoutRequest
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/logoutrequest

Swift Structure

**Structure**

```swift theme={null}
struct LogoutRequest
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```


# MessageSignatureResponse
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/messagesignatureresponse

Swift Structure

**Structure**

```swift theme={null}
struct MessageSignatureResponse
```

## Structures

### MessageSignatureResponse.MessageParams

```swift theme={null}
struct MessageParams
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `approvals` | `Approvals` | Inherited from `SignatureApiModel.approvals`. |
| `chainType` | `String?` | Inherited from `SignatureApiModel.chainType`. |
| `createdAt` | `Date` | Inherited from `SignatureApiModel.createdAt`. |
| `id` | `String` | Inherited from `SignatureApiModel.id`. |
| `params` | `MessageSignatureResponse.MessageParams` | - |
| `status` | `String` | Inherited from `SignatureApiModel.status`. |
| `type` | `String` | Inherited from `SignatureApiModel.type`. |
| `walletType` | `String?` | Inherited from `SignatureApiModel.walletType`. |


# NFT
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/nft

Swift Structure

**Structure**

```swift theme={null}
struct NFT
```

## Structures

### NFT.Locator

```swift theme={null}
struct Locator
```

### NFT.Metadata

```swift theme={null}
struct Metadata
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `chain` | `Chain` | - |
| `contractAddress` | `String` | - |
| `id` | `String` | Inherited from `Identifiable.id`. |
| `locator` | `NFT.Locator` | - |
| `metadata` | `NFT.Metadata` | - |
| `tokenId` | `String` | - |
| `tokenStandard` | `String` | - |


# NonCustodialSignerCallback
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/noncustodialsignercallback

Swift Structure

**Structure**

```swift theme={null}
struct NonCustodialSignerCallback
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `otpCancelled` | `() -> Void` | - |
| `otpCode` | `(String) -> Void` | - |

## Type Properties

| Property | Type | Description |
| - | - | - |
| `noOp` | `NonCustodialSignerCallback` | - |


# OTPRequest
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/otprequest

Swift Structure

**Structure**

Carries the identifier needed to verify an OTP sent by `sendOTP(to:)`.

```swift theme={null}
struct OTPRequest
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `id` | `String` | Inherited from `Identifiable.id`. |
| `requestId` | `String` | Pass this to `verifyOTP(code:requestId:)` along with the user’s code. |


# PasskeySignerData
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/passkeysignerdata

Swift Structure

**Structure**

```swift theme={null}
struct PasskeySignerData
```

## Structures

### PasskeySignerData.PublicKey

```swift theme={null}
struct PublicKey
```

## Initializers

### init(id:name:publicKey:validatorContractVersion:)

```swift theme={null}
init(id: String, name: String, publicKey: PasskeySignerData.PublicKey, validatorContractVersion: String? = nil)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `id` | `String` | - |
| `locatorId` | `String` | Inherited from `AdminSignerData.locatorId`. |
| `name` | `String` | - |
| `publicKey` | `PasskeySignerData.PublicKey` | - |
| `type` | `AdminSignerDataType` | Inherited from `AdminSignerData.type`. |
| `validatorContractVersion` | `String?` | - |


# PhoneSignerApiModel
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/phonesignerapimodel

Swift Structure

**Structure**

```swift theme={null}
struct PhoneSignerApiModel
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `locator` | `String` | - |
| `phone` | `String` | - |
| `toDomain` | `any AdminSignerData` | Inherited from `AdminSignerApiModel.toDomain`. |
| `type` | `AdminSignerDataType` | Inherited from `AdminSignerApiModel.type`. |


# PhoneSignerData
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/phonesignerdata

Swift Structure

**Structure**

```swift theme={null}
struct PhoneSignerData
```

## Initializers

### init(phone:)

```swift theme={null}
init(phone: String)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `locatorId` | `String` | Inherited from `AdminSignerData.locatorId`. |
| `phone` | `String` | - |
| `type` | `AdminSignerDataType` | Inherited from `AdminSignerData.type`. |


# RecoveryMethod
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/recoverymethod

Swift Structure

**Structure**

A recovery method of a wallet, with its install status.

```swift theme={null}
struct RecoveryMethod
```

## Overview

A recovery method can recover the wallet only when its `status` is `SignerStatus.active`.

* `SignerStatus.active`: the signer is installed on the wallet.
* `SignerStatus.awaitingApproval`: the install waits for approval from a signer of the wallet.
* `SignerStatus.pending`: the install is in progress. Get the wallet again later to see the new status.
* `SignerStatus.failed`: the install did not complete. The signer cannot recover the wallet.
* `SignerStatus.unknown`: the wallet does not give a status for this signer. EVM wallets always give this value.

## Initializers

### init(signer:status:)

```swift theme={null}
init(signer: any AdminSignerData, status: SignerStatus = .unknown)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `signer` | `any AdminSignerData` | The signer that can recover the wallet. |
| `status` | `SignerStatus` | The install status of `signer` on the wallet. |


# RefreshJWTRequest
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/refreshjwtrequest

Swift Structure

**Structure**

```swift theme={null}
struct RefreshJWTRequest
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```


# RefreshJWTResponse
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/refreshjwtresponse

Swift Structure

**Structure**

```swift theme={null}
struct RefreshJWTResponse
```

## Structures

### RefreshJWTResponse.RefreshToken

```swift theme={null}
struct RefreshToken
```

### RefreshJWTResponse.User

```swift theme={null}
struct User
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```


# RegistrationApprovals
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/registrationapprovals

Swift Structure

**Structure**

```swift theme={null}
struct RegistrationApprovals
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `pending` | `[ApprovalEntry]` | - |


# RegistrationTransaction
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/registrationtransaction

Swift Structure

**Structure**

Pending transaction returned when registering a signer on Solana/Stellar wallets, which approve registrations through a regular transaction instead of the per-chain entries EVM returns under `chains`.

```swift theme={null}
struct RegistrationTransaction
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `id` | `String` | - |
| `status` | `String?` | - |


# ServerSignerApiModel
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/serversignerapimodel

Swift Structure

**Structure**

```swift theme={null}
struct ServerSignerApiModel
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `address` | `String` | - |
| `locator` | `String` | - |
| `toDomain` | `any AdminSignerData` | Inherited from `AdminSignerApiModel.toDomain`. |
| `type` | `AdminSignerDataType` | Inherited from `AdminSignerApiModel.type`. |


# ServerSignerData
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/serversignerdata

Swift Structure

**Structure**

```swift theme={null}
struct ServerSignerData
```

## Initializers

### init(address:)

```swift theme={null}
init(address: String)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `address` | `String` | - |
| `locatorId` | `String` | Inherited from `AdminSignerData.locatorId`. |
| `type` | `AdminSignerDataType` | Inherited from `AdminSignerData.type`. |


# SignerApiModel
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/signerapimodel

Swift Structure

**Structure**

```swift theme={null}
struct SignerApiModel
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `locator` | `String` | - |


# SignMessageRequest
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/signmessagerequest

Swift Structure

**Structure**

```swift theme={null}
struct SignMessageRequest
```

## Structures

### SignMessageRequest.Params

```swift theme={null}
struct Params
```

## Initializers

### init(params:)

```swift theme={null}
init(params: SignMessageRequest.Params)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `params` | `SignMessageRequest.Params` | - |
| `type` | `String` | - |


# SignRequest
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/signrequest

Swift Structure

**Structure**

```swift theme={null}
struct SignRequest
```


# SignRequestApi
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/signrequestapi

Swift Structure

**Structure**

```swift theme={null}
struct SignRequestApi
```

## Initializers

### init(approvals:)

```swift theme={null}
init(approvals: [SignRequestApi.Approval])
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `approvals` | `[SignRequestApi.Approval]` | - |

## Enumerations

### SignRequestApi.Approval

```swift theme={null}
enum Approval
```


# SignTypedDataRequest
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/signtypeddatarequest

Swift Structure

**Structure**

```swift theme={null}
struct SignTypedDataRequest
```

## Structures

### SignTypedDataRequest.Params

```swift theme={null}
struct Params
```

### SignTypedDataRequest.TypedData

```swift theme={null}
struct TypedData
```

## Initializers

### init(params:)

```swift theme={null}
init(params: SignTypedDataRequest.Params)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `params` | `SignTypedDataRequest.Params` | - |
| `type` | `String` | - |


# SolanaAddress
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/solanaaddress

Swift Structure

**Structure**

```swift theme={null}
struct SolanaAddress
```

## Initializers

### init(address:)

Inherited from `BlockchainAddress.init(address:)`.

```swift theme={null}
init(address: String) throws(BlockchainAddressError)
```

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `address` | `String` | - |
| `description` | `String` | Inherited from `CustomStringConvertible.description`. |
| `publicKey` | `String` | - |

## Instance Methods

### encode(to:)

Inherited from `Encodable.encode(to:)`.

```swift theme={null}
func encode(to encoder: any Encoder) throws
```


# SolanaTransactionApiModel
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/solanatransactionapimodel

Swift Structure

**Structure**

```swift theme={null}
struct SolanaTransactionApiModel
```

## Structures

### SolanaTransactionApiModel.FeeConfig

```swift theme={null}
struct FeeConfig
```

### SolanaTransactionApiModel.OnChainData

```swift theme={null}
struct OnChainData
```

### SolanaTransactionApiModel.Params

```swift theme={null}
struct Params
```

### SolanaTransactionApiModel.SendParams

```swift theme={null}
struct SendParams
```

### SolanaTransactionApiModel.SolanaApprovalEntry

```swift theme={null}
struct SolanaApprovalEntry
```

### SolanaTransactionApiModel.SolanaApprovals

```swift theme={null}
struct SolanaApprovals
```

### SolanaTransactionApiModel.SolanaSubmittedApprovalEntry

```swift theme={null}
struct SolanaSubmittedApprovalEntry
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `approvals` | `SolanaTransactionApiModel.SolanaApprovals?` | - |
| `chainType` | `String?` | - |
| `createdAt` | `Date` | - |
| `error` | `TransactionErrorApiModel?` | - |
| `id` | `String` | Inherited from `Identifiable.id`. |
| `onChain` | `SolanaTransactionApiModel.OnChainData` | - |
| `params` | `SolanaTransactionApiModel.Params` | - |
| `sendParams` | `SolanaTransactionApiModel.SendParams?` | - |
| `status` | `TransactionStatusApiModel` | - |
| `walletType` | `WalletType` | - |

## Instance Methods

### toDomain()

Inherited from `TransactionApiModel.toDomain()`.

```swift theme={null}
func toDomain() -> Transaction
```


# StellarAddress
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/stellaraddress

Swift Structure

**Structure**

```swift theme={null}
struct StellarAddress
```

## Initializers

### init(address:)

Inherited from `BlockchainAddress.init(address:)`.

```swift theme={null}
init(address: String) throws(BlockchainAddressError)
```

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `address` | `String` | - |
| `description` | `String` | Inherited from `CustomStringConvertible.description`. |

## Instance Methods

### encode(to:)

Inherited from `Encodable.encode(to:)`.

```swift theme={null}
func encode(to encoder: any Encoder) throws
```


# StellarTransactionApiModel
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/stellartransactionapimodel

Swift Structure

**Structure**

```swift theme={null}
struct StellarTransactionApiModel
```

## Structures

### StellarTransactionApiModel.FeeConfig

```swift theme={null}
struct FeeConfig
```

### StellarTransactionApiModel.OnChainData

```swift theme={null}
struct OnChainData
```

### StellarTransactionApiModel.Params

```swift theme={null}
struct Params
```

### StellarTransactionApiModel.SendParams

```swift theme={null}
struct SendParams
```

### StellarTransactionApiModel.StellarApprovalEntry

```swift theme={null}
struct StellarApprovalEntry
```

### StellarTransactionApiModel.StellarApprovals

```swift theme={null}
struct StellarApprovals
```

### StellarTransactionApiModel.StellarOnChainTransaction

```swift theme={null}
struct StellarOnChainTransaction
```

### StellarTransactionApiModel.StellarSubmittedApprovalEntry

```swift theme={null}
struct StellarSubmittedApprovalEntry
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `approvals` | `StellarTransactionApiModel.StellarApprovals?` | - |
| `chainType` | `String?` | - |
| `createdAt` | `Date` | - |
| `error` | `TransactionErrorApiModel?` | - |
| `id` | `String` | Inherited from `Identifiable.id`. |
| `onChain` | `StellarTransactionApiModel.OnChainData` | - |
| `params` | `StellarTransactionApiModel.Params` | - |
| `sendParams` | `StellarTransactionApiModel.SendParams?` | - |
| `status` | `TransactionStatusApiModel` | - |
| `walletType` | `WalletType` | - |

## Instance Methods

### toDomain()

Inherited from `TransactionApiModel.toDomain()`.

```swift theme={null}
func toDomain() -> Transaction
```


# SubmittedApprovalEntry
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/submittedapprovalentry

Swift Structure

**Structure**

```swift theme={null}
struct SubmittedApprovalEntry
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```


# TokenAccountBalance
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/tokenaccountbalance

Swift Structure

**Structure**

```swift theme={null}
struct TokenAccountBalance
```

## Initializers

### init(type:amount:rawAmount:available:locked:)

```swift theme={null}
init(type: TokenAccountType, amount: String, rawAmount: String, available: TokenAmount, locked: TokenAmount)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `amount` | `String` | - |
| `available` | `TokenAmount` | - |
| `locked` | `TokenAmount` | - |
| `rawAmount` | `String` | - |
| `type` | `TokenAccountType` | - |


# TokenAmount
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/tokenamount

Swift Structure

**Structure**

```swift theme={null}
struct TokenAmount
```

## Initializers

### init(amount:rawAmount:)

```swift theme={null}
init(amount: String, rawAmount: String)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `amount` | `String` | - |
| `rawAmount` | `String` | - |


# TokenBalance
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/tokenbalance

Swift Structure

**Structure**

```swift theme={null}
struct TokenBalance
```

## Initializers

### init(symbol:name:amount:contractAddress:decimals:rawAmount:available:locked:accounts:)

```swift theme={null}
init(symbol: TokenBalance.Symbol, name: String, amount: String, contractAddress: String? = nil, decimals: Int? = nil, rawAmount: String? = nil, available: TokenAmount? = nil, locked: TokenAmount? = nil, accounts: [TokenAccountBalance]? = nil)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `accounts` | `[TokenAccountBalance]?` | The balance of this token in each account that holds it, such as the wallet and a card. The value is nil when the balance API does not give it. |
| `amount` | `String` | - |
| `available` | `TokenAmount?` | The part of the balance that the wallet can spend now, on the wallet’s own chain. The value is nil when the balance API does not give it. |
| `contractAddress` | `String?` | - |
| `decimals` | `Int?` | - |
| `locked` | `TokenAmount?` | The part of the balance that the wallet cannot spend yet, such as a card charge that is pending. The value is nil when the balance API does not give it. |
| `name` | `String` | - |
| `rawAmount` | `String?` | - |
| `symbol` | `TokenBalance.Symbol` | - |
| `token` | `CryptoCurrency` | - |

## Enumerations

### TokenBalance.Symbol

```swift theme={null}
enum Symbol
```


# TokenLinkOptions
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/tokenlinkoptions

Swift Structure

**Structure**

```swift theme={null}
struct TokenLinkOptions
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `isCompressed` | `Bool?` | - |


# Transaction
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/transaction

Swift Structure

**Structure**

```swift theme={null}
struct Transaction
```

## Structures

### Transaction.Approvals

```swift theme={null}
struct Approvals
```

### Transaction.Call

```swift theme={null}
struct Call
```

### Transaction.Error

```swift theme={null}
struct Error
```

### Transaction.FeeConfig

```swift theme={null}
struct FeeConfig
```

### Transaction.OnChainData

```swift theme={null}
struct OnChainData
```

### Transaction.Params

```swift theme={null}
struct Params
```

### Transaction.UserOperation

```swift theme={null}
struct UserOperation
```

## Initializers

### init(id:status:onChain:params:walletType:createdAt:approvals:error:)

```swift theme={null}
init(id: String, status: Transaction.Status, onChain: Transaction.OnChainData, params: Transaction.Params, walletType: WalletType, createdAt: Date, approvals: Transaction.Approvals?, error: Transaction.Error?)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `approvals` | `Transaction.Approvals?` | - |
| `createdAt` | `Date` | - |
| `description` | `String` | Inherited from `CustomStringConvertible.description`. |
| `error` | `Transaction.Error?` | - |
| `id` | `String` | - |
| `onChain` | `Transaction.OnChainData` | - |
| `params` | `Transaction.Params` | - |
| `status` | `Transaction.Status` | - |
| `walletType` | `WalletType` | - |

## Type Aliases

### Transaction.Status

```swift theme={null}
typealias Status = TransactionStatus
```


# TransactionErrorApiModel
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/transactionerrorapimodel

Swift Structure

**Structure**

```swift theme={null}
struct TransactionErrorApiModel
```

## Structures

### TransactionErrorApiModel.Revert

```swift theme={null}
struct Revert
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `message` | `String` | - |
| `reason` | `String` | - |
| `revert` | `TransactionErrorApiModel.Revert?` | - |


# TransactionSummary
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/transactionsummary

Swift Structure

**Structure**

A compact result returned after a token transfer is confirmed on-chain.

```swift theme={null}
struct TransactionSummary
```

## Overview

Returned by `send(_:_:_:idempotencyKey:)`.

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `explorerLink` | `URL` | A block explorer URL for this transaction. |
| `hash` | `String` | The on-chain transaction hash. |
| `transactionID` | `String` | The Crossmint transaction ID. |


# Transfer
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/transfer

Swift Structure

**Structure**

Represents a token transfer event in the wallet’s transaction history.

```swift theme={null}
struct Transfer
```

## Overview

Use this model to display transaction history in your application. Each transfer contains information about the sender, recipient, token, amount, and timestamp.

## Example

```swift theme={null}
let result = try await wallet.listTransfers(tokens: [.eth, .usdc])
for transfer in result.transfers {
    print("\(transfer.type): \(transfer.amount) \(transfer.tokenSymbol ?? "tokens")")
}
```

## Initializers

### init(type:fromAddress:toAddress:transactionHash:tokenSymbol:amount:rawAmount:timestamp:mintHash:)

```swift theme={null}
init(type: TransferType, fromAddress: String, toAddress: String, transactionHash: String, tokenSymbol: String?, amount: Decimal, rawAmount: String, timestamp: Date, mintHash: String?)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `amount` | `Decimal` | The human-readable amount of tokens transferred. |
| `fromAddress` | `String` | The blockchain address that sent the transfer. |
| `id` | `String` | Inherited from `Identifiable.id`. |
| `mintHash` | `String?` | The mint hash for NFT transfers. |
| `rawAmount` | `String` | The raw amount string as returned by the API. |
| `timestamp` | `Date` | The date and time when the transfer occurred. |
| `toAddress` | `String` | The blockchain address that received the transfer. |
| `tokenSymbol` | `String?` | The symbol of the token involved in the transfer. |
| `transactionHash` | `String` | The unique hash identifying this transaction on the blockchain. |
| `type` | `TransferType` | The direction of the transfer relative to the wallet. |


# TransferListResult
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/transferlistresult

Swift Structure

**Structure**

The result of fetching wallet transfer history.

```swift theme={null}
struct TransferListResult
```

## Overview

This struct contains an array of `Transfer` events representing the wallet’s transaction history. The transfers are sorted by timestamp in descending order (most recent first).

## Initializers

### init(transfers:)

```swift theme={null}
init(transfers: [Transfer])
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `transfers` | `[Transfer]` | The array of transfer events. |


# TransferTokenRequest
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/transfertokenrequest

Swift Structure

**Structure**

```swift theme={null}
struct TransferTokenRequest
```

## Initializers

### init(chainType:tokenLocator:recipient:amount:signer:idempotencyKey:)

```swift theme={null}
init(chainType: ChainType, tokenLocator: String, recipient: String, amount: String, signer: String? = nil, idempotencyKey: String? = nil)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `amount` | `String` | - |
| `chainType` | `ChainType` | - |
| `idempotencyKey` | `String?` | - |
| `recipient` | `String` | - |
| `signer` | `String?` | - |
| `tokenLocator` | `String` | - |


# TypedDataSignatureResponse
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/typeddatasignatureresponse

Swift Structure

**Structure**

```swift theme={null}
struct TypedDataSignatureResponse
```

## Structures

### TypedDataSignatureResponse.TypedDataParams

```swift theme={null}
struct TypedDataParams
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `approvals` | `Approvals` | Inherited from `SignatureApiModel.approvals`. |
| `chainType` | `String?` | Inherited from `SignatureApiModel.chainType`. |
| `createdAt` | `Date` | Inherited from `SignatureApiModel.createdAt`. |
| `id` | `String` | Inherited from `SignatureApiModel.id`. |
| `params` | `TypedDataSignatureResponse.TypedDataParams` | - |
| `status` | `String` | Inherited from `SignatureApiModel.status`. |
| `type` | `String` | Inherited from `SignatureApiModel.type`. |
| `walletType` | `String?` | Inherited from `SignatureApiModel.walletType`. |


# ValidateEmailRequest
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/validateemailrequest

Swift Structure

**Structure**

```swift theme={null}
struct ValidateEmailRequest
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```


# ValidateEmailResponse
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/validateemailresponse

Swift Structure

**Structure**

```swift theme={null}
struct ValidateEmailResponse
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```


# ValidateTokenRequest
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/validatetokenrequest

Swift Structure

**Structure**

```swift theme={null}
struct ValidateTokenRequest
```


# ValidateTokenResponse
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/validatetokenresponse

Swift Structure

**Structure**

```swift theme={null}
struct ValidateTokenResponse
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```


# WalletApiModel
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/walletapimodel

Swift Structure

**Structure**

```swift theme={null}
struct WalletApiModel
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `address` | `String` | - |
| `chainType` | `ChainType` | - |
| `config` | `WalletConfigApiModel` | - |
| `createdAt` | `Date` | - |
| `owner` | `Owner?` | - |
| `type` | `WalletType` | - |


# WalletConfig
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/walletconfig

Swift Structure

**Structure**

```swift theme={null}
struct WalletConfig
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `recovery` | `any AdminSignerData` | The first recovery signer of the wallet. |
| `recoveryMethods` | `[any AdminSignerData]` | Every recovery signer of the wallet. Each one can authorize on its own. |


# WalletConfigApiModel
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/walletconfigapimodel

Swift Structure

**Structure**

```swift theme={null}
struct WalletConfigApiModel
```

## Initializers

### init(from:)

Inherited from `Decodable.init(from:)`.

```swift theme={null}
init(from decoder: any Decoder) throws
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `adminSigner` | `any AdminSignerApiModel` | - |


# WalletOptions
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/walletoptions

Swift Structure

**Structure**

Configuration for wallet creation and retrieval.

```swift theme={null}
struct WalletOptions
```

## Initializers

### init(deviceSigner:passkeyHost:)

```swift theme={null}
init(deviceSigner: Bool = false, passkeyHost: String? = nil)
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `deviceSigner` | `Bool` | When `true`, a device-bound signing key is generated in the Secure Enclave (or a software keychain on devices without one) and registered as a delegated signer on the wallet. Transactions can then be signed without an OTP prompt on that device. |
| `passkeyHost` | `String?` | The domain of the passkeys of this wallet, for example `"example.com"`. |


# WalletSigner
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/structs/walletsigner

Swift Structure

**Structure**

A signer registered on a wallet, as returned by `signers()`.

```swift theme={null}
struct WalletSigner
```

## Instance Properties

| Property | Type | Description |
| - | - | - |
| `locator` | `SignerLocator` | The signer locator. Use `value` for the string form, e.g. `"email:user@example.com"` or `"device:<pubkey>"`. |
| `name` | `String?` | The name of the signer, if it has one. For example, the name that the user gave to a passkey. The value is `nil` when the signer has no name, for example an email or phone signer. |
| `status` | `SignerStatus` | The registration status of this signer on the wallet’s chain. |


# EmailSignerError
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/type-aliases/emailsignererror

Swift Type Alias

**Type Alias**

Renamed when phone signers joined email signers behind the same protocol. Removable in the next major: no app-reachable API can throw it, since `load()` is capped to internal.

```swift theme={null}
typealias EmailSignerError = NonCustodialSignerError
```


# Secp256k1PrivateKey
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/type-aliases/secp256k1privatekey

Swift Type Alias

**Type Alias**

```swift theme={null}
typealias Secp256k1PrivateKey = P256K.Signing.PrivateKey
```


# Secp256k1PublicKey
Source: https://docs.crossmint.com/sdk-reference/wallets/swift/type-aliases/secp256k1publickey

Swift Type Alias

**Type Alias**

```swift theme={null}
typealias Secp256k1PublicKey = P256K.Signing.PublicKey
```


# AuthRejectedError
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/AuthRejectedError



Defined in: [packages/wallets/src/signers/types.ts:33](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L33)

## Extends

* `Error`

## Constructors

### new AuthRejectedError()

> **new AuthRejectedError**(): `AuthRejectedError`

Defined in: [packages/wallets/src/signers/types.ts:34](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L34)

#### Returns

`AuthRejectedError`

#### Overrides

`Error.constructor`

## Properties

| Property | Modifier | Type | Description | Inherited from | Defined in |
| - | - | - | - | - | - |
|  `message` | `public` | `string` | - | `Error.message` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
|  `name` | `public` | `string` | - | `Error.name` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
|  `stack?` | `public` | `string` | - | `Error.stack` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
|  `prepareStackTrace?` | `static` | (`err`: `Error`, `stackTraces`: `CallSite`\[]) => `any` | Optional override for formatting stack traces **See** [https://v8.dev/docs/stack-trace-api#customizing-stack-traces](https://v8.dev/docs/stack-trace-api#customizing-stack-traces) | `Error.prepareStackTrace` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:28 |
|  `stackTraceLimit` | `static` | `number` | - | `Error.stackTraceLimit` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:30 |

## Methods

### captureStackTrace()

> `static` **captureStackTrace**(`targetObject`, `constructorOpt`?): `void`

Defined in: node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:21

Create .stack property on a target object

#### Parameters

| Parameter | Type |
| - | - |
| `targetObject` | `object` |
| `constructorOpt`? | `Function` |

#### Returns

`void`

#### Inherited from

`Error.captureStackTrace`


# CrossmintWallets
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/CrossmintWallets



Defined in: [packages/wallets/src/sdk.ts:11](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/sdk.ts#L11)

## Methods

### createDeviceSigner()

> **createDeviceSigner**(`deviceKeyStorage`, `address`?): `Promise`\<`DeviceSignerConfig`>

Defined in: [packages/wallets/src/sdk.ts:67](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/sdk.ts#L67)

#### Parameters

| Parameter | Type |
| - | - |
| `deviceKeyStorage` | [`DeviceSignerKeyStorage`](./DeviceSignerKeyStorage) |
| `address`? | `string` |

#### Returns

`Promise`\<`DeviceSignerConfig`>

***

### createPasskeySigner()

> **createPasskeySigner**(`passkeyName`): `Promise`\<[`RegisterSignerPasskeyParams`](../type-aliases/RegisterSignerPasskeyParams)>

Defined in: [packages/wallets/src/sdk.ts:71](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/sdk.ts#L71)

#### Parameters

| Parameter | Type |
| - | - |
| `passkeyName` | `string` |

#### Returns

`Promise`\<[`RegisterSignerPasskeyParams`](../type-aliases/RegisterSignerPasskeyParams)>

***

### createWallet()

> **createWallet**\<`C`>(`options`): `Promise`\<[`Wallet`](./Wallet)\<`C`>>

Defined in: [packages/wallets/src/sdk.ts:63](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/sdk.ts#L63)

Create a new wallet.
Works on both client and server side.
A recovery method (`recovery` or `recoveryMethods`) is required; `signers` are optional.
If no signer is provided, the wallet is read-only until one is added.

#### Type Parameters

| Type Parameter |
| - |
| `C` *extends* [`Chain`](../type-aliases/Chain) |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `options` | [`WalletCreateArgs`](../type-aliases/WalletCreateArgs)\<`C`> | Wallet creation options |

#### Returns

`Promise`\<[`Wallet`](./Wallet)\<`C`>>

A new wallet

***

### getWallet()

#### Call Signature

> **getWallet**\<`C`>(`args`): `Promise`\<[`Wallet`](./Wallet)\<`C`>>

Defined in: [packages/wallets/src/sdk.ts:40](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/sdk.ts#L40)

Get an existing wallet.
Works on both client and server side.
On client side, provide wallet args directly.
On server side, provide the wallet locator string and wallet args.

##### Type Parameters

| Type Parameter |
| - |
| `C` *extends* [`Chain`](../type-aliases/Chain) |

##### Parameters

| Parameter | Type |
| - | - |
| `args` | [`WalletArgsFor`](../type-aliases/WalletArgsFor)\<`C`> |

##### Returns

`Promise`\<[`Wallet`](./Wallet)\<`C`>>

A wallet if found, throws WalletNotAvailableError if not found

#### Call Signature

> **getWallet**\<`C`>(`walletLocator`, `args`): `Promise`\<[`Wallet`](./Wallet)\<`C`>>

Defined in: [packages/wallets/src/sdk.ts:41](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/sdk.ts#L41)

Get an existing wallet.
Works on both client and server side.
On client side, provide wallet args directly.
On server side, provide the wallet locator string and wallet args.

##### Type Parameters

| Type Parameter |
| - |
| `C` *extends* [`Chain`](../type-aliases/Chain) |

##### Parameters

| Parameter | Type |
| - | - |
| `walletLocator` | `string` |
| `args` | [`WalletArgsFor`](../type-aliases/WalletArgsFor)\<`C`> |

##### Returns

`Promise`\<[`Wallet`](./Wallet)\<`C`>>

A wallet if found, throws WalletNotAvailableError if not found

***

### from()

> `static` **from**(`crossmint`): `CrossmintWallets`

Defined in: [packages/wallets/src/sdk.ts:27](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/sdk.ts#L27)

Initialize the Wallets SDK

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `crossmint` | `Crossmint` | Crossmint data (use `createCrossmint` to initialize) |

#### Returns

`CrossmintWallets`

A new CrossmintWallets instance


# DeviceSignerKeyStorage
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/DeviceSignerKeyStorage



Defined in: [packages/wallets/src/utils/device-signers/DeviceSignerKeyStorage.ts:7](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/device-signers/DeviceSignerKeyStorage.ts#L7)

## Extended by

* [`IframeDeviceSignerKeyStorage`](./IframeDeviceSignerKeyStorage)

## Constructors

### new DeviceSignerKeyStorage()

> **new DeviceSignerKeyStorage**(`apiKey`): `DeviceSignerKeyStorage`

Defined in: [packages/wallets/src/utils/device-signers/DeviceSignerKeyStorage.ts:8](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/device-signers/DeviceSignerKeyStorage.ts#L8)

#### Parameters

| Parameter | Type |
| - | - |
| `apiKey` | `string` |

#### Returns

`DeviceSignerKeyStorage`

## Methods

### deleteKey()

> `abstract` **deleteKey**(`address`): `Promise`\<`void`>

Defined in: [packages/wallets/src/utils/device-signers/DeviceSignerKeyStorage.ts:66](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/device-signers/DeviceSignerKeyStorage.ts#L66)

Delete the key pair associated with the given wallet address.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `address` | `string` | The wallet address whose key pair to remove. |

#### Returns

`Promise`\<`void`>

***

### generateKey()

#### Call Signature

> `abstract` **generateKey**(`params`): `Promise`\<`string`>

Defined in: [packages/wallets/src/utils/device-signers/DeviceSignerKeyStorage.ts:17](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/device-signers/DeviceSignerKeyStorage.ts#L17)

Generate a new P-256 key pair and persist it.

##### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | \{ `address`: `string`; `biometricPolicy`: `"always"` \| `"none"`; } | Key generation parameters. |
| `params.address`? | `string` | Optional wallet address to associate the key with. If omitted, the key should be stored under a temporary identifier until [mapAddressToKey](./#mapaddresstokey) is called. |
| `params.biometricPolicy`? | `"always"` \| `"none"` | - |

##### Returns

`Promise`\<`string`>

The uncompressed public key encoded as a base64 string.

#### Call Signature

> `abstract` **generateKey**(`params`): `Promise`\<`string`>

Defined in: [packages/wallets/src/utils/device-signers/DeviceSignerKeyStorage.ts:21](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/device-signers/DeviceSignerKeyStorage.ts#L21)

Generate a new P-256 key pair and persist it.

##### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | \{ `address`: `string`; `biometricExpirationTime`: `number`; `biometricPolicy`: `"session"`; } | Key generation parameters. |
| `params.address`? | `string` | Optional wallet address to associate the key with. If omitted, the key should be stored under a temporary identifier until [mapAddressToKey](./#mapaddresstokey) is called. |
| `params.biometricExpirationTime` | `number` | - |
| `params.biometricPolicy` | `"session"` | - |

##### Returns

`Promise`\<`string`>

The uncompressed public key encoded as a base64 string.

#### Call Signature

> `abstract` **generateKey**(`params`): `Promise`\<`string`>

Defined in: [packages/wallets/src/utils/device-signers/DeviceSignerKeyStorage.ts:26](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/device-signers/DeviceSignerKeyStorage.ts#L26)

Generate a new P-256 key pair and persist it.

##### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | \{ `address`: `string`; `biometricExpirationTime`: `number`; `biometricPolicy`: `BiometricPolicy`; } | Key generation parameters. |
| `params.address`? | `string` | Optional wallet address to associate the key with. If omitted, the key should be stored under a temporary identifier until [mapAddressToKey](./#mapaddresstokey) is called. |
| `params.biometricExpirationTime`? | `number` | - |
| `params.biometricPolicy`? | `BiometricPolicy` | - |

##### Returns

`Promise`\<`string`>

The uncompressed public key encoded as a base64 string.

***

### getDeviceName()

> `abstract` **getDeviceName**(): `string`

Defined in: [packages/wallets/src/utils/device-signers/DeviceSignerKeyStorage.ts:73](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/device-signers/DeviceSignerKeyStorage.ts#L73)

Get a human-readable name for this device (e.g. "MacBook Pro", "iPhone 15").
Used to label device signers in the API for identification purposes.

#### Returns

`string`

A descriptive name for the current device.

***

### getKey()

> `abstract` **getKey**(`address`): `Promise`\<`string` | `null`>

Defined in: [packages/wallets/src/utils/device-signers/DeviceSignerKeyStorage.ts:45](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/device-signers/DeviceSignerKeyStorage.ts#L45)

Retrieve the public key for a given wallet address.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `address` | `string` | The wallet address whose public key to look up. |

#### Returns

`Promise`\<`string` | `null`>

The base64-encoded public key, or `null` if no key is found for the address.

***

### hasKey()

> `abstract` **hasKey**(`publicKeyBase64`): `Promise`\<`boolean`>

Defined in: [packages/wallets/src/utils/device-signers/DeviceSignerKeyStorage.ts:52](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/device-signers/DeviceSignerKeyStorage.ts#L52)

Check if a key with the given public key exists on this device.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `publicKeyBase64` | `string` | The base64-encoded public key to look for. |

#### Returns

`Promise`\<`boolean`>

`true` if the key exists on the device, `false` otherwise.

***

### mapAddressToKey()

> `abstract` **mapAddressToKey**(`address`, `publicKeyBase64`): `Promise`\<`void`>

Defined in: [packages/wallets/src/utils/device-signers/DeviceSignerKeyStorage.ts:38](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/device-signers/DeviceSignerKeyStorage.ts#L38)

Associate an already-generated key pair with a wallet address.
Used when the wallet address is not yet known at the time of key generation.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `address` | `string` | The wallet address to map the key to. |
| `publicKeyBase64` | `string` | The base64-encoded public key returned by [generateKey](./#generatekey). |

#### Returns

`Promise`\<`void`>

***

### signMessage()

> `abstract` **signMessage**(`address`, `message`): `Promise`\<\{ `r`: `string`; `s`: `string`; }>

Defined in: [packages/wallets/src/utils/device-signers/DeviceSignerKeyStorage.ts:60](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/device-signers/DeviceSignerKeyStorage.ts#L60)

Sign a message using the private key associated with the given wallet address.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `address` | `string` | The wallet address whose private key to sign with. |
| `message` | `string` | The message string to sign. |

#### Returns

`Promise`\<\{ `r`: `string`; `s`: `string`; }>

The ECDSA signature split into its `r` and `s` components, each as a hex string.


# DuplicateRecoverySignerError
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/DuplicateRecoverySignerError



Defined in: [packages/wallets/src/utils/errors.ts:119](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/errors.ts#L119)

## Extends

* `CrossmintSDKError`

## Constructors

### new DuplicateRecoverySignerError()

> **new DuplicateRecoverySignerError**(`message`, `details`?): `DuplicateRecoverySignerError`

Defined in: [packages/wallets/src/utils/errors.ts:120](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/errors.ts#L120)

#### Parameters

| Parameter | Type |
| - | - |
| `message` | `string` |
| `details`? | `string` |

#### Returns

`DuplicateRecoverySignerError`

#### Overrides

`CrossmintSDKError.constructor`

## Properties

| Property | Modifier | Type | Description | Inherited from | Defined in |
| - | - | - | - | - | - |
|  `code` | `readonly` | `string` | - | `CrossmintSDKError.code` | packages/common/base/dist/error/index.d.ts:4 |
|  `details?` | `readonly` | `string` | - | [`InvalidRecoveryConfigError`](./InvalidRecoveryConfigError).[`details`](./InvalidRecoveryConfigError#details) | packages/common/base/dist/error/index.d.ts:5 |
|  `message` | `public` | `string` | - | `CrossmintSDKError.message` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
|  `name` | `public` | `string` | - | `CrossmintSDKError.name` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
|  `stack?` | `public` | `string` | - | `CrossmintSDKError.stack` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
|  `prepareStackTrace?` | `static` | (`err`: `Error`, `stackTraces`: `CallSite`\[]) => `any` | Optional override for formatting stack traces **See** [https://v8.dev/docs/stack-trace-api#customizing-stack-traces](https://v8.dev/docs/stack-trace-api#customizing-stack-traces) | `CrossmintSDKError.prepareStackTrace` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:28 |
|  `stackTraceLimit` | `static` | `number` | - | `CrossmintSDKError.stackTraceLimit` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:30 |

## Methods

### captureStackTrace()

> `static` **captureStackTrace**(`targetObject`, `constructorOpt`?): `void`

Defined in: node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:21

Create .stack property on a target object

#### Parameters

| Parameter | Type |
| - | - |
| `targetObject` | `object` |
| `constructorOpt`? | `Function` |

#### Returns

`void`

#### Inherited from

`CrossmintSDKError.captureStackTrace`


# EVMWallet
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/EVMWallet



Defined in: [packages/wallets/src/wallets/evm.ts:21](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/evm.ts#L21)

## Extends

* [`Wallet`](./Wallet)\<[`EVMChain`](../type-aliases/EVMChain)>

## Constructors

### new EVMWallet()

> **new EVMWallet**(`wallet`): `EVMWallet`

Defined in: [packages/wallets/src/wallets/evm.ts:22](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/evm.ts#L22)

#### Parameters

| Parameter | Type |
| - | - |
| `wallet` | [`Wallet`](./Wallet)\<`EVMSmartWalletChain`> |

#### Returns

`EVMWallet`

#### Overrides

[`Wallet`](./Wallet).[`constructor`](./Wallet#constructor)

## Properties

| Property | Type | Inherited from | Defined in |
| - | - | - | - |
|  `address` | `string` | [`Wallet`](./Wallet).[`address`](./Wallet#address) | [packages/wallets/src/wallets/wallet.ts:104](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L104) |
|  `alias?` | `string` | [`Wallet`](./Wallet).[`alias`](./Wallet#alias) | [packages/wallets/src/wallets/wallet.ts:106](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L106) |
|  `chain` | `EVMSmartWalletChain` | [`Wallet`](./Wallet).[`chain`](./Wallet#chain) | [packages/wallets/src/wallets/wallet.ts:103](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L103) |
|  `owner?` | `string` | [`Wallet`](./Wallet).[`owner`](./Wallet#owner) | [packages/wallets/src/wallets/wallet.ts:105](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L105) |

## Accessors

### apiClient

#### Get Signature

> **get** **apiClient**(): [`WalletsApiClient`](./WalletsApiClient)

Defined in: [packages/wallets/src/wallets/wallet.ts:296](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L296)

##### Returns

[`WalletsApiClient`](./WalletsApiClient)

#### Inherited from

[`Wallet`](./Wallet).[`apiClient`](./Wallet#apiclient)

***

### recovery

#### Get Signature

> **get** **recovery**(): [`SignerConfigForChain`](../type-aliases/SignerConfigForChain)\<`C`>

Defined in: [packages/wallets/src/wallets/wallet.ts:321](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L321)

**`Experimental`**

Get the primary recovery signer config. Use [recoveryMethods](./#recoverymethods) for the full list on wallets
created with several recovery signers.

##### Returns

[`SignerConfigForChain`](../type-aliases/SignerConfigForChain)\<`C`>

The recovery signer config
This API is experimental and may change in the future

#### Inherited from

[`Wallet`](./Wallet).[`recovery`](./Wallet#recovery)

***

### recoveryMethods

#### Get Signature

> **get** **recoveryMethods**(): [`RecoverySignerConfigForChain`](../type-aliases/RecoverySignerConfigForChain)\<`C`>\[]

Defined in: [packages/wallets/src/wallets/wallet.ts:331](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L331)

**`Experimental`**

Get every recovery signer config of the wallet. Wallets on chains that support a single recovery
signer always return one entry.

##### Returns

[`RecoverySignerConfigForChain`](../type-aliases/RecoverySignerConfigForChain)\<`C`>\[]

The recovery signer configs
This API is experimental and may change in the future

#### Inherited from

[`Wallet`](./Wallet).[`recoveryMethods`](./Wallet#recoverymethods)

***

### signer

#### Get Signature

> **get** **signer**(): [`SignerAdapter`](../interfaces/SignerAdapter)\<keyof `SignResultMap`> | `undefined`

Defined in: [packages/wallets/src/wallets/wallet.ts:201](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L201)

##### Returns

[`SignerAdapter`](../interfaces/SignerAdapter)\<keyof `SignResultMap`> | `undefined`

#### Inherited from

[`Wallet`](./Wallet).[`signer`](./Wallet#signer)

## Methods

### addRecoveryMethod()

> **addRecoveryMethod**\<`T`>(`recoveryMethod`, `options`?): `Promise`\<[`AddRecoveryMethodReturnType`](../type-aliases/AddRecoveryMethodReturnType)>

Defined in: [packages/wallets/src/wallets/wallet.ts:860](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L860)

Add a recovery method to the wallet. Supported on Solana and Stellar only.
Always uses one of the existing recovery methods to approve the change, selected as in [addSigner](./#addsigner).

#### Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* [`AddRecoveryMethodOptions`](../type-aliases/AddRecoveryMethodOptions) \| `undefined` | `undefined` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `recoveryMethod` | [`DeviceSignerConfig`](../type-aliases/DeviceSignerConfig) \| [`ServerSignerConfig`](../type-aliases/ServerSignerConfig) \| [`ExternalWalletRegistrationConfig`](../type-aliases/ExternalWalletRegistrationConfig) \| `PasskeySignerConfig` \| [`EmailSignerConfig`](../type-aliases/EmailSignerConfig) \| [`PhoneSignerConfig`](../type-aliases/PhoneSignerConfig) \| `ApiKeySignerConfig` \| [`EvmExternalWalletSignerConfig`](../type-aliases/EvmExternalWalletSignerConfig) | The recovery method configuration object |
| `options`? | `T` | The options for the operation |

#### Returns

`Promise`\<[`AddRecoveryMethodReturnType`](../type-aliases/AddRecoveryMethodReturnType)>

#### Inherited from

[`Wallet`](./Wallet).[`addRecoveryMethod`](./Wallet#addrecoverymethod)

***

### addSigner()

> **addSigner**\<`T`>(`signer`, `options`?): `Promise`\<`T` *extends* `PrepareOnly`\<`true`> ? [`Signer`](../type-aliases/Signer) & `object` : [`Signer`](../type-aliases/Signer)>

Defined in: [packages/wallets/src/wallets/wallet.ts:649](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L649)

Add a signer to the wallet.
Always uses a recovery method internally to approve the registration: the one selected via
[useRecoveryMethod](./#userecoverymethod), else the active signer when it is one of the recovery methods, else the wallet's
single recovery method. Wallets with several recovery methods must select one first; an operational signer
cannot authorize this.
If the signer being added is the current operational signer, it will be reassembled with the new locator.
Otherwise, the original signer is restored after the operation.

#### Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* [`AddSignerOptions`](../type-aliases/AddSignerOptions) \| `undefined` | `undefined` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `signer` | [`DeviceSignerConfig`](../type-aliases/DeviceSignerConfig) \| [`ServerSignerConfig`](../type-aliases/ServerSignerConfig) \| [`ExternalWalletRegistrationConfig`](../type-aliases/ExternalWalletRegistrationConfig) \| `PasskeySignerConfig` \| [`EmailSignerConfig`](../type-aliases/EmailSignerConfig) \| [`PhoneSignerConfig`](../type-aliases/PhoneSignerConfig) \| `ApiKeySignerConfig` \| [`EvmExternalWalletSignerConfig`](../type-aliases/EvmExternalWalletSignerConfig) | The signer configuration object |
| `options`? | `T` | The options for the operation |

#### Returns

`Promise`\<`T` *extends* `PrepareOnly`\<`true`> ? [`Signer`](../type-aliases/Signer) & `object` : [`Signer`](../type-aliases/Signer)>

#### Inherited from

[`Wallet`](./Wallet).[`addSigner`](./Wallet#addsigner)

***

### approve()

> **approve**\<`T`>(`params`): `Promise`\<`ApproveResult`\<`T`>>

Defined in: [packages/wallets/src/wallets/wallet.ts:599](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L599)

Approve a transaction or signature

#### Type Parameters

| Type Parameter |
| - |
| `T` *extends* [`ApproveParams`](../type-aliases/ApproveParams) |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | `T` | The parameters |

#### Returns

`Promise`\<`ApproveResult`\<`T`>>

The transaction or signature

#### Inherited from

[`Wallet`](./Wallet).[`approve`](./Wallet#approve)

***

### ~~approveTransaction()~~

> **approveTransaction**(`params`): `Promise`\<`Error`>

Defined in: [packages/wallets/src/wallets/wallet.ts:575](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L575)

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | [`ApproveParams`](../type-aliases/ApproveParams) | The parameters |

#### Returns

`Promise`\<`Error`>

The transaction

#### Deprecated

Use `approve` instead.
Approve a transaction

#### Inherited from

[`Wallet`](./Wallet).[`approveTransaction`](./Wallet#approvetransaction)

***

### balances()

> **balances**(`tokens`?): `Promise`\<[`Balances`](../type-aliases/Balances)\<`EVMSmartWalletChain`>>

Defined in: [packages/wallets/src/wallets/wallet.ts:348](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L348)

Get the wallet balances - always includes USDC and native token (ETH/SOL)

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `tokens`? | `string`\[] | Additional tokens to request (optional: native token and usdc are always included) |

#### Returns

`Promise`\<[`Balances`](../type-aliases/Balances)\<`EVMSmartWalletChain`>>

The balances returns nativeToken, usdc, tokens

#### Throws

If the balances cannot be retrieved

#### Inherited from

[`Wallet`](./Wallet).[`balances`](./Wallet#balances)

***

### getViemClient()

> **getViemClient**(`params`?): `object`

Defined in: [packages/wallets/src/wallets/evm.ts:210](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/evm.ts#L210)

Get a Viem public client instance configured for this wallet's chain.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params`? | \{ `transport`: `HttpTransport`; } | Optional transport configuration |
| `params.transport`? | `HttpTransport` | - |

#### Returns

`object`

A Viem public client

##### account

> **account**: `undefined`

The Account of the Client.

##### batch?

> `optional` **batch**: `object`

Flags for batch settings.

###### batch.multicall?

> `optional` **multicall**: `boolean` | \{ `batchSize`: `number`; `wait`: `number`; }

Toggle to enable `eth_call` multicall aggregation.

###### Type Declaration

`boolean`

\{ `batchSize`: `number`; `wait`: `number`; }

##### cacheTime

> **cacheTime**: `number`

Time (in ms) that cached data will remain in memory.

##### call()

> **call**: (`parameters`) => `Promise`\<`CallReturnType`>

Executes a new message call immediately without submitting a transaction to the network.

* Docs: [https://viem.sh/docs/actions/public/call](https://viem.sh/docs/actions/public/call)
* JSON-RPC Methods: [`eth_call`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_call)

###### Parameters

| Parameter | Type |
| - | - |
| `parameters` | `CallParameters`\<`Chain`> |

###### Returns

`Promise`\<`CallReturnType`>

The call data. CallReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const data = await client.call({
  account: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
  data: '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2',
  to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
})
```

##### ccipRead?

> `optional` **ccipRead**: `false` | \{ `request`: (`parameters`) => `Promise`\<`` `0x${string}` ``>; }

[CCIP Read](https://eips.ethereum.org/EIPS/eip-3668) configuration.

###### Type Declaration

`false`

\{ `request`: (`parameters`) => `Promise`\<`` `0x${string}` ``>; }

##### chain

> **chain**: `Chain`

Chain for the client.

##### createAccessList()

> **createAccessList**: (`parameters`) => `Promise`\<\{ `accessList`: `AccessList`; `gasUsed`: `bigint`; }>

Creates an EIP-2930 access list that you can include in a transaction.

* Docs: [https://viem.sh/docs/actions/public/createAccessList](https://viem.sh/docs/actions/public/createAccessList)
* JSON-RPC Methods: `eth_createAccessList`

###### Parameters

| Parameter | Type |
| - | - |
| `parameters` | `CreateAccessListParameters`\<`Chain`> |

###### Returns

`Promise`\<\{ `accessList`: `AccessList`; `gasUsed`: `bigint`; }>

The call data. CreateAccessListReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})

const data = await client.createAccessList({
  data: '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2',
  to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
})
```

##### createBlockFilter()

> **createBlockFilter**: () => `Promise`\<\{ `id`: `` `0x${string}` ``; `request`: `EIP1193RequestFn`\<readonly \[\{ `Method`: `"eth_getFilterChanges"`; `Parameters`: \[`` `0x${string}` ``]; `ReturnType`: `` `0x${string}` ``\[] | `RpcLog`\[]; }, \{ `Method`: `"eth_getFilterLogs"`; `Parameters`: \[`` `0x${string}` ``]; `ReturnType`: `RpcLog`\[]; }, \{ `Method`: `"eth_uninstallFilter"`; `Parameters`: \[`` `0x${string}` ``]; `ReturnType`: `boolean`; }]>; `type`: `"block"`; }>

Creates a Filter to listen for new block hashes that can be used with [`getFilterChanges`](https://viem.sh/docs/actions/public/getFilterChanges).

* Docs: [https://viem.sh/docs/actions/public/createBlockFilter](https://viem.sh/docs/actions/public/createBlockFilter)
* JSON-RPC Methods: [`eth_newBlockFilter`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_newBlockFilter)

###### Returns

`Promise`\<\{ `id`: `` `0x${string}` ``; `request`: `EIP1193RequestFn`\<readonly \[\{ `Method`: `"eth_getFilterChanges"`; `Parameters`: \[`` `0x${string}` ``]; `ReturnType`: `` `0x${string}` ``\[] | `RpcLog`\[]; }, \{ `Method`: `"eth_getFilterLogs"`; `Parameters`: \[`` `0x${string}` ``]; `ReturnType`: `RpcLog`\[]; }, \{ `Method`: `"eth_uninstallFilter"`; `Parameters`: \[`` `0x${string}` ``]; `ReturnType`: `boolean`; }]>; `type`: `"block"`; }>

Filter. CreateBlockFilterReturnType

###### Example

```ts theme={null}
import { createPublicClient, createBlockFilter, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const filter = await createBlockFilter(client)
// { id: "0x345a6572337856574a76364e457a4366", type: 'block' }
```

##### createContractEventFilter()

> **createContractEventFilter**: \<`abi`, `eventName`, `args`, `strict`, `fromBlock`, `toBlock`>(`args`) => `Promise`\<`CreateContractEventFilterReturnType`\<`abi`, `eventName`, `args`, `strict`, `fromBlock`, `toBlock`>>

Creates a Filter to retrieve event logs that can be used with [`getFilterChanges`](https://viem.sh/docs/actions/public/getFilterChanges) or [`getFilterLogs`](https://viem.sh/docs/actions/public/getFilterLogs).

* Docs: [https://viem.sh/docs/contract/createContractEventFilter](https://viem.sh/docs/contract/createContractEventFilter)

###### Type Parameters

| Type Parameter | Default type |
| - | - |
| `abi` *extends* `Abi` \| readonly `unknown`\[] | - |
| `eventName` *extends* `string` \| `undefined` | - |
| `args` *extends* `Record`\<`string`, `unknown`> \| readonly `unknown`\[] \| `undefined` | - |
| `strict` *extends* `boolean` \| `undefined` | `undefined` |
| `fromBlock` *extends* `bigint` \| `BlockTag` \| `undefined` | `undefined` |
| `toBlock` *extends* `bigint` \| `BlockTag` \| `undefined` | `undefined` |

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `CreateContractEventFilterParameters`\<`abi`, `eventName`, `args`, `strict`, `fromBlock`, `toBlock`> | CreateContractEventFilterParameters |

###### Returns

`Promise`\<`CreateContractEventFilterReturnType`\<`abi`, `eventName`, `args`, `strict`, `fromBlock`, `toBlock`>>

[`Filter`](https://viem.sh/docs/glossary/types#filter). CreateContractEventFilterReturnType

###### Example

```ts theme={null}
import { createPublicClient, http, parseAbi } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const filter = await client.createContractEventFilter({
  abi: parseAbi(['event Transfer(address indexed, address indexed, uint256)']),
})
```

##### createEventFilter()

> **createEventFilter**: \<`abiEvent`, `abiEvents`, `strict`, `fromBlock`, `toBlock`, `_EventName`, `_Args`>(`args`?) => `Promise`\<\{ \[K in string | number | symbol]: Filter\<"event", abiEvents, \_EventName, \_Args, strict, fromBlock, toBlock>\[K] }>

Creates a [`Filter`](https://viem.sh/docs/glossary/types#filter) to listen for new events that can be used with [`getFilterChanges`](https://viem.sh/docs/actions/public/getFilterChanges).

* Docs: [https://viem.sh/docs/actions/public/createEventFilter](https://viem.sh/docs/actions/public/createEventFilter)
* JSON-RPC Methods: [`eth_newFilter`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_newfilter)

###### Type Parameters

| Type Parameter | Default type |
| - | - |
| `abiEvent` *extends* `AbiEvent` \| `undefined` | `undefined` |
| `abiEvents` *extends* readonly `unknown`\[] \| readonly `AbiEvent`\[] \| `undefined` | `abiEvent` *extends* `AbiEvent` ? \[`abiEvent`] : `undefined` |
| `strict` *extends* `boolean` \| `undefined` | `undefined` |
| `fromBlock` *extends* `bigint` \| `BlockTag` \| `undefined` | `undefined` |
| `toBlock` *extends* `bigint` \| `BlockTag` \| `undefined` | `undefined` |
| `_EventName` *extends* `string` \| `undefined` | `MaybeAbiEventName`\<`abiEvent`> |
| `_Args` *extends* `Record`\<`string`, `unknown`> \| readonly `unknown`\[] \| `undefined` | `undefined` |

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args`? | `CreateEventFilterParameters`\<`abiEvent`, `abiEvents`, `strict`, `fromBlock`, `toBlock`, `_EventName`, `_Args`> | CreateEventFilterParameters |

###### Returns

`Promise`\<\{ \[K in string | number | symbol]: Filter\<"event", abiEvents, \_EventName, \_Args, strict, fromBlock, toBlock>\[K] }>

[`Filter`](https://viem.sh/docs/glossary/types#filter). CreateEventFilterReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const filter = await client.createEventFilter({
  address: '0xfba3912ca04dd458c843e2ee08967fc04f3579c2',
})
```

##### createPendingTransactionFilter()

> **createPendingTransactionFilter**: () => `Promise`\<\{ `id`: `` `0x${string}` ``; `request`: `EIP1193RequestFn`\<readonly \[\{ `Method`: `"eth_getFilterChanges"`; `Parameters`: \[`` `0x${string}` ``]; `ReturnType`: `` `0x${string}` ``\[] | `RpcLog`\[]; }, \{ `Method`: `"eth_getFilterLogs"`; `Parameters`: \[`` `0x${string}` ``]; `ReturnType`: `RpcLog`\[]; }, \{ `Method`: `"eth_uninstallFilter"`; `Parameters`: \[`` `0x${string}` ``]; `ReturnType`: `boolean`; }]>; `type`: `"transaction"`; }>

Creates a Filter to listen for new pending transaction hashes that can be used with [`getFilterChanges`](https://viem.sh/docs/actions/public/getFilterChanges).

* Docs: [https://viem.sh/docs/actions/public/createPendingTransactionFilter](https://viem.sh/docs/actions/public/createPendingTransactionFilter)
* JSON-RPC Methods: [`eth_newPendingTransactionFilter`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_newpendingtransactionfilter)

###### Returns

`Promise`\<\{ `id`: `` `0x${string}` ``; `request`: `EIP1193RequestFn`\<readonly \[\{ `Method`: `"eth_getFilterChanges"`; `Parameters`: \[`` `0x${string}` ``]; `ReturnType`: `` `0x${string}` ``\[] | `RpcLog`\[]; }, \{ `Method`: `"eth_getFilterLogs"`; `Parameters`: \[`` `0x${string}` ``]; `ReturnType`: `RpcLog`\[]; }, \{ `Method`: `"eth_uninstallFilter"`; `Parameters`: \[`` `0x${string}` ``]; `ReturnType`: `boolean`; }]>; `type`: `"transaction"`; }>

[`Filter`](https://viem.sh/docs/glossary/types#filter). CreateBlockFilterReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const filter = await client.createPendingTransactionFilter()
// { id: "0x345a6572337856574a76364e457a4366", type: 'transaction' }
```

##### estimateContractGas()

> **estimateContractGas**: \<`chain`, `abi`, `functionName`, `args`>(`args`) => `Promise`\<`bigint`>

Estimates the gas required to successfully execute a contract write function call.

* Docs: [https://viem.sh/docs/contract/estimateContractGas](https://viem.sh/docs/contract/estimateContractGas)

###### Type Parameters

| Type Parameter |
| - |
| `chain` *extends* `Chain` \| `undefined` |
| `abi` *extends* `Abi` \| readonly `unknown`\[] |
| `functionName` *extends* `string` |
| `args` *extends* `unknown` |

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `EstimateContractGasParameters`\<`abi`, `functionName`, `args`, `chain`> | EstimateContractGasParameters |

###### Returns

`Promise`\<`bigint`>

The gas estimate (in wei). EstimateContractGasReturnType

###### Remarks

Internally, uses a [Public Client](https://viem.sh/docs/clients/public) to call the [`estimateGas` action](https://viem.sh/docs/actions/public/estimateGas) with [ABI-encoded `data`](https://viem.sh/docs/contract/encodeFunctionData).

###### Example

```ts theme={null}
import { createPublicClient, http, parseAbi } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const gas = await client.estimateContractGas({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: parseAbi(['function mint() public']),
  functionName: 'mint',
  account: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
})
```

##### estimateFeesPerGas()

> **estimateFeesPerGas**: \<`chainOverride`, `type`>(`args`?) => `Promise`\<`EstimateFeesPerGasReturnType`\<`type`>>

Returns an estimate for the fees per gas for a transaction to be included
in the next block.

* Docs: [https://viem.sh/docs/actions/public/estimateFeesPerGas](https://viem.sh/docs/actions/public/estimateFeesPerGas)

###### Type Parameters

| Type Parameter | Default type |
| - | - |
| `chainOverride` *extends* `Chain` \| `undefined` | `undefined` |
| `type` *extends* `FeeValuesType` | `"eip1559"` |

###### Parameters

| Parameter | Type |
| - | - |
| `args`? | `EstimateFeesPerGasParameters`\<`Chain`, `chainOverride`, `type`> |

###### Returns

`Promise`\<`EstimateFeesPerGasReturnType`\<`type`>>

An estimate (in wei) for the fees per gas. EstimateFeesPerGasReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const maxPriorityFeePerGas = await client.estimateFeesPerGas()
// { maxFeePerGas: ..., maxPriorityFeePerGas: ... }
```

##### estimateGas()

> **estimateGas**: (`args`) => `Promise`\<`bigint`>

Estimates the gas necessary to complete a transaction without submitting it to the network.

* Docs: [https://viem.sh/docs/actions/public/estimateGas](https://viem.sh/docs/actions/public/estimateGas)
* JSON-RPC Methods: [`eth_estimateGas`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_estimategas)

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `EstimateGasParameters`\<`Chain`> | EstimateGasParameters |

###### Returns

`Promise`\<`bigint`>

The gas estimate (in wei). EstimateGasReturnType

###### Example

```ts theme={null}
import { createPublicClient, http, parseEther } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const gasEstimate = await client.estimateGas({
  account: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
  to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
  value: parseEther('1'),
})
```

##### estimateMaxPriorityFeePerGas()

> **estimateMaxPriorityFeePerGas**: \<`chainOverride`>(`args`?) => `Promise`\<`bigint`>

Returns an estimate for the max priority fee per gas (in wei) for a transaction
to be included in the next block.

* Docs: [https://viem.sh/docs/actions/public/estimateMaxPriorityFeePerGas](https://viem.sh/docs/actions/public/estimateMaxPriorityFeePerGas)

###### Type Parameters

| Type Parameter | Default type |
| - | - |
| `chainOverride` *extends* `Chain` \| `undefined` | `undefined` |

###### Parameters

| Parameter | Type |
| - | - |
| `args`? | \{ `chain`: `chainOverride` \| `null`; } |
| `args.chain`? | `chainOverride` \| `null` |

###### Returns

`Promise`\<`bigint`>

An estimate (in wei) for the max priority fee per gas. EstimateMaxPriorityFeePerGasReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const maxPriorityFeePerGas = await client.estimateMaxPriorityFeePerGas()
// 10000000n
```

##### experimental\_blockTag?

> `optional` **experimental\_blockTag**: `BlockTag`

Default block tag to use for RPC requests.

##### extend()

> **extend**: \<`client`>(`fn`) => `Client`\<`HttpTransport`, `Chain`, `undefined`, `PublicRpcSchema`, \{ \[K in string | number | symbol]: client\[K] } & `PublicActions`\<`HttpTransport`, `Chain`>>

###### Type Parameters

| Type Parameter |
| - |
| `client` *extends* `object` & `ExactPartial`\<`ExtendableProtectedActions`\<`HttpTransport`, `Chain`, `undefined`>> |

###### Parameters

| Parameter | Type |
| - | - |
| `fn` | (`client`) => `client` |

###### Returns

`Client`\<`HttpTransport`, `Chain`, `undefined`, `PublicRpcSchema`, \{ \[K in string | number | symbol]: client\[K] } & `PublicActions`\<`HttpTransport`, `Chain`>>

##### getBalance()

> **getBalance**: (`args`) => `Promise`\<`bigint`>

Returns the balance of an address in wei.

* Docs: [https://viem.sh/docs/actions/public/getBalance](https://viem.sh/docs/actions/public/getBalance)
* JSON-RPC Methods: [`eth_getBalance`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getbalance)

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `GetBalanceParameters` | GetBalanceParameters |

###### Returns

`Promise`\<`bigint`>

The balance of the address in wei. GetBalanceReturnType

###### Remarks

You can convert the balance to ether units with [`formatEther`](https://viem.sh/docs/utilities/formatEther).

```ts theme={null}
const balance = await getBalance(client, {
  address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
  blockTag: 'safe'
})
const balanceAsEther = formatEther(balance)
// "6.942"
```

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const balance = await client.getBalance({
  address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
})
// 10000000000000000000000n (wei)
```

##### getBlobBaseFee()

> **getBlobBaseFee**: () => `Promise`\<`bigint`>

Returns the base fee per blob gas in wei.

* Docs: [https://viem.sh/docs/actions/public/getBlobBaseFee](https://viem.sh/docs/actions/public/getBlobBaseFee)
* JSON-RPC Methods: [`eth_blobBaseFee`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_blobBaseFee)

###### Returns

`Promise`\<`bigint`>

The blob base fee (in wei). GetBlobBaseFeeReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'
import { getBlobBaseFee } from 'viem/public'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const blobBaseFee = await client.getBlobBaseFee()
```

##### getBlock()

> **getBlock**: \<`includeTransactions`, `blockTag`>(`args`?) => `Promise`\<\{ `baseFeePerGas`: `bigint` | `null`; `blobGasUsed`: `bigint`; `difficulty`: `bigint`; `excessBlobGas`: `bigint`; `extraData`: `` `0x${string}` ``; `gasLimit`: `bigint`; `gasUsed`: `bigint`; `hash`: `blockTag` *extends* `"pending"` ? `null` : `` `0x${string}` ``; `logsBloom`: `blockTag` *extends* `"pending"` ? `null` : `` `0x${string}` ``; `miner`: `` `0x${string}` ``; `mixHash`: `` `0x${string}` ``; `nonce`: `blockTag` *extends* `"pending"` ? `null` : `` `0x${string}` ``; `number`: `blockTag` *extends* `"pending"` ? `null` : `bigint`; `parentBeaconBlockRoot`: `` `0x${string}` ``; `parentHash`: `` `0x${string}` ``; `receiptsRoot`: `` `0x${string}` ``; `sealFields`: `` `0x${string}` ``\[]; `sha3Uncles`: `` `0x${string}` ``; `size`: `bigint`; `stateRoot`: `` `0x${string}` ``; `timestamp`: `bigint`; `totalDifficulty`: `bigint` | `null`; `transactions`: `includeTransactions` *extends* `true` ? (\{ `accessList`: `undefined`; `authorizationList`: `undefined`; `blobVersionedHashes`: `undefined`; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `bigint`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `undefined`; `maxPriorityFeePerGas`: `undefined`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"legacy"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `undefined`; } | \{ `accessList`: `AccessList`; `authorizationList`: `undefined`; `blobVersionedHashes`: `undefined`; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `bigint`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `undefined`; `maxPriorityFeePerGas`: `undefined`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"eip2930"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `number`; } | \{ `accessList`: `AccessList`; `authorizationList`: `undefined`; `blobVersionedHashes`: `undefined`; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `undefined`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `bigint`; `maxPriorityFeePerGas`: `bigint`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"eip1559"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `number`; } | \{ `accessList`: `AccessList`; `authorizationList`: `undefined`; `blobVersionedHashes`: readonly `` `0x${string}` ``\[]; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `undefined`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `bigint`; `maxFeePerGas`: `bigint`; `maxPriorityFeePerGas`: `bigint`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"eip4844"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `number`; } | \{ `accessList`: `AccessList`; `authorizationList`: `SignedAuthorizationList`; `blobVersionedHashes`: `undefined`; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `undefined`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `bigint`; `maxPriorityFeePerGas`: `bigint`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"eip7702"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `number`; })\[] : `` `0x${string}` ``\[]; `transactionsRoot`: `` `0x${string}` ``; `uncles`: `` `0x${string}` ``\[]; `withdrawals`: `Withdrawal`\[]; `withdrawalsRoot`: `` `0x${string}` ``; }>

Returns information about a block at a block number, hash, or tag.

* Docs: [https://viem.sh/docs/actions/public/getBlock](https://viem.sh/docs/actions/public/getBlock)
* Examples: [https://stackblitz.com/github/wevm/viem/tree/main/examples/blocks\_fetching-blocks](https://stackblitz.com/github/wevm/viem/tree/main/examples/blocks_fetching-blocks)
* JSON-RPC Methods:
  * Calls [`eth_getBlockByNumber`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getblockbynumber) for `blockNumber` & `blockTag`.
  * Calls [`eth_getBlockByHash`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getblockbyhash) for `blockHash`.

###### Type Parameters

| Type Parameter | Default type |
| - | - |
| `includeTransactions` *extends* `boolean` | `false` |
| `blockTag` *extends* `BlockTag` | `"latest"` |

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args`? | `GetBlockParameters`\<`includeTransactions`, `blockTag`> | GetBlockParameters |

###### Returns

`Promise`\<\{ `baseFeePerGas`: `bigint` | `null`; `blobGasUsed`: `bigint`; `difficulty`: `bigint`; `excessBlobGas`: `bigint`; `extraData`: `` `0x${string}` ``; `gasLimit`: `bigint`; `gasUsed`: `bigint`; `hash`: `blockTag` *extends* `"pending"` ? `null` : `` `0x${string}` ``; `logsBloom`: `blockTag` *extends* `"pending"` ? `null` : `` `0x${string}` ``; `miner`: `` `0x${string}` ``; `mixHash`: `` `0x${string}` ``; `nonce`: `blockTag` *extends* `"pending"` ? `null` : `` `0x${string}` ``; `number`: `blockTag` *extends* `"pending"` ? `null` : `bigint`; `parentBeaconBlockRoot`: `` `0x${string}` ``; `parentHash`: `` `0x${string}` ``; `receiptsRoot`: `` `0x${string}` ``; `sealFields`: `` `0x${string}` ``\[]; `sha3Uncles`: `` `0x${string}` ``; `size`: `bigint`; `stateRoot`: `` `0x${string}` ``; `timestamp`: `bigint`; `totalDifficulty`: `bigint` | `null`; `transactions`: `includeTransactions` *extends* `true` ? (\{ `accessList`: `undefined`; `authorizationList`: `undefined`; `blobVersionedHashes`: `undefined`; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `bigint`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `undefined`; `maxPriorityFeePerGas`: `undefined`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"legacy"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `undefined`; } | \{ `accessList`: `AccessList`; `authorizationList`: `undefined`; `blobVersionedHashes`: `undefined`; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `bigint`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `undefined`; `maxPriorityFeePerGas`: `undefined`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"eip2930"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `number`; } | \{ `accessList`: `AccessList`; `authorizationList`: `undefined`; `blobVersionedHashes`: `undefined`; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `undefined`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `bigint`; `maxPriorityFeePerGas`: `bigint`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"eip1559"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `number`; } | \{ `accessList`: `AccessList`; `authorizationList`: `undefined`; `blobVersionedHashes`: readonly `` `0x${string}` ``\[]; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `undefined`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `bigint`; `maxFeePerGas`: `bigint`; `maxPriorityFeePerGas`: `bigint`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"eip4844"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `number`; } | \{ `accessList`: `AccessList`; `authorizationList`: `SignedAuthorizationList`; `blobVersionedHashes`: `undefined`; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `undefined`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `bigint`; `maxPriorityFeePerGas`: `bigint`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"eip7702"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `number`; })\[] : `` `0x${string}` ``\[]; `transactionsRoot`: `` `0x${string}` ``; `uncles`: `` `0x${string}` ``\[]; `withdrawals`: `Withdrawal`\[]; `withdrawalsRoot`: `` `0x${string}` ``; }>

Information about the block. GetBlockReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const block = await client.getBlock()
```

##### getBlockNumber()

> **getBlockNumber**: (`args`?) => `Promise`\<`bigint`>

Returns the number of the most recent block seen.

* Docs: [https://viem.sh/docs/actions/public/getBlockNumber](https://viem.sh/docs/actions/public/getBlockNumber)
* Examples: [https://stackblitz.com/github/wevm/viem/tree/main/examples/blocks\_fetching-blocks](https://stackblitz.com/github/wevm/viem/tree/main/examples/blocks_fetching-blocks)
* JSON-RPC Methods: [`eth_blockNumber`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_blocknumber)

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args`? | `GetBlockNumberParameters` | GetBlockNumberParameters |

###### Returns

`Promise`\<`bigint`>

The number of the block. GetBlockNumberReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const blockNumber = await client.getBlockNumber()
// 69420n
```

##### getBlockTransactionCount()

> **getBlockTransactionCount**: (`args`?) => `Promise`\<`number`>

Returns the number of Transactions at a block number, hash, or tag.

* Docs: [https://viem.sh/docs/actions/public/getBlockTransactionCount](https://viem.sh/docs/actions/public/getBlockTransactionCount)
* JSON-RPC Methods:
  * Calls [`eth_getBlockTransactionCountByNumber`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getblocktransactioncountbynumber) for `blockNumber` & `blockTag`.
  * Calls [`eth_getBlockTransactionCountByHash`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getblocktransactioncountbyhash) for `blockHash`.

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args`? | `GetBlockTransactionCountParameters` | GetBlockTransactionCountParameters |

###### Returns

`Promise`\<`number`>

The block transaction count. GetBlockTransactionCountReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const count = await client.getBlockTransactionCount()
```

##### ~~getBytecode()~~

> **getBytecode**: (`args`) => `Promise`\<`GetCodeReturnType`>

###### Parameters

| Parameter | Type |
| - | - |
| `args` | `GetCodeParameters` |

###### Returns

`Promise`\<`GetCodeReturnType`>

###### Deprecated

Use `getCode` instead.

##### getChainId()

> **getChainId**: () => `Promise`\<`number`>

Returns the chain ID associated with the current network.

* Docs: [https://viem.sh/docs/actions/public/getChainId](https://viem.sh/docs/actions/public/getChainId)
* JSON-RPC Methods: [`eth_chainId`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_chainid)

###### Returns

`Promise`\<`number`>

The current chain ID. GetChainIdReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const chainId = await client.getChainId()
// 1
```

##### getCode()

> **getCode**: (`args`) => `Promise`\<`GetCodeReturnType`>

Retrieves the bytecode at an address.

* Docs: [https://viem.sh/docs/contract/getCode](https://viem.sh/docs/contract/getCode)
* JSON-RPC Methods: [`eth_getCode`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getcode)

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `GetCodeParameters` | GetBytecodeParameters |

###### Returns

`Promise`\<`GetCodeReturnType`>

The contract's bytecode. GetBytecodeReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const code = await client.getCode({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
})
```

##### getContractEvents()

> **getContractEvents**: \<`abi`, `eventName`, `strict`, `fromBlock`, `toBlock`>(`args`) => `Promise`\<`GetContractEventsReturnType`\<`abi`, `eventName`, `strict`, `fromBlock`, `toBlock`>>

Returns a list of event logs emitted by a contract.

* Docs: [https://viem.sh/docs/actions/public/getContractEvents](https://viem.sh/docs/actions/public/getContractEvents)
* JSON-RPC Methods: [`eth_getLogs`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getlogs)

###### Type Parameters

| Type Parameter | Default type |
| - | - |
| `abi` *extends* `Abi` \| readonly `unknown`\[] | - |
| `eventName` *extends* `string` \| `undefined` | `undefined` |
| `strict` *extends* `boolean` \| `undefined` | `undefined` |
| `fromBlock` *extends* `bigint` \| `BlockTag` \| `undefined` | `undefined` |
| `toBlock` *extends* `bigint` \| `BlockTag` \| `undefined` | `undefined` |

###### Parameters

| Parameter | Type |
| - | - |
| `args` | `GetContractEventsParameters`\<`abi`, `eventName`, `strict`, `fromBlock`, `toBlock`> |

###### Returns

`Promise`\<`GetContractEventsReturnType`\<`abi`, `eventName`, `strict`, `fromBlock`, `toBlock`>>

A list of event logs. GetContractEventsReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'
import { wagmiAbi } from './abi'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const logs = await client.getContractEvents(client, {
 address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
 abi: wagmiAbi,
 eventName: 'Transfer'
})
```

##### getEip712Domain()

> **getEip712Domain**: (`args`) => `Promise`\<`GetEip712DomainReturnType`>

Reads the EIP-712 domain from a contract, based on the ERC-5267 specification.

###### Parameters

| Parameter | Type |
| - | - |
| `args` | `GetEip712DomainParameters` |

###### Returns

`Promise`\<`GetEip712DomainReturnType`>

The EIP-712 domain, fields, and extensions. GetEip712DomainReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})

const domain = await client.getEip712Domain({
  address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
})
// {
//   domain: {
//     name: 'ExampleContract',
//     version: '1',
//     chainId: 1,
//     verifyingContract: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
//   },
//   fields: '0x0f',
//   extensions: [],
// }
```

##### getEnsAddress()

> **getEnsAddress**: (`args`) => `Promise`\<`GetEnsAddressReturnType`>

Gets address for ENS name.

* Docs: [https://viem.sh/docs/ens/actions/getEnsAddress](https://viem.sh/docs/ens/actions/getEnsAddress)
* Examples: [https://stackblitz.com/github/wevm/viem/tree/main/examples/ens](https://stackblitz.com/github/wevm/viem/tree/main/examples/ens)

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | \{ `blockNumber`: `bigint`; `blockTag`: `BlockTag`; `coinType`: `number`; `gatewayUrls`: `string`\[]; `name`: `string`; `strict`: `boolean`; `universalResolverAddress`: `` `0x${string}` ``; } | GetEnsAddressParameters |
| `args.blockNumber`? | `bigint` | The balance of the account at a block number. |
| `args.blockTag`? | `BlockTag` | The balance of the account at a block tag. **Default** `'latest'` |
| `args.coinType`? | `number` | ENSIP-9 compliant coinType used to resolve addresses for other chains |
| `args.gatewayUrls`? | `string`\[] | Universal Resolver gateway URLs to use for resolving CCIP-read requests. |
| `args.name` | `string` | Name to get the address for. |
| `args.strict`? | `boolean` | Whether or not to throw errors propagated from the ENS Universal Resolver Contract. |
| `args.universalResolverAddress`? | `` `0x${string}` `` | Address of ENS Universal Resolver Contract. |

###### Returns

`Promise`\<`GetEnsAddressReturnType`>

Address for ENS name or `null` if not found. GetEnsAddressReturnType

###### Remarks

Calls `resolve(bytes, bytes)` on ENS Universal Resolver Contract.

Since ENS names prohibit certain forbidden characters (e.g. underscore) and have other validation rules, you likely want to [normalize ENS names](https://docs.ens.domains/contract-api-reference/name-processing#normalising-names) with [UTS-46 normalization](https://unicode.org/reports/tr46) before passing them to `getEnsAddress`. You can use the built-in [`normalize`](https://viem.sh/docs/ens/utilities/normalize) function for this.

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'
import { normalize } from 'viem/ens'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const ensAddress = await client.getEnsAddress({
  name: normalize('wevm.eth'),
})
// '0xd2135CfB216b74109775236E36d4b433F1DF507B'
```

##### getEnsAvatar()

> **getEnsAvatar**: (`args`) => `Promise`\<`GetEnsAvatarReturnType`>

Gets the avatar of an ENS name.

* Docs: [https://viem.sh/docs/ens/actions/getEnsAvatar](https://viem.sh/docs/ens/actions/getEnsAvatar)
* Examples: [https://stackblitz.com/github/wevm/viem/tree/main/examples/ens](https://stackblitz.com/github/wevm/viem/tree/main/examples/ens)

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | \{ `assetGatewayUrls`: `AssetGatewayUrls`; `blockNumber`: `bigint`; `blockTag`: `BlockTag`; `gatewayUrls`: `string`\[]; `name`: `string`; `strict`: `boolean`; `universalResolverAddress`: `` `0x${string}` ``; } | GetEnsAvatarParameters |
| `args.assetGatewayUrls`? | `AssetGatewayUrls` | Gateway urls to resolve IPFS and/or Arweave assets. |
| `args.blockNumber`? | `bigint` | The balance of the account at a block number. |
| `args.blockTag`? | `BlockTag` | The balance of the account at a block tag. **Default** `'latest'` |
| `args.gatewayUrls`? | `string`\[] | Universal Resolver gateway URLs to use for resolving CCIP-read requests. |
| `args.name` | `string` | ENS name to get Text for. |
| `args.strict`? | `boolean` | Whether or not to throw errors propagated from the ENS Universal Resolver Contract. |
| `args.universalResolverAddress`? | `` `0x${string}` `` | Address of ENS Universal Resolver Contract. |

###### Returns

`Promise`\<`GetEnsAvatarReturnType`>

Avatar URI or `null` if not found. GetEnsAvatarReturnType

###### Remarks

Calls [`getEnsText`](https://viem.sh/docs/ens/actions/getEnsText) with `key` set to `'avatar'`.

Since ENS names prohibit certain forbidden characters (e.g. underscore) and have other validation rules, you likely want to [normalize ENS names](https://docs.ens.domains/contract-api-reference/name-processing#normalising-names) with [UTS-46 normalization](https://unicode.org/reports/tr46) before passing them to `getEnsAddress`. You can use the built-in [`normalize`](https://viem.sh/docs/ens/utilities/normalize) function for this.

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'
import { normalize } from 'viem/ens'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const ensAvatar = await client.getEnsAvatar({
  name: normalize('wevm.eth'),
})
// 'https://ipfs.io/ipfs/Qma8mnp6xV3J2cRNf3mTth5C8nV11CAnceVinc3y8jSbio'
```

##### getEnsName()

> **getEnsName**: (`args`) => `Promise`\<`GetEnsNameReturnType`>

Gets primary name for specified address.

* Docs: [https://viem.sh/docs/ens/actions/getEnsName](https://viem.sh/docs/ens/actions/getEnsName)
* Examples: [https://stackblitz.com/github/wevm/viem/tree/main/examples/ens](https://stackblitz.com/github/wevm/viem/tree/main/examples/ens)

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | \{ `address`: `` `0x${string}` ``; `blockNumber`: `bigint`; `blockTag`: `BlockTag`; `gatewayUrls`: `string`\[]; `strict`: `boolean`; `universalResolverAddress`: `` `0x${string}` ``; } | GetEnsNameParameters |
| `args.address` | `` `0x${string}` `` | Address to get ENS name for. |
| `args.blockNumber`? | `bigint` | The balance of the account at a block number. |
| `args.blockTag`? | `BlockTag` | The balance of the account at a block tag. **Default** `'latest'` |
| `args.gatewayUrls`? | `string`\[] | Universal Resolver gateway URLs to use for resolving CCIP-read requests. |
| `args.strict`? | `boolean` | Whether or not to throw errors propagated from the ENS Universal Resolver Contract. |
| `args.universalResolverAddress`? | `` `0x${string}` `` | Address of ENS Universal Resolver Contract. |

###### Returns

`Promise`\<`GetEnsNameReturnType`>

Name or `null` if not found. GetEnsNameReturnType

###### Remarks

Calls `reverse(bytes)` on ENS Universal Resolver Contract to "reverse resolve" the address to the primary ENS name.

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const ensName = await client.getEnsName({
  address: '0xd2135CfB216b74109775236E36d4b433F1DF507B',
})
// 'wevm.eth'
```

##### getEnsResolver()

> **getEnsResolver**: (`args`) => `Promise`\<`` `0x${string}` ``>

Gets resolver for ENS name.

* Docs: [https://viem.sh/docs/ens/actions/getEnsResolver](https://viem.sh/docs/ens/actions/getEnsResolver)
* Examples: [https://stackblitz.com/github/wevm/viem/tree/main/examples/ens](https://stackblitz.com/github/wevm/viem/tree/main/examples/ens)

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | \{ `blockNumber`: `bigint`; `blockTag`: `BlockTag`; `name`: `string`; `universalResolverAddress`: `` `0x${string}` ``; } | GetEnsResolverParameters |
| `args.blockNumber`? | `bigint` | The balance of the account at a block number. |
| `args.blockTag`? | `BlockTag` | The balance of the account at a block tag. **Default** `'latest'` |
| `args.name` | `string` | Name to get the address for. |
| `args.universalResolverAddress`? | `` `0x${string}` `` | Address of ENS Universal Resolver Contract. |

###### Returns

`Promise`\<`` `0x${string}` ``>

Address for ENS resolver. GetEnsResolverReturnType

###### Remarks

Calls `findResolver(bytes)` on ENS Universal Resolver Contract to retrieve the resolver of an ENS name.

Since ENS names prohibit certain forbidden characters (e.g. underscore) and have other validation rules, you likely want to [normalize ENS names](https://docs.ens.domains/contract-api-reference/name-processing#normalising-names) with [UTS-46 normalization](https://unicode.org/reports/tr46) before passing them to `getEnsAddress`. You can use the built-in [`normalize`](https://viem.sh/docs/ens/utilities/normalize) function for this.

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'
import { normalize } from 'viem/ens'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const resolverAddress = await client.getEnsResolver({
  name: normalize('wevm.eth'),
})
// '0x4976fb03C32e5B8cfe2b6cCB31c09Ba78EBaBa41'
```

##### getEnsText()

> **getEnsText**: (`args`) => `Promise`\<`GetEnsTextReturnType`>

Gets a text record for specified ENS name.

* Docs: [https://viem.sh/docs/ens/actions/getEnsResolver](https://viem.sh/docs/ens/actions/getEnsResolver)
* Examples: [https://stackblitz.com/github/wevm/viem/tree/main/examples/ens](https://stackblitz.com/github/wevm/viem/tree/main/examples/ens)

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | \{ `blockNumber`: `bigint`; `blockTag`: `BlockTag`; `gatewayUrls`: `string`\[]; `key`: `string`; `name`: `string`; `strict`: `boolean`; `universalResolverAddress`: `` `0x${string}` ``; } | GetEnsTextParameters |
| `args.blockNumber`? | `bigint` | The balance of the account at a block number. |
| `args.blockTag`? | `BlockTag` | The balance of the account at a block tag. **Default** `'latest'` |
| `args.gatewayUrls`? | `string`\[] | Universal Resolver gateway URLs to use for resolving CCIP-read requests. |
| `args.key` | `string` | Text record to retrieve. |
| `args.name` | `string` | ENS name to get Text for. |
| `args.strict`? | `boolean` | Whether or not to throw errors propagated from the ENS Universal Resolver Contract. |
| `args.universalResolverAddress`? | `` `0x${string}` `` | Address of ENS Universal Resolver Contract. |

###### Returns

`Promise`\<`GetEnsTextReturnType`>

Address for ENS resolver. GetEnsTextReturnType

###### Remarks

Calls `resolve(bytes, bytes)` on ENS Universal Resolver Contract.

Since ENS names prohibit certain forbidden characters (e.g. underscore) and have other validation rules, you likely want to [normalize ENS names](https://docs.ens.domains/contract-api-reference/name-processing#normalising-names) with [UTS-46 normalization](https://unicode.org/reports/tr46) before passing them to `getEnsAddress`. You can use the built-in [`normalize`](https://viem.sh/docs/ens/utilities/normalize) function for this.

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'
import { normalize } from 'viem/ens'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const twitterRecord = await client.getEnsText({
  name: normalize('wevm.eth'),
  key: 'com.twitter',
})
// 'wevm_dev'
```

##### getFeeHistory()

> **getFeeHistory**: (`args`) => `Promise`\<`GetFeeHistoryReturnType`>

Returns a collection of historical gas information.

* Docs: [https://viem.sh/docs/actions/public/getFeeHistory](https://viem.sh/docs/actions/public/getFeeHistory)
* JSON-RPC Methods: [`eth_feeHistory`](https://docs.alchemy.com/reference/eth-feehistory)

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `GetFeeHistoryParameters` | GetFeeHistoryParameters |

###### Returns

`Promise`\<`GetFeeHistoryReturnType`>

The gas estimate (in wei). GetFeeHistoryReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const feeHistory = await client.getFeeHistory({
  blockCount: 4,
  rewardPercentiles: [25, 75],
})
```

##### getFilterChanges()

> **getFilterChanges**: \<`filterType`, `abi`, `eventName`, `strict`, `fromBlock`, `toBlock`>(`args`) => `Promise`\<`GetFilterChangesReturnType`\<`filterType`, `abi`, `eventName`, `strict`, `fromBlock`, `toBlock`>>

Returns a list of logs or hashes based on a [Filter](https://viem.sh/docs/glossary/terms#filter) since the last time it was called.

* Docs: [https://viem.sh/docs/actions/public/getFilterChanges](https://viem.sh/docs/actions/public/getFilterChanges)
* JSON-RPC Methods: [`eth_getFilterChanges`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getfilterchanges)

###### Type Parameters

| Type Parameter | Default type |
| - | - |
| `filterType` *extends* `FilterType` | - |
| `abi` *extends* `Abi` \| readonly `unknown`\[] \| `undefined` | - |
| `eventName` *extends* `string` \| `undefined` | - |
| `strict` *extends* `boolean` \| `undefined` | `undefined` |
| `fromBlock` *extends* `bigint` \| `BlockTag` \| `undefined` | `undefined` |
| `toBlock` *extends* `bigint` \| `BlockTag` \| `undefined` | `undefined` |

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `GetFilterChangesParameters`\<`filterType`, `abi`, `eventName`, `strict`, `fromBlock`, `toBlock`> | GetFilterChangesParameters |

###### Returns

`Promise`\<`GetFilterChangesReturnType`\<`filterType`, `abi`, `eventName`, `strict`, `fromBlock`, `toBlock`>>

Logs or hashes. GetFilterChangesReturnType

###### Remarks

A Filter can be created from the following actions:

* [`createBlockFilter`](https://viem.sh/docs/actions/public/createBlockFilter)
* [`createContractEventFilter`](https://viem.sh/docs/contract/createContractEventFilter)
* [`createEventFilter`](https://viem.sh/docs/actions/public/createEventFilter)
* [`createPendingTransactionFilter`](https://viem.sh/docs/actions/public/createPendingTransactionFilter)

Depending on the type of filter, the return value will be different:

* If the filter was created with `createContractEventFilter` or `createEventFilter`, it returns a list of logs.
* If the filter was created with `createPendingTransactionFilter`, it returns a list of transaction hashes.
* If the filter was created with `createBlockFilter`, it returns a list of block hashes.

###### Examples

```ts theme={null}
// Blocks
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const filter = await client.createBlockFilter()
const hashes = await client.getFilterChanges({ filter })
```

```ts theme={null}
// Contract Events
import { createPublicClient, http, parseAbi } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const filter = await client.createContractEventFilter({
  address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
  abi: parseAbi(['event Transfer(address indexed, address indexed, uint256)']),
  eventName: 'Transfer',
})
const logs = await client.getFilterChanges({ filter })
```

```ts theme={null}
// Raw Events
import { createPublicClient, http, parseAbiItem } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const filter = await client.createEventFilter({
  address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
  event: parseAbiItem('event Transfer(address indexed, address indexed, uint256)'),
})
const logs = await client.getFilterChanges({ filter })
```

```ts theme={null}
// Transactions
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const filter = await client.createPendingTransactionFilter()
const hashes = await client.getFilterChanges({ filter })
```

##### getFilterLogs()

> **getFilterLogs**: \<`abi`, `eventName`, `strict`, `fromBlock`, `toBlock`>(`args`) => `Promise`\<`GetFilterLogsReturnType`\<`abi`, `eventName`, `strict`, `fromBlock`, `toBlock`>>

Returns a list of event logs since the filter was created.

* Docs: [https://viem.sh/docs/actions/public/getFilterLogs](https://viem.sh/docs/actions/public/getFilterLogs)
* JSON-RPC Methods: [`eth_getFilterLogs`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getfilterlogs)

###### Type Parameters

| Type Parameter | Default type |
| - | - |
| `abi` *extends* `Abi` \| readonly `unknown`\[] \| `undefined` | - |
| `eventName` *extends* `string` \| `undefined` | - |
| `strict` *extends* `boolean` \| `undefined` | `undefined` |
| `fromBlock` *extends* `bigint` \| `BlockTag` \| `undefined` | `undefined` |
| `toBlock` *extends* `bigint` \| `BlockTag` \| `undefined` | `undefined` |

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `GetFilterLogsParameters`\<`abi`, `eventName`, `strict`, `fromBlock`, `toBlock`> | GetFilterLogsParameters |

###### Returns

`Promise`\<`GetFilterLogsReturnType`\<`abi`, `eventName`, `strict`, `fromBlock`, `toBlock`>>

A list of event logs. GetFilterLogsReturnType

###### Remarks

`getFilterLogs` is only compatible with **event filters**.

###### Example

```ts theme={null}
import { createPublicClient, http, parseAbiItem } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const filter = await client.createEventFilter({
  address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
  event: parseAbiItem('event Transfer(address indexed, address indexed, uint256)'),
})
const logs = await client.getFilterLogs({ filter })
```

##### getGasPrice()

> **getGasPrice**: () => `Promise`\<`bigint`>

Returns the current price of gas (in wei).

* Docs: [https://viem.sh/docs/actions/public/getGasPrice](https://viem.sh/docs/actions/public/getGasPrice)
* JSON-RPC Methods: [`eth_gasPrice`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_gasprice)

###### Returns

`Promise`\<`bigint`>

The gas price (in wei). GetGasPriceReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const gasPrice = await client.getGasPrice()
```

##### getLogs()

> **getLogs**: \<`abiEvent`, `abiEvents`, `strict`, `fromBlock`, `toBlock`>(`args`?) => `Promise`\<`GetLogsReturnType`\<`abiEvent`, `abiEvents`, `strict`, `fromBlock`, `toBlock`>>

Returns a list of event logs matching the provided parameters.

* Docs: [https://viem.sh/docs/actions/public/getLogs](https://viem.sh/docs/actions/public/getLogs)
* Examples: [https://stackblitz.com/github/wevm/viem/tree/main/examples/logs\_event-logs](https://stackblitz.com/github/wevm/viem/tree/main/examples/logs_event-logs)
* JSON-RPC Methods: [`eth_getLogs`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getlogs)

###### Type Parameters

| Type Parameter | Default type |
| - | - |
| `abiEvent` *extends* `AbiEvent` \| `undefined` | `undefined` |
| `abiEvents` *extends* readonly `unknown`\[] \| readonly `AbiEvent`\[] \| `undefined` | `abiEvent` *extends* `AbiEvent` ? \[`abiEvent`] : `undefined` |
| `strict` *extends* `boolean` \| `undefined` | `undefined` |
| `fromBlock` *extends* `bigint` \| `BlockTag` \| `undefined` | `undefined` |
| `toBlock` *extends* `bigint` \| `BlockTag` \| `undefined` | `undefined` |

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args`? | `GetLogsParameters`\<`abiEvent`, `abiEvents`, `strict`, `fromBlock`, `toBlock`> | GetLogsParameters |

###### Returns

`Promise`\<`GetLogsReturnType`\<`abiEvent`, `abiEvents`, `strict`, `fromBlock`, `toBlock`>>

A list of event logs. GetLogsReturnType

###### Example

```ts theme={null}
import { createPublicClient, http, parseAbiItem } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const logs = await client.getLogs()
```

##### getProof()

> **getProof**: (`args`) => `Promise`\<`GetProofReturnType`>

Returns the account and storage values of the specified account including the Merkle-proof.

* Docs: [https://viem.sh/docs/actions/public/getProof](https://viem.sh/docs/actions/public/getProof)
* JSON-RPC Methods:
  * Calls [`eth_getProof`](https://eips.ethereum.org/EIPS/eip-1186)

###### Parameters

| Parameter | Type |
| - | - |
| `args` | `GetProofParameters` |

###### Returns

`Promise`\<`GetProofReturnType`>

Proof data. GetProofReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const block = await client.getProof({
 address: '0x...',
 storageKeys: ['0x...'],
})
```

##### getStorageAt()

> **getStorageAt**: (`args`) => `Promise`\<`GetStorageAtReturnType`>

Returns the value from a storage slot at a given address.

* Docs: [https://viem.sh/docs/contract/getStorageAt](https://viem.sh/docs/contract/getStorageAt)
* JSON-RPC Methods: [`eth_getStorageAt`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getstorageat)

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `GetStorageAtParameters` | GetStorageAtParameters |

###### Returns

`Promise`\<`GetStorageAtReturnType`>

The value of the storage slot. GetStorageAtReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'
import { getStorageAt } from 'viem/contract'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const code = await client.getStorageAt({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  slot: toHex(0),
})
```

##### getTransaction()

> **getTransaction**: \<`blockTag`>(`args`) => `Promise`\<\{ `accessList`: `undefined`; `authorizationList`: `undefined`; `blobVersionedHashes`: `undefined`; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `bigint`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `undefined`; `maxPriorityFeePerGas`: `undefined`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"legacy"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `undefined`; } | \{ `accessList`: `AccessList`; `authorizationList`: `undefined`; `blobVersionedHashes`: `undefined`; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `bigint`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `undefined`; `maxPriorityFeePerGas`: `undefined`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"eip2930"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `number`; } | \{ `accessList`: `AccessList`; `authorizationList`: `undefined`; `blobVersionedHashes`: `undefined`; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `undefined`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `bigint`; `maxPriorityFeePerGas`: `bigint`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"eip1559"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `number`; } | \{ `accessList`: `AccessList`; `authorizationList`: `undefined`; `blobVersionedHashes`: readonly `` `0x${string}` ``\[]; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `undefined`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `bigint`; `maxFeePerGas`: `bigint`; `maxPriorityFeePerGas`: `bigint`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"eip4844"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `number`; } | \{ `accessList`: `AccessList`; `authorizationList`: `SignedAuthorizationList`; `blobVersionedHashes`: `undefined`; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `undefined`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `bigint`; `maxPriorityFeePerGas`: `bigint`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"eip7702"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `number`; }>

Returns information about a [Transaction](https://viem.sh/docs/glossary/terms#transaction) given a hash or block identifier.

* Docs: [https://viem.sh/docs/actions/public/getTransaction](https://viem.sh/docs/actions/public/getTransaction)
* Example: [https://stackblitz.com/github/wevm/viem/tree/main/examples/transactions\_fetching-transactions](https://stackblitz.com/github/wevm/viem/tree/main/examples/transactions_fetching-transactions)
* JSON-RPC Methods: [`eth_getTransactionByHash`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getTransactionByHash)

###### Type Parameters

| Type Parameter | Default type |
| - | - |
| `blockTag` *extends* `BlockTag` | `"latest"` |

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `GetTransactionParameters`\<`blockTag`> | GetTransactionParameters |

###### Returns

`Promise`\<\{ `accessList`: `undefined`; `authorizationList`: `undefined`; `blobVersionedHashes`: `undefined`; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `bigint`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `undefined`; `maxPriorityFeePerGas`: `undefined`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"legacy"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `undefined`; } | \{ `accessList`: `AccessList`; `authorizationList`: `undefined`; `blobVersionedHashes`: `undefined`; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `bigint`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `undefined`; `maxPriorityFeePerGas`: `undefined`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"eip2930"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `number`; } | \{ `accessList`: `AccessList`; `authorizationList`: `undefined`; `blobVersionedHashes`: `undefined`; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `undefined`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `bigint`; `maxPriorityFeePerGas`: `bigint`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"eip1559"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `number`; } | \{ `accessList`: `AccessList`; `authorizationList`: `undefined`; `blobVersionedHashes`: readonly `` `0x${string}` ``\[]; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `undefined`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `bigint`; `maxFeePerGas`: `bigint`; `maxPriorityFeePerGas`: `bigint`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"eip4844"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `number`; } | \{ `accessList`: `AccessList`; `authorizationList`: `SignedAuthorizationList`; `blobVersionedHashes`: `undefined`; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `undefined`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `bigint`; `maxPriorityFeePerGas`: `bigint`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"eip7702"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `number`; }>

The transaction information. GetTransactionReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const transaction = await client.getTransaction({
  hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
})
```

##### getTransactionConfirmations()

> **getTransactionConfirmations**: (`args`) => `Promise`\<`bigint`>

Returns the number of blocks passed (confirmations) since the transaction was processed on a block.

* Docs: [https://viem.sh/docs/actions/public/getTransactionConfirmations](https://viem.sh/docs/actions/public/getTransactionConfirmations)
* Example: [https://stackblitz.com/github/wevm/viem/tree/main/examples/transactions\_fetching-transactions](https://stackblitz.com/github/wevm/viem/tree/main/examples/transactions_fetching-transactions)
* JSON-RPC Methods: [`eth_getTransactionConfirmations`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getTransactionConfirmations)

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `GetTransactionConfirmationsParameters`\<`Chain`> | GetTransactionConfirmationsParameters |

###### Returns

`Promise`\<`bigint`>

The number of blocks passed since the transaction was processed. If confirmations is 0, then the Transaction has not been confirmed & processed yet. GetTransactionConfirmationsReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const confirmations = await client.getTransactionConfirmations({
  hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
})
```

##### getTransactionCount()

> **getTransactionCount**: (`args`) => `Promise`\<`number`>

Returns the number of [Transactions](https://viem.sh/docs/glossary/terms#transaction) an Account has broadcast / sent.

* Docs: [https://viem.sh/docs/actions/public/getTransactionCount](https://viem.sh/docs/actions/public/getTransactionCount)
* JSON-RPC Methods: [`eth_getTransactionCount`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_gettransactioncount)

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `GetTransactionCountParameters` | GetTransactionCountParameters |

###### Returns

`Promise`\<`number`>

The number of transactions an account has sent. GetTransactionCountReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const transactionCount = await client.getTransactionCount({
  address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
})
```

##### getTransactionReceipt()

> **getTransactionReceipt**: (`args`) => `Promise`\<`TransactionReceipt`>

Returns the [Transaction Receipt](https://viem.sh/docs/glossary/terms#transaction-receipt) given a [Transaction](https://viem.sh/docs/glossary/terms#transaction) hash.

* Docs: [https://viem.sh/docs/actions/public/getTransactionReceipt](https://viem.sh/docs/actions/public/getTransactionReceipt)
* Example: [https://stackblitz.com/github/wevm/viem/tree/main/examples/transactions\_fetching-transactions](https://stackblitz.com/github/wevm/viem/tree/main/examples/transactions_fetching-transactions)
* JSON-RPC Methods: [`eth_getTransactionReceipt`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getTransactionReceipt)

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `GetTransactionReceiptParameters` | GetTransactionReceiptParameters |

###### Returns

`Promise`\<`TransactionReceipt`>

The transaction receipt. GetTransactionReceiptReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const transactionReceipt = await client.getTransactionReceipt({
  hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
})
```

##### key

> **key**: `string`

A key for the client.

##### multicall()

> **multicall**: \<`contracts`, `allowFailure`>(`args`) => `Promise`\<`MulticallReturnType`\<`contracts`, `allowFailure`>>

Similar to [`readContract`](https://viem.sh/docs/contract/readContract), but batches up multiple functions on a contract in a single RPC call via the [`multicall3` contract](https://github.com/mds1/multicall).

* Docs: [https://viem.sh/docs/contract/multicall](https://viem.sh/docs/contract/multicall)

###### Type Parameters

| Type Parameter | Default type |
| - | - |
| `contracts` *extends* readonly `unknown`\[] | - |
| `allowFailure` *extends* `boolean` | `true` |

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `MulticallParameters`\<`contracts`, `allowFailure`> | MulticallParameters |

###### Returns

`Promise`\<`MulticallReturnType`\<`contracts`, `allowFailure`>>

An array of results with accompanying status. MulticallReturnType

###### Example

```ts theme={null}
import { createPublicClient, http, parseAbi } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const abi = parseAbi([
  'function balanceOf(address) view returns (uint256)',
  'function totalSupply() view returns (uint256)',
])
const result = await client.multicall({
  contracts: [
    {
      address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
      abi,
      functionName: 'balanceOf',
      args: ['0xA0Cf798816D4b9b9866b5330EEa46a18382f251e'],
    },
    {
      address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
      abi,
      functionName: 'totalSupply',
    },
  ],
})
// [{ result: 424122n, status: 'success' }, { result: 1000000n, status: 'success' }]
```

##### name

> **name**: `string`

A name for the client.

##### pollingInterval

> **pollingInterval**: `number`

Frequency (in ms) for polling enabled actions & events. Defaults to 4\_000 milliseconds.

##### prepareTransactionRequest()

> **prepareTransactionRequest**: \<`request`, `chainOverride`, `accountOverride`>(`args`) => `Promise`\<\{ \[K in string | number | symbol]: (UnionRequiredBy\<Extract\<UnionOmit\<(...), (...)> & ((...) extends (...) ? (...) : (...)) & ((...) extends (...) ? (...) : (...)), IsNever\<(...)> extends true ? unknown : ExactPartial\<(...)>> & \{ chainId?: number }, ParameterTypeToParameters\<request\["parameters"] extends readonly PrepareTransactionRequestParameterType\[] ? any\[any]\[number] : "fees" | "gas" | "nonce" | "blobVersionedHashes" | "chainId" | "type">> & (unknown extends request\["kzg"] ? \{} : Pick\<request, "kzg">))\[K] }>

Prepares a transaction request for signing.

* Docs: [https://viem.sh/docs/actions/wallet/prepareTransactionRequest](https://viem.sh/docs/actions/wallet/prepareTransactionRequest)

###### Type Parameters

| Type Parameter | Default type |
| - | - |
| `request` *extends* `Omit`\<\{ `accessList`: `undefined`; `authorizationList`: `undefined`; `blobs`: `undefined`; `blobVersionedHashes`: `undefined`; `data`: `` `0x${string}` ``; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `bigint`; `kzg`: `undefined`; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `undefined`; `maxPriorityFeePerGas`: `undefined`; `nonce`: `number`; `sidecars`: `undefined`; `to`: `` `0x${string}` `` \| `null`; `type`: `"legacy"`; `value`: `bigint`; }, `"from"`> \| `Omit`\<\{ `accessList`: `AccessList`; `authorizationList`: `undefined`; `blobs`: `undefined`; `blobVersionedHashes`: `undefined`; `data`: `` `0x${string}` ``; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `bigint`; `kzg`: `undefined`; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `undefined`; `maxPriorityFeePerGas`: `undefined`; `nonce`: `number`; `sidecars`: `undefined`; `to`: `` `0x${string}` `` \| `null`; `type`: `"eip2930"`; `value`: `bigint`; }, `"from"`> \| `Omit`\<\{ `accessList`: `AccessList`; `authorizationList`: `undefined`; `blobs`: `undefined`; `blobVersionedHashes`: `undefined`; `data`: `` `0x${string}` ``; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `undefined`; `kzg`: `undefined`; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `bigint`; `maxPriorityFeePerGas`: `bigint`; `nonce`: `number`; `sidecars`: `undefined`; `to`: `` `0x${string}` `` \| `null`; `type`: `"eip1559"`; `value`: `bigint`; }, `"from"`> \| `Omit`\<\{ `accessList`: `AccessList`; `authorizationList`: `undefined`; `blobs`: readonly `` `0x${string}` ``\[] \| readonly `Uint8Array`\[]; `blobVersionedHashes`: readonly `` `0x${string}` ``\[]; `data`: `` `0x${string}` ``; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `undefined`; `kzg`: `Kzg`; `maxFeePerBlobGas`: `bigint`; `maxFeePerGas`: `bigint`; `maxPriorityFeePerGas`: `bigint`; `nonce`: `number`; `sidecars`: readonly `BlobSidecar`\<`` `0x${string}` ``>\[]; `to`: `` `0x${string}` `` \| `null`; `type`: `"eip4844"`; `value`: `bigint`; }, `"from"`> \| `Omit`\<\{ `accessList`: `AccessList`; `authorizationList`: `AuthorizationList`\<`number`, `boolean`>; `blobs`: `undefined`; `blobVersionedHashes`: `undefined`; `data`: `` `0x${string}` ``; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `undefined`; `kzg`: `undefined`; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `bigint`; `maxPriorityFeePerGas`: `bigint`; `nonce`: `number`; `sidecars`: `undefined`; `to`: `` `0x${string}` `` \| `null`; `type`: `"eip7702"`; `value`: `bigint`; }, `"from"`> & `object` & `object` | - |
| `chainOverride` *extends* `Chain` \| `undefined` | `undefined` |
| `accountOverride` *extends* `` `0x${string}` `` \| `Account` \| `undefined` | `undefined` |

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `PrepareTransactionRequestParameters`\<`Chain`, `Account` \| `undefined`, `chainOverride`, `accountOverride`, `request`> | PrepareTransactionRequestParameters |

###### Returns

`Promise`\<\{ \[K in string | number | symbol]: (UnionRequiredBy\<Extract\<UnionOmit\<(...), (...)> & ((...) extends (...) ? (...) : (...)) & ((...) extends (...) ? (...) : (...)), IsNever\<(...)> extends true ? unknown : ExactPartial\<(...)>> & \{ chainId?: number }, ParameterTypeToParameters\<request\["parameters"] extends readonly PrepareTransactionRequestParameterType\[] ? any\[any]\[number] : "fees" | "gas" | "nonce" | "blobVersionedHashes" | "chainId" | "type">> & (unknown extends request\["kzg"] ? \{} : Pick\<request, "kzg">))\[K] }>

The transaction request. PrepareTransactionRequestReturnType

###### Examples

```ts theme={null}
import { createWalletClient, custom } from 'viem'
import { mainnet } from 'viem/chains'

const client = createWalletClient({
  chain: mainnet,
  transport: custom(window.ethereum),
})
const request = await client.prepareTransactionRequest({
  account: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
  to: '0x0000000000000000000000000000000000000000',
  value: 1n,
})
```

```ts theme={null}
// Account Hoisting
import { createWalletClient, http } from 'viem'
import { privateKeyToAccount } from 'viem/accounts'
import { mainnet } from 'viem/chains'

const client = createWalletClient({
  account: privateKeyToAccount('0x…'),
  chain: mainnet,
  transport: custom(window.ethereum),
})
const request = await client.prepareTransactionRequest({
  to: '0x0000000000000000000000000000000000000000',
  value: 1n,
})
```

##### readContract()

> **readContract**: \<`abi`, `functionName`, `args`>(`args`) => `Promise`\<`ReadContractReturnType`\<`abi`, `functionName`, `args`>>

Calls a read-only function on a contract, and returns the response.

* Docs: [https://viem.sh/docs/contract/readContract](https://viem.sh/docs/contract/readContract)
* Examples: [https://stackblitz.com/github/wevm/viem/tree/main/examples/contracts\_reading-contracts](https://stackblitz.com/github/wevm/viem/tree/main/examples/contracts_reading-contracts)

###### Type Parameters

| Type Parameter |
| - |
| `abi` *extends* `Abi` \| readonly `unknown`\[] |
| `functionName` *extends* `string` |
| `args` *extends* `unknown` |

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `ReadContractParameters`\<`abi`, `functionName`, `args`> | ReadContractParameters |

###### Returns

`Promise`\<`ReadContractReturnType`\<`abi`, `functionName`, `args`>>

The response from the contract. Type is inferred. ReadContractReturnType

###### Remarks

A "read-only" function (constant function) on a Solidity contract is denoted by a `view` or `pure` keyword. They can only read the state of the contract, and cannot make any changes to it. Since read-only methods do not change the state of the contract, they do not require any gas to be executed, and can be called by any user without the need to pay for gas.

Internally, uses a [Public Client](https://viem.sh/docs/clients/public) to call the [`call` action](https://viem.sh/docs/actions/public/call) with [ABI-encoded `data`](https://viem.sh/docs/contract/encodeFunctionData).

###### Example

```ts theme={null}
import { createPublicClient, http, parseAbi } from 'viem'
import { mainnet } from 'viem/chains'
import { readContract } from 'viem/contract'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const result = await client.readContract({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: parseAbi(['function balanceOf(address) view returns (uint256)']),
  functionName: 'balanceOf',
  args: ['0xA0Cf798816D4b9b9866b5330EEa46a18382f251e'],
})
// 424122n
```

##### request

> **request**: `EIP1193RequestFn`\<`PublicRpcSchema`>

Request function wrapped with friendly error handling

##### sendRawTransaction()

> **sendRawTransaction**: (`args`) => `Promise`\<`` `0x${string}` ``>

Sends a **signed** transaction to the network

* Docs: [https://viem.sh/docs/actions/wallet/sendRawTransaction](https://viem.sh/docs/actions/wallet/sendRawTransaction)
* JSON-RPC Method: [`eth_sendRawTransaction`](https://ethereum.github.io/execution-apis/api-documentation/)

###### Parameters

| Parameter | Type |
| - | - |
| `args` | `SendRawTransactionParameters` |

###### Returns

`Promise`\<`` `0x${string}` ``>

The transaction hash. SendRawTransactionReturnType

###### Example

```ts theme={null}
import { createWalletClient, custom } from 'viem'
import { mainnet } from 'viem/chains'
import { sendRawTransaction } from 'viem/wallet'

const client = createWalletClient({
  chain: mainnet,
  transport: custom(window.ethereum),
})

const hash = await client.sendRawTransaction({
  serializedTransaction: '0x02f850018203118080825208808080c080a04012522854168b27e5dc3d5839bab5e6b39e1a0ffd343901ce1622e3d64b48f1a04e00902ae0502c4728cbf12156290df99c3ed7de85b1dbfe20b5c36931733a33'
})
```

##### ~~simulate()~~

> **simulate**: \<`calls`>(`args`) => `Promise`\<`SimulateBlocksReturnType`\<`calls`>>

###### Type Parameters

| Type Parameter |
| - |
| `calls` *extends* readonly `unknown`\[] |

###### Parameters

| Parameter | Type |
| - | - |
| `args` | `SimulateBlocksParameters`\<`calls`> |

###### Returns

`Promise`\<`SimulateBlocksReturnType`\<`calls`>>

###### Deprecated

Use `simulateBlocks` instead.

##### simulateBlocks()

> **simulateBlocks**: \<`calls`>(`args`) => `Promise`\<`SimulateBlocksReturnType`\<`calls`>>

Simulates a set of calls on block(s) with optional block and state overrides.

###### Type Parameters

| Type Parameter |
| - |
| `calls` *extends* readonly `unknown`\[] |

###### Parameters

| Parameter | Type |
| - | - |
| `args` | `SimulateBlocksParameters`\<`calls`> |

###### Returns

`Promise`\<`SimulateBlocksReturnType`\<`calls`>>

Simulated blocks. SimulateReturnType

###### Example

```ts theme={null}
import { createPublicClient, http, parseEther } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})

const result = await client.simulateBlocks({
  blocks: [{
    blockOverrides: {
      number: 69420n,
    },
    calls: [{
      {
        account: '0x5a0b54d5dc17e482fe8b0bdca5320161b95fb929',
        data: '0xdeadbeef',
        to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
      },
      {
        account: '0x5a0b54d5dc17e482fe8b0bdca5320161b95fb929',
        to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
        value: parseEther('1'),
      },
    }],
    stateOverrides: [{
      address: '0x5a0b54d5dc17e482fe8b0bdca5320161b95fb929',
      balance: parseEther('10'),
    }],
  }]
})
```

##### simulateCalls()

> **simulateCalls**: \<`calls`>(`args`) => `Promise`\<`SimulateCallsReturnType`\<`calls`>>

Simulates a set of calls.

###### Type Parameters

| Type Parameter |
| - |
| `calls` *extends* readonly `unknown`\[] |

###### Parameters

| Parameter | Type |
| - | - |
| `args` | `SimulateCallsParameters`\<`calls`> |

###### Returns

`Promise`\<`SimulateCallsReturnType`\<`calls`>>

Results. SimulateCallsReturnType

###### Example

```ts theme={null}
import { createPublicClient, http, parseEther } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})

const result = await client.simulateCalls({
  account: '0x5a0b54d5dc17e482fe8b0bdca5320161b95fb929',
  calls: [{
    {
      data: '0xdeadbeef',
      to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
    },
    {
      to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
      value: parseEther('1'),
    },
  ]
})
```

##### simulateContract()

> **simulateContract**: \<`abi`, `functionName`, `args`, `chainOverride`, `accountOverride`>(`args`) => `Promise`\<`SimulateContractReturnType`\<`abi`, `functionName`, `args`, `Chain`, `Account` | `undefined`, `chainOverride`, `accountOverride`>>

Simulates/validates a contract interaction. This is useful for retrieving **return data** and **revert reasons** of contract write functions.

* Docs: [https://viem.sh/docs/contract/simulateContract](https://viem.sh/docs/contract/simulateContract)
* Examples: [https://stackblitz.com/github/wevm/viem/tree/main/examples/contracts\_writing-to-contracts](https://stackblitz.com/github/wevm/viem/tree/main/examples/contracts_writing-to-contracts)

###### Type Parameters

| Type Parameter | Default type |
| - | - |
| `abi` *extends* `Abi` \| readonly `unknown`\[] | - |
| `functionName` *extends* `string` | - |
| `args` *extends* `unknown` | - |
| `chainOverride` *extends* `Chain` \| `undefined` | - |
| `accountOverride` *extends* `` `0x${string}` `` \| `Account` \| `undefined` | `undefined` |

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `SimulateContractParameters`\<`abi`, `functionName`, `args`, `Chain`, `chainOverride`, `accountOverride`> | SimulateContractParameters |

###### Returns

`Promise`\<`SimulateContractReturnType`\<`abi`, `functionName`, `args`, `Chain`, `Account` | `undefined`, `chainOverride`, `accountOverride`>>

The simulation result and write request. SimulateContractReturnType

###### Remarks

This function does not require gas to execute and ***does not*** change the state of the blockchain. It is almost identical to [`readContract`](https://viem.sh/docs/contract/readContract), but also supports contract write functions.

Internally, uses a [Public Client](https://viem.sh/docs/clients/public) to call the [`call` action](https://viem.sh/docs/actions/public/call) with [ABI-encoded `data`](https://viem.sh/docs/contract/encodeFunctionData).

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const result = await client.simulateContract({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: parseAbi(['function mint(uint32) view returns (uint32)']),
  functionName: 'mint',
  args: ['69420'],
  account: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
})
```

##### transport

> **transport**: `TransportConfig`\<`"http"`, `EIP1193RequestFn`> & `object`

The RPC transport

###### Type Declaration

###### fetchOptions?

> `optional` **fetchOptions**: `Omit`\<`RequestInit`, `"body"`>

###### url?

> `optional` **url**: `string`

##### type

> **type**: `string`

The type of client.

##### uid

> **uid**: `string`

A unique ID for the client.

##### uninstallFilter()

> **uninstallFilter**: (`args`) => `Promise`\<`boolean`>

Destroys a Filter that was created from one of the following Actions:

* [`createBlockFilter`](https://viem.sh/docs/actions/public/createBlockFilter)

* [`createEventFilter`](https://viem.sh/docs/actions/public/createEventFilter)

* [`createPendingTransactionFilter`](https://viem.sh/docs/actions/public/createPendingTransactionFilter)

* Docs: [https://viem.sh/docs/actions/public/uninstallFilter](https://viem.sh/docs/actions/public/uninstallFilter)

* JSON-RPC Methods: [`eth_uninstallFilter`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_uninstallFilter)

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `UninstallFilterParameters` | UninstallFilterParameters |

###### Returns

`Promise`\<`boolean`>

A boolean indicating if the Filter was successfully uninstalled. UninstallFilterReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'
import { createPendingTransactionFilter, uninstallFilter } from 'viem/public'

const filter = await client.createPendingTransactionFilter()
const uninstalled = await client.uninstallFilter({ filter })
// true
```

##### verifyMessage()

> **verifyMessage**: (`args`) => `Promise`\<`boolean`>

Verify that a message was signed by the provided address.

Compatible with Smart Contract Accounts & Externally Owned Accounts via [ERC-6492](https://eips.ethereum.org/EIPS/eip-6492).

* Docs [https://viem.sh/docs/actions/public/verifyMessage](https://viem.sh/docs/actions/public/verifyMessage)

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | \{ `address`: `` `0x${string}` ``; `blockNumber`: `bigint`; `blockTag`: `BlockTag`; `factory`: `` `0x${string}` ``; `factoryData`: `` `0x${string}` ``; `message`: `SignableMessage`; `signature`: `` `0x${string}` `` \| `Signature` \| `Uint8Array`; `universalSignatureVerifierAddress`: `` `0x${string}` ``; } | - |
| `args.address` | `` `0x${string}` `` | The address that signed the original message. |
| `args.blockNumber`? | `bigint` | The balance of the account at a block number. |
| `args.blockTag`? | `BlockTag` | The balance of the account at a block tag. **Default** `'latest'` |
| `args.factory`? | `` `0x${string}` `` | - |
| `args.factoryData`? | `` `0x${string}` `` | - |
| `args.message` | `SignableMessage` | The message to be verified. |
| `args.signature` | `` `0x${string}` `` \| `Signature` \| `Uint8Array` | The signature that was generated by signing the message with the address's private key. |
| `args.universalSignatureVerifierAddress`? | `` `0x${string}` `` | - |

###### Returns

`Promise`\<`boolean`>

Whether or not the signature is valid. VerifyMessageReturnType

##### verifySiweMessage()

> **verifySiweMessage**: (`args`) => `Promise`\<`boolean`>

Verifies [EIP-4361](https://eips.ethereum.org/EIPS/eip-4361) formatted message was signed.

Compatible with Smart Contract Accounts & Externally Owned Accounts via [ERC-6492](https://eips.ethereum.org/EIPS/eip-6492).

* Docs [https://viem.sh/docs/siwe/actions/verifySiweMessage](https://viem.sh/docs/siwe/actions/verifySiweMessage)

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | \{ `address`: `` `0x${string}` ``; `blockNumber`: `bigint`; `blockTag`: `BlockTag`; `domain`: `string`; `message`: `string`; `nonce`: `string`; `scheme`: `string`; `signature`: `` `0x${string}` ``; `time`: `Date`; } | - |
| `args.address`? | `` `0x${string}` `` | Ethereum address to check against. |
| `args.blockNumber`? | `bigint` | The balance of the account at a block number. |
| `args.blockTag`? | `BlockTag` | The balance of the account at a block tag. **Default** `'latest'` |
| `args.domain`? | `string` | [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986) authority to check against. |
| `args.message` | `string` | EIP-4361 formatted message. |
| `args.nonce`? | `string` | Random string to check against. |
| `args.scheme`? | `string` | [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) URI scheme to check against. |
| `args.signature` | `` `0x${string}` `` | Signature to check against. |
| `args.time`? | `Date` | Current time to check optional `expirationTime` and `notBefore` fields. **Default** `new Date()` |

###### Returns

`Promise`\<`boolean`>

Whether or not the signature is valid. VerifySiweMessageReturnType

##### verifyTypedData()

> **verifyTypedData**: (`args`) => `Promise`\<`boolean`>

Verify that typed data was signed by the provided address.

* Docs [https://viem.sh/docs/actions/public/verifyTypedData](https://viem.sh/docs/actions/public/verifyTypedData)

###### Parameters

| Parameter | Type |
| - | - |
| `args` | `VerifyTypedDataParameters` |

###### Returns

`Promise`\<`boolean`>

Whether or not the signature is valid. VerifyTypedDataReturnType

##### waitForTransactionReceipt()

> **waitForTransactionReceipt**: (`args`) => `Promise`\<`TransactionReceipt`>

Waits for the [Transaction](https://viem.sh/docs/glossary/terms#transaction) to be included on a [Block](https://viem.sh/docs/glossary/terms#block) (one confirmation), and then returns the [Transaction Receipt](https://viem.sh/docs/glossary/terms#transaction-receipt). If the Transaction reverts, then the action will throw an error.

* Docs: [https://viem.sh/docs/actions/public/waitForTransactionReceipt](https://viem.sh/docs/actions/public/waitForTransactionReceipt)
* Example: [https://stackblitz.com/github/wevm/viem/tree/main/examples/transactions\_sending-transactions](https://stackblitz.com/github/wevm/viem/tree/main/examples/transactions_sending-transactions)
* JSON-RPC Methods:
  * Polls [`eth_getTransactionReceipt`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getTransactionReceipt) on each block until it has been processed.
  * If a Transaction has been replaced:
    * Calls [`eth_getBlockByNumber`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getblockbynumber) and extracts the transactions
    * Checks if one of the Transactions is a replacement
    * If so, calls [`eth_getTransactionReceipt`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getTransactionReceipt).

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `WaitForTransactionReceiptParameters`\<`Chain`> | WaitForTransactionReceiptParameters |

###### Returns

`Promise`\<`TransactionReceipt`>

The transaction receipt. WaitForTransactionReceiptReturnType

###### Remarks

The `waitForTransactionReceipt` action additionally supports Replacement detection (e.g. sped up Transactions).

Transactions can be replaced when a user modifies their transaction in their wallet (to speed up or cancel). Transactions are replaced when they are sent from the same nonce.

There are 3 types of Transaction Replacement reasons:

* `repriced`: The gas price has been modified (e.g. different `maxFeePerGas`)
* `cancelled`: The Transaction has been cancelled (e.g. `value === 0n`)
* `replaced`: The Transaction has been replaced (e.g. different `value` or `data`)

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const transactionReceipt = await client.waitForTransactionReceipt({
  hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
})
```

##### watchBlockNumber()

> **watchBlockNumber**: (`args`) => `WatchBlockNumberReturnType`

Watches and returns incoming block numbers.

* Docs: [https://viem.sh/docs/actions/public/watchBlockNumber](https://viem.sh/docs/actions/public/watchBlockNumber)
* Examples: [https://stackblitz.com/github/wevm/viem/tree/main/examples/blocks\_watching-blocks](https://stackblitz.com/github/wevm/viem/tree/main/examples/blocks_watching-blocks)
* JSON-RPC Methods:
  * When `poll: true`, calls [`eth_blockNumber`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_blocknumber) on a polling interval.
  * When `poll: false` & WebSocket Transport, uses a WebSocket subscription via [`eth_subscribe`](https://docs.alchemy.com/reference/eth-subscribe-polygon) and the `"newHeads"` event.

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `WatchBlockNumberParameters` | WatchBlockNumberParameters |

###### Returns

`WatchBlockNumberReturnType`

A function that can be invoked to stop watching for new block numbers. WatchBlockNumberReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const unwatch = await client.watchBlockNumber({
  onBlockNumber: (blockNumber) => console.log(blockNumber),
})
```

##### watchBlocks()

> **watchBlocks**: \<`includeTransactions`, `blockTag`>(`args`) => `WatchBlocksReturnType`

Watches and returns information for incoming blocks.

* Docs: [https://viem.sh/docs/actions/public/watchBlocks](https://viem.sh/docs/actions/public/watchBlocks)
* Examples: [https://stackblitz.com/github/wevm/viem/tree/main/examples/blocks\_watching-blocks](https://stackblitz.com/github/wevm/viem/tree/main/examples/blocks_watching-blocks)
* JSON-RPC Methods:
  * When `poll: true`, calls [`eth_getBlockByNumber`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getBlockByNumber) on a polling interval.
  * When `poll: false` & WebSocket Transport, uses a WebSocket subscription via [`eth_subscribe`](https://docs.alchemy.com/reference/eth-subscribe-polygon) and the `"newHeads"` event.

###### Type Parameters

| Type Parameter | Default type |
| - | - |
| `includeTransactions` *extends* `boolean` | `false` |
| `blockTag` *extends* `BlockTag` | `"latest"` |

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `WatchBlocksParameters`\<`HttpTransport`, `Chain`, `includeTransactions`, `blockTag`> | WatchBlocksParameters |

###### Returns

`WatchBlocksReturnType`

A function that can be invoked to stop watching for new block numbers. WatchBlocksReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const unwatch = await client.watchBlocks({
  onBlock: (block) => console.log(block),
})
```

##### watchContractEvent()

> **watchContractEvent**: \<`abi`, `eventName`, `strict`>(`args`) => `WatchContractEventReturnType`

Watches and returns emitted contract event logs.

* Docs: [https://viem.sh/docs/contract/watchContractEvent](https://viem.sh/docs/contract/watchContractEvent)

###### Type Parameters

| Type Parameter | Default type |
| - | - |
| `abi` *extends* `Abi` \| readonly `unknown`\[] | - |
| `eventName` *extends* `string` | - |
| `strict` *extends* `boolean` \| `undefined` | `undefined` |

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `WatchContractEventParameters`\<`abi`, `eventName`, `strict`, `HttpTransport`> | WatchContractEventParameters |

###### Returns

`WatchContractEventReturnType`

A function that can be invoked to stop watching for new event logs. WatchContractEventReturnType

###### Remarks

This Action will batch up all the event logs found within the [`pollingInterval`](https://viem.sh/docs/contract/watchContractEvent#pollinginterval-optional), and invoke them via [`onLogs`](https://viem.sh/docs/contract/watchContractEvent#onLogs).

`watchContractEvent` will attempt to create an [Event Filter](https://viem.sh/docs/contract/createContractEventFilter) and listen to changes to the Filter per polling interval, however, if the RPC Provider does not support Filters (e.g. `eth_newFilter`), then `watchContractEvent` will fall back to using [`getLogs`](https://viem.sh/docs/actions/public/getLogs) instead.

###### Example

```ts theme={null}
import { createPublicClient, http, parseAbi } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const unwatch = client.watchContractEvent({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: parseAbi(['event Transfer(address indexed from, address indexed to, uint256 value)']),
  eventName: 'Transfer',
  args: { from: '0xc961145a54C96E3aE9bAA048c4F4D6b04C13916b' },
  onLogs: (logs) => console.log(logs),
})
```

##### watchEvent()

> **watchEvent**: \<`abiEvent`, `abiEvents`, `strict`>(`args`) => `WatchEventReturnType`

Watches and returns emitted [Event Logs](https://viem.sh/docs/glossary/terms#event-log).

* Docs: [https://viem.sh/docs/actions/public/watchEvent](https://viem.sh/docs/actions/public/watchEvent)
* JSON-RPC Methods:
  * **RPC Provider supports `eth_newFilter`:**
    * Calls [`eth_newFilter`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_newfilter) to create a filter (called on initialize).
    * On a polling interval, it will call [`eth_getFilterChanges`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getfilterchanges).
  * **RPC Provider does not support `eth_newFilter`:**
    * Calls [`eth_getLogs`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getlogs) for each block between the polling interval.

###### Type Parameters

| Type Parameter | Default type |
| - | - |
| `abiEvent` *extends* `AbiEvent` \| `undefined` | `undefined` |
| `abiEvents` *extends* readonly `unknown`\[] \| readonly `AbiEvent`\[] \| `undefined` | `abiEvent` *extends* `AbiEvent` ? \[`abiEvent`] : `undefined` |
| `strict` *extends* `boolean` \| `undefined` | `undefined` |

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `WatchEventParameters`\<`abiEvent`, `abiEvents`, `strict`, `HttpTransport`> | WatchEventParameters |

###### Returns

`WatchEventReturnType`

A function that can be invoked to stop watching for new Event Logs. WatchEventReturnType

###### Remarks

This Action will batch up all the Event Logs found within the [`pollingInterval`](https://viem.sh/docs/actions/public/watchEvent#pollinginterval-optional), and invoke them via [`onLogs`](https://viem.sh/docs/actions/public/watchEvent#onLogs).

`watchEvent` will attempt to create an [Event Filter](https://viem.sh/docs/actions/public/createEventFilter) and listen to changes to the Filter per polling interval, however, if the RPC Provider does not support Filters (e.g. `eth_newFilter`), then `watchEvent` will fall back to using [`getLogs`](https://viem.sh/docs/actions/public/getLogs) instead.

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const unwatch = client.watchEvent({
  onLogs: (logs) => console.log(logs),
})
```

##### watchPendingTransactions()

> **watchPendingTransactions**: (`args`) => `WatchPendingTransactionsReturnType`

Watches and returns pending transaction hashes.

* Docs: [https://viem.sh/docs/actions/public/watchPendingTransactions](https://viem.sh/docs/actions/public/watchPendingTransactions)
* JSON-RPC Methods:
  * When `poll: true`
    * Calls [`eth_newPendingTransactionFilter`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_newpendingtransactionfilter) to initialize the filter.
    * Calls [`eth_getFilterChanges`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getFilterChanges) on a polling interval.
  * When `poll: false` & WebSocket Transport, uses a WebSocket subscription via [`eth_subscribe`](https://docs.alchemy.com/reference/eth-subscribe-polygon) and the `"newPendingTransactions"` event.

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `WatchPendingTransactionsParameters`\<`HttpTransport`> | WatchPendingTransactionsParameters |

###### Returns

`WatchPendingTransactionsReturnType`

A function that can be invoked to stop watching for new pending transaction hashes. WatchPendingTransactionsReturnType

###### Remarks

This Action will batch up all the pending transactions found within the [`pollingInterval`](https://viem.sh/docs/actions/public/watchPendingTransactions#pollinginterval-optional), and invoke them via [`onTransactions`](https://viem.sh/docs/actions/public/watchPendingTransactions#ontransactions).

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const unwatch = await client.watchPendingTransactions({
  onTransactions: (hashes) => console.log(hashes),
})
```

***

### isSignerApproved()

> **isSignerApproved**(`signerLocator`): `Promise`\<`boolean`>

Defined in: [packages/wallets/src/wallets/wallet.ts:1203](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L1203)

Check if a signer is approved and usable for the current wallet chain.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `signerLocator` | `string` | The locator of the signer to check |

#### Returns

`Promise`\<`boolean`>

true if the signer is approved for this chain, false if it is not approved or not registered

#### Throws

if the approval state could not be fetched

#### Inherited from

[`Wallet`](./Wallet).[`isSignerApproved`](./Wallet#issignerapproved)

***

### needsRecovery()

> **needsRecovery**(): `boolean`

Defined in: [packages/wallets/src/wallets/wallet.ts:1211](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L1211)

Whether the wallet needs recovery (signer registration) before the next transaction.

#### Returns

`boolean`

true if recovery is needed

#### Inherited from

[`Wallet`](./Wallet).[`needsRecovery`](./Wallet#needsrecovery)

***

### nfts()

> **nfts**(`params`): `Promise`\<`unknown`>

Defined in: [packages/wallets/src/wallets/wallet.ts:417](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L417)

Get the wallet NFTs

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | \{ `page`: `number`; `perPage`: `number`; } | The parameters |
| `params.page` | `number` | The page number |
| `params.perPage` | `number` | The number of NFTs per page |

#### Returns

`Promise`\<`unknown`>

The NFTs

#### Inherited from

[`Wallet`](./Wallet).[`nfts`](./Wallet#nfts)

***

### recover()

> **recover**(): `Promise`\<`void`>

Defined in: [packages/wallets/src/wallets/wallet.ts:1227](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L1227)

Register a device signer with the wallet using the recovery signer.
Generates a new device key and registers it on-chain.
Returns early if the device signer's locator is already approved on-chain.

#### Returns

`Promise`\<`void`>

#### Inherited from

[`Wallet`](./Wallet).[`recover`](./Wallet#recover)

***

### removeRecoveryMethod()

> **removeRecoveryMethod**\<`T`>(`recoveryMethod`, `options`?): `Promise`\<[`RemoveRecoveryMethodReturnType`](../type-aliases/RemoveRecoveryMethodReturnType)>

Defined in: [packages/wallets/src/wallets/wallet.ts:927](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L927)

Remove a recovery method from the wallet. Supported on Solana and Stellar only.
Always uses one of the remaining recovery methods to approve the change, selected as in [addSigner](./#addsigner).

#### Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* [`RemoveRecoveryMethodOptions`](../type-aliases/RemoveRecoveryMethodOptions) \| `undefined` | `undefined` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `recoveryMethod` | [`DeviceSignerConfig`](../type-aliases/DeviceSignerConfig) \| [`ServerSignerConfig`](../type-aliases/ServerSignerConfig) \| [`ExternalWalletRegistrationConfig`](../type-aliases/ExternalWalletRegistrationConfig) \| `PasskeySignerConfig` \| [`EmailSignerConfig`](../type-aliases/EmailSignerConfig) \| [`PhoneSignerConfig`](../type-aliases/PhoneSignerConfig) \| `ApiKeySignerConfig` \| [`EvmExternalWalletSignerConfig`](../type-aliases/EvmExternalWalletSignerConfig) | The recovery method to remove, provided as a signer config object |
| `options`? | `T` | The options for the operation |

#### Returns

`Promise`\<[`RemoveRecoveryMethodReturnType`](../type-aliases/RemoveRecoveryMethodReturnType)>

#### Inherited from

[`Wallet`](./Wallet).[`removeRecoveryMethod`](./Wallet#removerecoverymethod)

***

### removeSigner()

> **removeSigner**\<`T`>(`signer`, `options`?): `Promise`\<`RemoveSignerReturnType`>

Defined in: [packages/wallets/src/wallets/wallet.ts:810](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L810)

Remove a signer from the wallet.
Always uses a recovery method internally to approve the removal, selected as in [addSigner](./#addsigner).

#### Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* [`RemoveSignerOptions`](../type-aliases/RemoveSignerOptions) \| `undefined` | `undefined` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `signer` | [`DeviceSignerConfig`](../type-aliases/DeviceSignerConfig) \| [`ServerSignerConfig`](../type-aliases/ServerSignerConfig) \| [`ExternalWalletRegistrationConfig`](../type-aliases/ExternalWalletRegistrationConfig) \| `PasskeySignerConfig` \| [`EmailSignerConfig`](../type-aliases/EmailSignerConfig) \| [`PhoneSignerConfig`](../type-aliases/PhoneSignerConfig) \| `ApiKeySignerConfig` \| [`EvmExternalWalletSignerConfig`](../type-aliases/EvmExternalWalletSignerConfig) | The signer to remove, provided as a signer config object |
| `options`? | `T` | The options for the operation |

#### Returns

`Promise`\<`RemoveSignerReturnType`>

#### Inherited from

[`Wallet`](./Wallet).[`removeSigner`](./Wallet#removesigner)

***

### send()

> **send**\<`T`>(`to`, `token`, `amount`, `options`?): `Promise`\<[`Transaction`](../type-aliases/Transaction)\<`T` *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

Defined in: [packages/wallets/src/wallets/wallet.ts:492](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L492)

Send a token to a wallet or user locator

#### Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* `SendTokenTransactionOptions` \| `undefined` | `undefined` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `to` | `string` \| `UserLocator` | The recipient (address or user locator) |
| `token` | `string` | The token (address or currency symbol) |
| `amount` | `string` | The amount to send (decimal units) |
| `options`? | `T` | The options for the transaction |

#### Returns

`Promise`\<[`Transaction`](../type-aliases/Transaction)\<`T` *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

The transaction

#### Inherited from

[`Wallet`](./Wallet).[`send`](./Wallet#send)

***

### sendTransaction()

> **sendTransaction**\<`T`>(`params`): `Promise`\<[`Transaction`](../type-aliases/Transaction)\<`T`\[`"options"`] *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

Defined in: [packages/wallets/src/wallets/evm.ts:60](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/evm.ts#L60)

Send a raw EVM transaction.

#### Type Parameters

| Type Parameter |
| - |
| `T` *extends* [`EVMTransactionInput`](../type-aliases/EVMTransactionInput) |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | `T` | The transaction parameters (raw transaction, ABI call, or encoded data) |

#### Returns

`Promise`\<[`Transaction`](../type-aliases/Transaction)\<`T`\[`"options"`] *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

The transaction result

***

### signerIsRegistered()

> **signerIsRegistered**(`signerLocator`): `Promise`\<`boolean`>

Defined in: [packages/wallets/src/wallets/wallet.ts:1193](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L1193)

Check if a signer is registered in this wallet.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `signerLocator` | `string` | The locator of the signer to check |

#### Returns

`Promise`\<`boolean`>

true if the signer is registered

#### Inherited from

[`Wallet`](./Wallet).[`signerIsRegistered`](./Wallet#signerisregistered)

***

### signers()

> **signers**(): `Promise`\<[`Signer`](../type-aliases/Signer)\[]>

Defined in: [packages/wallets/src/wallets/wallet.ts:1244](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L1244)

List the signers for this wallet.
Returns full signer objects with status.
For EVM wallets, only signers with an approval (pending or completed) for the wallet's chain are included.

#### Returns

`Promise`\<[`Signer`](../type-aliases/Signer)\[]>

The signers

#### Inherited from

[`Wallet`](./Wallet).[`signers`](./Wallet#signers)

***

### signMessage()

> **signMessage**\<`T`>(`params`): `Promise`\<[`Signature`](../type-aliases/Signature)\<`T`\[`"options"`] *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

Defined in: [packages/wallets/src/wallets/evm.ts:100](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/evm.ts#L100)

Sign a message with the wallet's private key.

#### Type Parameters

| Type Parameter |
| - |
| `T` *extends* `SignMessageInput` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | `T` | The message to sign |

#### Returns

`Promise`\<[`Signature`](../type-aliases/Signature)\<`T`\[`"options"`] *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

The signature

***

### signTypedData()

> **signTypedData**\<`T`>(`params`): `Promise`\<[`Signature`](../type-aliases/Signature)\<`T`\[`"options"`] *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

Defined in: [packages/wallets/src/wallets/evm.ts:147](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/evm.ts#L147)

Sign EIP-712 typed data.

#### Type Parameters

| Type Parameter |
| - |
| `T` *extends* `SignTypedDataInput` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | `T` | The typed data parameters (domain, types, message, primaryType, chain) |

#### Returns

`Promise`\<[`Signature`](../type-aliases/Signature)\<`T`\[`"options"`] *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

The signature

***

### stagingFund()

> **stagingFund**(`amount`, `chain`?): `Promise`\<`FundWalletResponse`>

Defined in: [packages/wallets/src/wallets/wallet.ts:387](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L387)

Funds the wallet with Crossmint's stablecoin (USDXM).

**Note:** This method is only available in staging environments and exclusively supports USDXM tokens.
It cannot be used in production environments.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `amount` | `number` | The amount of USDXM to fund the wallet with |
| `chain`? | [`Chain`](../type-aliases/Chain) | Optional chain to fund on. If not provided, uses the wallet's default chain |

#### Returns

`Promise`\<`FundWalletResponse`>

The funding response

#### Throws

If the funding operation fails or if called in a production environment

#### Inherited from

[`Wallet`](./Wallet).[`stagingFund`](./Wallet#stagingfund)

***

### transaction()

> **transaction**(`transactionId`): `Promise`\<`WalletsTransactionV2025ResponseDtoClass`>

Defined in: [packages/wallets/src/wallets/wallet.ts:449](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L449)

Get a transaction by id

#### Parameters

| Parameter | Type |
| - | - |
| `transactionId` | `string` |

#### Returns

`Promise`\<`WalletsTransactionV2025ResponseDtoClass`>

The transaction

#### Throws

If the transaction cannot be retrieved

#### Inherited from

[`Wallet`](./Wallet).[`transaction`](./Wallet#transaction)

***

### transactions()

> **transactions**(): `Promise`\<`GetTransactionsResponse`>

Defined in: [packages/wallets/src/wallets/wallet.ts:436](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L436)

Get the wallet transactions

#### Returns

`Promise`\<`GetTransactionsResponse`>

The transactions

#### Throws

If the transactions cannot be retrieved

#### Inherited from

[`Wallet`](./Wallet).[`transactions`](./Wallet#transactions)

***

### transfers()

> **transfers**(`params`): `Promise`\<`WalletsActivityResponseUnstableDto`>

Defined in: [packages/wallets/src/wallets/wallet.ts:464](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L464)

Get the wallet transfers

#### Parameters

| Parameter | Type |
| - | - |
| `params` | \{ `status`: `"successful"` \| `"failed"`; `tokens`: `string`; } |
| `params.status` | `"successful"` \| `"failed"` |
| `params.tokens`? | `string` |

#### Returns

`Promise`\<`WalletsActivityResponseUnstableDto`>

The transfers

#### Throws

If the transfers cannot be retrieved

#### Inherited from

[`Wallet`](./Wallet).[`transfers`](./Wallet#transfers)

***

### useRecoveryMethod()

> **useRecoveryMethod**(`recoveryMethod`): `Promise`\<`void`>

Defined in: [packages/wallets/src/wallets/wallet.ts:1044](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L1044)

**`Experimental`**

Select which of the wallet's recovery methods authorizes admin operations ([addSigner](./#addsigner),
[removeSigner](./#removesigner), [addRecoveryMethod](./#addrecoverymethod), [removeRecoveryMethod](./#removerecoverymethod)). Unlike [useSigner](./#usesigner),
this does not change the active signer used for transactions and signatures.

The config must refer to one of [recoveryMethods](./#recoverymethods); pass the fuller form when the method needs it to
operate (an `onSign` callback for external wallets, the `secret` for server signers).

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `recoveryMethod` | [`DeviceSignerConfig`](../type-aliases/DeviceSignerConfig) \| [`ServerSignerConfig`](../type-aliases/ServerSignerConfig) \| `PasskeySignerConfig` \| [`EmailSignerConfig`](../type-aliases/EmailSignerConfig) \| [`PhoneSignerConfig`](../type-aliases/PhoneSignerConfig) \| `ApiKeySignerConfig` \| [`EvmExternalWalletSignerConfig`](../type-aliases/EvmExternalWalletSignerConfig) | The recovery method config object to authorize with This API is experimental and may change in the future |

#### Returns

`Promise`\<`void`>

#### Inherited from

[`Wallet`](./Wallet).[`useRecoveryMethod`](./Wallet#userecoverymethod)

***

### useSigner()

> **useSigner**(`signer`): `Promise`\<`void`>

Defined in: [packages/wallets/src/wallets/wallet.ts:1000](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L1000)

Set the active signer for this wallet.
Accepts a signer config object. The locator is inferred internally.
Works for both registered signers and the recovery signer.

For passkey signers: if no `id` is provided, the wallet will auto-select the passkey
if exactly one passkey signer is registered. If multiple passkeys exist, an `id` must be specified.

For device signers: if no device key is found locally, the signer will be created
automatically during the next transaction (via recovery).

For external-wallet signers: the config object must include an onSign callback
(applies to both registered and recovery signers).

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `signer` | [`DeviceSignerConfig`](../type-aliases/DeviceSignerConfig) \| [`ServerSignerConfig`](../type-aliases/ServerSignerConfig) \| `PasskeySignerConfig` \| [`EmailSignerConfig`](../type-aliases/EmailSignerConfig) \| [`PhoneSignerConfig`](../type-aliases/PhoneSignerConfig) \| `ApiKeySignerConfig` \| [`EvmExternalWalletSignerConfig`](../type-aliases/EvmExternalWalletSignerConfig) | The signer config object to use |

#### Returns

`Promise`\<`void`>

#### Inherited from

[`Wallet`](./Wallet).[`useSigner`](./Wallet#usesigner)

***

### waitForInit()

> **waitForInit**(): `Promise`\<`void`>

Defined in: [packages/wallets/src/wallets/wallet.ts:209](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L209)

Wait for the wallet's internal signer initialization to complete.
After this resolves, `needsRecovery()` reflects the true state.

#### Returns

`Promise`\<`void`>

#### Inherited from

[`Wallet`](./Wallet).[`waitForInit`](./Wallet#waitforinit)

***

### from()

> `static` **from**(`wallet`): `EVMWallet`

Defined in: [packages/wallets/src/wallets/evm.ts:40](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/evm.ts#L40)

#### Parameters

| Parameter | Type |
| - | - |
| `wallet` | [`Wallet`](./Wallet)\<[`Chain`](../type-aliases/Chain)> |

#### Returns

`EVMWallet`


# IframeDeviceSignerKeyStorage
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/IframeDeviceSignerKeyStorage



Defined in: [packages/wallets/src/utils/device-signers/IframeDeviceSignerKeyStorage.ts:41](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/device-signers/IframeDeviceSignerKeyStorage.ts#L41)

DeviceSignerKeyStorage backed by a hidden iframe.
All crypto operations are delegated to the iframe via postMessage RPC,
keeping key material isolated in the iframe's origin.

## Extends

* [`DeviceSignerKeyStorage`](./DeviceSignerKeyStorage)

## Constructors

### new IframeDeviceSignerKeyStorage()

> **new IframeDeviceSignerKeyStorage**(`apiKey`): `IframeDeviceSignerKeyStorage`

Defined in: [packages/wallets/src/utils/device-signers/IframeDeviceSignerKeyStorage.ts:48](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/device-signers/IframeDeviceSignerKeyStorage.ts#L48)

#### Parameters

| Parameter | Type |
| - | - |
| `apiKey` | `string` |

#### Returns

`IframeDeviceSignerKeyStorage`

#### Overrides

[`DeviceSignerKeyStorage`](./DeviceSignerKeyStorage).[`constructor`](./DeviceSignerKeyStorage#constructor)

## Methods

### deleteKey()

> **deleteKey**(`address`): `Promise`\<`void`>

Defined in: [packages/wallets/src/utils/device-signers/IframeDeviceSignerKeyStorage.ts:123](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/device-signers/IframeDeviceSignerKeyStorage.ts#L123)

Delete the key pair associated with the given wallet address.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `address` | `string` | The wallet address whose key pair to remove. |

#### Returns

`Promise`\<`void`>

#### Overrides

[`DeviceSignerKeyStorage`](./DeviceSignerKeyStorage).[`deleteKey`](./DeviceSignerKeyStorage#deletekey)

***

### destroy()

> **destroy**(): `void`

Defined in: [packages/wallets/src/utils/device-signers/IframeDeviceSignerKeyStorage.ts:127](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/device-signers/IframeDeviceSignerKeyStorage.ts#L127)

#### Returns

`void`

***

### generateKey()

> **generateKey**(`params`): `Promise`\<`string`>

Defined in: [packages/wallets/src/utils/device-signers/IframeDeviceSignerKeyStorage.ts:78](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/device-signers/IframeDeviceSignerKeyStorage.ts#L78)

Generate a new P-256 key pair and persist it.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | \{ `address`: `string`; `biometricExpirationTime`: `number`; `biometricPolicy`: `BiometricPolicy`; } | Key generation parameters. |
| `params.address`? | `string` | Optional wallet address to associate the key with. If omitted, the key should be stored under a temporary identifier until [mapAddressToKey](./DeviceSignerKeyStorage#mapaddresstokey) is called. |
| `params.biometricExpirationTime`? | `number` | - |
| `params.biometricPolicy`? | `BiometricPolicy` | - |

#### Returns

`Promise`\<`string`>

The uncompressed public key encoded as a base64 string.

#### Overrides

[`DeviceSignerKeyStorage`](./DeviceSignerKeyStorage).[`generateKey`](./DeviceSignerKeyStorage#generatekey)

***

### getDeviceName()

> **getDeviceName**(): `string`

Defined in: [packages/wallets/src/utils/device-signers/IframeDeviceSignerKeyStorage.ts:328](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/device-signers/IframeDeviceSignerKeyStorage.ts#L328)

Get a human-readable name for this device (e.g. "MacBook Pro", "iPhone 15").
Used to label device signers in the API for identification purposes.

#### Returns

`string`

A descriptive name for the current device.

#### Overrides

[`DeviceSignerKeyStorage`](./DeviceSignerKeyStorage).[`getDeviceName`](./DeviceSignerKeyStorage#getdevicename)

***

### getKey()

> **getKey**(`address`): `Promise`\<`string` | `null`>

Defined in: [packages/wallets/src/utils/device-signers/IframeDeviceSignerKeyStorage.ts:97](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/device-signers/IframeDeviceSignerKeyStorage.ts#L97)

Retrieve the public key for a given wallet address.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `address` | `string` | The wallet address whose public key to look up. |

#### Returns

`Promise`\<`string` | `null`>

The base64-encoded public key, or `null` if no key is found for the address.

#### Overrides

[`DeviceSignerKeyStorage`](./DeviceSignerKeyStorage).[`getKey`](./DeviceSignerKeyStorage#getkey)

***

### hasKey()

> **hasKey**(`publicKeyBase64`): `Promise`\<`boolean`>

Defined in: [packages/wallets/src/utils/device-signers/IframeDeviceSignerKeyStorage.ts:106](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/device-signers/IframeDeviceSignerKeyStorage.ts#L106)

Check if a key with the given public key exists on this device.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `publicKeyBase64` | `string` | The base64-encoded public key to look for. |

#### Returns

`Promise`\<`boolean`>

`true` if the key exists on the device, `false` otherwise.

#### Overrides

[`DeviceSignerKeyStorage`](./DeviceSignerKeyStorage).[`hasKey`](./DeviceSignerKeyStorage#haskey)

***

### mapAddressToKey()

> **mapAddressToKey**(`address`, `publicKeyBase64`): `Promise`\<`void`>

Defined in: [packages/wallets/src/utils/device-signers/IframeDeviceSignerKeyStorage.ts:89](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/device-signers/IframeDeviceSignerKeyStorage.ts#L89)

Associate an already-generated key pair with a wallet address.
Used when the wallet address is not yet known at the time of key generation.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `address` | `string` | The wallet address to map the key to. |
| `publicKeyBase64` | `string` | The base64-encoded public key returned by [generateKey](./DeviceSignerKeyStorage#generatekey). |

#### Returns

`Promise`\<`void`>

#### Overrides

[`DeviceSignerKeyStorage`](./DeviceSignerKeyStorage).[`mapAddressToKey`](./DeviceSignerKeyStorage#mapaddresstokey)

***

### setBiometricRequestHandler()

> **setBiometricRequestHandler**(`handler`): `void`

Defined in: [packages/wallets/src/utils/device-signers/IframeDeviceSignerKeyStorage.ts:70](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/device-signers/IframeDeviceSignerKeyStorage.ts#L70)

Set a handler that is called before each WebAuthn ceremony to obtain user activation.
The handler should show a UI prompt (e.g. PasskeyPrompt) and resolve when the user clicks.

#### Parameters

| Parameter | Type |
| - | - |
| `handler` | [`BiometricRequestHandler`](../type-aliases/BiometricRequestHandler) |

#### Returns

`void`

***

### signMessage()

> **signMessage**(`address`, `message`): `Promise`\<\{ `r`: `string`; `s`: `string`; }>

Defined in: [packages/wallets/src/utils/device-signers/IframeDeviceSignerKeyStorage.ts:115](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/device-signers/IframeDeviceSignerKeyStorage.ts#L115)

Sign a message using the private key associated with the given wallet address.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `address` | `string` | The wallet address whose private key to sign with. |
| `message` | `string` | The message string to sign. |

#### Returns

`Promise`\<\{ `r`: `string`; `s`: `string`; }>

The ECDSA signature split into its `r` and `s` components, each as a hex string.

#### Overrides

[`DeviceSignerKeyStorage`](./DeviceSignerKeyStorage).[`signMessage`](./DeviceSignerKeyStorage#signmessage)


# InvalidRecoveryConfigError
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/InvalidRecoveryConfigError



Defined in: [packages/wallets/src/utils/errors.ts:107](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/errors.ts#L107)

Thrown for recovery configurations the SDK can reject before calling the API.

## Extends

* `CrossmintSDKError`

## Constructors

### new InvalidRecoveryConfigError()

> **new InvalidRecoveryConfigError**(`message`, `details`?): `InvalidRecoveryConfigError`

Defined in: [packages/wallets/src/utils/errors.ts:108](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/errors.ts#L108)

#### Parameters

| Parameter | Type |
| - | - |
| `message` | `string` |
| `details`? | `string` |

#### Returns

`InvalidRecoveryConfigError`

#### Overrides

`CrossmintSDKError.constructor`

## Properties

| Property | Modifier | Type | Description | Inherited from | Defined in |
| - | - | - | - | - | - |
|  `code` | `readonly` | `string` | - | `CrossmintSDKError.code` | packages/common/base/dist/error/index.d.ts:4 |
|  `details?` | `readonly` | `string` | - | `CrossmintSDKError.details` | packages/common/base/dist/error/index.d.ts:5 |
|  `message` | `public` | `string` | - | `CrossmintSDKError.message` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
|  `name` | `public` | `string` | - | `CrossmintSDKError.name` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
|  `stack?` | `public` | `string` | - | `CrossmintSDKError.stack` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
|  `prepareStackTrace?` | `static` | (`err`: `Error`, `stackTraces`: `CallSite`\[]) => `any` | Optional override for formatting stack traces **See** [https://v8.dev/docs/stack-trace-api#customizing-stack-traces](https://v8.dev/docs/stack-trace-api#customizing-stack-traces) | `CrossmintSDKError.prepareStackTrace` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:28 |
|  `stackTraceLimit` | `static` | `number` | - | `CrossmintSDKError.stackTraceLimit` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:30 |

## Methods

### captureStackTrace()

> `static` **captureStackTrace**(`targetObject`, `constructorOpt`?): `void`

Defined in: node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:21

Create .stack property on a target object

#### Parameters

| Parameter | Type |
| - | - |
| `targetObject` | `object` |
| `constructorOpt`? | `Function` |

#### Returns

`void`

#### Inherited from

`CrossmintSDKError.captureStackTrace`


# InvalidTransferAmountError
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/InvalidTransferAmountError



Defined in: [packages/wallets/src/utils/errors.ts:223](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/errors.ts#L223)

## Extends

* `CrossmintSDKError`

## Constructors

### new InvalidTransferAmountError()

> **new InvalidTransferAmountError**(`message`, `details`?): `InvalidTransferAmountError`

Defined in: [packages/wallets/src/utils/errors.ts:224](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/errors.ts#L224)

#### Parameters

| Parameter | Type |
| - | - |
| `message` | `string` |
| `details`? | `string` |

#### Returns

`InvalidTransferAmountError`

#### Overrides

`CrossmintSDKError.constructor`

## Properties

| Property | Modifier | Type | Description | Inherited from | Defined in |
| - | - | - | - | - | - |
|  `code` | `readonly` | `string` | - | `CrossmintSDKError.code` | packages/common/base/dist/error/index.d.ts:4 |
|  `details?` | `readonly` | `string` | - | `CrossmintSDKError.details` | packages/common/base/dist/error/index.d.ts:5 |
|  `message` | `public` | `string` | - | `CrossmintSDKError.message` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
|  `name` | `public` | `string` | - | `CrossmintSDKError.name` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
|  `stack?` | `public` | `string` | - | `CrossmintSDKError.stack` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
|  `prepareStackTrace?` | `static` | (`err`: `Error`, `stackTraces`: `CallSite`\[]) => `any` | Optional override for formatting stack traces **See** [https://v8.dev/docs/stack-trace-api#customizing-stack-traces](https://v8.dev/docs/stack-trace-api#customizing-stack-traces) | `CrossmintSDKError.prepareStackTrace` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:28 |
|  `stackTraceLimit` | `static` | `number` | - | `CrossmintSDKError.stackTraceLimit` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:30 |

## Methods

### captureStackTrace()

> `static` **captureStackTrace**(`targetObject`, `constructorOpt`?): `void`

Defined in: node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:21

Create .stack property on a target object

#### Parameters

| Parameter | Type |
| - | - |
| `targetObject` | `object` |
| `constructorOpt`? | `Function` |

#### Returns

`void`

#### Inherited from

`CrossmintSDKError.captureStackTrace`


# JWTDecryptionError
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/JWTDecryptionError



Defined in: packages/common/base/dist/error/index.d.ts:21

## Extends

* [`NotAuthorizedError`](./NotAuthorizedError)

## Constructors

### new JWTDecryptionError()

> **new JWTDecryptionError**(`details`?): `JWTDecryptionError`

Defined in: packages/common/base/dist/error/index.d.ts:23

#### Parameters

| Parameter | Type |
| - | - |
| `details`? | `string` |

#### Returns

`JWTDecryptionError`

#### Overrides

[`NotAuthorizedError`](./NotAuthorizedError).[`constructor`](./NotAuthorizedError#constructor)

## Properties

| Property | Modifier | Type | Description | Overrides | Inherited from | Defined in |
| - | - | - | - | - | - | - |
|  `code` | `readonly` | `string` | - | [`NotAuthorizedError`](./NotAuthorizedError).[`code`](./NotAuthorizedError#code) | - | packages/common/base/dist/error/index.d.ts:22 |
|  `details?` | `readonly` | `string` | - | - | [`NotAuthorizedError`](./NotAuthorizedError).[`details`](./NotAuthorizedError#details) | packages/common/base/dist/error/index.d.ts:5 |
|  `message` | `public` | `string` | - | - | [`NotAuthorizedError`](./NotAuthorizedError).[`message`](./NotAuthorizedError#message) | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
|  `name` | `public` | `string` | - | - | [`NotAuthorizedError`](./NotAuthorizedError).[`name`](./NotAuthorizedError#name) | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
|  `stack?` | `public` | `string` | - | - | [`NotAuthorizedError`](./NotAuthorizedError).[`stack`](./NotAuthorizedError#stack) | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
|  `prepareStackTrace?` | `static` | (`err`: `Error`, `stackTraces`: `CallSite`\[]) => `any` | Optional override for formatting stack traces **See** [https://v8.dev/docs/stack-trace-api#customizing-stack-traces](https://v8.dev/docs/stack-trace-api#customizing-stack-traces) | - | [`NotAuthorizedError`](./NotAuthorizedError).[`prepareStackTrace`](./NotAuthorizedError#preparestacktrace) | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:28 |
|  `stackTraceLimit` | `static` | `number` | - | - | [`NotAuthorizedError`](./NotAuthorizedError).[`stackTraceLimit`](./NotAuthorizedError#stacktracelimit) | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:30 |

## Methods

### captureStackTrace()

> `static` **captureStackTrace**(`targetObject`, `constructorOpt`?): `void`

Defined in: node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:21

Create .stack property on a target object

#### Parameters

| Parameter | Type |
| - | - |
| `targetObject` | `object` |
| `constructorOpt`? | `Function` |

#### Returns

`void`

#### Inherited from

[`NotAuthorizedError`](./NotAuthorizedError).[`captureStackTrace`](./NotAuthorizedError#capturestacktrace)


# JWTExpiredError
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/JWTExpiredError



Defined in: packages/common/base/dist/error/index.d.ts:11

## Extends

* [`NotAuthorizedError`](./NotAuthorizedError)

## Constructors

### new JWTExpiredError()

> **new JWTExpiredError**(`expiredAt`?, `details`?): `JWTExpiredError`

Defined in: packages/common/base/dist/error/index.d.ts:15

#### Parameters

| Parameter | Type |
| - | - |
| `expiredAt`? | `string` \| `Date` |
| `details`? | `string` |

#### Returns

`JWTExpiredError`

#### Overrides

[`NotAuthorizedError`](./NotAuthorizedError).[`constructor`](./NotAuthorizedError#constructor)

## Properties

| Property | Modifier | Type | Description | Overrides | Inherited from | Defined in |
| - | - | - | - | - | - | - |
|  `code` | `readonly` | `string` | - | [`NotAuthorizedError`](./NotAuthorizedError).[`code`](./NotAuthorizedError#code) | - | packages/common/base/dist/error/index.d.ts:12 |
|  `details?` | `readonly` | `string` | - | - | [`NotAuthorizedError`](./NotAuthorizedError).[`details`](./NotAuthorizedError#details) | packages/common/base/dist/error/index.d.ts:5 |
|  `expiredAt?` | `readonly` | `string` | The expiry time of the JWT as an ISO 8601 timestamp, when reported by the API. | - | - | packages/common/base/dist/error/index.d.ts:14 |
|  `message` | `public` | `string` | - | - | [`NotAuthorizedError`](./NotAuthorizedError).[`message`](./NotAuthorizedError#message) | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
|  `name` | `public` | `string` | - | - | [`NotAuthorizedError`](./NotAuthorizedError).[`name`](./NotAuthorizedError#name) | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
|  `stack?` | `public` | `string` | - | - | [`NotAuthorizedError`](./NotAuthorizedError).[`stack`](./NotAuthorizedError#stack) | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
|  `prepareStackTrace?` | `static` | (`err`: `Error`, `stackTraces`: `CallSite`\[]) => `any` | Optional override for formatting stack traces **See** [https://v8.dev/docs/stack-trace-api#customizing-stack-traces](https://v8.dev/docs/stack-trace-api#customizing-stack-traces) | - | [`NotAuthorizedError`](./NotAuthorizedError).[`prepareStackTrace`](./NotAuthorizedError#preparestacktrace) | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:28 |
|  `stackTraceLimit` | `static` | `number` | - | - | [`NotAuthorizedError`](./NotAuthorizedError).[`stackTraceLimit`](./NotAuthorizedError#stacktracelimit) | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:30 |

## Methods

### captureStackTrace()

> `static` **captureStackTrace**(`targetObject`, `constructorOpt`?): `void`

Defined in: node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:21

Create .stack property on a target object

#### Parameters

| Parameter | Type |
| - | - |
| `targetObject` | `object` |
| `constructorOpt`? | `Function` |

#### Returns

`void`

#### Inherited from

[`NotAuthorizedError`](./NotAuthorizedError).[`captureStackTrace`](./NotAuthorizedError#capturestacktrace)


# JWTIdentifierError
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/JWTIdentifierError



Defined in: packages/common/base/dist/error/index.d.ts:25

## Extends

* [`NotAuthorizedError`](./NotAuthorizedError)

## Constructors

### new JWTIdentifierError()

> **new JWTIdentifierError**(`identifierKey`?, `details`?): `JWTIdentifierError`

Defined in: packages/common/base/dist/error/index.d.ts:28

#### Parameters

| Parameter | Type |
| - | - |
| `identifierKey`? | `string` |
| `details`? | `string` |

#### Returns

`JWTIdentifierError`

#### Overrides

[`NotAuthorizedError`](./NotAuthorizedError).[`constructor`](./NotAuthorizedError#constructor)

## Properties

| Property | Modifier | Type | Description | Overrides | Inherited from | Defined in |
| - | - | - | - | - | - | - |
|  `code` | `readonly` | `string` | - | [`NotAuthorizedError`](./NotAuthorizedError).[`code`](./NotAuthorizedError#code) | - | packages/common/base/dist/error/index.d.ts:26 |
|  `details?` | `readonly` | `string` | - | - | [`NotAuthorizedError`](./NotAuthorizedError).[`details`](./NotAuthorizedError#details) | packages/common/base/dist/error/index.d.ts:5 |
|  `identifierKey?` | `readonly` | `string` | - | - | - | packages/common/base/dist/error/index.d.ts:27 |
|  `message` | `public` | `string` | - | - | [`NotAuthorizedError`](./NotAuthorizedError).[`message`](./NotAuthorizedError#message) | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
|  `name` | `public` | `string` | - | - | [`NotAuthorizedError`](./NotAuthorizedError).[`name`](./NotAuthorizedError#name) | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
|  `stack?` | `public` | `string` | - | - | [`NotAuthorizedError`](./NotAuthorizedError).[`stack`](./NotAuthorizedError#stack) | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
|  `prepareStackTrace?` | `static` | (`err`: `Error`, `stackTraces`: `CallSite`\[]) => `any` | Optional override for formatting stack traces **See** [https://v8.dev/docs/stack-trace-api#customizing-stack-traces](https://v8.dev/docs/stack-trace-api#customizing-stack-traces) | - | [`NotAuthorizedError`](./NotAuthorizedError).[`prepareStackTrace`](./NotAuthorizedError#preparestacktrace) | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:28 |
|  `stackTraceLimit` | `static` | `number` | - | - | [`NotAuthorizedError`](./NotAuthorizedError).[`stackTraceLimit`](./NotAuthorizedError#stacktracelimit) | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:30 |

## Methods

### captureStackTrace()

> `static` **captureStackTrace**(`targetObject`, `constructorOpt`?): `void`

Defined in: node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:21

Create .stack property on a target object

#### Parameters

| Parameter | Type |
| - | - |
| `targetObject` | `object` |
| `constructorOpt`? | `Function` |

#### Returns

`void`

#### Inherited from

[`NotAuthorizedError`](./NotAuthorizedError).[`captureStackTrace`](./NotAuthorizedError#capturestacktrace)


# JWTInvalidError
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/JWTInvalidError



Defined in: packages/common/base/dist/error/index.d.ts:17

## Extends

* [`NotAuthorizedError`](./NotAuthorizedError)

## Constructors

### new JWTInvalidError()

> **new JWTInvalidError**(`details`?): `JWTInvalidError`

Defined in: packages/common/base/dist/error/index.d.ts:19

#### Parameters

| Parameter | Type |
| - | - |
| `details`? | `string` |

#### Returns

`JWTInvalidError`

#### Overrides

[`NotAuthorizedError`](./NotAuthorizedError).[`constructor`](./NotAuthorizedError#constructor)

## Properties

| Property | Modifier | Type | Description | Overrides | Inherited from | Defined in |
| - | - | - | - | - | - | - |
|  `code` | `readonly` | `string` | - | [`NotAuthorizedError`](./NotAuthorizedError).[`code`](./NotAuthorizedError#code) | - | packages/common/base/dist/error/index.d.ts:18 |
|  `details?` | `readonly` | `string` | - | - | [`NotAuthorizedError`](./NotAuthorizedError).[`details`](./NotAuthorizedError#details) | packages/common/base/dist/error/index.d.ts:5 |
|  `message` | `public` | `string` | - | - | [`NotAuthorizedError`](./NotAuthorizedError).[`message`](./NotAuthorizedError#message) | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
|  `name` | `public` | `string` | - | - | [`NotAuthorizedError`](./NotAuthorizedError).[`name`](./NotAuthorizedError#name) | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
|  `stack?` | `public` | `string` | - | - | [`NotAuthorizedError`](./NotAuthorizedError).[`stack`](./NotAuthorizedError#stack) | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
|  `prepareStackTrace?` | `static` | (`err`: `Error`, `stackTraces`: `CallSite`\[]) => `any` | Optional override for formatting stack traces **See** [https://v8.dev/docs/stack-trace-api#customizing-stack-traces](https://v8.dev/docs/stack-trace-api#customizing-stack-traces) | - | [`NotAuthorizedError`](./NotAuthorizedError).[`prepareStackTrace`](./NotAuthorizedError#preparestacktrace) | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:28 |
|  `stackTraceLimit` | `static` | `number` | - | - | [`NotAuthorizedError`](./NotAuthorizedError).[`stackTraceLimit`](./NotAuthorizedError#stacktracelimit) | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:30 |

## Methods

### captureStackTrace()

> `static` **captureStackTrace**(`targetObject`, `constructorOpt`?): `void`

Defined in: node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:21

Create .stack property on a target object

#### Parameters

| Parameter | Type |
| - | - |
| `targetObject` | `object` |
| `constructorOpt`? | `Function` |

#### Returns

`void`

#### Inherited from

[`NotAuthorizedError`](./NotAuthorizedError).[`captureStackTrace`](./NotAuthorizedError#capturestacktrace)


# KeyExportError
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/KeyExportError



Defined in: [packages/wallets/src/signers/types.ts:74](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L74)

## Extends

* `Error`

## Constructors

### new KeyExportError()

> **new KeyExportError**(`message`, `code`?): `KeyExportError`

Defined in: [packages/wallets/src/signers/types.ts:77](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L77)

#### Parameters

| Parameter | Type |
| - | - |
| `message` | `string` |
| `code`? | `string` |

#### Returns

`KeyExportError`

#### Overrides

`Error.constructor`

## Properties

| Property | Modifier | Type | Description | Inherited from | Defined in |
| - | - | - | - | - | - |
|  `code` | `readonly` | `string` \| `undefined` | - | - | [packages/wallets/src/signers/types.ts:75](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L75) |
|  `message` | `public` | `string` | - | `Error.message` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
|  `name` | `public` | `string` | - | `Error.name` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
|  `stack?` | `public` | `string` | - | `Error.stack` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
|  `prepareStackTrace?` | `static` | (`err`: `Error`, `stackTraces`: `CallSite`\[]) => `any` | Optional override for formatting stack traces **See** [https://v8.dev/docs/stack-trace-api#customizing-stack-traces](https://v8.dev/docs/stack-trace-api#customizing-stack-traces) | `Error.prepareStackTrace` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:28 |
|  `stackTraceLimit` | `static` | `number` | - | `Error.stackTraceLimit` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:30 |

## Methods

### captureStackTrace()

> `static` **captureStackTrace**(`targetObject`, `constructorOpt`?): `void`

Defined in: node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:21

Create .stack property on a target object

#### Parameters

| Parameter | Type |
| - | - |
| `targetObject` | `object` |
| `constructorOpt`? | `Function` |

#### Returns

`void`

#### Inherited from

`Error.captureStackTrace`


# NotAuthorizedError
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/NotAuthorizedError



Defined in: packages/common/base/dist/error/index.d.ts:8

## Extends

* `CrossmintSDKError`

## Extended by

* [`JWTExpiredError`](./JWTExpiredError)
* [`JWTInvalidError`](./JWTInvalidError)
* [`JWTDecryptionError`](./JWTDecryptionError)
* [`JWTIdentifierError`](./JWTIdentifierError)

## Constructors

### new NotAuthorizedError()

> **new NotAuthorizedError**(`message`, `details`?): `NotAuthorizedError`

Defined in: packages/common/base/dist/error/index.d.ts:9

#### Parameters

| Parameter | Type |
| - | - |
| `message` | `string` |
| `details`? | `string` |

#### Returns

`NotAuthorizedError`

#### Overrides

`CrossmintSDKError.constructor`

## Properties

| Property | Modifier | Type | Description | Inherited from | Defined in |
| - | - | - | - | - | - |
|  `code` | `readonly` | `string` | - | `CrossmintSDKError.code` | packages/common/base/dist/error/index.d.ts:4 |
|  `details?` | `readonly` | `string` | - | `CrossmintSDKError.details` | packages/common/base/dist/error/index.d.ts:5 |
|  `message` | `public` | `string` | - | `CrossmintSDKError.message` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
|  `name` | `public` | `string` | - | `CrossmintSDKError.name` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
|  `stack?` | `public` | `string` | - | `CrossmintSDKError.stack` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
|  `prepareStackTrace?` | `static` | (`err`: `Error`, `stackTraces`: `CallSite`\[]) => `any` | Optional override for formatting stack traces **See** [https://v8.dev/docs/stack-trace-api#customizing-stack-traces](https://v8.dev/docs/stack-trace-api#customizing-stack-traces) | `CrossmintSDKError.prepareStackTrace` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:28 |
|  `stackTraceLimit` | `static` | `number` | - | `CrossmintSDKError.stackTraceLimit` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:30 |

## Methods

### captureStackTrace()

> `static` **captureStackTrace**(`targetObject`, `constructorOpt`?): `void`

Defined in: node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:21

Create .stack property on a target object

#### Parameters

| Parameter | Type |
| - | - |
| `targetObject` | `object` |
| `constructorOpt`? | `Function` |

#### Returns

`void`

#### Inherited from

`CrossmintSDKError.captureStackTrace`


# NotSupportedOnApiVersionError
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/NotSupportedOnApiVersionError



Defined in: [packages/wallets/src/utils/errors.ts:145](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/errors.ts#L145)

## Extends

* `CrossmintSDKError`

## Constructors

### new NotSupportedOnApiVersionError()

> **new NotSupportedOnApiVersionError**(`message`, `details`?): `NotSupportedOnApiVersionError`

Defined in: [packages/wallets/src/utils/errors.ts:146](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/errors.ts#L146)

#### Parameters

| Parameter | Type |
| - | - |
| `message` | `string` |
| `details`? | `string` |

#### Returns

`NotSupportedOnApiVersionError`

#### Overrides

`CrossmintSDKError.constructor`

## Properties

| Property | Modifier | Type | Description | Inherited from | Defined in |
| - | - | - | - | - | - |
|  `code` | `readonly` | `string` | - | `CrossmintSDKError.code` | packages/common/base/dist/error/index.d.ts:4 |
|  `details?` | `readonly` | `string` | - | `CrossmintSDKError.details` | packages/common/base/dist/error/index.d.ts:5 |
|  `message` | `public` | `string` | - | `CrossmintSDKError.message` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
|  `name` | `public` | `string` | - | `CrossmintSDKError.name` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
|  `stack?` | `public` | `string` | - | `CrossmintSDKError.stack` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
|  `prepareStackTrace?` | `static` | (`err`: `Error`, `stackTraces`: `CallSite`\[]) => `any` | Optional override for formatting stack traces **See** [https://v8.dev/docs/stack-trace-api#customizing-stack-traces](https://v8.dev/docs/stack-trace-api#customizing-stack-traces) | `CrossmintSDKError.prepareStackTrace` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:28 |
|  `stackTraceLimit` | `static` | `number` | - | `CrossmintSDKError.stackTraceLimit` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:30 |

## Methods

### captureStackTrace()

> `static` **captureStackTrace**(`targetObject`, `constructorOpt`?): `void`

Defined in: node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:21

Create .stack property on a target object

#### Parameters

| Parameter | Type |
| - | - |
| `targetObject` | `object` |
| `constructorOpt`? | `Function` |

#### Returns

`void`

#### Inherited from

`CrossmintSDKError.captureStackTrace`


# OnboardingSessionExpiredError
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/OnboardingSessionExpiredError



Defined in: [packages/wallets/src/signers/types.ts:89](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L89)

Thrown when the signer frame was reloaded between starting and completing onboarding, so the
in-memory onboarding state (and the OTP issued for it) is gone. A fresh OTP has already been
requested when this is thrown; the caller should prompt the user to enter the new code.

## Extends

* `Error`

## Constructors

### new OnboardingSessionExpiredError()

> **new OnboardingSessionExpiredError**(`message`): `OnboardingSessionExpiredError`

Defined in: [packages/wallets/src/signers/types.ts:90](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L90)

#### Parameters

| Parameter | Type | Default value |
| - | - | - |
| `message` | `string` | `"The signer session expired before the code could be verified. A new code has been sent."` |

#### Returns

`OnboardingSessionExpiredError`

#### Overrides

`Error.constructor`

## Properties

| Property | Modifier | Type | Description | Inherited from | Defined in |
| - | - | - | - | - | - |
|  `message` | `public` | `string` | - | `Error.message` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
|  `name` | `public` | `string` | - | `Error.name` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
|  `stack?` | `public` | `string` | - | `Error.stack` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
|  `prepareStackTrace?` | `static` | (`err`: `Error`, `stackTraces`: `CallSite`\[]) => `any` | Optional override for formatting stack traces **See** [https://v8.dev/docs/stack-trace-api#customizing-stack-traces](https://v8.dev/docs/stack-trace-api#customizing-stack-traces) | `Error.prepareStackTrace` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:28 |
|  `stackTraceLimit` | `static` | `number` | - | `Error.stackTraceLimit` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:30 |

## Methods

### captureStackTrace()

> `static` **captureStackTrace**(`targetObject`, `constructorOpt`?): `void`

Defined in: node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:21

Create .stack property on a target object

#### Parameters

| Parameter | Type |
| - | - |
| `targetObject` | `object` |
| `constructorOpt`? | `Function` |

#### Returns

`void`

#### Inherited from

`Error.captureStackTrace`


# OtpValidationError
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/OtpValidationError



Defined in: [packages/wallets/src/signers/types.ts:40](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L40)

## Extends

* `Error`

## Constructors

### new OtpValidationError()

> **new OtpValidationError**(`message`, `code`?): `OtpValidationError`

Defined in: [packages/wallets/src/signers/types.ts:43](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L43)

#### Parameters

| Parameter | Type |
| - | - |
| `message` | `string` |
| `code`? | `string` |

#### Returns

`OtpValidationError`

#### Overrides

`Error.constructor`

## Properties

| Property | Modifier | Type | Description | Inherited from | Defined in |
| - | - | - | - | - | - |
|  `code` | `readonly` | `string` \| `undefined` | - | - | [packages/wallets/src/signers/types.ts:41](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L41) |
|  `message` | `public` | `string` | - | `Error.message` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
|  `name` | `public` | `string` | - | `Error.name` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
|  `stack?` | `public` | `string` | - | `Error.stack` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
|  `prepareStackTrace?` | `static` | (`err`: `Error`, `stackTraces`: `CallSite`\[]) => `any` | Optional override for formatting stack traces **See** [https://v8.dev/docs/stack-trace-api#customizing-stack-traces](https://v8.dev/docs/stack-trace-api#customizing-stack-traces) | `Error.prepareStackTrace` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:28 |
|  `stackTraceLimit` | `static` | `number` | - | `Error.stackTraceLimit` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:30 |

## Methods

### captureStackTrace()

> `static` **captureStackTrace**(`targetObject`, `constructorOpt`?): `void`

Defined in: node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:21

Create .stack property on a target object

#### Parameters

| Parameter | Type |
| - | - |
| `targetObject` | `object` |
| `constructorOpt`? | `Function` |

#### Returns

`void`

#### Inherited from

`Error.captureStackTrace`


# QuorumSignerNotSupportedError
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/QuorumSignerNotSupportedError



Defined in: [packages/wallets/src/utils/errors.ts:100](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/errors.ts#L100)

## Extends

* `CrossmintSDKError`

## Constructors

### new QuorumSignerNotSupportedError()

> **new QuorumSignerNotSupportedError**(`message`, `details`?): `QuorumSignerNotSupportedError`

Defined in: [packages/wallets/src/utils/errors.ts:101](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/errors.ts#L101)

#### Parameters

| Parameter | Type |
| - | - |
| `message` | `string` |
| `details`? | `string` |

#### Returns

`QuorumSignerNotSupportedError`

#### Overrides

`CrossmintSDKError.constructor`

## Properties

| Property | Modifier | Type | Description | Inherited from | Defined in |
| - | - | - | - | - | - |
|  `code` | `readonly` | `string` | - | `CrossmintSDKError.code` | packages/common/base/dist/error/index.d.ts:4 |
|  `details?` | `readonly` | `string` | - | `CrossmintSDKError.details` | packages/common/base/dist/error/index.d.ts:5 |
|  `message` | `public` | `string` | - | `CrossmintSDKError.message` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
|  `name` | `public` | `string` | - | `CrossmintSDKError.name` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
|  `stack?` | `public` | `string` | - | `CrossmintSDKError.stack` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
|  `prepareStackTrace?` | `static` | (`err`: `Error`, `stackTraces`: `CallSite`\[]) => `any` | Optional override for formatting stack traces **See** [https://v8.dev/docs/stack-trace-api#customizing-stack-traces](https://v8.dev/docs/stack-trace-api#customizing-stack-traces) | `CrossmintSDKError.prepareStackTrace` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:28 |
|  `stackTraceLimit` | `static` | `number` | - | `CrossmintSDKError.stackTraceLimit` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:30 |

## Methods

### captureStackTrace()

> `static` **captureStackTrace**(`targetObject`, `constructorOpt`?): `void`

Defined in: node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:21

Create .stack property on a target object

#### Parameters

| Parameter | Type |
| - | - |
| `targetObject` | `object` |
| `constructorOpt`? | `Function` |

#### Returns

`void`

#### Inherited from

`CrossmintSDKError.captureStackTrace`


# RecoveryAdminSignerConflictError
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/RecoveryAdminSignerConflictError



Defined in: [packages/wallets/src/utils/errors.ts:151](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/errors.ts#L151)

## Extends

* `CrossmintSDKError`

## Constructors

### new RecoveryAdminSignerConflictError()

> **new RecoveryAdminSignerConflictError**(`message`, `details`?): `RecoveryAdminSignerConflictError`

Defined in: [packages/wallets/src/utils/errors.ts:152](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/errors.ts#L152)

#### Parameters

| Parameter | Type |
| - | - |
| `message` | `string` |
| `details`? | `string` |

#### Returns

`RecoveryAdminSignerConflictError`

#### Overrides

`CrossmintSDKError.constructor`

## Properties

| Property | Modifier | Type | Description | Inherited from | Defined in |
| - | - | - | - | - | - |
|  `code` | `readonly` | `string` | - | `CrossmintSDKError.code` | packages/common/base/dist/error/index.d.ts:4 |
|  `details?` | `readonly` | `string` | - | `CrossmintSDKError.details` | packages/common/base/dist/error/index.d.ts:5 |
|  `message` | `public` | `string` | - | `CrossmintSDKError.message` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
|  `name` | `public` | `string` | - | `CrossmintSDKError.name` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
|  `stack?` | `public` | `string` | - | `CrossmintSDKError.stack` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
|  `prepareStackTrace?` | `static` | (`err`: `Error`, `stackTraces`: `CallSite`\[]) => `any` | Optional override for formatting stack traces **See** [https://v8.dev/docs/stack-trace-api#customizing-stack-traces](https://v8.dev/docs/stack-trace-api#customizing-stack-traces) | `CrossmintSDKError.prepareStackTrace` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:28 |
|  `stackTraceLimit` | `static` | `number` | - | `CrossmintSDKError.stackTraceLimit` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:30 |

## Methods

### captureStackTrace()

> `static` **captureStackTrace**(`targetObject`, `constructorOpt`?): `void`

Defined in: node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:21

Create .stack property on a target object

#### Parameters

| Parameter | Type |
| - | - |
| `targetObject` | `object` |
| `constructorOpt`? | `Function` |

#### Returns

`void`

#### Inherited from

`CrossmintSDKError.captureStackTrace`


# RecoveryMethodRequiredError
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/RecoveryMethodRequiredError



Defined in: [packages/wallets/src/utils/errors.ts:137](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/errors.ts#L137)

## Extends

* [`SignerRequiredError`](./SignerRequiredError)

## Constructors

### new RecoveryMethodRequiredError()

> **new RecoveryMethodRequiredError**(`message`, `details`?): `RecoveryMethodRequiredError`

Defined in: [packages/wallets/src/utils/errors.ts:132](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/errors.ts#L132)

#### Parameters

| Parameter | Type |
| - | - |
| `message` | `string` |
| `details`? | `string` |

#### Returns

`RecoveryMethodRequiredError`

#### Inherited from

[`SignerRequiredError`](./SignerRequiredError).[`constructor`](./SignerRequiredError#constructor)

## Properties

| Property | Modifier | Type | Description | Inherited from | Defined in |
| - | - | - | - | - | - |
|  `code` | `readonly` | `string` | - | [`SignerRequiredError`](./SignerRequiredError).[`code`](./SignerRequiredError#code) | packages/common/base/dist/error/index.d.ts:4 |
|  `details?` | `readonly` | `string` | - | [`SignerRequiredError`](./SignerRequiredError).[`details`](./SignerRequiredError#details) | packages/common/base/dist/error/index.d.ts:5 |
|  `message` | `public` | `string` | - | [`SignerRequiredError`](./SignerRequiredError).[`message`](./SignerRequiredError#message) | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
|  `name` | `public` | `string` | - | [`SignerRequiredError`](./SignerRequiredError).[`name`](./SignerRequiredError#name) | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
|  `stack?` | `public` | `string` | - | [`SignerRequiredError`](./SignerRequiredError).[`stack`](./SignerRequiredError#stack) | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
|  `prepareStackTrace?` | `static` | (`err`: `Error`, `stackTraces`: `CallSite`\[]) => `any` | Optional override for formatting stack traces **See** [https://v8.dev/docs/stack-trace-api#customizing-stack-traces](https://v8.dev/docs/stack-trace-api#customizing-stack-traces) | [`SignerRequiredError`](./SignerRequiredError).[`prepareStackTrace`](./SignerRequiredError#preparestacktrace) | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:28 |
|  `stackTraceLimit` | `static` | `number` | - | [`SignerRequiredError`](./SignerRequiredError).[`stackTraceLimit`](./SignerRequiredError#stacktracelimit) | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:30 |

## Methods

### captureStackTrace()

> `static` **captureStackTrace**(`targetObject`, `constructorOpt`?): `void`

Defined in: node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:21

Create .stack property on a target object

#### Parameters

| Parameter | Type |
| - | - |
| `targetObject` | `object` |
| `constructorOpt`? | `Function` |

#### Returns

`void`

#### Inherited from

[`SignerRequiredError`](./SignerRequiredError).[`captureStackTrace`](./SignerRequiredError#capturestacktrace)


# RecoveryNotSupportedOnChainError
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/RecoveryNotSupportedOnChainError



Defined in: [packages/wallets/src/utils/errors.ts:139](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/errors.ts#L139)

## Extends

* `CrossmintSDKError`

## Constructors

### new RecoveryNotSupportedOnChainError()

> **new RecoveryNotSupportedOnChainError**(`message`, `details`?): `RecoveryNotSupportedOnChainError`

Defined in: [packages/wallets/src/utils/errors.ts:140](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/errors.ts#L140)

#### Parameters

| Parameter | Type |
| - | - |
| `message` | `string` |
| `details`? | `string` |

#### Returns

`RecoveryNotSupportedOnChainError`

#### Overrides

`CrossmintSDKError.constructor`

## Properties

| Property | Modifier | Type | Description | Inherited from | Defined in |
| - | - | - | - | - | - |
|  `code` | `readonly` | `string` | - | `CrossmintSDKError.code` | packages/common/base/dist/error/index.d.ts:4 |
|  `details?` | `readonly` | `string` | - | `CrossmintSDKError.details` | packages/common/base/dist/error/index.d.ts:5 |
|  `message` | `public` | `string` | - | `CrossmintSDKError.message` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
|  `name` | `public` | `string` | - | `CrossmintSDKError.name` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
|  `stack?` | `public` | `string` | - | `CrossmintSDKError.stack` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
|  `prepareStackTrace?` | `static` | (`err`: `Error`, `stackTraces`: `CallSite`\[]) => `any` | Optional override for formatting stack traces **See** [https://v8.dev/docs/stack-trace-api#customizing-stack-traces](https://v8.dev/docs/stack-trace-api#customizing-stack-traces) | `CrossmintSDKError.prepareStackTrace` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:28 |
|  `stackTraceLimit` | `static` | `number` | - | `CrossmintSDKError.stackTraceLimit` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:30 |

## Methods

### captureStackTrace()

> `static` **captureStackTrace**(`targetObject`, `constructorOpt`?): `void`

Defined in: node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:21

Create .stack property on a target object

#### Parameters

| Parameter | Type |
| - | - |
| `targetObject` | `object` |
| `constructorOpt`? | `Function` |

#### Returns

`void`

#### Inherited from

`CrossmintSDKError.captureStackTrace`


# RecoverySignerConflictError
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/RecoverySignerConflictError



Defined in: [packages/wallets/src/utils/errors.ts:125](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/errors.ts#L125)

## Extends

* `CrossmintSDKError`

## Constructors

### new RecoverySignerConflictError()

> **new RecoverySignerConflictError**(`message`, `details`?): `RecoverySignerConflictError`

Defined in: [packages/wallets/src/utils/errors.ts:126](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/errors.ts#L126)

#### Parameters

| Parameter | Type |
| - | - |
| `message` | `string` |
| `details`? | `string` |

#### Returns

`RecoverySignerConflictError`

#### Overrides

`CrossmintSDKError.constructor`

## Properties

| Property | Modifier | Type | Description | Inherited from | Defined in |
| - | - | - | - | - | - |
|  `code` | `readonly` | `string` | - | `CrossmintSDKError.code` | packages/common/base/dist/error/index.d.ts:4 |
|  `details?` | `readonly` | `string` | - | `CrossmintSDKError.details` | packages/common/base/dist/error/index.d.ts:5 |
|  `message` | `public` | `string` | - | `CrossmintSDKError.message` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
|  `name` | `public` | `string` | - | `CrossmintSDKError.name` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
|  `stack?` | `public` | `string` | - | `CrossmintSDKError.stack` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
|  `prepareStackTrace?` | `static` | (`err`: `Error`, `stackTraces`: `CallSite`\[]) => `any` | Optional override for formatting stack traces **See** [https://v8.dev/docs/stack-trace-api#customizing-stack-traces](https://v8.dev/docs/stack-trace-api#customizing-stack-traces) | `CrossmintSDKError.prepareStackTrace` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:28 |
|  `stackTraceLimit` | `static` | `number` | - | `CrossmintSDKError.stackTraceLimit` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:30 |

## Methods

### captureStackTrace()

> `static` **captureStackTrace**(`targetObject`, `constructorOpt`?): `void`

Defined in: node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:21

Create .stack property on a target object

#### Parameters

| Parameter | Type |
| - | - |
| `targetObject` | `object` |
| `constructorOpt`? | `Function` |

#### Returns

`void`

#### Inherited from

`CrossmintSDKError.captureStackTrace`


# RecoverySignerLimitExceededError
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/RecoverySignerLimitExceededError



Defined in: [packages/wallets/src/utils/errors.ts:113](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/errors.ts#L113)

## Extends

* `CrossmintSDKError`

## Constructors

### new RecoverySignerLimitExceededError()

> **new RecoverySignerLimitExceededError**(`message`, `details`?): `RecoverySignerLimitExceededError`

Defined in: [packages/wallets/src/utils/errors.ts:114](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/errors.ts#L114)

#### Parameters

| Parameter | Type |
| - | - |
| `message` | `string` |
| `details`? | `string` |

#### Returns

`RecoverySignerLimitExceededError`

#### Overrides

`CrossmintSDKError.constructor`

## Properties

| Property | Modifier | Type | Description | Inherited from | Defined in |
| - | - | - | - | - | - |
|  `code` | `readonly` | `string` | - | `CrossmintSDKError.code` | packages/common/base/dist/error/index.d.ts:4 |
|  `details?` | `readonly` | `string` | - | `CrossmintSDKError.details` | packages/common/base/dist/error/index.d.ts:5 |
|  `message` | `public` | `string` | - | `CrossmintSDKError.message` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
|  `name` | `public` | `string` | - | `CrossmintSDKError.name` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
|  `stack?` | `public` | `string` | - | `CrossmintSDKError.stack` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
|  `prepareStackTrace?` | `static` | (`err`: `Error`, `stackTraces`: `CallSite`\[]) => `any` | Optional override for formatting stack traces **See** [https://v8.dev/docs/stack-trace-api#customizing-stack-traces](https://v8.dev/docs/stack-trace-api#customizing-stack-traces) | `CrossmintSDKError.prepareStackTrace` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:28 |
|  `stackTraceLimit` | `static` | `number` | - | `CrossmintSDKError.stackTraceLimit` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:30 |

## Methods

### captureStackTrace()

> `static` **captureStackTrace**(`targetObject`, `constructorOpt`?): `void`

Defined in: node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:21

Create .stack property on a target object

#### Parameters

| Parameter | Type |
| - | - |
| `targetObject` | `object` |
| `constructorOpt`? | `Function` |

#### Returns

`void`

#### Inherited from

`CrossmintSDKError.captureStackTrace`


# SignerAuthenticationError
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/SignerAuthenticationError



Defined in: [packages/wallets/src/signers/types.ts:54](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L54)

Thrown when the signer backend rejects the request's credentials (missing, empty or expired JWT).
Distinct from `OtpValidationError`: the OTP flow never ran, the user must re-authenticate with the app first.

## Extends

* `Error`

## Constructors

### new SignerAuthenticationError()

> **new SignerAuthenticationError**(`message`, `code`?): `SignerAuthenticationError`

Defined in: [packages/wallets/src/signers/types.ts:57](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L57)

#### Parameters

| Parameter | Type |
| - | - |
| `message` | `string` |
| `code`? | `string` |

#### Returns

`SignerAuthenticationError`

#### Overrides

`Error.constructor`

## Properties

| Property | Modifier | Type | Description | Inherited from | Defined in |
| - | - | - | - | - | - |
|  `code` | `readonly` | `string` \| `undefined` | - | - | [packages/wallets/src/signers/types.ts:55](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L55) |
|  `message` | `public` | `string` | - | `Error.message` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
|  `name` | `public` | `string` | - | `Error.name` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
|  `stack?` | `public` | `string` | - | `Error.stack` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
|  `prepareStackTrace?` | `static` | (`err`: `Error`, `stackTraces`: `CallSite`\[]) => `any` | Optional override for formatting stack traces **See** [https://v8.dev/docs/stack-trace-api#customizing-stack-traces](https://v8.dev/docs/stack-trace-api#customizing-stack-traces) | `Error.prepareStackTrace` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:28 |
|  `stackTraceLimit` | `static` | `number` | - | `Error.stackTraceLimit` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:30 |

## Methods

### captureStackTrace()

> `static` **captureStackTrace**(`targetObject`, `constructorOpt`?): `void`

Defined in: node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:21

Create .stack property on a target object

#### Parameters

| Parameter | Type |
| - | - |
| `targetObject` | `object` |
| `constructorOpt`? | `Function` |

#### Returns

`void`

#### Inherited from

`Error.captureStackTrace`


# SignerRequiredError
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/SignerRequiredError



Defined in: [packages/wallets/src/utils/errors.ts:131](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/errors.ts#L131)

## Extends

* `CrossmintSDKError`

## Extended by

* [`RecoveryMethodRequiredError`](./RecoveryMethodRequiredError)

## Constructors

### new SignerRequiredError()

> **new SignerRequiredError**(`message`, `details`?): `SignerRequiredError`

Defined in: [packages/wallets/src/utils/errors.ts:132](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/errors.ts#L132)

#### Parameters

| Parameter | Type |
| - | - |
| `message` | `string` |
| `details`? | `string` |

#### Returns

`SignerRequiredError`

#### Overrides

`CrossmintSDKError.constructor`

## Properties

| Property | Modifier | Type | Description | Inherited from | Defined in |
| - | - | - | - | - | - |
|  `code` | `readonly` | `string` | - | `CrossmintSDKError.code` | packages/common/base/dist/error/index.d.ts:4 |
|  `details?` | `readonly` | `string` | - | `CrossmintSDKError.details` | packages/common/base/dist/error/index.d.ts:5 |
|  `message` | `public` | `string` | - | `CrossmintSDKError.message` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
|  `name` | `public` | `string` | - | `CrossmintSDKError.name` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
|  `stack?` | `public` | `string` | - | `CrossmintSDKError.stack` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
|  `prepareStackTrace?` | `static` | (`err`: `Error`, `stackTraces`: `CallSite`\[]) => `any` | Optional override for formatting stack traces **See** [https://v8.dev/docs/stack-trace-api#customizing-stack-traces](https://v8.dev/docs/stack-trace-api#customizing-stack-traces) | `CrossmintSDKError.prepareStackTrace` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:28 |
|  `stackTraceLimit` | `static` | `number` | - | `CrossmintSDKError.stackTraceLimit` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:30 |

## Methods

### captureStackTrace()

> `static` **captureStackTrace**(`targetObject`, `constructorOpt`?): `void`

Defined in: node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:21

Create .stack property on a target object

#### Parameters

| Parameter | Type |
| - | - |
| `targetObject` | `object` |
| `constructorOpt`? | `Function` |

#### Returns

`void`

#### Inherited from

`CrossmintSDKError.captureStackTrace`


# SignerStatusError
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/SignerStatusError



Defined in: [packages/wallets/src/signers/types.ts:64](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L64)

## Extends

* `Error`

## Constructors

### new SignerStatusError()

> **new SignerStatusError**(`message`, `code`?): `SignerStatusError`

Defined in: [packages/wallets/src/signers/types.ts:67](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L67)

#### Parameters

| Parameter | Type |
| - | - |
| `message` | `string` |
| `code`? | `string` |

#### Returns

`SignerStatusError`

#### Overrides

`Error.constructor`

## Properties

| Property | Modifier | Type | Description | Inherited from | Defined in |
| - | - | - | - | - | - |
|  `code` | `readonly` | `string` \| `undefined` | - | - | [packages/wallets/src/signers/types.ts:65](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L65) |
|  `message` | `public` | `string` | - | `Error.message` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
|  `name` | `public` | `string` | - | `Error.name` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
|  `stack?` | `public` | `string` | - | `Error.stack` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
|  `prepareStackTrace?` | `static` | (`err`: `Error`, `stackTraces`: `CallSite`\[]) => `any` | Optional override for formatting stack traces **See** [https://v8.dev/docs/stack-trace-api#customizing-stack-traces](https://v8.dev/docs/stack-trace-api#customizing-stack-traces) | `Error.prepareStackTrace` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:28 |
|  `stackTraceLimit` | `static` | `number` | - | `Error.stackTraceLimit` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:30 |

## Methods

### captureStackTrace()

> `static` **captureStackTrace**(`targetObject`, `constructorOpt`?): `void`

Defined in: node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:21

Create .stack property on a target object

#### Parameters

| Parameter | Type |
| - | - |
| `targetObject` | `object` |
| `constructorOpt`? | `Function` |

#### Returns

`void`

#### Inherited from

`Error.captureStackTrace`


# SolanaWallet
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/SolanaWallet



Defined in: [packages/wallets/src/wallets/solana.ts:18](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/solana.ts#L18)

## Extends

* [`Wallet`](./Wallet)\<[`SolanaChain`](../type-aliases/SolanaChain)>

## Constructors

### new SolanaWallet()

> **new SolanaWallet**(`wallet`): `SolanaWallet`

Defined in: [packages/wallets/src/wallets/solana.ts:19](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/solana.ts#L19)

#### Parameters

| Parameter | Type |
| - | - |
| `wallet` | [`Wallet`](./Wallet)\<`"solana"`> |

#### Returns

`SolanaWallet`

#### Overrides

[`Wallet`](./Wallet).[`constructor`](./Wallet#constructor)

## Properties

| Property | Type | Inherited from | Defined in |
| - | - | - | - |
|  `address` | `string` | [`Wallet`](./Wallet).[`address`](./Wallet#address) | [packages/wallets/src/wallets/wallet.ts:104](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L104) |
|  `alias?` | `string` | [`Wallet`](./Wallet).[`alias`](./Wallet#alias) | [packages/wallets/src/wallets/wallet.ts:106](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L106) |
|  `chain` | `"solana"` | [`Wallet`](./Wallet).[`chain`](./Wallet#chain) | [packages/wallets/src/wallets/wallet.ts:103](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L103) |
|  `owner?` | `string` | [`Wallet`](./Wallet).[`owner`](./Wallet#owner) | [packages/wallets/src/wallets/wallet.ts:105](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L105) |

## Accessors

### apiClient

#### Get Signature

> **get** **apiClient**(): [`WalletsApiClient`](./WalletsApiClient)

Defined in: [packages/wallets/src/wallets/wallet.ts:296](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L296)

##### Returns

[`WalletsApiClient`](./WalletsApiClient)

#### Inherited from

[`Wallet`](./Wallet).[`apiClient`](./Wallet#apiclient)

***

### recovery

#### Get Signature

> **get** **recovery**(): [`SignerConfigForChain`](../type-aliases/SignerConfigForChain)\<`C`>

Defined in: [packages/wallets/src/wallets/wallet.ts:321](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L321)

**`Experimental`**

Get the primary recovery signer config. Use [recoveryMethods](./#recoverymethods) for the full list on wallets
created with several recovery signers.

##### Returns

[`SignerConfigForChain`](../type-aliases/SignerConfigForChain)\<`C`>

The recovery signer config
This API is experimental and may change in the future

#### Inherited from

[`Wallet`](./Wallet).[`recovery`](./Wallet#recovery)

***

### recoveryMethods

#### Get Signature

> **get** **recoveryMethods**(): [`RecoverySignerConfigForChain`](../type-aliases/RecoverySignerConfigForChain)\<`C`>\[]

Defined in: [packages/wallets/src/wallets/wallet.ts:331](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L331)

**`Experimental`**

Get every recovery signer config of the wallet. Wallets on chains that support a single recovery
signer always return one entry.

##### Returns

[`RecoverySignerConfigForChain`](../type-aliases/RecoverySignerConfigForChain)\<`C`>\[]

The recovery signer configs
This API is experimental and may change in the future

#### Inherited from

[`Wallet`](./Wallet).[`recoveryMethods`](./Wallet#recoverymethods)

***

### signer

#### Get Signature

> **get** **signer**(): [`SignerAdapter`](../interfaces/SignerAdapter)\<keyof `SignResultMap`> | `undefined`

Defined in: [packages/wallets/src/wallets/wallet.ts:201](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L201)

##### Returns

[`SignerAdapter`](../interfaces/SignerAdapter)\<keyof `SignResultMap`> | `undefined`

#### Inherited from

[`Wallet`](./Wallet).[`signer`](./Wallet#signer)

## Methods

### addRecoveryMethod()

> **addRecoveryMethod**\<`T`>(`recoveryMethod`, `options`?): `Promise`\<[`AddRecoveryMethodReturnType`](../type-aliases/AddRecoveryMethodReturnType)>

Defined in: [packages/wallets/src/wallets/wallet.ts:860](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L860)

Add a recovery method to the wallet. Supported on Solana and Stellar only.
Always uses one of the existing recovery methods to approve the change, selected as in [addSigner](./#addsigner).

#### Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* [`AddRecoveryMethodOptions`](../type-aliases/AddRecoveryMethodOptions) \| `undefined` | `undefined` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `recoveryMethod` | [`DeviceSignerConfig`](../type-aliases/DeviceSignerConfig) \| [`ExternalWalletRegistrationConfig`](../type-aliases/ExternalWalletRegistrationConfig) \| [`EmailSignerConfig`](../type-aliases/EmailSignerConfig) \| [`PhoneSignerConfig`](../type-aliases/PhoneSignerConfig) \| `BaseSignerConfig`\<`"solana"`> | The recovery method configuration object |
| `options`? | `T` | The options for the operation |

#### Returns

`Promise`\<[`AddRecoveryMethodReturnType`](../type-aliases/AddRecoveryMethodReturnType)>

#### Inherited from

[`Wallet`](./Wallet).[`addRecoveryMethod`](./Wallet#addrecoverymethod)

***

### addSigner()

> **addSigner**\<`T`>(`signer`, `options`?): `Promise`\<`T` *extends* `PrepareOnly`\<`true`> ? [`Signer`](../type-aliases/Signer) & `object` : [`Signer`](../type-aliases/Signer)>

Defined in: [packages/wallets/src/wallets/wallet.ts:649](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L649)

Add a signer to the wallet.
Always uses a recovery method internally to approve the registration: the one selected via
[useRecoveryMethod](./#userecoverymethod), else the active signer when it is one of the recovery methods, else the wallet's
single recovery method. Wallets with several recovery methods must select one first; an operational signer
cannot authorize this.
If the signer being added is the current operational signer, it will be reassembled with the new locator.
Otherwise, the original signer is restored after the operation.

#### Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* [`AddSignerOptions`](../type-aliases/AddSignerOptions) \| `undefined` | `undefined` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `signer` | [`DeviceSignerConfig`](../type-aliases/DeviceSignerConfig) \| [`ExternalWalletRegistrationConfig`](../type-aliases/ExternalWalletRegistrationConfig) \| [`EmailSignerConfig`](../type-aliases/EmailSignerConfig) \| [`PhoneSignerConfig`](../type-aliases/PhoneSignerConfig) \| `BaseSignerConfig`\<`"solana"`> | The signer configuration object |
| `options`? | `T` | The options for the operation |

#### Returns

`Promise`\<`T` *extends* `PrepareOnly`\<`true`> ? [`Signer`](../type-aliases/Signer) & `object` : [`Signer`](../type-aliases/Signer)>

#### Inherited from

[`Wallet`](./Wallet).[`addSigner`](./Wallet#addsigner)

***

### approve()

> **approve**\<`T`>(`params`): `Promise`\<`ApproveResult`\<`T`>>

Defined in: [packages/wallets/src/wallets/wallet.ts:599](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L599)

Approve a transaction or signature

#### Type Parameters

| Type Parameter |
| - |
| `T` *extends* [`ApproveParams`](../type-aliases/ApproveParams) |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | `T` | The parameters |

#### Returns

`Promise`\<`ApproveResult`\<`T`>>

The transaction or signature

#### Inherited from

[`Wallet`](./Wallet).[`approve`](./Wallet#approve)

***

### ~~approveTransaction()~~

> **approveTransaction**(`params`): `Promise`\<`Error`>

Defined in: [packages/wallets/src/wallets/wallet.ts:575](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L575)

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | [`ApproveParams`](../type-aliases/ApproveParams) | The parameters |

#### Returns

`Promise`\<`Error`>

The transaction

#### Deprecated

Use `approve` instead.
Approve a transaction

#### Inherited from

[`Wallet`](./Wallet).[`approveTransaction`](./Wallet#approvetransaction)

***

### balances()

> **balances**(`tokens`?): `Promise`\<[`Balances`](../type-aliases/Balances)\<`"solana"`>>

Defined in: [packages/wallets/src/wallets/wallet.ts:348](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L348)

Get the wallet balances - always includes USDC and native token (ETH/SOL)

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `tokens`? | `string`\[] | Additional tokens to request (optional: native token and usdc are always included) |

#### Returns

`Promise`\<[`Balances`](../type-aliases/Balances)\<`"solana"`>>

The balances returns nativeToken, usdc, tokens

#### Throws

If the balances cannot be retrieved

#### Inherited from

[`Wallet`](./Wallet).[`balances`](./Wallet#balances)

***

### isSignerApproved()

> **isSignerApproved**(`signerLocator`): `Promise`\<`boolean`>

Defined in: [packages/wallets/src/wallets/wallet.ts:1203](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L1203)

Check if a signer is approved and usable for the current wallet chain.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `signerLocator` | `string` | The locator of the signer to check |

#### Returns

`Promise`\<`boolean`>

true if the signer is approved for this chain, false if it is not approved or not registered

#### Throws

if the approval state could not be fetched

#### Inherited from

[`Wallet`](./Wallet).[`isSignerApproved`](./Wallet#issignerapproved)

***

### needsRecovery()

> **needsRecovery**(): `boolean`

Defined in: [packages/wallets/src/wallets/wallet.ts:1211](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L1211)

Whether the wallet needs recovery (signer registration) before the next transaction.

#### Returns

`boolean`

true if recovery is needed

#### Inherited from

[`Wallet`](./Wallet).[`needsRecovery`](./Wallet#needsrecovery)

***

### nfts()

> **nfts**(`params`): `Promise`\<`unknown`>

Defined in: [packages/wallets/src/wallets/wallet.ts:417](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L417)

Get the wallet NFTs

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | \{ `page`: `number`; `perPage`: `number`; } | The parameters |
| `params.page` | `number` | The page number |
| `params.perPage` | `number` | The number of NFTs per page |

#### Returns

`Promise`\<`unknown`>

The NFTs

#### Inherited from

[`Wallet`](./Wallet).[`nfts`](./Wallet#nfts)

***

### recover()

> **recover**(): `Promise`\<`void`>

Defined in: [packages/wallets/src/wallets/wallet.ts:1227](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L1227)

Register a device signer with the wallet using the recovery signer.
Generates a new device key and registers it on-chain.
Returns early if the device signer's locator is already approved on-chain.

#### Returns

`Promise`\<`void`>

#### Inherited from

[`Wallet`](./Wallet).[`recover`](./Wallet#recover)

***

### removeRecoveryMethod()

> **removeRecoveryMethod**\<`T`>(`recoveryMethod`, `options`?): `Promise`\<[`RemoveRecoveryMethodReturnType`](../type-aliases/RemoveRecoveryMethodReturnType)>

Defined in: [packages/wallets/src/wallets/wallet.ts:927](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L927)

Remove a recovery method from the wallet. Supported on Solana and Stellar only.
Always uses one of the remaining recovery methods to approve the change, selected as in [addSigner](./#addsigner).

#### Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* [`RemoveRecoveryMethodOptions`](../type-aliases/RemoveRecoveryMethodOptions) \| `undefined` | `undefined` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `recoveryMethod` | [`DeviceSignerConfig`](../type-aliases/DeviceSignerConfig) \| [`ExternalWalletRegistrationConfig`](../type-aliases/ExternalWalletRegistrationConfig) \| [`EmailSignerConfig`](../type-aliases/EmailSignerConfig) \| [`PhoneSignerConfig`](../type-aliases/PhoneSignerConfig) \| `BaseSignerConfig`\<`"solana"`> | The recovery method to remove, provided as a signer config object |
| `options`? | `T` | The options for the operation |

#### Returns

`Promise`\<[`RemoveRecoveryMethodReturnType`](../type-aliases/RemoveRecoveryMethodReturnType)>

#### Inherited from

[`Wallet`](./Wallet).[`removeRecoveryMethod`](./Wallet#removerecoverymethod)

***

### removeSigner()

> **removeSigner**\<`T`>(`signer`, `options`?): `Promise`\<`RemoveSignerReturnType`>

Defined in: [packages/wallets/src/wallets/wallet.ts:810](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L810)

Remove a signer from the wallet.
Always uses a recovery method internally to approve the removal, selected as in [addSigner](./#addsigner).

#### Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* [`RemoveSignerOptions`](../type-aliases/RemoveSignerOptions) \| `undefined` | `undefined` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `signer` | [`DeviceSignerConfig`](../type-aliases/DeviceSignerConfig) \| [`ExternalWalletRegistrationConfig`](../type-aliases/ExternalWalletRegistrationConfig) \| [`EmailSignerConfig`](../type-aliases/EmailSignerConfig) \| [`PhoneSignerConfig`](../type-aliases/PhoneSignerConfig) \| `BaseSignerConfig`\<`"solana"`> | The signer to remove, provided as a signer config object |
| `options`? | `T` | The options for the operation |

#### Returns

`Promise`\<`RemoveSignerReturnType`>

#### Inherited from

[`Wallet`](./Wallet).[`removeSigner`](./Wallet#removesigner)

***

### send()

> **send**\<`T`>(`to`, `token`, `amount`, `options`?): `Promise`\<[`Transaction`](../type-aliases/Transaction)\<`T` *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

Defined in: [packages/wallets/src/wallets/wallet.ts:492](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L492)

Send a token to a wallet or user locator

#### Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* `SendTokenTransactionOptions` \| `undefined` | `undefined` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `to` | `string` \| `UserLocator` | The recipient (address or user locator) |
| `token` | `string` | The token (address or currency symbol) |
| `amount` | `string` | The amount to send (decimal units) |
| `options`? | `T` | The options for the transaction |

#### Returns

`Promise`\<[`Transaction`](../type-aliases/Transaction)\<`T` *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

The transaction

#### Inherited from

[`Wallet`](./Wallet).[`send`](./Wallet#send)

***

### sendTransaction()

> **sendTransaction**\<`T`>(`params`): `Promise`\<[`Transaction`](../type-aliases/Transaction)\<`T` *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

Defined in: [packages/wallets/src/wallets/solana.ts:57](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/solana.ts#L57)

Send a raw Solana transaction.

#### Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* `TransactionInputOptions` \| `undefined` | `undefined` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | [`SolanaTransactionInput`](../type-aliases/SolanaTransactionInput) & `object` | The transaction parameters (serialized transaction or Transaction object) |

#### Returns

`Promise`\<[`Transaction`](../type-aliases/Transaction)\<`T` *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

The transaction result

***

### signerIsRegistered()

> **signerIsRegistered**(`signerLocator`): `Promise`\<`boolean`>

Defined in: [packages/wallets/src/wallets/wallet.ts:1193](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L1193)

Check if a signer is registered in this wallet.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `signerLocator` | `string` | The locator of the signer to check |

#### Returns

`Promise`\<`boolean`>

true if the signer is registered

#### Inherited from

[`Wallet`](./Wallet).[`signerIsRegistered`](./Wallet#signerisregistered)

***

### signers()

> **signers**(): `Promise`\<[`Signer`](../type-aliases/Signer)\[]>

Defined in: [packages/wallets/src/wallets/wallet.ts:1244](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L1244)

List the signers for this wallet.
Returns full signer objects with status.
For EVM wallets, only signers with an approval (pending or completed) for the wallet's chain are included.

#### Returns

`Promise`\<[`Signer`](../type-aliases/Signer)\[]>

The signers

#### Inherited from

[`Wallet`](./Wallet).[`signers`](./Wallet#signers)

***

### stagingFund()

> **stagingFund**(`amount`, `chain`?): `Promise`\<`FundWalletResponse`>

Defined in: [packages/wallets/src/wallets/wallet.ts:387](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L387)

Funds the wallet with Crossmint's stablecoin (USDXM).

**Note:** This method is only available in staging environments and exclusively supports USDXM tokens.
It cannot be used in production environments.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `amount` | `number` | The amount of USDXM to fund the wallet with |
| `chain`? | [`Chain`](../type-aliases/Chain) | Optional chain to fund on. If not provided, uses the wallet's default chain |

#### Returns

`Promise`\<`FundWalletResponse`>

The funding response

#### Throws

If the funding operation fails or if called in a production environment

#### Inherited from

[`Wallet`](./Wallet).[`stagingFund`](./Wallet#stagingfund)

***

### transaction()

> **transaction**(`transactionId`): `Promise`\<`WalletsTransactionV2025ResponseDtoClass`>

Defined in: [packages/wallets/src/wallets/wallet.ts:449](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L449)

Get a transaction by id

#### Parameters

| Parameter | Type |
| - | - |
| `transactionId` | `string` |

#### Returns

`Promise`\<`WalletsTransactionV2025ResponseDtoClass`>

The transaction

#### Throws

If the transaction cannot be retrieved

#### Inherited from

[`Wallet`](./Wallet).[`transaction`](./Wallet#transaction)

***

### transactions()

> **transactions**(): `Promise`\<`GetTransactionsResponse`>

Defined in: [packages/wallets/src/wallets/wallet.ts:436](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L436)

Get the wallet transactions

#### Returns

`Promise`\<`GetTransactionsResponse`>

The transactions

#### Throws

If the transactions cannot be retrieved

#### Inherited from

[`Wallet`](./Wallet).[`transactions`](./Wallet#transactions)

***

### transfers()

> **transfers**(`params`): `Promise`\<`WalletsActivityResponseUnstableDto`>

Defined in: [packages/wallets/src/wallets/wallet.ts:464](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L464)

Get the wallet transfers

#### Parameters

| Parameter | Type |
| - | - |
| `params` | \{ `status`: `"successful"` \| `"failed"`; `tokens`: `string`; } |
| `params.status` | `"successful"` \| `"failed"` |
| `params.tokens`? | `string` |

#### Returns

`Promise`\<`WalletsActivityResponseUnstableDto`>

The transfers

#### Throws

If the transfers cannot be retrieved

#### Inherited from

[`Wallet`](./Wallet).[`transfers`](./Wallet#transfers)

***

### useRecoveryMethod()

> **useRecoveryMethod**(`recoveryMethod`): `Promise`\<`void`>

Defined in: [packages/wallets/src/wallets/wallet.ts:1044](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L1044)

**`Experimental`**

Select which of the wallet's recovery methods authorizes admin operations ([addSigner](./#addsigner),
[removeSigner](./#removesigner), [addRecoveryMethod](./#addrecoverymethod), [removeRecoveryMethod](./#removerecoverymethod)). Unlike [useSigner](./#usesigner),
this does not change the active signer used for transactions and signatures.

The config must refer to one of [recoveryMethods](./#recoverymethods); pass the fuller form when the method needs it to
operate (an `onSign` callback for external wallets, the `secret` for server signers).

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `recoveryMethod` | [`DeviceSignerConfig`](../type-aliases/DeviceSignerConfig) \| [`EmailSignerConfig`](../type-aliases/EmailSignerConfig) \| [`PhoneSignerConfig`](../type-aliases/PhoneSignerConfig) \| `BaseSignerConfig`\<`"solana"`> | The recovery method config object to authorize with This API is experimental and may change in the future |

#### Returns

`Promise`\<`void`>

#### Inherited from

[`Wallet`](./Wallet).[`useRecoveryMethod`](./Wallet#userecoverymethod)

***

### useSigner()

> **useSigner**(`signer`): `Promise`\<`void`>

Defined in: [packages/wallets/src/wallets/wallet.ts:1000](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L1000)

Set the active signer for this wallet.
Accepts a signer config object. The locator is inferred internally.
Works for both registered signers and the recovery signer.

For passkey signers: if no `id` is provided, the wallet will auto-select the passkey
if exactly one passkey signer is registered. If multiple passkeys exist, an `id` must be specified.

For device signers: if no device key is found locally, the signer will be created
automatically during the next transaction (via recovery).

For external-wallet signers: the config object must include an onSign callback
(applies to both registered and recovery signers).

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `signer` | [`DeviceSignerConfig`](../type-aliases/DeviceSignerConfig) \| [`EmailSignerConfig`](../type-aliases/EmailSignerConfig) \| [`PhoneSignerConfig`](../type-aliases/PhoneSignerConfig) \| `BaseSignerConfig`\<`"solana"`> | The signer config object to use |

#### Returns

`Promise`\<`void`>

#### Inherited from

[`Wallet`](./Wallet).[`useSigner`](./Wallet#usesigner)

***

### waitForInit()

> **waitForInit**(): `Promise`\<`void`>

Defined in: [packages/wallets/src/wallets/wallet.ts:209](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L209)

Wait for the wallet's internal signer initialization to complete.
After this resolves, `needsRecovery()` reflects the true state.

#### Returns

`Promise`\<`void`>

#### Inherited from

[`Wallet`](./Wallet).[`waitForInit`](./Wallet#waitforinit)

***

### from()

> `static` **from**(`wallet`): `SolanaWallet`

Defined in: [packages/wallets/src/wallets/solana.ts:37](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/solana.ts#L37)

#### Parameters

| Parameter | Type |
| - | - |
| `wallet` | [`Wallet`](./Wallet)\<[`Chain`](../type-aliases/Chain)> |

#### Returns

`SolanaWallet`


# StellarWallet
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/StellarWallet



Defined in: [packages/wallets/src/wallets/stellar.ts:20](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/stellar.ts#L20)

## Extends

* [`Wallet`](./Wallet)\<[`StellarChain`](../type-aliases/StellarChain)>

## Constructors

### new StellarWallet()

> **new StellarWallet**(`wallet`): `StellarWallet`

Defined in: [packages/wallets/src/wallets/stellar.ts:21](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/stellar.ts#L21)

#### Parameters

| Parameter | Type |
| - | - |
| `wallet` | [`Wallet`](./Wallet)\<`"stellar"`> |

#### Returns

`StellarWallet`

#### Overrides

[`Wallet`](./Wallet).[`constructor`](./Wallet#constructor)

## Properties

| Property | Type | Inherited from | Defined in |
| - | - | - | - |
|  `address` | `string` | [`Wallet`](./Wallet).[`address`](./Wallet#address) | [packages/wallets/src/wallets/wallet.ts:104](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L104) |
|  `alias?` | `string` | [`Wallet`](./Wallet).[`alias`](./Wallet#alias) | [packages/wallets/src/wallets/wallet.ts:106](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L106) |
|  `chain` | `"stellar"` | [`Wallet`](./Wallet).[`chain`](./Wallet#chain) | [packages/wallets/src/wallets/wallet.ts:103](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L103) |
|  `owner?` | `string` | [`Wallet`](./Wallet).[`owner`](./Wallet#owner) | [packages/wallets/src/wallets/wallet.ts:105](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L105) |

## Accessors

### apiClient

#### Get Signature

> **get** **apiClient**(): [`WalletsApiClient`](./WalletsApiClient)

Defined in: [packages/wallets/src/wallets/wallet.ts:296](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L296)

##### Returns

[`WalletsApiClient`](./WalletsApiClient)

#### Inherited from

[`Wallet`](./Wallet).[`apiClient`](./Wallet#apiclient)

***

### recovery

#### Get Signature

> **get** **recovery**(): [`SignerConfigForChain`](../type-aliases/SignerConfigForChain)\<`C`>

Defined in: [packages/wallets/src/wallets/wallet.ts:321](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L321)

**`Experimental`**

Get the primary recovery signer config. Use [recoveryMethods](./#recoverymethods) for the full list on wallets
created with several recovery signers.

##### Returns

[`SignerConfigForChain`](../type-aliases/SignerConfigForChain)\<`C`>

The recovery signer config
This API is experimental and may change in the future

#### Inherited from

[`Wallet`](./Wallet).[`recovery`](./Wallet#recovery)

***

### recoveryMethods

#### Get Signature

> **get** **recoveryMethods**(): [`RecoverySignerConfigForChain`](../type-aliases/RecoverySignerConfigForChain)\<`C`>\[]

Defined in: [packages/wallets/src/wallets/wallet.ts:331](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L331)

**`Experimental`**

Get every recovery signer config of the wallet. Wallets on chains that support a single recovery
signer always return one entry.

##### Returns

[`RecoverySignerConfigForChain`](../type-aliases/RecoverySignerConfigForChain)\<`C`>\[]

The recovery signer configs
This API is experimental and may change in the future

#### Inherited from

[`Wallet`](./Wallet).[`recoveryMethods`](./Wallet#recoverymethods)

***

### signer

#### Get Signature

> **get** **signer**(): [`SignerAdapter`](../interfaces/SignerAdapter)\<keyof `SignResultMap`> | `undefined`

Defined in: [packages/wallets/src/wallets/wallet.ts:201](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L201)

##### Returns

[`SignerAdapter`](../interfaces/SignerAdapter)\<keyof `SignResultMap`> | `undefined`

#### Inherited from

[`Wallet`](./Wallet).[`signer`](./Wallet#signer)

## Methods

### addRecoveryMethod()

> **addRecoveryMethod**\<`T`>(`recoveryMethod`, `options`?): `Promise`\<[`AddRecoveryMethodReturnType`](../type-aliases/AddRecoveryMethodReturnType)>

Defined in: [packages/wallets/src/wallets/wallet.ts:860](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L860)

Add a recovery method to the wallet. Supported on Solana and Stellar only.
Always uses one of the existing recovery methods to approve the change, selected as in [addSigner](./#addsigner).

#### Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* [`AddRecoveryMethodOptions`](../type-aliases/AddRecoveryMethodOptions) \| `undefined` | `undefined` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `recoveryMethod` | [`DeviceSignerConfig`](../type-aliases/DeviceSignerConfig) \| [`ExternalWalletRegistrationConfig`](../type-aliases/ExternalWalletRegistrationConfig) \| [`EmailSignerConfig`](../type-aliases/EmailSignerConfig) \| [`PhoneSignerConfig`](../type-aliases/PhoneSignerConfig) \| `BaseSignerConfig`\<`"stellar"`> | The recovery method configuration object |
| `options`? | `T` | The options for the operation |

#### Returns

`Promise`\<[`AddRecoveryMethodReturnType`](../type-aliases/AddRecoveryMethodReturnType)>

#### Inherited from

[`Wallet`](./Wallet).[`addRecoveryMethod`](./Wallet#addrecoverymethod)

***

### addSigner()

> **addSigner**\<`T`>(`signer`, `options`?): `Promise`\<`T` *extends* `PrepareOnly`\<`true`> ? [`Signer`](../type-aliases/Signer) & `object` : [`Signer`](../type-aliases/Signer)>

Defined in: [packages/wallets/src/wallets/wallet.ts:649](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L649)

Add a signer to the wallet.
Always uses a recovery method internally to approve the registration: the one selected via
[useRecoveryMethod](./#userecoverymethod), else the active signer when it is one of the recovery methods, else the wallet's
single recovery method. Wallets with several recovery methods must select one first; an operational signer
cannot authorize this.
If the signer being added is the current operational signer, it will be reassembled with the new locator.
Otherwise, the original signer is restored after the operation.

#### Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* [`AddSignerOptions`](../type-aliases/AddSignerOptions) \| `undefined` | `undefined` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `signer` | [`DeviceSignerConfig`](../type-aliases/DeviceSignerConfig) \| [`ExternalWalletRegistrationConfig`](../type-aliases/ExternalWalletRegistrationConfig) \| [`EmailSignerConfig`](../type-aliases/EmailSignerConfig) \| [`PhoneSignerConfig`](../type-aliases/PhoneSignerConfig) \| `BaseSignerConfig`\<`"stellar"`> | The signer configuration object |
| `options`? | `T` | The options for the operation |

#### Returns

`Promise`\<`T` *extends* `PrepareOnly`\<`true`> ? [`Signer`](../type-aliases/Signer) & `object` : [`Signer`](../type-aliases/Signer)>

#### Inherited from

[`Wallet`](./Wallet).[`addSigner`](./Wallet#addsigner)

***

### approve()

> **approve**\<`T`>(`params`): `Promise`\<`ApproveResult`\<`T`>>

Defined in: [packages/wallets/src/wallets/wallet.ts:599](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L599)

Approve a transaction or signature

#### Type Parameters

| Type Parameter |
| - |
| `T` *extends* [`ApproveParams`](../type-aliases/ApproveParams) |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | `T` | The parameters |

#### Returns

`Promise`\<`ApproveResult`\<`T`>>

The transaction or signature

#### Inherited from

[`Wallet`](./Wallet).[`approve`](./Wallet#approve)

***

### ~~approveTransaction()~~

> **approveTransaction**(`params`): `Promise`\<`Error`>

Defined in: [packages/wallets/src/wallets/wallet.ts:575](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L575)

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | [`ApproveParams`](../type-aliases/ApproveParams) | The parameters |

#### Returns

`Promise`\<`Error`>

The transaction

#### Deprecated

Use `approve` instead.
Approve a transaction

#### Inherited from

[`Wallet`](./Wallet).[`approveTransaction`](./Wallet#approvetransaction)

***

### balances()

> **balances**(`tokens`?): `Promise`\<[`Balances`](../type-aliases/Balances)\<`"stellar"`>>

Defined in: [packages/wallets/src/wallets/wallet.ts:348](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L348)

Get the wallet balances - always includes USDC and native token (ETH/SOL)

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `tokens`? | `string`\[] | Additional tokens to request (optional: native token and usdc are always included) |

#### Returns

`Promise`\<[`Balances`](../type-aliases/Balances)\<`"stellar"`>>

The balances returns nativeToken, usdc, tokens

#### Throws

If the balances cannot be retrieved

#### Inherited from

[`Wallet`](./Wallet).[`balances`](./Wallet#balances)

***

### isSignerApproved()

> **isSignerApproved**(`signerLocator`): `Promise`\<`boolean`>

Defined in: [packages/wallets/src/wallets/wallet.ts:1203](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L1203)

Check if a signer is approved and usable for the current wallet chain.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `signerLocator` | `string` | The locator of the signer to check |

#### Returns

`Promise`\<`boolean`>

true if the signer is approved for this chain, false if it is not approved or not registered

#### Throws

if the approval state could not be fetched

#### Inherited from

[`Wallet`](./Wallet).[`isSignerApproved`](./Wallet#issignerapproved)

***

### migrate()

> **migrate**\<`T`>(`options`?): `Promise`\<[`Transaction`](../type-aliases/Transaction)\<`T` *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

Defined in: [packages/wallets/src/wallets/stellar.ts:168](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/stellar.ts#L168)

Run only the migration phase of a Stellar wallet upgrade. Use this when the
upgrade transaction has already confirmed on-chain (e.g. from a previous
`upgrade({ prepareOnly: true })` flow) and the wallet is in the locked state.

#### Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* `MigrateOptions` \| `undefined` | `undefined` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `options`? | `T` | Optional prepareOnly / signer override. |

#### Returns

`Promise`\<[`Transaction`](../type-aliases/Transaction)\<`T` *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

***

### needsRecovery()

> **needsRecovery**(): `boolean`

Defined in: [packages/wallets/src/wallets/wallet.ts:1211](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L1211)

Whether the wallet needs recovery (signer registration) before the next transaction.

#### Returns

`boolean`

true if recovery is needed

#### Inherited from

[`Wallet`](./Wallet).[`needsRecovery`](./Wallet#needsrecovery)

***

### nfts()

> **nfts**(`params`): `Promise`\<`unknown`>

Defined in: [packages/wallets/src/wallets/wallet.ts:417](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L417)

Get the wallet NFTs

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | \{ `page`: `number`; `perPage`: `number`; } | The parameters |
| `params.page` | `number` | The page number |
| `params.perPage` | `number` | The number of NFTs per page |

#### Returns

`Promise`\<`unknown`>

The NFTs

#### Inherited from

[`Wallet`](./Wallet).[`nfts`](./Wallet#nfts)

***

### recover()

> **recover**(): `Promise`\<`void`>

Defined in: [packages/wallets/src/wallets/wallet.ts:1227](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L1227)

Register a device signer with the wallet using the recovery signer.
Generates a new device key and registers it on-chain.
Returns early if the device signer's locator is already approved on-chain.

#### Returns

`Promise`\<`void`>

#### Inherited from

[`Wallet`](./Wallet).[`recover`](./Wallet#recover)

***

### removeRecoveryMethod()

> **removeRecoveryMethod**\<`T`>(`recoveryMethod`, `options`?): `Promise`\<[`RemoveRecoveryMethodReturnType`](../type-aliases/RemoveRecoveryMethodReturnType)>

Defined in: [packages/wallets/src/wallets/wallet.ts:927](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L927)

Remove a recovery method from the wallet. Supported on Solana and Stellar only.
Always uses one of the remaining recovery methods to approve the change, selected as in [addSigner](./#addsigner).

#### Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* [`RemoveRecoveryMethodOptions`](../type-aliases/RemoveRecoveryMethodOptions) \| `undefined` | `undefined` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `recoveryMethod` | [`DeviceSignerConfig`](../type-aliases/DeviceSignerConfig) \| [`ExternalWalletRegistrationConfig`](../type-aliases/ExternalWalletRegistrationConfig) \| [`EmailSignerConfig`](../type-aliases/EmailSignerConfig) \| [`PhoneSignerConfig`](../type-aliases/PhoneSignerConfig) \| `BaseSignerConfig`\<`"stellar"`> | The recovery method to remove, provided as a signer config object |
| `options`? | `T` | The options for the operation |

#### Returns

`Promise`\<[`RemoveRecoveryMethodReturnType`](../type-aliases/RemoveRecoveryMethodReturnType)>

#### Inherited from

[`Wallet`](./Wallet).[`removeRecoveryMethod`](./Wallet#removerecoverymethod)

***

### removeSigner()

> **removeSigner**\<`T`>(`signer`, `options`?): `Promise`\<`RemoveSignerReturnType`>

Defined in: [packages/wallets/src/wallets/wallet.ts:810](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L810)

Remove a signer from the wallet.
Always uses a recovery method internally to approve the removal, selected as in [addSigner](./#addsigner).

#### Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* [`RemoveSignerOptions`](../type-aliases/RemoveSignerOptions) \| `undefined` | `undefined` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `signer` | [`DeviceSignerConfig`](../type-aliases/DeviceSignerConfig) \| [`ExternalWalletRegistrationConfig`](../type-aliases/ExternalWalletRegistrationConfig) \| [`EmailSignerConfig`](../type-aliases/EmailSignerConfig) \| [`PhoneSignerConfig`](../type-aliases/PhoneSignerConfig) \| `BaseSignerConfig`\<`"stellar"`> | The signer to remove, provided as a signer config object |
| `options`? | `T` | The options for the operation |

#### Returns

`Promise`\<`RemoveSignerReturnType`>

#### Inherited from

[`Wallet`](./Wallet).[`removeSigner`](./Wallet#removesigner)

***

### send()

> **send**\<`T`>(`to`, `token`, `amount`, `options`?): `Promise`\<[`Transaction`](../type-aliases/Transaction)\<`T` *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

Defined in: [packages/wallets/src/wallets/wallet.ts:492](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L492)

Send a token to a wallet or user locator

#### Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* `SendTokenTransactionOptions` \| `undefined` | `undefined` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `to` | `string` \| `UserLocator` | The recipient (address or user locator) |
| `token` | `string` | The token (address or currency symbol) |
| `amount` | `string` | The amount to send (decimal units) |
| `options`? | `T` | The options for the transaction |

#### Returns

`Promise`\<[`Transaction`](../type-aliases/Transaction)\<`T` *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

The transaction

#### Inherited from

[`Wallet`](./Wallet).[`send`](./Wallet#send)

***

### sendTransaction()

> **sendTransaction**\<`T`>(`params`): `Promise`\<[`Transaction`](../type-aliases/Transaction)\<`T` *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

Defined in: [packages/wallets/src/wallets/stellar.ts:59](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/stellar.ts#L59)

Send a raw Stellar transaction (serialized transaction or contract call).

#### Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* `TransactionInputOptions` \| `undefined` | `undefined` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | `StellarTransactionInput` & `object` | The transaction parameters |

#### Returns

`Promise`\<[`Transaction`](../type-aliases/Transaction)\<`T` *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

The transaction result

***

### signerIsRegistered()

> **signerIsRegistered**(`signerLocator`): `Promise`\<`boolean`>

Defined in: [packages/wallets/src/wallets/wallet.ts:1193](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L1193)

Check if a signer is registered in this wallet.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `signerLocator` | `string` | The locator of the signer to check |

#### Returns

`Promise`\<`boolean`>

true if the signer is registered

#### Inherited from

[`Wallet`](./Wallet).[`signerIsRegistered`](./Wallet#signerisregistered)

***

### signers()

> **signers**(): `Promise`\<[`Signer`](../type-aliases/Signer)\[]>

Defined in: [packages/wallets/src/wallets/wallet.ts:1244](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L1244)

List the signers for this wallet.
Returns full signer objects with status.
For EVM wallets, only signers with an approval (pending or completed) for the wallet's chain are included.

#### Returns

`Promise`\<[`Signer`](../type-aliases/Signer)\[]>

The signers

#### Inherited from

[`Wallet`](./Wallet).[`signers`](./Wallet#signers)

***

### stagingFund()

> **stagingFund**(`amount`, `chain`?): `Promise`\<`FundWalletResponse`>

Defined in: [packages/wallets/src/wallets/wallet.ts:387](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L387)

Funds the wallet with Crossmint's stablecoin (USDXM).

**Note:** This method is only available in staging environments and exclusively supports USDXM tokens.
It cannot be used in production environments.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `amount` | `number` | The amount of USDXM to fund the wallet with |
| `chain`? | [`Chain`](../type-aliases/Chain) | Optional chain to fund on. If not provided, uses the wallet's default chain |

#### Returns

`Promise`\<`FundWalletResponse`>

The funding response

#### Throws

If the funding operation fails or if called in a production environment

#### Inherited from

[`Wallet`](./Wallet).[`stagingFund`](./Wallet#stagingfund)

***

### transaction()

> **transaction**(`transactionId`): `Promise`\<`WalletsTransactionV2025ResponseDtoClass`>

Defined in: [packages/wallets/src/wallets/wallet.ts:449](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L449)

Get a transaction by id

#### Parameters

| Parameter | Type |
| - | - |
| `transactionId` | `string` |

#### Returns

`Promise`\<`WalletsTransactionV2025ResponseDtoClass`>

The transaction

#### Throws

If the transaction cannot be retrieved

#### Inherited from

[`Wallet`](./Wallet).[`transaction`](./Wallet#transaction)

***

### transactions()

> **transactions**(): `Promise`\<`GetTransactionsResponse`>

Defined in: [packages/wallets/src/wallets/wallet.ts:436](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L436)

Get the wallet transactions

#### Returns

`Promise`\<`GetTransactionsResponse`>

The transactions

#### Throws

If the transactions cannot be retrieved

#### Inherited from

[`Wallet`](./Wallet).[`transactions`](./Wallet#transactions)

***

### transfers()

> **transfers**(`params`): `Promise`\<`WalletsActivityResponseUnstableDto`>

Defined in: [packages/wallets/src/wallets/wallet.ts:464](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L464)

Get the wallet transfers

#### Parameters

| Parameter | Type |
| - | - |
| `params` | \{ `status`: `"successful"` \| `"failed"`; `tokens`: `string`; } |
| `params.status` | `"successful"` \| `"failed"` |
| `params.tokens`? | `string` |

#### Returns

`Promise`\<`WalletsActivityResponseUnstableDto`>

The transfers

#### Throws

If the transfers cannot be retrieved

#### Inherited from

[`Wallet`](./Wallet).[`transfers`](./Wallet#transfers)

***

### upgrade()

> **upgrade**\<`T`>(`options`?): `Promise`\<[`Transaction`](../type-aliases/Transaction)\<`T` *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

Defined in: [packages/wallets/src/wallets/stellar.ts:116](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/stellar.ts#L116)

Upgrade this Stellar smart wallet to the latest contract version.

Stellar wallet upgrades are a two-phase on-chain process: first an `upgrade-wallet`
transaction swaps the contract bytecode (leaving the wallet temporarily locked),
then a `migrate-wallet` transaction transforms the signer storage layout and
unlocks the wallet. This method orchestrates both phases.

Idempotent: if the wallet is already locked from a previous upgrade attempt,
the phase-1 call is skipped and only the migration is executed.

#### Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* `UpgradeOptions` \| `undefined` | `undefined` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `options`? | `T` | Optional prepareOnly / signer override. When `prepareOnly` is true, returns a prepared transaction without approving it; the developer must then approve it and (if it was the phase-1 tx) call `migrate()` for phase 2. |

#### Returns

`Promise`\<[`Transaction`](../type-aliases/Transaction)\<`T` *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

* When `prepareOnly` is true and the wallet is not already locked: the prepared
  phase-1 `upgrade-wallet` transaction.
  * When `prepareOnly` is true and the wallet is already locked (idempotent path):
    the prepared phase-2 `migrate-wallet` transaction.
  * Otherwise: the confirmed migrate transaction result.

***

### useRecoveryMethod()

> **useRecoveryMethod**(`recoveryMethod`): `Promise`\<`void`>

Defined in: [packages/wallets/src/wallets/wallet.ts:1044](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L1044)

**`Experimental`**

Select which of the wallet's recovery methods authorizes admin operations ([addSigner](./#addsigner),
[removeSigner](./#removesigner), [addRecoveryMethod](./#addrecoverymethod), [removeRecoveryMethod](./#removerecoverymethod)). Unlike [useSigner](./#usesigner),
this does not change the active signer used for transactions and signatures.

The config must refer to one of [recoveryMethods](./#recoverymethods); pass the fuller form when the method needs it to
operate (an `onSign` callback for external wallets, the `secret` for server signers).

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `recoveryMethod` | [`DeviceSignerConfig`](../type-aliases/DeviceSignerConfig) \| [`EmailSignerConfig`](../type-aliases/EmailSignerConfig) \| [`PhoneSignerConfig`](../type-aliases/PhoneSignerConfig) \| `BaseSignerConfig`\<`"stellar"`> | The recovery method config object to authorize with This API is experimental and may change in the future |

#### Returns

`Promise`\<`void`>

#### Inherited from

[`Wallet`](./Wallet).[`useRecoveryMethod`](./Wallet#userecoverymethod)

***

### useSigner()

> **useSigner**(`signer`): `Promise`\<`void`>

Defined in: [packages/wallets/src/wallets/wallet.ts:1000](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L1000)

Set the active signer for this wallet.
Accepts a signer config object. The locator is inferred internally.
Works for both registered signers and the recovery signer.

For passkey signers: if no `id` is provided, the wallet will auto-select the passkey
if exactly one passkey signer is registered. If multiple passkeys exist, an `id` must be specified.

For device signers: if no device key is found locally, the signer will be created
automatically during the next transaction (via recovery).

For external-wallet signers: the config object must include an onSign callback
(applies to both registered and recovery signers).

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `signer` | [`DeviceSignerConfig`](../type-aliases/DeviceSignerConfig) \| [`EmailSignerConfig`](../type-aliases/EmailSignerConfig) \| [`PhoneSignerConfig`](../type-aliases/PhoneSignerConfig) \| `BaseSignerConfig`\<`"stellar"`> | The signer config object to use |

#### Returns

`Promise`\<`void`>

#### Inherited from

[`Wallet`](./Wallet).[`useSigner`](./Wallet#usesigner)

***

### waitForInit()

> **waitForInit**(): `Promise`\<`void`>

Defined in: [packages/wallets/src/wallets/wallet.ts:209](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L209)

Wait for the wallet's internal signer initialization to complete.
After this resolves, `needsRecovery()` reflects the true state.

#### Returns

`Promise`\<`void`>

#### Inherited from

[`Wallet`](./Wallet).[`waitForInit`](./Wallet#waitforinit)

***

### from()

> `static` **from**(`wallet`): `StellarWallet`

Defined in: [packages/wallets/src/wallets/stellar.ts:39](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/stellar.ts#L39)

#### Parameters

| Parameter | Type |
| - | - |
| `wallet` | [`Wallet`](./Wallet)\<[`Chain`](../type-aliases/Chain)> |

#### Returns

`StellarWallet`


# UnsupportedBrowserError
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/UnsupportedBrowserError



Defined in: [packages/wallets/src/utils/errors.ts:163](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/errors.ts#L163)

Thrown when the browser does not support third-party storage partitioning,
making it unsafe to store device-signer keys in IndexedDB. Consumers should
either prompt the user to upgrade their browser or fall back to a non-device
signer (e.g. recovery signer).

## Extends

* `CrossmintSDKError`

## Constructors

### new UnsupportedBrowserError()

> **new UnsupportedBrowserError**(`message`, `details`?): `UnsupportedBrowserError`

Defined in: [packages/wallets/src/utils/errors.ts:164](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/errors.ts#L164)

#### Parameters

| Parameter | Type |
| - | - |
| `message` | `string` |
| `details`? | `string` |

#### Returns

`UnsupportedBrowserError`

#### Overrides

`CrossmintSDKError.constructor`

## Properties

| Property | Modifier | Type | Description | Inherited from | Defined in |
| - | - | - | - | - | - |
|  `code` | `readonly` | `string` | - | `CrossmintSDKError.code` | packages/common/base/dist/error/index.d.ts:4 |
|  `details?` | `readonly` | `string` | - | `CrossmintSDKError.details` | packages/common/base/dist/error/index.d.ts:5 |
|  `message` | `public` | `string` | - | `CrossmintSDKError.message` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
|  `name` | `public` | `string` | - | `CrossmintSDKError.name` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
|  `stack?` | `public` | `string` | - | `CrossmintSDKError.stack` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
|  `prepareStackTrace?` | `static` | (`err`: `Error`, `stackTraces`: `CallSite`\[]) => `any` | Optional override for formatting stack traces **See** [https://v8.dev/docs/stack-trace-api#customizing-stack-traces](https://v8.dev/docs/stack-trace-api#customizing-stack-traces) | `CrossmintSDKError.prepareStackTrace` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:28 |
|  `stackTraceLimit` | `static` | `number` | - | `CrossmintSDKError.stackTraceLimit` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:30 |

## Methods

### captureStackTrace()

> `static` **captureStackTrace**(`targetObject`, `constructorOpt`?): `void`

Defined in: node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:21

Create .stack property on a target object

#### Parameters

| Parameter | Type |
| - | - |
| `targetObject` | `object` |
| `constructorOpt`? | `Function` |

#### Returns

`void`

#### Inherited from

`CrossmintSDKError.captureStackTrace`


# Wallet
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/Wallet



Defined in: [packages/wallets/src/wallets/wallet.ts:102](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L102)

## Extended by

* [`SolanaWallet`](./SolanaWallet)
* [`EVMWallet`](./EVMWallet)
* [`StellarWallet`](./StellarWallet)

## Type Parameters

| Type Parameter |
| - |
| `C` *extends* [`Chain`](../type-aliases/Chain) |

## Constructors

### new Wallet()

> **new Wallet**\<`C`>(`args`, `apiClient`): `Wallet`\<`C`>

Defined in: [packages/wallets/src/wallets/wallet.ts:117](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L117)

#### Parameters

| Parameter | Type |
| - | - |
| `args` | `WalletContructorType`\<`C`> |
| `apiClient` | [`WalletsApiClient`](./WalletsApiClient) |

#### Returns

`Wallet`\<`C`>

## Properties

| Property | Type | Defined in |
| - | - | - |
|  `address` | `string` | [packages/wallets/src/wallets/wallet.ts:104](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L104) |
|  `alias?` | `string` | [packages/wallets/src/wallets/wallet.ts:106](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L106) |
|  `chain` | `C` | [packages/wallets/src/wallets/wallet.ts:103](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L103) |
|  `owner?` | `string` | [packages/wallets/src/wallets/wallet.ts:105](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L105) |

## Accessors

### apiClient

#### Get Signature

> **get** **apiClient**(): [`WalletsApiClient`](./WalletsApiClient)

Defined in: [packages/wallets/src/wallets/wallet.ts:296](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L296)

##### Returns

[`WalletsApiClient`](./WalletsApiClient)

***

### recovery

#### Get Signature

> **get** **recovery**(): [`SignerConfigForChain`](../type-aliases/SignerConfigForChain)\<`C`>

Defined in: [packages/wallets/src/wallets/wallet.ts:321](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L321)

**`Experimental`**

Get the primary recovery signer config. Use [recoveryMethods](./#recoverymethods) for the full list on wallets
created with several recovery signers.

##### Returns

[`SignerConfigForChain`](../type-aliases/SignerConfigForChain)\<`C`>

The recovery signer config
This API is experimental and may change in the future

***

### recoveryMethods

#### Get Signature

> **get** **recoveryMethods**(): [`RecoverySignerConfigForChain`](../type-aliases/RecoverySignerConfigForChain)\<`C`>\[]

Defined in: [packages/wallets/src/wallets/wallet.ts:331](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L331)

**`Experimental`**

Get every recovery signer config of the wallet. Wallets on chains that support a single recovery
signer always return one entry.

##### Returns

[`RecoverySignerConfigForChain`](../type-aliases/RecoverySignerConfigForChain)\<`C`>\[]

The recovery signer configs
This API is experimental and may change in the future

***

### signer

#### Get Signature

> **get** **signer**(): [`SignerAdapter`](../interfaces/SignerAdapter)\<keyof `SignResultMap`> | `undefined`

Defined in: [packages/wallets/src/wallets/wallet.ts:201](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L201)

##### Returns

[`SignerAdapter`](../interfaces/SignerAdapter)\<keyof `SignResultMap`> | `undefined`

## Methods

### addRecoveryMethod()

> **addRecoveryMethod**\<`T`>(`recoveryMethod`, `options`?): `Promise`\<[`AddRecoveryMethodReturnType`](../type-aliases/AddRecoveryMethodReturnType)>

Defined in: [packages/wallets/src/wallets/wallet.ts:860](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L860)

Add a recovery method to the wallet. Supported on Solana and Stellar only.
Always uses one of the existing recovery methods to approve the change, selected as in [addSigner](./#addsigner).

#### Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* [`AddRecoveryMethodOptions`](../type-aliases/AddRecoveryMethodOptions) \| `undefined` | `undefined` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `recoveryMethod` | [`SignerConfigForChain`](../type-aliases/SignerConfigForChain)\<`C`> \| [`ServerSignerConfig`](../type-aliases/ServerSignerConfig) \| [`ExternalWalletRegistrationConfig`](../type-aliases/ExternalWalletRegistrationConfig) | The recovery method configuration object |
| `options`? | `T` | The options for the operation |

#### Returns

`Promise`\<[`AddRecoveryMethodReturnType`](../type-aliases/AddRecoveryMethodReturnType)>

***

### addSigner()

> **addSigner**\<`T`>(`signer`, `options`?): `Promise`\<`T` *extends* `PrepareOnly`\<`true`> ? `AddSignerReturnType`\<`C`> : [`Signer`](../type-aliases/Signer)>

Defined in: [packages/wallets/src/wallets/wallet.ts:649](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L649)

Add a signer to the wallet.
Always uses a recovery method internally to approve the registration: the one selected via
[useRecoveryMethod](./#userecoverymethod), else the active signer when it is one of the recovery methods, else the wallet's
single recovery method. Wallets with several recovery methods must select one first; an operational signer
cannot authorize this.
If the signer being added is the current operational signer, it will be reassembled with the new locator.
Otherwise, the original signer is restored after the operation.

#### Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* [`AddSignerOptions`](../type-aliases/AddSignerOptions) \| `undefined` | `undefined` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `signer` | [`SignerConfigForChain`](../type-aliases/SignerConfigForChain)\<`C`> \| [`ServerSignerConfig`](../type-aliases/ServerSignerConfig) \| [`ExternalWalletRegistrationConfig`](../type-aliases/ExternalWalletRegistrationConfig) | The signer configuration object |
| `options`? | `T` | The options for the operation |

#### Returns

`Promise`\<`T` *extends* `PrepareOnly`\<`true`> ? `AddSignerReturnType`\<`C`> : [`Signer`](../type-aliases/Signer)>

***

### approve()

> **approve**\<`T`>(`params`): `Promise`\<`ApproveResult`\<`T`>>

Defined in: [packages/wallets/src/wallets/wallet.ts:599](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L599)

Approve a transaction or signature

#### Type Parameters

| Type Parameter |
| - |
| `T` *extends* [`ApproveParams`](../type-aliases/ApproveParams) |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | `T` | The parameters |

#### Returns

`Promise`\<`ApproveResult`\<`T`>>

The transaction or signature

***

### ~~approveTransaction()~~

> **approveTransaction**(`params`): `Promise`\<`Error`>

Defined in: [packages/wallets/src/wallets/wallet.ts:575](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L575)

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | [`ApproveParams`](../type-aliases/ApproveParams) | The parameters |

#### Returns

`Promise`\<`Error`>

The transaction

#### Deprecated

Use `approve` instead.
Approve a transaction

***

### balances()

> **balances**(`tokens`?): `Promise`\<[`Balances`](../type-aliases/Balances)\<`C`>>

Defined in: [packages/wallets/src/wallets/wallet.ts:348](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L348)

Get the wallet balances - always includes USDC and native token (ETH/SOL)

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `tokens`? | `string`\[] | Additional tokens to request (optional: native token and usdc are always included) |

#### Returns

`Promise`\<[`Balances`](../type-aliases/Balances)\<`C`>>

The balances returns nativeToken, usdc, tokens

#### Throws

If the balances cannot be retrieved

***

### isSignerApproved()

> **isSignerApproved**(`signerLocator`): `Promise`\<`boolean`>

Defined in: [packages/wallets/src/wallets/wallet.ts:1203](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L1203)

Check if a signer is approved and usable for the current wallet chain.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `signerLocator` | `string` | The locator of the signer to check |

#### Returns

`Promise`\<`boolean`>

true if the signer is approved for this chain, false if it is not approved or not registered

#### Throws

if the approval state could not be fetched

***

### needsRecovery()

> **needsRecovery**(): `boolean`

Defined in: [packages/wallets/src/wallets/wallet.ts:1211](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L1211)

Whether the wallet needs recovery (signer registration) before the next transaction.

#### Returns

`boolean`

true if recovery is needed

***

### nfts()

> **nfts**(`params`): `Promise`\<`unknown`>

Defined in: [packages/wallets/src/wallets/wallet.ts:417](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L417)

Get the wallet NFTs

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | \{ `page`: `number`; `perPage`: `number`; } | The parameters |
| `params.page` | `number` | The page number |
| `params.perPage` | `number` | The number of NFTs per page |

#### Returns

`Promise`\<`unknown`>

The NFTs

***

### recover()

> **recover**(): `Promise`\<`void`>

Defined in: [packages/wallets/src/wallets/wallet.ts:1227](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L1227)

Register a device signer with the wallet using the recovery signer.
Generates a new device key and registers it on-chain.
Returns early if the device signer's locator is already approved on-chain.

#### Returns

`Promise`\<`void`>

***

### removeRecoveryMethod()

> **removeRecoveryMethod**\<`T`>(`recoveryMethod`, `options`?): `Promise`\<[`RemoveRecoveryMethodReturnType`](../type-aliases/RemoveRecoveryMethodReturnType)>

Defined in: [packages/wallets/src/wallets/wallet.ts:927](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L927)

Remove a recovery method from the wallet. Supported on Solana and Stellar only.
Always uses one of the remaining recovery methods to approve the change, selected as in [addSigner](./#addsigner).

#### Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* [`RemoveRecoveryMethodOptions`](../type-aliases/RemoveRecoveryMethodOptions) \| `undefined` | `undefined` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `recoveryMethod` | [`SignerConfigForChain`](../type-aliases/SignerConfigForChain)\<`C`> \| [`ExternalWalletRegistrationConfig`](../type-aliases/ExternalWalletRegistrationConfig) | The recovery method to remove, provided as a signer config object |
| `options`? | `T` | The options for the operation |

#### Returns

`Promise`\<[`RemoveRecoveryMethodReturnType`](../type-aliases/RemoveRecoveryMethodReturnType)>

***

### removeSigner()

> **removeSigner**\<`T`>(`signer`, `options`?): `Promise`\<`RemoveSignerReturnType`>

Defined in: [packages/wallets/src/wallets/wallet.ts:810](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L810)

Remove a signer from the wallet.
Always uses a recovery method internally to approve the removal, selected as in [addSigner](./#addsigner).

#### Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* [`RemoveSignerOptions`](../type-aliases/RemoveSignerOptions) \| `undefined` | `undefined` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `signer` | [`SignerConfigForChain`](../type-aliases/SignerConfigForChain)\<`C`> \| [`ExternalWalletRegistrationConfig`](../type-aliases/ExternalWalletRegistrationConfig) | The signer to remove, provided as a signer config object |
| `options`? | `T` | The options for the operation |

#### Returns

`Promise`\<`RemoveSignerReturnType`>

***

### send()

> **send**\<`T`>(`to`, `token`, `amount`, `options`?): `Promise`\<[`Transaction`](../type-aliases/Transaction)\<`T` *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

Defined in: [packages/wallets/src/wallets/wallet.ts:492](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L492)

Send a token to a wallet or user locator

#### Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* `SendTokenTransactionOptions` \| `undefined` | `undefined` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `to` | `string` \| `UserLocator` | The recipient (address or user locator) |
| `token` | `string` | The token (address or currency symbol) |
| `amount` | `string` | The amount to send (decimal units) |
| `options`? | `T` | The options for the transaction |

#### Returns

`Promise`\<[`Transaction`](../type-aliases/Transaction)\<`T` *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

The transaction

***

### signerIsRegistered()

> **signerIsRegistered**(`signerLocator`): `Promise`\<`boolean`>

Defined in: [packages/wallets/src/wallets/wallet.ts:1193](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L1193)

Check if a signer is registered in this wallet.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `signerLocator` | `string` | The locator of the signer to check |

#### Returns

`Promise`\<`boolean`>

true if the signer is registered

***

### signers()

> **signers**(): `Promise`\<[`Signer`](../type-aliases/Signer)\[]>

Defined in: [packages/wallets/src/wallets/wallet.ts:1244](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L1244)

List the signers for this wallet.
Returns full signer objects with status.
For EVM wallets, only signers with an approval (pending or completed) for the wallet's chain are included.

#### Returns

`Promise`\<[`Signer`](../type-aliases/Signer)\[]>

The signers

***

### stagingFund()

> **stagingFund**(`amount`, `chain`?): `Promise`\<`FundWalletResponse`>

Defined in: [packages/wallets/src/wallets/wallet.ts:387](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L387)

Funds the wallet with Crossmint's stablecoin (USDXM).

**Note:** This method is only available in staging environments and exclusively supports USDXM tokens.
It cannot be used in production environments.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `amount` | `number` | The amount of USDXM to fund the wallet with |
| `chain`? | [`Chain`](../type-aliases/Chain) | Optional chain to fund on. If not provided, uses the wallet's default chain |

#### Returns

`Promise`\<`FundWalletResponse`>

The funding response

#### Throws

If the funding operation fails or if called in a production environment

***

### transaction()

> **transaction**(`transactionId`): `Promise`\<`WalletsTransactionV2025ResponseDtoClass`>

Defined in: [packages/wallets/src/wallets/wallet.ts:449](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L449)

Get a transaction by id

#### Parameters

| Parameter | Type |
| - | - |
| `transactionId` | `string` |

#### Returns

`Promise`\<`WalletsTransactionV2025ResponseDtoClass`>

The transaction

#### Throws

If the transaction cannot be retrieved

***

### transactions()

> **transactions**(): `Promise`\<`GetTransactionsResponse`>

Defined in: [packages/wallets/src/wallets/wallet.ts:436](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L436)

Get the wallet transactions

#### Returns

`Promise`\<`GetTransactionsResponse`>

The transactions

#### Throws

If the transactions cannot be retrieved

***

### transfers()

> **transfers**(`params`): `Promise`\<`WalletsActivityResponseUnstableDto`>

Defined in: [packages/wallets/src/wallets/wallet.ts:464](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L464)

Get the wallet transfers

#### Parameters

| Parameter | Type |
| - | - |
| `params` | \{ `status`: `"successful"` \| `"failed"`; `tokens`: `string`; } |
| `params.status` | `"successful"` \| `"failed"` |
| `params.tokens`? | `string` |

#### Returns

`Promise`\<`WalletsActivityResponseUnstableDto`>

The transfers

#### Throws

If the transfers cannot be retrieved

***

### useRecoveryMethod()

> **useRecoveryMethod**(`recoveryMethod`): `Promise`\<`void`>

Defined in: [packages/wallets/src/wallets/wallet.ts:1044](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L1044)

**`Experimental`**

Select which of the wallet's recovery methods authorizes admin operations ([addSigner](./#addsigner),
[removeSigner](./#removesigner), [addRecoveryMethod](./#addrecoverymethod), [removeRecoveryMethod](./#removerecoverymethod)). Unlike [useSigner](./#usesigner),
this does not change the active signer used for transactions and signatures.

The config must refer to one of [recoveryMethods](./#recoverymethods); pass the fuller form when the method needs it to
operate (an `onSign` callback for external wallets, the `secret` for server signers).

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `recoveryMethod` | [`SignerConfigForChain`](../type-aliases/SignerConfigForChain)\<`C`> | The recovery method config object to authorize with This API is experimental and may change in the future |

#### Returns

`Promise`\<`void`>

***

### useSigner()

> **useSigner**(`signer`): `Promise`\<`void`>

Defined in: [packages/wallets/src/wallets/wallet.ts:1000](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L1000)

Set the active signer for this wallet.
Accepts a signer config object. The locator is inferred internally.
Works for both registered signers and the recovery signer.

For passkey signers: if no `id` is provided, the wallet will auto-select the passkey
if exactly one passkey signer is registered. If multiple passkeys exist, an `id` must be specified.

For device signers: if no device key is found locally, the signer will be created
automatically during the next transaction (via recovery).

For external-wallet signers: the config object must include an onSign callback
(applies to both registered and recovery signers).

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `signer` | [`SignerConfigForChain`](../type-aliases/SignerConfigForChain)\<`C`> | The signer config object to use |

#### Returns

`Promise`\<`void`>

***

### waitForInit()

> **waitForInit**(): `Promise`\<`void`>

Defined in: [packages/wallets/src/wallets/wallet.ts:209](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L209)

Wait for the wallet's internal signer initialization to complete.
After this resolves, `needsRecovery()` reflects the true state.

#### Returns

`Promise`\<`void`>


# WalletNotAvailableError
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/WalletNotAvailableError



Defined in: [packages/wallets/src/utils/errors.ts:43](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/errors.ts#L43)

## Extends

* `CrossmintSDKError`

## Constructors

### new WalletNotAvailableError()

> **new WalletNotAvailableError**(`message`, `details`?): `WalletNotAvailableError`

Defined in: [packages/wallets/src/utils/errors.ts:44](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/errors.ts#L44)

#### Parameters

| Parameter | Type |
| - | - |
| `message` | `string` |
| `details`? | `string` |

#### Returns

`WalletNotAvailableError`

#### Overrides

`CrossmintSDKError.constructor`

## Properties

| Property | Modifier | Type | Description | Inherited from | Defined in |
| - | - | - | - | - | - |
|  `code` | `readonly` | `string` | - | `CrossmintSDKError.code` | packages/common/base/dist/error/index.d.ts:4 |
|  `details?` | `readonly` | `string` | - | `CrossmintSDKError.details` | packages/common/base/dist/error/index.d.ts:5 |
|  `message` | `public` | `string` | - | `CrossmintSDKError.message` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1077 |
|  `name` | `public` | `string` | - | `CrossmintSDKError.name` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
|  `stack?` | `public` | `string` | - | `CrossmintSDKError.stack` | node\_modules/.pnpm/typescript\@5.5.3/node\_modules/typescript/lib/lib.es5.d.ts:1078 |
|  `prepareStackTrace?` | `static` | (`err`: `Error`, `stackTraces`: `CallSite`\[]) => `any` | Optional override for formatting stack traces **See** [https://v8.dev/docs/stack-trace-api#customizing-stack-traces](https://v8.dev/docs/stack-trace-api#customizing-stack-traces) | `CrossmintSDKError.prepareStackTrace` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:28 |
|  `stackTraceLimit` | `static` | `number` | - | `CrossmintSDKError.stackTraceLimit` | node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:30 |

## Methods

### captureStackTrace()

> `static` **captureStackTrace**(`targetObject`, `constructorOpt`?): `void`

Defined in: node\_modules/.pnpm/@types+node\@20.14.8/node\_modules/@types/node/globals.d.ts:21

Create .stack property on a target object

#### Parameters

| Parameter | Type |
| - | - |
| `targetObject` | `object` |
| `constructorOpt`? | `Function` |

#### Returns

`void`

#### Inherited from

`CrossmintSDKError.captureStackTrace`


# WalletsApiClient
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/classes/WalletsApiClient



Defined in: [packages/wallets/src/api/client.ts:47](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L47)

## Extends

* `CrossmintApiClient`

## Constructors

### new WalletsApiClient()

> **new WalletsApiClient**(`crossmint`): `ApiClient`

Defined in: [packages/wallets/src/api/client.ts:51](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L51)

#### Parameters

| Parameter | Type |
| - | - |
| `crossmint` | `Crossmint` |

#### Returns

`ApiClient`

#### Overrides

`CrossmintApiClient.constructor`

## Properties

| Property | Type | Inherited from | Defined in |
| - | - | - | - |
|  `crossmint` | `Crossmint` | `CrossmintApiClient.crossmint` | packages/common/base/dist/apiClient/CrossmintApiClient.d.ts:15 |

## Accessors

### baseUrl

#### Get Signature

> **get** **baseUrl**(): `string`

Defined in: packages/common/base/dist/apiClient/CrossmintApiClient.d.ts:21

##### Returns

`string`

#### Inherited from

`CrossmintApiClient.baseUrl`

***

### commonHeaders

#### Get Signature

> **get** **commonHeaders**(): `object`

Defined in: packages/common/base/dist/apiClient/CrossmintApiClient.d.ts:22

##### Returns

`object`

###### Authorization?

> `optional` **Authorization**: `string`

###### x-api-key

> **x-api-key**: `string`

###### x-app-identifier?

> `optional` **x-app-identifier**: `string`

###### x-client-name

> **x-client-name**: `string`

###### x-client-version

> **x-client-version**: `string`

###### x-extension-id?

> `optional` **x-extension-id**: `string`

#### Inherited from

`CrossmintApiClient.commonHeaders`

***

### environment

#### Get Signature

> **get** **environment**(): `APIKeyEnvironmentPrefix`

Defined in: [packages/wallets/src/api/client.ts:348](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L348)

##### Returns

`APIKeyEnvironmentPrefix`

#### Overrides

`CrossmintApiClient.environment`

***

### isServerSide

#### Get Signature

> **get** **isServerSide**(): `boolean`

Defined in: [packages/wallets/src/api/client.ts:344](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L344)

##### Returns

`boolean`

***

### projectId

#### Get Signature

> **get** **projectId**(): `string`

Defined in: [packages/wallets/src/api/client.ts:355](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L355)

##### Returns

`string`

## Methods

### approveSignature()

> **approveSignature**(`walletLocator`, `signatureId`, `params`): `Promise`\<`ApproveSignatureResponse`>

Defined in: [packages/wallets/src/api/client.ts:146](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L146)

#### Parameters

| Parameter | Type |
| - | - |
| `walletLocator` | `string` |
| `signatureId` | `string` |
| `params` | `SubmitApprovalV2025Dto` |

#### Returns

`Promise`\<`ApproveSignatureResponse`>

***

### approveTransaction()

> **approveTransaction**(`walletLocator`, `transactionId`, `params`): `Promise`\<`ApproveTransactionResponse`>

Defined in: [packages/wallets/src/api/client.ts:116](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L116)

#### Parameters

| Parameter | Type |
| - | - |
| `walletLocator` | `string` |
| `transactionId` | `string` |
| `params` | `SubmitApprovalV2025Dto` |

#### Returns

`Promise`\<`ApproveTransactionResponse`>

***

### buildUrl()

> **buildUrl**(`path`): `string`

Defined in: packages/common/base/dist/apiClient/ApiClient.d.ts:11

#### Parameters

| Parameter | Type |
| - | - |
| `path` | `string` |

#### Returns

`string`

#### Inherited from

`CrossmintApiClient.buildUrl`

***

### createSignature()

> **createSignature**(`walletLocator`, `params`): `Promise`\<`CreateSignatureResponse`>

Defined in: [packages/wallets/src/api/client.ts:135](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L135)

#### Parameters

| Parameter | Type |
| - | - |
| `walletLocator` | `string` |
| `params` | `CreateSignatureV2025Dto` |

#### Returns

`Promise`\<`CreateSignatureResponse`>

***

### createTransaction()

> **createTransaction**(`walletLocator`, `params`): `Promise`\<`CreateTransactionResponse`>

Defined in: [packages/wallets/src/api/client.ts:105](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L105)

#### Parameters

| Parameter | Type |
| - | - |
| `walletLocator` | `string` |
| `params` | `CreateTransactionV2025DtoClass` |

#### Returns

`Promise`\<`CreateTransactionResponse`>

***

### createWallet()

> **createWallet**(`params`): `Promise`\<`CreateWalletResponse`>

Defined in: [packages/wallets/src/api/client.ts:59](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L59)

#### Parameters

| Parameter | Type |
| - | - |
| `params` | `CreateWalletV2025DtoClass` |

#### Returns

`Promise`\<`CreateWalletResponse`>

***

### delete()

> **delete**(`path`, `params`): `Promise`\<`Response`>

Defined in: packages/common/base/dist/apiClient/ApiClient.d.ts:15

#### Parameters

| Parameter | Type |
| - | - |
| `path` | `string` |
| `params` | `Omit`\<`RequestInit`, `"method"`> |

#### Returns

`Promise`\<`Response`>

#### Inherited from

`CrossmintApiClient.delete`

***

### fundWallet()

> **fundWallet**(`walletLocator`, `params`): `Promise`\<`FundWalletResponse`>

Defined in: [packages/wallets/src/api/client.ts:228](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L228)

#### Parameters

| Parameter | Type |
| - | - |
| `walletLocator` | `string` |
| `params` | `FundWalletAmountDto` |

#### Returns

`Promise`\<`FundWalletResponse`>

***

### get()

> **get**(`path`, `params`): `Promise`\<`Response`>

Defined in: packages/common/base/dist/apiClient/ApiClient.d.ts:12

#### Parameters

| Parameter | Type |
| - | - |
| `path` | `string` |
| `params` | `Omit`\<`RequestInit`, `"method"`> |

#### Returns

`Promise`\<`Response`>

#### Inherited from

`CrossmintApiClient.get`

***

### getBalance()

> **getBalance**(`walletLocator`, `params`): `Promise`\<`GetBalanceResponse`>

Defined in: [packages/wallets/src/api/client.ts:212](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L212)

#### Parameters

| Parameter | Type |
| - | - |
| `walletLocator` | `string` |
| `params` | \{ `chains`: [`Chain`](../type-aliases/Chain)\[]; `tokens`: `string`\[]; } |
| `params.chains` | [`Chain`](../type-aliases/Chain)\[] |
| `params.tokens` | `string`\[] |

#### Returns

`Promise`\<`GetBalanceResponse`>

***

### getNfts()

> **getNfts**(`params`): `Promise`\<`unknown`>

Defined in: [packages/wallets/src/api/client.ts:177](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L177)

#### Parameters

| Parameter | Type |
| - | - |
| `params` | \{ `address`: `string`; `chain`: `string`; `page`: `number`; `perPage`: `number`; } |
| `params.address` | `string` |
| `params.chain` | `string` |
| `params.page` | `number` |
| `params.perPage` | `number` |

#### Returns

`Promise`\<`unknown`>

***

### getSignature()

> **getSignature**(`walletLocator`, `signatureId`): `Promise`\<`GetSignatureResponse`>

Defined in: [packages/wallets/src/api/client.ts:163](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L163)

#### Parameters

| Parameter | Type |
| - | - |
| `walletLocator` | `string` |
| `signatureId` | `string` |

#### Returns

`Promise`\<`GetSignatureResponse`>

***

### getSigner()

> **getSigner**(`walletLocator`, `signer`): `Promise`\<`GetSignerResponse`>

Defined in: [packages/wallets/src/api/client.ts:298](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L298)

#### Parameters

| Parameter | Type |
| - | - |
| `walletLocator` | `string` |
| `signer` | `string` |

#### Returns

`Promise`\<`GetSignerResponse`>

***

### getTransaction()

> **getTransaction**(`walletLocator`, `transactionId`): `Promise`\<`GetTransactionResponse`>

Defined in: [packages/wallets/src/api/client.ts:128](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L128)

#### Parameters

| Parameter | Type |
| - | - |
| `walletLocator` | `string` |
| `transactionId` | `string` |

#### Returns

`Promise`\<`GetTransactionResponse`>

***

### getTransactions()

> **getTransactions**(`walletLocator`): `Promise`\<`GetTransactionsResponse`>

Defined in: [packages/wallets/src/api/client.ts:170](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L170)

#### Parameters

| Parameter | Type |
| - | - |
| `walletLocator` | `string` |

#### Returns

`Promise`\<`GetTransactionsResponse`>

***

### getTransfers()

> **getTransfers**(`walletLocator`, `params`): `Promise`\<`GetTransfersResponse`>

Defined in: [packages/wallets/src/api/client.ts:193](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L193)

#### Parameters

| Parameter | Type |
| - | - |
| `walletLocator` | `string` |
| `params` | \{ `chain`: [`Chain`](../type-aliases/Chain); `status`: `"successful"` \| `"failed"`; `tokens`: `string`; } |
| `params.chain` | [`Chain`](../type-aliases/Chain) |
| `params.status` | `"successful"` \| `"failed"` |
| `params.tokens`? | `string` |

#### Returns

`Promise`\<`GetTransfersResponse`>

***

### getWallet()

> **getWallet**(`locator`): `Promise`\<`GetWalletResponse`>

Defined in: [packages/wallets/src/api/client.ts:85](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L85)

#### Parameters

| Parameter | Type |
| - | - |
| `locator` | `string` |

#### Returns

`Promise`\<`GetWalletResponse`>

***

### patch()

> **patch**(`path`, `params`): `Promise`\<`Response`>

Defined in: packages/common/base/dist/apiClient/ApiClient.d.ts:16

#### Parameters

| Parameter | Type |
| - | - |
| `path` | `string` |
| `params` | `Omit`\<`RequestInit`, `"method"`> |

#### Returns

`Promise`\<`Response`>

#### Inherited from

`CrossmintApiClient.patch`

***

### post()

> **post**(`path`, `params`): `Promise`\<`Response`>

Defined in: packages/common/base/dist/apiClient/ApiClient.d.ts:13

#### Parameters

| Parameter | Type |
| - | - |
| `path` | `string` |
| `params` | `Omit`\<`RequestInit`, `"method"`> |

#### Returns

`Promise`\<`Response`>

#### Inherited from

`CrossmintApiClient.post`

***

### put()

> **put**(`path`, `params`): `Promise`\<`Response`>

Defined in: packages/common/base/dist/apiClient/ApiClient.d.ts:14

#### Parameters

| Parameter | Type |
| - | - |
| `path` | `string` |
| `params` | `Omit`\<`RequestInit`, `"method"`> |

#### Returns

`Promise`\<`Response`>

#### Inherited from

`CrossmintApiClient.put`

***

### registerRecoveryMethod()

> **registerRecoveryMethod**(`walletLocator`, `params`): `Promise`\<`RegisterRecoveryMethodResponse`>

Defined in: [packages/wallets/src/api/client.ts:267](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L267)

#### Parameters

| Parameter | Type |
| - | - |
| `walletLocator` | `string` |
| `params` | `RegisterRecoveryMethodParams` |

#### Returns

`Promise`\<`RegisterRecoveryMethodResponse`>

***

### registerSigner()

> **registerSigner**(`walletLocator`, `params`): `Promise`\<`RegisterSignerResponse`>

Defined in: [packages/wallets/src/api/client.ts:239](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L239)

#### Parameters

| Parameter | Type |
| - | - |
| `walletLocator` | `string` |
| `params` | `RegisterSignerParams` |

#### Returns

`Promise`\<`RegisterSignerResponse`>

***

### removeRecoveryMethod()

> **removeRecoveryMethod**(`walletLocator`, `signer`, `params`): `Promise`\<`RemoveRecoveryMethodResponse`>

Defined in: [packages/wallets/src/api/client.ts:278](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L278)

#### Parameters

| Parameter | Type |
| - | - |
| `walletLocator` | `string` |
| `signer` | `string` |
| `params` | `RemoveRecoveryMethodParams` |

#### Returns

`Promise`\<`RemoveRecoveryMethodResponse`>

***

### removeSigner()

> **removeSigner**(`walletLocator`, `signer`, `params`): `Promise`\<`RemoveSignerResponse`>

Defined in: [packages/wallets/src/api/client.ts:247](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L247)

#### Parameters

| Parameter | Type |
| - | - |
| `walletLocator` | `string` |
| `signer` | `string` |
| `params` | `RemoveSignerParams` |

#### Returns

`Promise`\<`RemoveSignerResponse`>

***

### send()

> **send**(`walletLocator`, `tokenLocator`, `params`): `Promise`\<`WalletsV1Alpha2TransactionResponseWithSendParamsDtoClass`>

Defined in: [packages/wallets/src/api/client.ts:318](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L318)

#### Parameters

| Parameter | Type |
| - | - |
| `walletLocator` | `string` |
| `tokenLocator` | `string` |
| `params` | `SendTokenDto` |

#### Returns

`Promise`\<`WalletsV1Alpha2TransactionResponseWithSendParamsDtoClass`>

***

### normalizePath()

> `static` **normalizePath**(`path`): `string`

Defined in: packages/common/base/dist/apiClient/ApiClient.d.ts:17

#### Parameters

| Parameter | Type |
| - | - |
| `path` | `string` |

#### Returns

`string`

#### Inherited from

`CrossmintApiClient.normalizePath`


# createCrossmint
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/functions/createCrossmint



> **createCrossmint**(`config`, `apiKeyExpectations`?): `Crossmint`

Defined in: packages/common/base/dist/types/Crossmint.d.ts:19

## Parameters

| Parameter | Type |
| - | - |
| `config` | `CrossmintConfig` |
| `apiKeyExpectations`? | `ValidateAPIKeyPrefixExpectations` |

## Returns

`Crossmint`


# createDeviceSigner
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/functions/createDeviceSigner



> **createDeviceSigner**(`deviceKeyStorage`, `address`?): `Promise`\<`DeviceSignerConfig`>

Defined in: [packages/wallets/src/utils/device-signers/createDeviceSigner.ts:18](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/device-signers/createDeviceSigner.ts#L18)

Creates a device signer by generating a new P-256 key pair via the provided key storage.

## Parameters

| Parameter | Type | Description |
| - | - | - |
| `deviceKeyStorage` | [`DeviceSignerKeyStorage`](../classes/DeviceSignerKeyStorage) | The device key storage implementation to use for key generation. |
| `address`? | `string` | Optional address of the wallet to associate the device signer with. |

## Returns

`Promise`\<`DeviceSignerConfig`>

A device signer descriptor containing the type, public key coordinates, and locator.

## Example

```ts theme={null}
const signer = await createDeviceSigner(deviceKeyStorage);
// signer = { type: "device", publicKey: { x, y }, locator: "device:<pubkey64>" }
```


# createServerSigner
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/functions/createServerSigner



> **createServerSigner**(`params`): [`ServerSigner`](../type-aliases/ServerSigner)

Defined in: [packages/wallets/src/utils/server-signers/createServerSigner.ts:41](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/server-signers/createServerSigner.ts#L41)

Creates a server signer by deriving a chain-specific key pair from a master secret using HKDF-SHA256.

The derivation is deterministic: same inputs always produce the same signer.

## Parameters

| Parameter | Type |
| - | - |
| `params` | [`CreateServerSignerParams`](../type-aliases/CreateServerSignerParams) |

## Returns

[`ServerSigner`](../type-aliases/ServerSigner)

A server signer containing the type, derived address, and key bytes.

## Example

```ts theme={null}
const signer = createServerSigner({
    secret: "xmsk1_abc123...",
    chain: "base-sepolia",
    projectId: "project-id",
    environment: "staging",
});
// signer = { type: "server", address: "0x...", keyBytes: Uint8Array }
```


# isExportableSignerAdapter
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/functions/isExportableSignerAdapter



> **isExportableSignerAdapter**(`signer`): `signer is ExportableSignerAdapter`

Defined in: [packages/wallets/src/signers/types.ts:297](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L297)

## Parameters

| Parameter | Type |
| - | - |
| `signer` | [`SignerAdapter`](../interfaces/SignerAdapter) |

## Returns

`signer is ExportableSignerAdapter`


# recoveryMethodsFromCreateArgs
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/functions/recoveryMethodsFromCreateArgs



> **recoveryMethodsFromCreateArgs**\<`C`>(`args`): `RecoverySignerConfigFor`\<`C`>\[]

Defined in: [packages/wallets/src/utils/recovery.ts:13](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/recovery.ts#L13)

Reads and normalizes the recovery methods from creation args.

`recoveryMethods` is the source of truth. The deprecated `recovery` is routed to it: a single method becomes a
one-entry list, and a list is used as is, so pre-1.17 callers keep working.

## Type Parameters

| Type Parameter |
| - |
| `C` *extends* [`Chain`](../type-aliases/Chain) |

## Parameters

| Parameter | Type |
| - | - |
| `args` | `Pick`\<[`WalletCreateArgs`](../type-aliases/WalletCreateArgs)\<`C`>, `"recovery"` \| `"recoveryMethods"`> |

## Returns

`RecoverySignerConfigFor`\<`C`>\[]


# ExportableSignerAdapter
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/interfaces/ExportableSignerAdapter



Defined in: [packages/wallets/src/signers/types.ts:290](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L290)

## Extends

* [`SignerAdapter`](./SignerAdapter)

## Properties

### \_exportPrivateKey()

> **\_exportPrivateKey**: (`exportTEEConnection`, `onExport`?) => `Promise`\<`void`>

Defined in: [packages/wallets/src/signers/types.ts:291](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L291)

#### Parameters

| Parameter | Type |
| - | - |
| `exportTEEConnection` | [`ExportSignerTEEConnection`](../type-aliases/ExportSignerTEEConnection) |
| `onExport`? | () => `void` \| `Promise`\<`void`> |

#### Returns

`Promise`\<`void`>

***

### status?

> `optional` **status**: `any`

Defined in: [packages/wallets/src/signers/types.ts:283](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L283)

#### Inherited from

[`ExportableSignerAdapter`](./).[`status`](./#status)

***

### type

> **type**: keyof `SignResultMap`

Defined in: [packages/wallets/src/signers/types.ts:282](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L282)

#### Inherited from

[`SignerAdapter`](./SignerAdapter).[`type`](./SignerAdapter#type)

## Methods

### address()?

> `optional` **address**(): `string`

Defined in: [packages/wallets/src/signers/types.ts:285](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L285)

#### Returns

`string`

#### Inherited from

[`SignerAdapter`](./SignerAdapter).[`address`](./SignerAdapter#address)

***

### locator()

> **locator**(): [`SignerLocator`](../type-aliases/SignerLocator)

Defined in: [packages/wallets/src/signers/types.ts:284](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L284)

#### Returns

[`SignerLocator`](../type-aliases/SignerLocator)

#### Inherited from

[`SignerAdapter`](./SignerAdapter).[`locator`](./SignerAdapter#locator)

***

### signMessage()

> **signMessage**(`message`): `Promise`\<`BaseSignResult` | `PasskeySignResult` | `DeviceSignResult`>

Defined in: [packages/wallets/src/signers/types.ts:286](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L286)

#### Parameters

| Parameter | Type |
| - | - |
| `message` | `string` |

#### Returns

`Promise`\<`BaseSignResult` | `PasskeySignResult` | `DeviceSignResult`>

#### Inherited from

[`SignerAdapter`](./SignerAdapter).[`signMessage`](./SignerAdapter#signmessage)

***

### signTransaction()

> **signTransaction**(`transaction`): `Promise`\<`BaseSignResult` | `PasskeySignResult` | `DeviceSignResult`>

Defined in: [packages/wallets/src/signers/types.ts:287](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L287)

#### Parameters

| Parameter | Type |
| - | - |
| `transaction` | `string` |

#### Returns

`Promise`\<`BaseSignResult` | `PasskeySignResult` | `DeviceSignResult`>

#### Inherited from

[`SignerAdapter`](./SignerAdapter).[`signTransaction`](./SignerAdapter#signtransaction)


# SignerAdapter
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/interfaces/SignerAdapter



Defined in: [packages/wallets/src/signers/types.ts:281](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L281)

## Extended by

* [`ExportableSignerAdapter`](./ExportableSignerAdapter)

## Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* keyof `SignResultMap` | keyof `SignResultMap` |

## Properties

### status?

> `optional` **status**: `any`

Defined in: [packages/wallets/src/signers/types.ts:283](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L283)

***

### type

> **type**: `T`

Defined in: [packages/wallets/src/signers/types.ts:282](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L282)

## Methods

### address()?

> `optional` **address**(): `string`

Defined in: [packages/wallets/src/signers/types.ts:285](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L285)

#### Returns

`string`

***

### locator()

> **locator**(): [`SignerLocator`](../type-aliases/SignerLocator)

Defined in: [packages/wallets/src/signers/types.ts:284](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L284)

#### Returns

[`SignerLocator`](../type-aliases/SignerLocator)

***

### signMessage()

> **signMessage**(`message`): `Promise`\<`SignResultMap`\[`T`]>

Defined in: [packages/wallets/src/signers/types.ts:286](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L286)

#### Parameters

| Parameter | Type |
| - | - |
| `message` | `string` |

#### Returns

`Promise`\<`SignResultMap`\[`T`]>

***

### signTransaction()

> **signTransaction**(`transaction`): `Promise`\<`SignResultMap`\[`T`]>

Defined in: [packages/wallets/src/signers/types.ts:287](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L287)

#### Parameters

| Parameter | Type |
| - | - |
| `transaction` | `string` |

#### Returns

`Promise`\<`SignResultMap`\[`T`]>


# Getting Started
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/overview



### Latest Node.js SDK version - <a href="https://www.npmjs.com/package/@crossmint/wallets-sdk"><img alt="npm" /></a>

Typescript SDK (`@crossmint/wallets-sdk`) for creating and managing [Crossmint Wallets](https://docs.crossmint.com) on EVM, Solana, and Stellar chains.

## Prerequisites

Get a Crossmint API key from the [developer console](https://docs.crossmint.com/introduction/platform/api-keys). Ensure your key has the **Wallet API** scopes enabled.

* **Client-side** (browser): Use a client API key
* **Server-side** (Node.js): Use a server API key

## Installation

```bash theme={null}
npm install @crossmint/wallets-sdk
# or
pnpm add @crossmint/wallets-sdk
# or
yarn add @crossmint/wallets-sdk
```

## Quick Start

### Server-side (Node.js)

```ts theme={null}
import { createCrossmint, CrossmintWallets } from "@crossmint/wallets-sdk";

const crossmint = createCrossmint({ apiKey: "YOUR_SERVER_API_KEY" });
const wallets = CrossmintWallets.from(crossmint);

// Create a wallet with a server signer
const wallet = await wallets.createWallet({
  chain: "base-sepolia",
  recoveryMethods: [{ type: "server", secret: "RECOVERY_SECRET" }],
});

console.log(wallet.address);

// Send tokens
const tx = await wallet.send("0xRecipientAddress", "usdc", "10");
console.log(tx.explorerLink);
```

### Client-side (Headless)

For client-side usage without React, you can use the SDK directly with JWT authentication:

```ts theme={null}
import { createCrossmint, CrossmintWallets } from "@crossmint/wallets-sdk";

const crossmint = createCrossmint({ apiKey: "YOUR_CLIENT_API_KEY" });
crossmint.setJwt("USER_JWT");

const wallets = CrossmintWallets.from(crossmint);

const wallet = await wallets.getWallet({ chain: "base-sepolia" });
console.log(wallet.address);
```

> For React apps, use [`@crossmint/client-sdk-react-ui`](https://www.npmjs.com/package/@crossmint/client-sdk-react-ui) which provides `CrossmintWalletProvider`, hooks, and built-in UI for OTP and passkey flows.

## Creating a Wallet

### Server signer

Create a wallet with a server key as a recovery method:

```ts theme={null}
import { createCrossmint, CrossmintWallets } from "@crossmint/wallets-sdk";

const crossmint = createCrossmint({ apiKey: "YOUR_SERVER_API_KEY" });
const wallets = CrossmintWallets.from(crossmint);

const wallet = await wallets.createWallet({
  chain: "base-sepolia",
  recoveryMethods: [{ type: "server", secret: "RECOVERY_SECRET" }],
});

console.log(wallet.address);
```

### External wallet signer

Bring your own key (MetaMask, KMS, etc.):

```ts theme={null}
const wallet = await wallets.createWallet({
  chain: "base-sepolia",
  recoveryMethods: [
    {
      type: "external-wallet",
      address: "0xYourWalletAddress",
      onSign: async (message: string) => {
        // Sign the message with your wallet/KMS and return the signature
        return await yourWallet.signMessage({ message: { raw: message as `0x${string}` } });
      },
    },
  ],
});
```

### Device signer (browser / React Native)

Device signers use hardware-backed P256 keys for frictionless client-side signing. They must be created on the client and can be passed to the server at wallet creation time:

```ts theme={null}
// Client: generate a device signer descriptor
const { createDeviceSigner } = useWallet();
const deviceSigner = await createDeviceSigner();
// Send deviceSigner to your server
```

```ts theme={null}
// Server: create the wallet with the device signer pre-registered
const wallet = await wallets.createWallet({
  chain: "base-sepolia",
  owner: "email:user@example.com",
  recoveryMethods: [{ type: "email", email: "user@example.com" }],
  signers: [deviceSigner],
});
```

> Device signers are **browser and React Native only** — not available in Node.js. See the [Server-Side Wallet with Device Signer](https://docs.crossmint.com/wallets/guides/signers/device-signer-server-wallet) guide for the full pattern.

### Retrieving an existing wallet

```ts theme={null}
// Client-side
const wallet = await wallets.getWallet({ chain: "base-sepolia" });
```

```ts theme={null}
// Server-side — requires a wallet locator
const wallet = await wallets.getWallet("0xWalletAddress", {
  chain: "base-sepolia",
});
```

## Core Concepts

### Signers

Wallets SDK uses a two-tier signer model:

* **Recovery method** — High-security, used for wallet recovery and adding new signers. Supports email OTP, phone OTP, external wallet, or server key.
* **Operational signer** — Low-friction, used for day-to-day signing. Supports server key, external wallet, passkey, and device (browser/mobile only). For server-side (Node.js) usage, use a **server** or **external-wallet** signer.

When no operational signer is available, the recovery method automatically serves as a fallback for signing.

## Usage

### Balances

```ts theme={null}
const balances = await wallet.balances();

console.log(balances.nativeToken.amount);
console.log(balances.usdc.amount);
```

### Send Tokens

```ts theme={null}
const tx = await wallet.send("0xRecipient", "usdc", "100");
console.log(tx.explorerLink);
```

### Transfers

```ts theme={null}
const transfers = await wallet.transfers({
  tokens: "usdc",
  status: "successful",
});
```

### NFTs

```ts theme={null}
const nfts = await wallet.nfts({ perPage: 10, page: 1 });
```

### Chain-Specific Transactions

```ts theme={null}
import { EVMWallet, SolanaWallet, StellarWallet } from "@crossmint/wallets-sdk";

// EVM — smart contract interaction
const evmWallet = EVMWallet.from(wallet);
const tx = await evmWallet.sendTransaction({
  to: "0xContractAddress",
  abi: contractAbi,
  functionName: "mint",
  args: [1],
  value: 0n,
});

// EVM — sign a message
const sig = await evmWallet.signMessage({ message: "Hello" });

// EVM — viem public client
const client = evmWallet.getViemClient();

// Solana
const solWallet = SolanaWallet.from(wallet);
const solTx = await solWallet.sendTransaction({
  serializedTransaction: "<base64-encoded-transaction>",
});

// Stellar
const stellarWallet = StellarWallet.from(wallet);
const stellarTx = await stellarWallet.sendTransaction({
  contractId: "C...",
  method: "transfer",
  args: { to: "G...", amount: "1000000" },
});
```

### Signer Management

```ts theme={null}
// Add a new signer
await wallet.addSigner({ type: "server", secret: "SECRET" });

// List signers
const signers = await wallet.signers();
console.log(signers); // [{ type: "server", locator: "server:...", status: "success" }, ...]

// Set the active signer (required after getWallet server-side)
await wallet.useSigner({ type: "server", secret: "SECRET" });
```

### Transaction Approval (Prepare-Only Mode)

For flows that require multi-step approval:

```ts theme={null}
// Create a transaction without auto-approving
const pendingTx = await wallet.send("0xRecipient", "usdc", "10", {
  prepareOnly: true,
});
console.log(pendingTx.transactionId);

// Approve later
const result = await wallet.approve({
  transactionId: pendingTx.transactionId,
});
```

## Signer Types

| Type | Use Case | Platforms |
| - | - | - |
| `device` | Hardware-backed, no OTP. **Browser and React Native only** — not available in Node.js. | Browser, React Native |
| `server` | Server-side automated operations (AI agents, backends). | Node.js |
| `email` | OTP-based recovery method. | All |
| `phone` | OTP-based recovery method. | All |
| `passkey` | WebAuthn/FIDO2 biometric signer. | Browser (EVM only) |
| `external-wallet` | Bring-your-own key (MetaMask, KMS, etc). | All |

## React / React Native

For React applications, use [`@crossmint/client-sdk-react-ui`](https://www.npmjs.com/package/@crossmint/client-sdk-react-ui) which provides wallet providers, hooks (`useWallet`, `useWalletOtpSigner`), and built-in UI for OTP and passkey flows.

For React Native, see [`@crossmint/client-sdk-react-native-ui`](https://www.npmjs.com/package/@crossmint/client-sdk-react-native-ui).

## Documentation

* [Crossmint Wallets Docs](https://docs.crossmint.com)
* [SDK Reference](https://docs.crossmint.com/sdk-reference/wallets)

## License

Apache-2.0


# Reference
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/reference



## Classes

* [AuthRejectedError](./classes/AuthRejectedError)
* [CrossmintWallets](./classes/CrossmintWallets)
* [DeviceSignerKeyStorage](./classes/DeviceSignerKeyStorage)
* [DuplicateRecoverySignerError](./classes/DuplicateRecoverySignerError)
* [EVMWallet](./classes/EVMWallet)
* [IframeDeviceSignerKeyStorage](./classes/IframeDeviceSignerKeyStorage)
* [InvalidRecoveryConfigError](./classes/InvalidRecoveryConfigError)
* [InvalidTransferAmountError](./classes/InvalidTransferAmountError)
* [JWTDecryptionError](./classes/JWTDecryptionError)
* [JWTExpiredError](./classes/JWTExpiredError)
* [JWTIdentifierError](./classes/JWTIdentifierError)
* [JWTInvalidError](./classes/JWTInvalidError)
* [KeyExportError](./classes/KeyExportError)
* [NotAuthorizedError](./classes/NotAuthorizedError)
* [NotSupportedOnApiVersionError](./classes/NotSupportedOnApiVersionError)
* [OnboardingSessionExpiredError](./classes/OnboardingSessionExpiredError)
* [OtpValidationError](./classes/OtpValidationError)
* [QuorumSignerNotSupportedError](./classes/QuorumSignerNotSupportedError)
* [RecoveryAdminSignerConflictError](./classes/RecoveryAdminSignerConflictError)
* [RecoveryMethodRequiredError](./classes/RecoveryMethodRequiredError)
* [RecoveryNotSupportedOnChainError](./classes/RecoveryNotSupportedOnChainError)
* [RecoverySignerConflictError](./classes/RecoverySignerConflictError)
* [RecoverySignerLimitExceededError](./classes/RecoverySignerLimitExceededError)
* [SignerAuthenticationError](./classes/SignerAuthenticationError)
* [SignerRequiredError](./classes/SignerRequiredError)
* [SignerStatusError](./classes/SignerStatusError)
* [SolanaWallet](./classes/SolanaWallet)
* [StellarWallet](./classes/StellarWallet)
* [UnsupportedBrowserError](./classes/UnsupportedBrowserError)
* [Wallet](./classes/Wallet)
* [WalletNotAvailableError](./classes/WalletNotAvailableError)
* [WalletsApiClient](./classes/WalletsApiClient)

## Interfaces

* [ExportableSignerAdapter](./interfaces/ExportableSignerAdapter)
* [SignerAdapter](./interfaces/SignerAdapter)

## Type Aliases

* [AddRecoveryMethodOptions](./type-aliases/AddRecoveryMethodOptions)
* [AddRecoveryMethodReturnType](./type-aliases/AddRecoveryMethodReturnType)
* [AddSignerOptions](./type-aliases/AddSignerOptions)
* [ApiKeySignerLocator](./type-aliases/ApiKeySignerLocator)
* [ApproveOptions](./type-aliases/ApproveOptions)
* [ApproveParams](./type-aliases/ApproveParams)
* [Balances](./type-aliases/Balances)
* [BiometricRequestHandler](./type-aliases/BiometricRequestHandler)
* [Callbacks](./type-aliases/Callbacks)
* [Chain](./type-aliases/Chain)
* [ClientSideWalletArgsFor](./type-aliases/ClientSideWalletArgsFor)
* [ClientSideWalletCreateArgs](./type-aliases/ClientSideWalletCreateArgs)
* [CreateServerSignerParams](./type-aliases/CreateServerSignerParams)
* [DeviceSignerConfig](./type-aliases/DeviceSignerConfig)
* [DeviceSignerLocator](./type-aliases/DeviceSignerLocator)
* [EmailSignerConfig](./type-aliases/EmailSignerConfig)
* [EmailSignerLocator](./type-aliases/EmailSignerLocator)
* [EVMChain](./type-aliases/EVMChain)
* [EvmExternalWalletSignerConfig](./type-aliases/EvmExternalWalletSignerConfig)
* [EVMTransactionInput](./type-aliases/EVMTransactionInput)
* [ExportSignerTEEConnection](./type-aliases/ExportSignerTEEConnection)
* [ExternalWalletRegistrationConfig](./type-aliases/ExternalWalletRegistrationConfig)
* [ExternalWalletSignerConfig](./type-aliases/ExternalWalletSignerConfig)
* [ExternalWalletSignerConfigForChain](./type-aliases/ExternalWalletSignerConfigForChain)
* [ExternalWalletSignerLocator](./type-aliases/ExternalWalletSignerLocator)
* [PasskeySignerLocator](./type-aliases/PasskeySignerLocator)
* [PhoneSignerConfig](./type-aliases/PhoneSignerConfig)
* [PhoneSignerLocator](./type-aliases/PhoneSignerLocator)
* [RecoverySignerConfigForChain](./type-aliases/RecoverySignerConfigForChain)
* [RegisterSignerPasskeyParams](./type-aliases/RegisterSignerPasskeyParams)
* [RemoveRecoveryMethodOptions](./type-aliases/RemoveRecoveryMethodOptions)
* [RemoveRecoveryMethodReturnType](./type-aliases/RemoveRecoveryMethodReturnType)
* [RemoveSignerOptions](./type-aliases/RemoveSignerOptions)
* [Scope](./type-aliases/Scope)
* [ServerSigner](./type-aliases/ServerSigner)
* [ServerSignerConfig](./type-aliases/ServerSignerConfig)
* [Signature](./type-aliases/Signature)
* [Signer](./type-aliases/Signer)
* [SignerConfigForChain](./type-aliases/SignerConfigForChain)
* [SignerLocator](./type-aliases/SignerLocator)
* [SignerStatus](./type-aliases/SignerStatus)
* [SolanaChain](./type-aliases/SolanaChain)
* [SolanaExternalWalletSignerConfig](./type-aliases/SolanaExternalWalletSignerConfig)
* [SolanaTransactionInput](./type-aliases/SolanaTransactionInput)
* [StellarChain](./type-aliases/StellarChain)
* [StellarExternalWalletSignerConfig](./type-aliases/StellarExternalWalletSignerConfig)
* [Transaction](./type-aliases/Transaction)
* [Transfers](./type-aliases/Transfers)
* [TransferScope](./type-aliases/TransferScope)
* [WalletArgsFor](./type-aliases/WalletArgsFor)
* [WalletCreateArgs](./type-aliases/WalletCreateArgs)
* [WalletOptions](./type-aliases/WalletOptions)
* [WalletPlugin](./type-aliases/WalletPlugin)

## Functions

* [createCrossmint](./functions/createCrossmint)
* [createDeviceSigner](./functions/createDeviceSigner)
* [createServerSigner](./functions/createServerSigner)
* [isExportableSignerAdapter](./functions/isExportableSignerAdapter)
* [recoveryMethodsFromCreateArgs](./functions/recoveryMethodsFromCreateArgs)


# AddRecoveryMethodOptions
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/AddRecoveryMethodOptions



> **AddRecoveryMethodOptions** = `PrepareOnly`

Defined in: [packages/wallets/src/wallets/types.ts:60](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L60)


# AddRecoveryMethodReturnType
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/AddRecoveryMethodReturnType



> **AddRecoveryMethodReturnType** = `object`

Defined in: [packages/wallets/src/wallets/types.ts:64](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L64)

## Properties

### status?

> `optional` **status**: `"success"`

Defined in: [packages/wallets/src/wallets/types.ts:64](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L64)

***

### transactionId

> **transactionId**: `string`

Defined in: [packages/wallets/src/wallets/types.ts:64](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L64)


# AddSignerOptions
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/AddSignerOptions



> **AddSignerOptions** = `PrepareOnly` & `object`

Defined in: [packages/wallets/src/wallets/types.ts:39](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L39)

## Type Declaration

### deployImmediately?

> `optional` **deployImmediately**: `boolean`

### scopes?

> `optional` **scopes**: [`Scope`](./Scope)\[]


# ApiKeySignerLocator
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/ApiKeySignerLocator



> **ApiKeySignerLocator** = `"api-key"` | `` `api-key:${string}` ``

Defined in: [packages/wallets/src/signers/types.ts:256](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L256)


# ApproveOptions
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/ApproveOptions



> **ApproveOptions** = `object`

Defined in: [packages/wallets/src/wallets/types.ts:330](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L330)

## Properties

### additionalSigners?

> `optional` **additionalSigners**: [`SignerAdapter`](../interfaces/SignerAdapter)\[]

Defined in: [packages/wallets/src/wallets/types.ts:332](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L332)

***

### approval?

> `optional` **approval**: `Approval`

Defined in: [packages/wallets/src/wallets/types.ts:331](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L331)


# ApproveParams
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/ApproveParams



> **ApproveParams** = `object`

Defined in: [packages/wallets/src/wallets/types.ts:335](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L335)

## Properties

### options?

> `optional` **options**: [`ApproveOptions`](./ApproveOptions)

Defined in: [packages/wallets/src/wallets/types.ts:338](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L338)

***

### signatureId?

> `optional` **signatureId**: `string`

Defined in: [packages/wallets/src/wallets/types.ts:337](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L337)

***

### transactionId?

> `optional` **transactionId**: `string`

Defined in: [packages/wallets/src/wallets/types.ts:336](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L336)


# Balances
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/Balances



> **Balances**\<`C`> = `object`

Defined in: [packages/wallets/src/wallets/types.ts:295](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L295)

## Type Parameters

| Type Parameter | Default type |
| - | - |
| `C` *extends* [`Chain`](./Chain) | [`Chain`](./Chain) |

## Properties

### nativeToken

> **nativeToken**: `TokenBalance`\<`C`>

Defined in: [packages/wallets/src/wallets/types.ts:296](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L296)

***

### tokens

> **tokens**: `TokenBalance`\<`C`>\[]

Defined in: [packages/wallets/src/wallets/types.ts:298](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L298)

***

### usdc

> **usdc**: `TokenBalance`\<`C`>

Defined in: [packages/wallets/src/wallets/types.ts:297](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L297)


# BiometricRequestHandler
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/BiometricRequestHandler



> **BiometricRequestHandler** = (`action`) => `Promise`\<`void`>

Defined in: [packages/wallets/src/utils/device-signers/IframeDeviceSignerKeyStorage.ts:34](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/device-signers/IframeDeviceSignerKeyStorage.ts#L34)

Callback invoked before a WebAuthn ceremony to obtain user activation.
Implementations should show a UI prompt and resolve when the user interacts (e.g. clicks a button).

## Parameters

| Parameter | Type | Description |
| - | - | - |
| `action` | `"createCredential"` \| `"sign"` | The biometric action being requested: `"createCredential"` for wallet creation, `"sign"` for transaction signing. |

## Returns

`Promise`\<`void`>


# Callbacks
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/Callbacks



> **Callbacks** = `object`

Defined in: [packages/wallets/src/wallets/types.ts:208](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L208)

## Properties

### onAuthRequired()?

> `optional` **onAuthRequired**: (`signerType`, `signerLocator`, `needsAuth`, `sendOtp`, `verifyOtp`, `reject`) => `Promise`\<`void`>

Defined in: [packages/wallets/src/wallets/types.ts:211](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L211)

#### Parameters

| Parameter | Type |
| - | - |
| `signerType` | `"email"` \| `"phone"` |
| `signerLocator` | `string` |
| `needsAuth` | `boolean` |
| `sendOtp` | () => `Promise`\<`void`> |
| `verifyOtp` | (`otp`) => `Promise`\<`void`> |
| `reject` | () => `void` |

#### Returns

`Promise`\<`void`>

***

### onTransactionStart()?

> `optional` **onTransactionStart**: () => `Promise`\<`void`>

Defined in: [packages/wallets/src/wallets/types.ts:210](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L210)

#### Returns

`Promise`\<`void`>

***

### onWalletCreationStart()?

> `optional` **onWalletCreationStart**: () => `Promise`\<`void`>

Defined in: [packages/wallets/src/wallets/types.ts:209](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L209)

#### Returns

`Promise`\<`void`>


# Chain
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/Chain



> **Chain** = [`SolanaChain`](./SolanaChain) | [`EVMChain`](./EVMChain) | [`StellarChain`](./StellarChain)

Defined in: [packages/wallets/src/chains/chains.ts:169](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/chains/chains.ts#L169)


# ClientSideWalletArgsFor
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/ClientSideWalletArgsFor



> **ClientSideWalletArgsFor**\<`C`> = `Omit`\<[`WalletArgsFor`](./WalletArgsFor)\<`C`>, `"owner"`>

Defined in: [packages/wallets/src/wallets/types.ts:274](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L274)

## Type Parameters

| Type Parameter |
| - |
| `C` *extends* [`Chain`](./Chain) |


# ClientSideWalletCreateArgs
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/ClientSideWalletCreateArgs



> **ClientSideWalletCreateArgs**\<`C`> = `Omit`\<[`WalletCreateArgs`](./WalletCreateArgs)\<`C`>, `"owner"`>

Defined in: [packages/wallets/src/wallets/types.ts:276](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L276)

## Type Parameters

| Type Parameter |
| - |
| `C` *extends* [`Chain`](./Chain) |


# CreateServerSignerParams
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/CreateServerSignerParams



> **CreateServerSignerParams** = `object`

Defined in: [packages/wallets/src/utils/server-signers/createServerSigner.ts:6](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/server-signers/createServerSigner.ts#L6)

## Properties

### chain

> **chain**: [`Chain`](./Chain)

Defined in: [packages/wallets/src/utils/server-signers/createServerSigner.ts:8](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/server-signers/createServerSigner.ts#L8)

***

### environment

> **environment**: `string`

Defined in: [packages/wallets/src/utils/server-signers/createServerSigner.ts:10](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/server-signers/createServerSigner.ts#L10)

***

### projectId

> **projectId**: `string`

Defined in: [packages/wallets/src/utils/server-signers/createServerSigner.ts:9](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/server-signers/createServerSigner.ts#L9)

***

### secret

> **secret**: `string`

Defined in: [packages/wallets/src/utils/server-signers/createServerSigner.ts:7](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/server-signers/createServerSigner.ts#L7)


# DeviceSignerConfig
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/DeviceSignerConfig



> **DeviceSignerConfig** = `object`

Defined in: [packages/wallets/src/signers/types.ts:235](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L235)

## Properties

### locator?

> `optional` **locator**: `string`

Defined in: [packages/wallets/src/signers/types.ts:238](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L238)

***

### name?

> `optional` **name**: `string`

Defined in: [packages/wallets/src/signers/types.ts:239](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L239)

***

### publicKey?

> `optional` **publicKey**: `object`

Defined in: [packages/wallets/src/signers/types.ts:237](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L237)

#### x

> **x**: `string`

#### y

> **y**: `string`

***

### type

> **type**: `"device"`

Defined in: [packages/wallets/src/signers/types.ts:236](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L236)


# DeviceSignerLocator
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/DeviceSignerLocator



> **DeviceSignerLocator** = `` `device:${string}` ``

Defined in: [packages/wallets/src/signers/types.ts:254](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L254)


# EVMChain
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/EVMChain



> **EVMChain** = `EVMSmartWalletChain`

Defined in: [packages/wallets/src/chains/chains.ts:167](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/chains/chains.ts#L167)


# EVMTransactionInput
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/EVMTransactionInput



> **EVMTransactionInput** = `EVMTransactionInputBase` & \{ `abi`: `Abi`; `args`: `unknown`\[]; `data`: `` `0x${string}` ``; `functionName`: `string`; `to`: `string`; `value`: `bigint`; } | \{ `transaction`: `string`; }

Defined in: [packages/wallets/src/wallets/types.ts:90](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L90)


# EmailSignerConfig
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/EmailSignerConfig



> **EmailSignerConfig** = `object`

Defined in: [packages/wallets/src/signers/types.ts:95](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L95)

## Properties

### email?

> `optional` **email**: `string`

Defined in: [packages/wallets/src/signers/types.ts:97](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L97)

***

### locator?

> `optional` **locator**: `string`

Defined in: [packages/wallets/src/signers/types.ts:98](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L98)

***

### type

> **type**: `"email"`

Defined in: [packages/wallets/src/signers/types.ts:96](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L96)


# EmailSignerLocator
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/EmailSignerLocator



> **EmailSignerLocator** = `` `email:${string}` ``

Defined in: [packages/wallets/src/signers/types.ts:251](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L251)


# EvmExternalWalletSignerConfig
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/EvmExternalWalletSignerConfig



> **EvmExternalWalletSignerConfig** = `object`

Defined in: packages/common/base/dist/types/signers.d.ts:14

## Properties

### address

> **address**: `string`

Defined in: packages/common/base/dist/types/signers.d.ts:16

***

### onSign()

> **onSign**: (`payload`) => `Promise`\<`string`>

Defined in: packages/common/base/dist/types/signers.d.ts:17

#### Parameters

| Parameter | Type |
| - | - |
| `payload` | `string` |

#### Returns

`Promise`\<`string`>

***

### type

> **type**: `"external-wallet"`

Defined in: packages/common/base/dist/types/signers.d.ts:15


# ExportSignerTEEConnection
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/ExportSignerTEEConnection



> **ExportSignerTEEConnection** = `HandshakeParent`\<*typeof* `exportSignerOutboundEvents`, *typeof* `exportSignerInboundEvents`>

Defined in: [packages/wallets/src/signers/types.ts:301](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L301)


# ExternalWalletRegistrationConfig
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/ExternalWalletRegistrationConfig



> **ExternalWalletRegistrationConfig** = `object`

Defined in: [packages/wallets/src/signers/types.ts:25](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L25)

## Properties

### address

> **address**: `string`

Defined in: [packages/wallets/src/signers/types.ts:27](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L27)

***

### type

> **type**: `"external-wallet"`

Defined in: [packages/wallets/src/signers/types.ts:26](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L26)


# ExternalWalletSignerConfig
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/ExternalWalletSignerConfig



> **ExternalWalletSignerConfig** = `object`

Defined in: packages/common/base/dist/types/signers.d.ts:3

## Properties

### address

> **address**: `string`

Defined in: packages/common/base/dist/types/signers.d.ts:5

***

### onSign

> **onSign**: (`transaction`) => `Promise`\<`VersionedTransaction`> | (`payload`) => `Promise`\<`string`>

Defined in: packages/common/base/dist/types/signers.d.ts:6

***

### type

> **type**: `"external-wallet"`

Defined in: packages/common/base/dist/types/signers.d.ts:4


# ExternalWalletSignerConfigForChain
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/ExternalWalletSignerConfigForChain



> **ExternalWalletSignerConfigForChain**\<`C`> = `C` *extends* [`SolanaChain`](./SolanaChain) ? [`SolanaExternalWalletSignerConfig`](./SolanaExternalWalletSignerConfig) : `C` *extends* [`StellarChain`](./StellarChain) ? [`StellarExternalWalletSignerConfig`](./StellarExternalWalletSignerConfig) : [`EvmExternalWalletSignerConfig`](./EvmExternalWalletSignerConfig)

Defined in: [packages/wallets/src/signers/types.ts:110](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L110)

## Type Parameters

| Type Parameter |
| - |
| `C` *extends* [`Chain`](./Chain) |


# ExternalWalletSignerLocator
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/ExternalWalletSignerLocator



> **ExternalWalletSignerLocator** = `` `external-wallet:${string}` ``

Defined in: [packages/wallets/src/signers/types.ts:255](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L255)


# PasskeySignerLocator
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/PasskeySignerLocator



> **PasskeySignerLocator** = `` `passkey:${string}` ``

Defined in: [packages/wallets/src/signers/types.ts:253](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L253)


# PhoneSignerConfig
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/PhoneSignerConfig



> **PhoneSignerConfig** = `object`

Defined in: [packages/wallets/src/signers/types.ts:101](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L101)

## Properties

### channel?

> `optional` **channel**: `"sms"` | `"whatsapp"`

Defined in: [packages/wallets/src/signers/types.ts:105](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L105)

***

### locator?

> `optional` **locator**: `string`

Defined in: [packages/wallets/src/signers/types.ts:104](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L104)

***

### phone?

> `optional` **phone**: `string`

Defined in: [packages/wallets/src/signers/types.ts:103](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L103)

***

### type

> **type**: `"phone"`

Defined in: [packages/wallets/src/signers/types.ts:102](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L102)


# PhoneSignerLocator
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/PhoneSignerLocator



> **PhoneSignerLocator** = `` `phone:${string}` ``

Defined in: [packages/wallets/src/signers/types.ts:252](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L252)


# RecoverySignerConfigForChain
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/RecoverySignerConfigForChain



> **RecoverySignerConfigForChain**\<`C`> = [`SignerConfigForChain`](./SignerConfigForChain)\<`C`> | `ApiSourcedServerSignerConfig`

Defined in: [packages/wallets/src/signers/types.ts:137](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L137)

## Type Parameters

| Type Parameter |
| - |
| `C` *extends* [`Chain`](./Chain) |


# RegisterSignerPasskeyParams
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/RegisterSignerPasskeyParams



> **RegisterSignerPasskeyParams** = `Extract`\<`CreateSignerV2025InputDtoClass`\[`"signer"`], \{ `type`: `"passkey"`; }>

Defined in: [packages/wallets/src/api/types.ts:82](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/types.ts#L82)


# RemoveRecoveryMethodOptions
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/RemoveRecoveryMethodOptions



> **RemoveRecoveryMethodOptions** = `PrepareOnly`

Defined in: [packages/wallets/src/wallets/types.ts:62](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L62)


# RemoveRecoveryMethodReturnType
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/RemoveRecoveryMethodReturnType



> **RemoveRecoveryMethodReturnType** = `object`

Defined in: [packages/wallets/src/wallets/types.ts:66](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L66)

## Properties

### status?

> `optional` **status**: `"success"`

Defined in: [packages/wallets/src/wallets/types.ts:66](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L66)

***

### transactionId

> **transactionId**: `string`

Defined in: [packages/wallets/src/wallets/types.ts:66](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L66)


# RemoveSignerOptions
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/RemoveSignerOptions



> **RemoveSignerOptions** = `PrepareOnly`

Defined in: [packages/wallets/src/wallets/types.ts:44](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L44)


# Scope
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/Scope



> **Scope** = [`TransferScope`](./TransferScope)

Defined in: [packages/wallets/src/api/types.ts:95](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/types.ts#L95)


# ServerSigner
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/ServerSigner



> **ServerSigner** = `object`

Defined in: [packages/wallets/src/utils/server-signers/createServerSigner.ts:13](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/server-signers/createServerSigner.ts#L13)

## Properties

### address

> **address**: `string`

Defined in: [packages/wallets/src/utils/server-signers/createServerSigner.ts:15](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/server-signers/createServerSigner.ts#L15)

***

### keyBytes

> **keyBytes**: `Uint8Array`

Defined in: [packages/wallets/src/utils/server-signers/createServerSigner.ts:16](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/server-signers/createServerSigner.ts#L16)

***

### type

> **type**: `"server"`

Defined in: [packages/wallets/src/utils/server-signers/createServerSigner.ts:14](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/utils/server-signers/createServerSigner.ts#L14)


# ServerSignerConfig
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/ServerSignerConfig



> **ServerSignerConfig** = `object`

Defined in: [packages/wallets/src/signers/types.ts:118](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L118)

## Properties

### secret

> **secret**: `string`

Defined in: [packages/wallets/src/signers/types.ts:120](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L120)

***

### type

> **type**: `"server"`

Defined in: [packages/wallets/src/signers/types.ts:119](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L119)


# Signature
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/Signature



> **Signature**\<`TPrepareOnly`> = `TPrepareOnly` *extends* `true` ? `object` : `object`

Defined in: [packages/wallets/src/wallets/types.ts:320](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L320)

## Type Parameters

| Type Parameter | Default type |
| - | - |
| `TPrepareOnly` *extends* `boolean` | `false` |


# Signer
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/Signer



> **Signer** = \{ `id`: `string`; `locator`: `string`; `name`: `string`; `publicKey`: \{ `x`: `string`; `y`: `string`; }; `scopes`: [`Scope`](./Scope)\[]; `status`: [`SignerStatus`](./SignerStatus); `type`: `"passkey"`; `validatorContractVersion`: `string`; } | \{ `address`: `string`; `locator`: `string`; `scopes`: [`Scope`](./Scope)\[]; `status`: [`SignerStatus`](./SignerStatus); `type`: `"api-key"`; } | \{ `address`: `string`; `locator`: `string`; `scopes`: [`Scope`](./Scope)\[]; `status`: [`SignerStatus`](./SignerStatus); `type`: `"external-wallet"`; } | \{ `address`: `string`; `email`: `string`; `locator`: `string`; `scopes`: [`Scope`](./Scope)\[]; `status`: [`SignerStatus`](./SignerStatus); `type`: `"email"`; } | \{ `address`: `string`; `locator`: `string`; `phone`: `string`; `scopes`: [`Scope`](./Scope)\[]; `status`: [`SignerStatus`](./SignerStatus); `type`: `"phone"`; } | \{ `locator`: `string`; `name`: `string`; `publicKey`: \{ `x`: `string`; `y`: `string`; }; `scopes`: [`Scope`](./Scope)\[]; `status`: [`SignerStatus`](./SignerStatus); `type`: `"device"`; } | \{ `address`: `string`; `locator`: `string`; `scopes`: [`Scope`](./Scope)\[]; `status`: [`SignerStatus`](./SignerStatus); `type`: `"server"`; }

Defined in: [packages/wallets/src/wallets/types.ts:146](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L146)


# SignerConfigForChain
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/SignerConfigForChain



> **SignerConfigForChain**\<`C`> = `C` *extends* [`SolanaChain`](./SolanaChain) ? [`EmailSignerConfig`](./EmailSignerConfig) | [`PhoneSignerConfig`](./PhoneSignerConfig) | `BaseSignerConfig`\<`C`> | [`DeviceSignerConfig`](./DeviceSignerConfig) : `C` *extends* [`StellarChain`](./StellarChain) ? [`EmailSignerConfig`](./EmailSignerConfig) | [`PhoneSignerConfig`](./PhoneSignerConfig) | `BaseSignerConfig`\<`C`> | [`DeviceSignerConfig`](./DeviceSignerConfig) : [`EmailSignerConfig`](./EmailSignerConfig) | [`PhoneSignerConfig`](./PhoneSignerConfig) | `PasskeySignerConfig` | `BaseSignerConfig`\<`C`> | [`DeviceSignerConfig`](./DeviceSignerConfig)

Defined in: [packages/wallets/src/signers/types.ts:242](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L242)

## Type Parameters

| Type Parameter |
| - |
| `C` *extends* [`Chain`](./Chain) |


# SignerLocator
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/SignerLocator



> **SignerLocator** = [`EmailSignerLocator`](./EmailSignerLocator) | [`PhoneSignerLocator`](./PhoneSignerLocator) | [`PasskeySignerLocator`](./PasskeySignerLocator) | [`DeviceSignerLocator`](./DeviceSignerLocator) | [`ExternalWalletSignerLocator`](./ExternalWalletSignerLocator) | [`ApiKeySignerLocator`](./ApiKeySignerLocator) | `ServerSignerLocator`

Defined in: [packages/wallets/src/signers/types.ts:259](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L259)


# SignerStatus
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/SignerStatus



> **SignerStatus** = `"success"` | `"active"` | `"pending"` | `"awaiting-approval"` | `"failed"`

Defined in: [packages/wallets/src/wallets/types.ts:138](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L138)


# SolanaChain
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/SolanaChain



> **SolanaChain** = `"solana"`

Defined in: [packages/wallets/src/chains/chains.ts:165](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/chains/chains.ts#L165)


# SolanaExternalWalletSignerConfig
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/SolanaExternalWalletSignerConfig



> **SolanaExternalWalletSignerConfig** = `object`

Defined in: packages/common/base/dist/types/signers.d.ts:8

## Properties

### address

> **address**: `string`

Defined in: packages/common/base/dist/types/signers.d.ts:10

***

### onSign()

> **onSign**: (`transaction`) => `Promise`\<`VersionedTransaction`>

Defined in: packages/common/base/dist/types/signers.d.ts:11

#### Parameters

| Parameter | Type |
| - | - |
| `transaction` | `VersionedTransaction` |

#### Returns

`Promise`\<`VersionedTransaction`>

***

### onSignBytes()?

> `optional` **onSignBytes**: (`payload`) => `Promise`\<`string`>

Defined in: packages/common/base/dist/types/signers.d.ts:12

#### Parameters

| Parameter | Type |
| - | - |
| `payload` | `string` |

#### Returns

`Promise`\<`string`>

***

### type

> **type**: `"external-wallet"`

Defined in: packages/common/base/dist/types/signers.d.ts:9


# SolanaTransactionInput
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/SolanaTransactionInput



> **SolanaTransactionInput** = \{ `transaction`: `VersionedTransaction`; } | \{ `serializedTransaction`: `string`; } & `object`

Defined in: [packages/wallets/src/wallets/types.ts:118](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L118)

## Type Declaration

### additionalSigners?

> `optional` **additionalSigners**: `Keypair`\[]

### options?

> `optional` **options**: `TransactionInputOptions`


# StellarChain
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/StellarChain



> **StellarChain** = `"stellar"`

Defined in: [packages/wallets/src/chains/chains.ts:166](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/chains/chains.ts#L166)


# StellarExternalWalletSignerConfig
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/StellarExternalWalletSignerConfig



> **StellarExternalWalletSignerConfig** = `object`

Defined in: packages/common/base/dist/types/signers.d.ts:19

## Properties

### address

> **address**: `string`

Defined in: packages/common/base/dist/types/signers.d.ts:21

***

### onSign()

> **onSign**: (`payload`) => `Promise`\<`string`>

Defined in: packages/common/base/dist/types/signers.d.ts:22

#### Parameters

| Parameter | Type |
| - | - |
| `payload` | `string` |

#### Returns

`Promise`\<`string`>

***

### type

> **type**: `"external-wallet"`

Defined in: packages/common/base/dist/types/signers.d.ts:20


# Transaction
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/Transaction



> **Transaction**\<`TPrepareOnly`> = `TPrepareOnly` *extends* `true` ? `object` : `object`

Defined in: [packages/wallets/src/wallets/types.ts:308](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L308)

## Type Parameters

| Type Parameter | Default type |
| - | - |
| `TPrepareOnly` *extends* `boolean` | `false` |


# TransferScope
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/TransferScope



> **TransferScope** = `object`

Defined in: [packages/wallets/src/api/types.ts:84](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/types.ts#L84)

## Properties

### recipients?

> `optional` **recipients**: `string`\[]

Defined in: [packages/wallets/src/api/types.ts:87](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/types.ts#L87)

***

### spendingLimit?

> `optional` **spendingLimit**: `object`

Defined in: [packages/wallets/src/api/types.ts:88](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/types.ts#L88)

#### amount

> **amount**: `string`

#### interval?

> `optional` **interval**: `number`

Positive integer representing the reset interval in seconds. Must be >= 1.

***

### tokenLocator

> **tokenLocator**: `string`

Defined in: [packages/wallets/src/api/types.ts:86](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/types.ts#L86)

***

### type

> **type**: `"transfer"`

Defined in: [packages/wallets/src/api/types.ts:85](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/types.ts#L85)


# Transfers
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/Transfers



> **Transfers** = `WalletsActivityResponseUnstableDto`

Defined in: [packages/wallets/src/api/types.ts:77](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/types.ts#L77)


# WalletArgsFor
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/WalletArgsFor



> **WalletArgsFor**\<`C`> = `object`

Defined in: [packages/wallets/src/wallets/types.ts:232](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L232)

## Type Parameters

| Type Parameter |
| - |
| `C` *extends* [`Chain`](./Chain) |

## Properties

### alias?

> `optional` **alias**: `string`

Defined in: [packages/wallets/src/wallets/types.ts:241](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L241)

Optional wallet alias.

***

### chain

> **chain**: `C`

Defined in: [packages/wallets/src/wallets/types.ts:234](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L234)

The blockchain to create the wallet on (e.g. "base-sepolia").

***

### options?

> `optional` **options**: [`WalletOptions`](./WalletOptions)

Defined in: [packages/wallets/src/wallets/types.ts:239](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L239)

***

### owner?

> `optional` **owner**: `string`

Defined in: [packages/wallets/src/wallets/types.ts:236](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L236)

Optional owner identifier.

***

### plugins?

> `optional` **plugins**: [`WalletPlugin`](./WalletPlugin)\<`C`>\[]

Defined in: [packages/wallets/src/wallets/types.ts:238](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L238)

Optional array of wallet plugins.


# WalletCreateArgs
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/WalletCreateArgs



> **WalletCreateArgs**\<`C`> = [`WalletArgsFor`](./WalletArgsFor)\<`C`> & `object`

Defined in: [packages/wallets/src/wallets/types.ts:247](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L247)

## Type Declaration

### alias?

> `optional` **alias**: `string`

### ~~recovery?~~

> `optional` **recovery**: `RecoverySignerConfigFor`\<`C`> | `RecoverySignerConfigFor`\<`C`>\[]

#### Deprecated

Use `recoveryMethods`. Still accepted: a single recovery method, or a list, which is treated
exactly like `recoveryMethods`. Pass either `recovery` or `recoveryMethods`, not both.

### recoveryMethods?

> `optional` **recoveryMethods**: `RecoverySignerConfigFor`\<`C`>\[]

Recovery methods, each able to authorize on its own. Only Solana and Stellar accept more than one.
Required unless the deprecated `recovery` is passed.

### signers?

> `optional` **signers**: ([`SignerConfigForChain`](./SignerConfigForChain)\<`C`> | [`ExternalWalletRegistrationConfig`](./ExternalWalletRegistrationConfig))\[]

Signers to register on the wallet during creation.

## Type Parameters

| Type Parameter |
| - |
| `C` *extends* [`Chain`](./Chain) |


# WalletOptions
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/WalletOptions



> **WalletOptions** = `object`

Defined in: [packages/wallets/src/wallets/types.ts:225](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L225)

## Properties

### callbacks?

> `optional` **callbacks**: [`Callbacks`](./Callbacks)

Defined in: [packages/wallets/src/wallets/types.ts:226](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L226)

***

### clientTEEConnection?

> `optional` **clientTEEConnection**: `HandshakeParent`\<*typeof* `signerOutboundEvents`, *typeof* `signerInboundEvents`>

Defined in: [packages/wallets/src/wallets/types.ts:227](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L227)

***

### deviceSignerKeyStorage?

> `optional` **deviceSignerKeyStorage**: `DeviceSignerKeyStorage`

Defined in: [packages/wallets/src/wallets/types.ts:229](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L229)

***

### resetSignerFrame()?

> `optional` **resetSignerFrame**: () => `Promise`\<`void`>

Defined in: [packages/wallets/src/wallets/types.ts:228](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L228)

#### Returns

`Promise`\<`void`>


# WalletPlugin
Source: https://docs.crossmint.com/sdk-reference/wallets/typescript/type-aliases/WalletPlugin



> **WalletPlugin**\<`C`> = `C` *extends* [`StellarChain`](./StellarChain) ? `StellarWalletPlugin` : `never`

Defined in: [packages/wallets/src/wallets/types.ts:223](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L223)

## Type Parameters

| Type Parameter |
| - |
| `C` *extends* [`Chain`](./Chain) |


# Get Started
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/react-native/get-started

Installation and setup for the React Native SDK reference for Crossmint wallets

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/sdk-reference/wallets/react-native/get-started) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

### Latest React Native SDK version - <a href="https://www.npmjs.com/package/@crossmint/client-sdk-react-native-ui"><img alt="npm" /></a>

The Crossmint React Native SDK (`@crossmint/client-sdk-react-native-ui`) provides React Native components and hooks for integrating Crossmint wallets into your mobile application.

## Installation

```bash theme={null}
npm install @crossmint/client-sdk-react-native-ui
```

## Provider Setup

Wrap your application with the required providers:

```tsx theme={null}
import {
    CrossmintProvider,
    CrossmintWalletProvider,
} from "@crossmint/client-sdk-react-native-ui";

function App() {
    return (
        <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
            <CrossmintWalletProvider
                createOnLogin={{
                    chain: "base-sepolia",
                    signer: { type: "email" },
                }}
            >
                {/* Your app components */}
            </CrossmintWalletProvider>
        </CrossmintProvider>
    );
}
```

## Quick Example

Once providers are set up, use hooks to access wallet state:

```tsx theme={null}
import { useWallet } from "@crossmint/client-sdk-react-native-ui";
import { View, Text } from "react-native";

function WalletInfo() {
    const { wallet, status } = useWallet();

    if (status === "in-progress") return <Text>Loading wallet...</Text>;
    if (!wallet) return <Text>No wallet connected</Text>;

    return (
        <View>
            <Text>Address: {wallet.address}</Text>
            <Text>Chain: {wallet.chain}</Text>
        </View>
    );
}
```

## Next Steps

* [Providers](/sdk-reference/wallets/v0/react-native/providers) — Configure providers and their options
* [Hooks](/sdk-reference/wallets/v0/react-native/hooks) — Access SDK state via React hooks
* [Wallets SDK Reference](/sdk-reference/wallets/v0/typescript/classes/Wallet) — Complete wallet method documentation


# Hooks
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/react-native/hooks

React Native hooks for React Native SDK reference for Crossmint wallets

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/sdk-reference/wallets/react-native/hooks) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

***

## useWallet()

### Returns

<ResponseField name="wallet" type="Wallet | undefined">
  The current wallet instance, or undefined if no wallet is loaded.
</ResponseField>

<ResponseField name="status" type="WalletStatus">
  Current wallet status. Options: `not-loaded` | `in-progress` | `loaded` | `error`.
</ResponseField>

<ResponseField name="getOrCreateWallet" type="(args: WalletArgsFor<Chain>) => Promise<Wallet | undefined>">
  Creates a new wallet or retrieves an existing one.

  <Expandable title="parameters">
    <ResponseField name="chain" type="Chain">
      The blockchain to create the wallet on (e.g. "base-sepolia").
    </ResponseField>

    <ResponseField name="signer" type="SignerConfigForChain">
      The signer configuration (e.g. `{ type: "email" }`).
    </ResponseField>

    <ResponseField name="owner" type="string">
      Optional owner identifier.
    </ResponseField>

    <ResponseField name="alias" type="string">
      Optional wallet alias.
    </ResponseField>

    <ResponseField name="plugins" type="WalletPlugin[]">
      Optional array of wallet plugins.
    </ResponseField>

    <ResponseField name="delegatedSigners" type="DelegatedSigner[]">
      Optional array of delegated signers.
    </ResponseField>
  </Expandable>
</ResponseField>

### Usage

```tsx theme={null}
import { useWallet } from "@crossmint/client-sdk-react-native-ui";
import { View, Text, TouchableOpacity } from "react-native";

function WalletActions() {
    const { wallet, status } = useWallet();

    if (status === "in-progress") return <Text>Loading wallet...</Text>;
    if (!wallet) return <Text>No wallet</Text>;

    const handleSend = async () => {
        const tx = await wallet.send("0x...", "usdc", "10");
        console.log("Transaction:", tx.explorerLink);
    };

    const handleBalances = async () => {
        const balances = await wallet.balances();
        console.log("USDC:", balances.usdc.amount);
        console.log("Native:", balances.nativeToken.amount);
    };

    return (
        <View>
            <Text>Wallet: {wallet.address}</Text>
            <TouchableOpacity onPress={handleBalances}>
                <Text>Check Balances</Text>
            </TouchableOpacity>
            <TouchableOpacity onPress={handleSend}>
                <Text>Send USDC</Text>
            </TouchableOpacity>
        </View>
    );
}
```

***

## useWalletEmailSigner()

Hook for managing email-based signer authentication flows. Provides OTP send/verify functions for wallets using an email signer. Must be used within a CrossmintWalletProvider.

### Returns

<ResponseField name="needsAuth" type="boolean">
  Whether the email signer currently requires authentication (OTP verification).
</ResponseField>

<ResponseField name="sendEmailWithOtp" type="() => Promise<void>">
  Sends a one-time password to the user's email address.
</ResponseField>

<ResponseField name="verifyOtp" type="(otp: string) => Promise<void>">
  Verifies the one-time password entered by the user.
</ResponseField>

<ResponseField name="reject" type="(error: Error) => void">
  Rejects the current authentication request with an error.
</ResponseField>

### Usage

```tsx theme={null}
import { useWalletEmailSigner } from "@crossmint/client-sdk-react-native-ui";
import { View, Text, TextInput, TouchableOpacity } from "react-native";
import { useState } from "react";

function EmailSignerFlow() {
    const { needsAuth, sendEmailWithOtp, verifyOtp, reject } = useWalletEmailSigner();
    const [otp, setOtp] = useState("");

    if (!needsAuth) return null;

    return (
        <View>
            <Text>Email verification required</Text>
            <TouchableOpacity onPress={sendEmailWithOtp}>
                <Text>Send OTP</Text>
            </TouchableOpacity>
            <TextInput value={otp} onChangeText={setOtp} placeholder="Enter OTP" />
            <TouchableOpacity onPress={() => verifyOtp(otp)}>
                <Text>Verify</Text>
            </TouchableOpacity>
            <TouchableOpacity onPress={() => reject(new Error("User cancelled"))}>
                <Text>Cancel</Text>
            </TouchableOpacity>
        </View>
    );
}
```

***

## Wallet Methods

The `wallet` instance returned by `useWallet()` provides methods for token transfers, balances, signing, and more.

Since the React Native SDK wraps the Wallets SDK, see the **[Wallets SDK Reference](/sdk-reference/wallets/v0/typescript/classes/Wallet)** for complete documentation.

| Method | Description |
| - | - |
| [`wallet.addDelegatedSigner()`](/sdk-reference/wallets/v0/typescript/classes/Wallet#adddelegatedsigner) | Add a delegated signer to the wallet |
| [`wallet.balances()`](/sdk-reference/wallets/v0/typescript/classes/Wallet#balances) | Get the wallet balances - always includes USDC and native token (ETH/SOL) |
| [`wallet.delegatedSigners()`](/sdk-reference/wallets/v0/typescript/classes/Wallet#delegatedsigners) | List the delegated signers for this wallet. |
| [`wallet.experimental_activity()`](/sdk-reference/wallets/v0/typescript/classes/Wallet#experimental-activity) | Get the wallet activity |
| [`wallet.experimental_nfts()`](/sdk-reference/wallets/v0/typescript/classes/Wallet#experimental-nfts) | Get the wallet NFTs |
| [`wallet.experimental_transaction()`](/sdk-reference/wallets/v0/typescript/classes/Wallet#experimental-transaction) | Get a transaction by id |
| [`wallet.experimental_transactions()`](/sdk-reference/wallets/v0/typescript/classes/Wallet#experimental-transactions) | Get the wallet transactions |
| [`wallet.send()`](/sdk-reference/wallets/v0/typescript/classes/Wallet#send) | Send a token to a wallet or user locator |
| [`wallet.stagingFund()`](/sdk-reference/wallets/v0/typescript/classes/Wallet#stagingfund) | Funds the wallet with Crossmint's stablecoin (USDXM).  **Note:** This method is only available in staging environments and exclusively supports USDXM tokens. It cannot be used in production environments. |

**Chain-specific:**

* [`EVMWallet`](/sdk-reference/wallets/v0/typescript/classes/EVMWallet) — `getViemClient()`, `sendTransaction()`, `signMessage()`, `signTypedData()`
* [`SolanaWallet`](/sdk-reference/wallets/v0/typescript/classes/SolanaWallet) — `sendTransaction()`
* [`StellarWallet`](/sdk-reference/wallets/v0/typescript/classes/StellarWallet) — `sendTransaction()`


# Providers
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/react-native/providers

React Native context providers for React Native SDK reference for Crossmint wallets

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/sdk-reference/wallets/react-native/providers) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

1. `CrossmintProvider` — SDK initialization (required for all Crossmint features)
2. `CrossmintWalletProvider` — Wallet creation and management

***

## CrossmintProvider

Root provider for the Crossmint SDK. Must wrap your entire application. Initializes the SDK with your API key and sets up logging.

### Props

<ResponseField name="apiKey" type="string">
  Your Crossmint client-side API key.
</ResponseField>

<ResponseField name="consoleLogLevel" type="ConsoleLogLevel">
  Minimum log level for console output (or "silent" to suppress all output). Logs below this level will not be written to the console. Set to "silent" to completely suppress console output. Defaults to "debug" (all logs shown) for backward compatibility.
</ResponseField>

<ResponseField name="overrideBaseUrl" type="string">
  Override the base API URL.
</ResponseField>

### Usage

```tsx theme={null}
import { CrossmintProvider } from "@crossmint/client-sdk-react-native-ui";

function App() {
    return (
        <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
            {/* Your app content */}
        </CrossmintProvider>
    );
}
```

***

## CrossmintWalletProvider

Provider for wallet creation and management. Must be nested inside CrossmintProvider. Handles secure communication with the Crossmint signer via a hidden WebView.

### Props

<ResponseField name="appearance" type="UIConfig">
  Optional appearance configuration for styling built-in UI components.
</ResponseField>

<ResponseField name="callbacks" type="{ onTransactionStart?: () => Promise<void>; onWalletCreationStart?: () => Promise<void> }">
  Optional lifecycle callbacks invoked during wallet creation and transaction signing.
</ResponseField>

<ResponseField name="createOnLogin" type="CreateOnLogin">
  Wallet configuration for automatic creation on user login. Defines the chain and signer type for the wallet.

  <Expandable title="properties">
    <ResponseField name="chain" type="Chain">
      The blockchain to create the wallet on (e.g. "base-sepolia").
    </ResponseField>

    <ResponseField name="signer" type="SignerConfigForChain">
      The signer configuration (e.g. `{ type: "email" }`).
    </ResponseField>

    <ResponseField name="owner" type="string">
      Optional owner identifier.
    </ResponseField>

    <ResponseField name="alias" type="string">
      Optional wallet alias.
    </ResponseField>

    <ResponseField name="plugins" type="WalletPlugin[]">
      Optional array of wallet plugins.
    </ResponseField>

    <ResponseField name="delegatedSigners" type="DelegatedSigner[]">
      Optional array of delegated signers.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="headlessSigningFlow" type="boolean">
  When true (default), no UI is rendered and signing flows must be handled manually. When false, built-in UI components are rendered.
</ResponseField>

### Usage

```tsx theme={null}
import {
    CrossmintProvider,
    CrossmintWalletProvider,
} from "@crossmint/client-sdk-react-native-ui";

function App() {
    return (
        <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
            <CrossmintWalletProvider
                createOnLogin={{
                    chain: "base-sepolia",
                    signer: { type: "email" },
                }}
            >
                {/* Your app content */}
            </CrossmintWalletProvider>
        </CrossmintProvider>
    );
}
```

> **Note:** CrossmintWalletProvider must be nested inside CrossmintProvider.


# Get Started
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/react/get-started

Installation and setup for the React SDK reference for Crossmint wallets

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/sdk-reference/wallets/react/get-started) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

### Latest React SDK version - <a href="https://www.npmjs.com/package/@crossmint/client-sdk-react-ui"><img alt="npm" /></a>

The Crossmint React SDK (`@crossmint/client-sdk-react-ui`) provides React components and hooks for integrating Crossmint wallets into your application.

## Installation

<Snippet />

## Provider Setup

Wrap your application with the required providers:

```tsx theme={null}
import {
    CrossmintProvider,
    CrossmintWalletProvider,
} from "@crossmint/client-sdk-react-ui";

function App() {
    return (
        <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
            <CrossmintWalletProvider
                createOnLogin={{
                    chain: "base-sepolia",
                    signer: { type: "email" },
                }}
            >
                {/* Your app components */}
            </CrossmintWalletProvider>
        </CrossmintProvider>
    );
}
```

## Quick Example

Once providers are set up, use hooks to access wallet state:

```tsx theme={null}
import { useWallet } from "@crossmint/client-sdk-react-ui";

function WalletInfo() {
    const { wallet, status } = useWallet();

    if (status === "in-progress") return <p>Loading wallet...</p>;
    if (!wallet) return <p>No wallet connected</p>;

    return (
        <div>
            <p>Address: {wallet.address}</p>
            <p>Chain: {wallet.chain}</p>
        </div>
    );
}
```

## Next Steps

* [Providers](/sdk-reference/wallets/v0/react/providers) — Configure providers and their options
* [Hooks](/sdk-reference/wallets/v0/react/hooks) — Access SDK state via React hooks
* [Components](/sdk-reference/wallets/react/components) — Drop-in UI components
* [Wallets SDK Reference](/sdk-reference/wallets/v0/typescript/classes/Wallet) — Complete wallet method documentation


# Hooks
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/react/hooks

React hooks for React SDK reference for Crossmint wallets

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/sdk-reference/wallets/react/hooks) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

***

## useWallet()

### Returns

<ResponseField name="wallet" type="Wallet | undefined">
  The current wallet instance, or undefined if no wallet is loaded.
</ResponseField>

<ResponseField name="status" type="WalletStatus">
  Current wallet status. Options: `not-loaded` | `in-progress` | `loaded` | `error`.
</ResponseField>

<ResponseField name="getOrCreateWallet" type="(args: WalletArgsFor<Chain>) => Promise<Wallet | undefined>">
  Creates a new wallet or retrieves an existing one.

  <Expandable title="parameters">
    <ResponseField name="chain" type="Chain">
      The blockchain to create the wallet on (e.g. "base-sepolia").
    </ResponseField>

    <ResponseField name="signer" type="SignerConfigForChain">
      The signer configuration (e.g. `{ type: "email" }`).
    </ResponseField>

    <ResponseField name="owner" type="string">
      Optional owner identifier.
    </ResponseField>

    <ResponseField name="alias" type="string">
      Optional wallet alias.
    </ResponseField>

    <ResponseField name="plugins" type="WalletPlugin[]">
      Optional array of wallet plugins.
    </ResponseField>

    <ResponseField name="delegatedSigners" type="DelegatedSigner[]">
      Optional array of delegated signers.
    </ResponseField>
  </Expandable>
</ResponseField>

### Usage

```tsx theme={null}
import { useWallet } from "@crossmint/client-sdk-react-ui";

function WalletActions() {
    const { wallet, status } = useWallet();

    if (status === "in-progress") return <p>Loading wallet...</p>;
    if (!wallet) return <p>No wallet</p>;

    const handleSend = async () => {
        const tx = await wallet.send("0x...", "usdc", "10");
        console.log("Transaction:", tx.explorerLink);
    };

    const handleBalances = async () => {
        const balances = await wallet.balances();
        console.log("USDC:", balances.usdc.amount);
        console.log("Native:", balances.nativeToken.amount);
    };

    return (
        <div>
            <p>Wallet: {wallet.address}</p>
            <button onClick={handleBalances}>Check Balances</button>
            <button onClick={handleSend}>Send USDC</button>
        </div>
    );
}
```

***

## Wallet Methods

The `wallet` instance returned by `useWallet()` provides methods for token transfers, balances, signing, and more.

Since the React SDK wraps the Wallets SDK, see the **[Wallets SDK Reference](/sdk-reference/wallets/v0/typescript/classes/Wallet)** for complete documentation.

| Method | Description |
| - | - |
| [`wallet.addDelegatedSigner()`](/sdk-reference/wallets/v0/typescript/classes/Wallet#adddelegatedsigner) | Add a delegated signer to the wallet |
| [`wallet.balances()`](/sdk-reference/wallets/v0/typescript/classes/Wallet#balances) | Get the wallet balances - always includes USDC and native token (ETH/SOL) |
| [`wallet.delegatedSigners()`](/sdk-reference/wallets/v0/typescript/classes/Wallet#delegatedsigners) | List the delegated signers for this wallet. |
| [`wallet.experimental_activity()`](/sdk-reference/wallets/v0/typescript/classes/Wallet#experimental-activity) | Get the wallet activity |
| [`wallet.experimental_nfts()`](/sdk-reference/wallets/v0/typescript/classes/Wallet#experimental-nfts) | Get the wallet NFTs |
| [`wallet.experimental_transaction()`](/sdk-reference/wallets/v0/typescript/classes/Wallet#experimental-transaction) | Get a transaction by id |
| [`wallet.experimental_transactions()`](/sdk-reference/wallets/v0/typescript/classes/Wallet#experimental-transactions) | Get the wallet transactions |
| [`wallet.send()`](/sdk-reference/wallets/v0/typescript/classes/Wallet#send) | Send a token to a wallet or user locator |
| [`wallet.stagingFund()`](/sdk-reference/wallets/v0/typescript/classes/Wallet#stagingfund) | Funds the wallet with Crossmint's stablecoin (USDXM).  **Note:** This method is only available in staging environments and exclusively supports USDXM tokens. It cannot be used in production environments. |

**Chain-specific:**

* [`EVMWallet`](/sdk-reference/wallets/v0/typescript/classes/EVMWallet) — `getViemClient()`, `sendTransaction()`, `signMessage()`, `signTypedData()`
* [`SolanaWallet`](/sdk-reference/wallets/v0/typescript/classes/SolanaWallet) — `sendTransaction()`
* [`StellarWallet`](/sdk-reference/wallets/v0/typescript/classes/StellarWallet) — `sendTransaction()`


# Providers
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/react/providers

React context providers for React SDK reference for Crossmint wallets

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/sdk-reference/wallets/react/providers) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

1. `CrossmintProvider` — SDK initialization (required for all Crossmint features)
2. `CrossmintWalletProvider` — Wallet creation and management

***

## CrossmintProvider

### Props

<ResponseField name="apiKey" type="string">
  Your Crossmint client-side API key.
</ResponseField>

<ResponseField name="appId" type="string">
  Application identifier, sent as `x-app-identifier` header.
</ResponseField>

<ResponseField name="consoleLogLevel" type="ConsoleLogLevel">
  Minimum log level for console output (or "silent" to suppress all output). Logs below this level will not be written to the console. Set to "silent" to completely suppress console output. Defaults to "debug" (all logs shown) for backward compatibility.
</ResponseField>

<ResponseField name="extensionId" type="string">
  Extension identifier, sent as `x-extension-id` header.
</ResponseField>

<ResponseField name="jwt" type="string">
  JWT token for authentication.
</ResponseField>

<ResponseField name="overrideBaseUrl" type="string">
  Override the base API URL.
</ResponseField>

### Usage

```tsx theme={null}
import { CrossmintProvider } from "@crossmint/client-sdk-react-ui";

function App() {
    return (
        <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
            {/* Your app content */}
        </CrossmintProvider>
    );
}
```

***

## CrossmintWalletProvider

### Props

<ResponseField name="appearance" type="UIConfig">
  Appearance configuration for wallet UI components.
</ResponseField>

<ResponseField name="callbacks" type="{ onTransactionStart?: () => Promise<void>; onWalletCreationStart?: () => Promise<void> }">
  Lifecycle callbacks for wallet creation and transaction events.
</ResponseField>

<ResponseField name="createOnLogin" type="CreateOnLogin">
  Configuration for automatic wallet creation on login.

  <Expandable title="properties">
    <ResponseField name="chain" type="Chain">
      The blockchain to create the wallet on (e.g. "base-sepolia").
    </ResponseField>

    <ResponseField name="signer" type="SignerConfigForChain">
      The signer configuration (e.g. `{ type: "email" }`).
    </ResponseField>

    <ResponseField name="owner" type="string">
      Optional owner identifier.
    </ResponseField>

    <ResponseField name="alias" type="string">
      Optional wallet alias.
    </ResponseField>

    <ResponseField name="plugins" type="WalletPlugin[]">
      Optional array of wallet plugins.
    </ResponseField>

    <ResponseField name="delegatedSigners" type="DelegatedSigner[]">
      Optional array of delegated signers.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="showPasskeyHelpers" type="boolean">
  Whether to show passkey helper UI. Default: true.
</ResponseField>

### Usage

```tsx theme={null}
import {
    CrossmintProvider,
    CrossmintWalletProvider,
} from "@crossmint/client-sdk-react-ui";

function App() {
    return (
        <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
            <CrossmintWalletProvider
                createOnLogin={{
                    chain: "base-sepolia",
                    signer: { type: "email" },
                }}
            >
                {/* Your app content */}
            </CrossmintWalletProvider>
        </CrossmintProvider>
    );
}
```

> **Note:** CrossmintWalletProvider must be nested inside CrossmintProvider.


# CrossmintWallets
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/typescript/classes/CrossmintWallets



<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/sdk-reference/wallets/typescript/classes/CrossmintWallets) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

Defined in: [packages/wallets/src/sdk.ts:9](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/sdk.ts#L9)

## Methods

### createWallet()

> **createWallet**\<`C`>(`options`): `Promise`\<[`Wallet`](./Wallet)\<`C`>>

Defined in: [packages/wallets/src/sdk.ts:54](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/sdk.ts#L54)

Create a new wallet, can only be called on the server side

#### Type Parameters

| Type Parameter |
| - |
| `C` *extends* [`Chain`](../type-aliases/Chain) |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `options` | [`WalletArgsFor`](../type-aliases/WalletArgsFor)\<`C`> | Wallet options |

#### Returns

`Promise`\<[`Wallet`](./Wallet)\<`C`>>

A new wallet

***

### getOrCreateWallet()

> **getOrCreateWallet**\<`C`>(`options`): `Promise`\<[`Wallet`](./Wallet)\<`C`>>

Defined in: [packages/wallets/src/sdk.ts:35](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/sdk.ts#L35)

Get or create a wallet, can only be called on the client side

#### Type Parameters

| Type Parameter |
| - |
| `C` *extends* [`Chain`](../type-aliases/Chain) |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `options` | [`WalletArgsFor`](../type-aliases/WalletArgsFor)\<`C`> | Wallet options |

#### Returns

`Promise`\<[`Wallet`](./Wallet)\<`C`>>

An existing wallet or a new wallet

***

### getWallet()

> **getWallet**\<`C`>(`walletLocator`, `options`): `Promise`\<[`Wallet`](./Wallet)\<`C`>>

Defined in: [packages/wallets/src/sdk.ts:45](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/sdk.ts#L45)

Get an existing wallet by its locator, can only be called on the server side

#### Type Parameters

| Type Parameter |
| - |
| `C` *extends* [`Chain`](../type-aliases/Chain) |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `walletLocator` | `string` | Wallet locator |
| `options` | [`WalletArgsFor`](../type-aliases/WalletArgsFor)\<`C`> | Wallet options |

#### Returns

`Promise`\<[`Wallet`](./Wallet)\<`C`>>

A wallet if found, throws WalletNotAvailableError if not found

***

### from()

> `static` **from**(`crossmint`): `CrossmintWallets`

Defined in: [packages/wallets/src/sdk.ts:25](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/sdk.ts#L25)

Initialize the Wallets SDK

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `crossmint` | `Crossmint` | Crossmint data (use `createCrossmint` to initialize) |

#### Returns

`CrossmintWallets`

A new CrossmintWallets instance


# EVMWallet
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/typescript/classes/EVMWallet



<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/sdk-reference/wallets/typescript/classes/EVMWallet) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

Defined in: [packages/wallets/src/wallets/evm.ts:20](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/evm.ts#L20)

## Extends

* [`Wallet`](./Wallet)\<[`EVMChain`](../type-aliases/EVMChain)>

## Constructors

### new EVMWallet()

> **new EVMWallet**(`wallet`): `EVMWallet`

Defined in: [packages/wallets/src/wallets/evm.ts:21](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/evm.ts#L21)

#### Parameters

| Parameter | Type |
| - | - |
| `wallet` | [`Wallet`](./Wallet)\<`EVMSmartWalletChain`> |

#### Returns

`EVMWallet`

#### Overrides

[`Wallet`](./Wallet).[`constructor`](./Wallet#constructor)

## Properties

| Property | Type | Inherited from | Defined in |
| - | - | - | - |
|  `address` | `string` | [`Wallet`](./Wallet).[`address`](./Wallet#address) | [packages/wallets/src/wallets/wallet.ts:62](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L62) |
|  `alias?` | `string` | [`Wallet`](./Wallet).[`alias`](./Wallet#alias) | [packages/wallets/src/wallets/wallet.ts:64](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L64) |
|  `chain` | `EVMSmartWalletChain` | [`Wallet`](./Wallet).[`chain`](./Wallet#chain) | [packages/wallets/src/wallets/wallet.ts:61](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L61) |
|  `owner?` | `string` | [`Wallet`](./Wallet).[`owner`](./Wallet#owner) | [packages/wallets/src/wallets/wallet.ts:63](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L63) |
|  `signer` | [`Signer`](../interfaces/Signer) | [`Wallet`](./Wallet).[`signer`](./Wallet#signer) | [packages/wallets/src/wallets/wallet.ts:65](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L65) |

## Methods

### addDelegatedSigner()

> **addDelegatedSigner**\<`T`>(`params`): `Promise`\<`T` *extends* `PrepareOnly`\<`true`> ? `object` : `void`>

Defined in: [packages/wallets/src/wallets/wallet.ts:465](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L465)

Add a delegated signer to the wallet

#### Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* `AddDelegatedSignerOptions` \| `undefined` | `undefined` |

#### Parameters

| Parameter | Type |
| - | - |
| `params` | \{ `options`: `T`; `signer`: `string` \| \{ `id`: `string`; `name`: `string`; `publicKey`: \{ `x`: `string`; `y`: `string`; }; `type`: `"passkey"`; }; } |
| `params.options`? | `T` |
| `params.signer` | `string` \| \{ `id`: `string`; `name`: `string`; `publicKey`: \{ `x`: `string`; `y`: `string`; }; `type`: `"passkey"`; } |

#### Returns

`Promise`\<`T` *extends* `PrepareOnly`\<`true`> ? `object` : `void`>

#### Inherited from

[`Wallet`](./Wallet).[`addDelegatedSigner`](./Wallet#adddelegatedsigner)

***

### approve()

> **approve**\<`T`>(`params`): `Promise`\<`ApproveResult`\<`T`>>

Defined in: [packages/wallets/src/wallets/wallet.ts:423](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L423)

Approve a transaction or signature

#### Type Parameters

| Type Parameter |
| - |
| `T` *extends* `ApproveParams` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | `T` | The parameters |

#### Returns

`Promise`\<`ApproveResult`\<`T`>>

The transaction or signature

#### Inherited from

[`Wallet`](./Wallet).[`approve`](./Wallet#approve)

***

### ~~approveTransaction()~~

> **approveTransaction**(`params`): `Promise`\<`Error`>

Defined in: [packages/wallets/src/wallets/wallet.ts:399](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L399)

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | `ApproveParams` | The parameters |

#### Returns

`Promise`\<`Error`>

The transaction

#### Deprecated

Use `approve` instead.
Approve a transaction

#### Inherited from

[`Wallet`](./Wallet).[`approveTransaction`](./Wallet#approvetransaction)

***

### balances()

> **balances**(`tokens`?): `Promise`\<[`Balances`](../type-aliases/Balances)\<`EVMSmartWalletChain`>>

Defined in: [packages/wallets/src/wallets/wallet.ts:118](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L118)

Get the wallet balances - always includes USDC and native token (ETH/SOL)

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `tokens`? | `string`\[] | Additional tokens to request (optional: native token and usdc are always included) |

#### Returns

`Promise`\<[`Balances`](../type-aliases/Balances)\<`EVMSmartWalletChain`>>

The balances returns nativeToken, usdc, tokens

#### Throws

If the balances cannot be retrieved

#### Inherited from

[`Wallet`](./Wallet).[`balances`](./Wallet#balances)

***

### delegatedSigners()

> **delegatedSigners**(): `Promise`\<[`DelegatedSigner`](../type-aliases/DelegatedSigner)\[]>

Defined in: [packages/wallets/src/wallets/wallet.ts:554](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L554)

List the delegated signers for this wallet.

#### Returns

`Promise`\<[`DelegatedSigner`](../type-aliases/DelegatedSigner)\[]>

The delegated signers

#### Inherited from

[`Wallet`](./Wallet).[`delegatedSigners`](./Wallet#delegatedsigners)

***

### experimental\_activity()

> **experimental\_activity**(): `Promise`\<`WalletsV1Alpha2ActivityResponseDto`>

Defined in: [packages/wallets/src/wallets/wallet.ts:312](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L312)

**`Experimental`**

Get the wallet activity

#### Returns

`Promise`\<`WalletsV1Alpha2ActivityResponseDto`>

The activity
This API is experimental and may change in the future

#### Throws

If the activity cannot be retrieved

#### Inherited from

[`Wallet`](./Wallet).[`experimental_activity`](./Wallet#experimental_activity)

***

### experimental\_apiClient()

> **experimental\_apiClient**(): [`WalletsApiClient`](./WalletsApiClient)

Defined in: [packages/wallets/src/wallets/wallet.ts:101](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L101)

**`Experimental`**

Get the API client

#### Returns

[`WalletsApiClient`](./WalletsApiClient)

The API client
This API is experimental and may change in the future

#### Inherited from

[`Wallet`](./Wallet).[`experimental_apiClient`](./Wallet#experimental_apiclient)

***

### experimental\_nfts()

> **experimental\_nfts**(`params`): `Promise`\<`WalletNftsResponseDto`>

Defined in: [packages/wallets/src/wallets/wallet.ts:272](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L272)

**`Experimental`**

Get the wallet NFTs

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | \{ `page`: `number`; `perPage`: `number`; } | The parameters |
| `params.page` | `number` | The page number |
| `params.perPage` | `number` | The number of NFTs per page |

#### Returns

`Promise`\<`WalletNftsResponseDto`>

The NFTs
This API is experimental and may change in the future

#### Inherited from

[`Wallet`](./Wallet).[`experimental_nfts`](./Wallet#experimental_nfts)

***

### experimental\_transaction()

> **experimental\_transaction**(`transactionId`): `Promise`\<`WalletsTransactionV2025ResponseDto`>

Defined in: [packages/wallets/src/wallets/wallet.ts:298](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L298)

Get a transaction by id

#### Parameters

| Parameter | Type |
| - | - |
| `transactionId` | `string` |

#### Returns

`Promise`\<`WalletsTransactionV2025ResponseDto`>

The transaction

#### Throws

If the transaction cannot be retrieved

#### Inherited from

[`Wallet`](./Wallet).[`experimental_transaction`](./Wallet#experimental_transaction)

***

### experimental\_transactions()

> **experimental\_transactions**(): `Promise`\<`GetTransactionsResponse`>

Defined in: [packages/wallets/src/wallets/wallet.ts:285](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L285)

Get the wallet transactions

#### Returns

`Promise`\<`GetTransactionsResponse`>

The transactions

#### Throws

If the transactions cannot be retrieved

#### Inherited from

[`Wallet`](./Wallet).[`experimental_transactions`](./Wallet#experimental_transactions)

***

### getViemClient()

> **getViemClient**(`params`?): `object`

Defined in: [packages/wallets/src/wallets/evm.ts:203](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/evm.ts#L203)

Get a Viem public client instance configured for this wallet's chain.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params`? | \{ `transport`: `HttpTransport`; } | Optional transport configuration |
| `params.transport`? | `HttpTransport` | - |

#### Returns

`object`

A Viem public client

##### account

> **account**: `undefined`

The Account of the Client.

##### batch?

> `optional` **batch**: `object`

Flags for batch settings.

###### batch.multicall?

> `optional` **multicall**: `boolean` | \{ `batchSize`: `number`; `wait`: `number`; }

Toggle to enable `eth_call` multicall aggregation.

###### Type Declaration

`boolean`

\{ `batchSize`: `number`; `wait`: `number`; }

##### cacheTime

> **cacheTime**: `number`

Time (in ms) that cached data will remain in memory.

##### call()

> **call**: (`parameters`) => `Promise`\<`CallReturnType`>

Executes a new message call immediately without submitting a transaction to the network.

* Docs: [https://viem.sh/docs/actions/public/call](https://viem.sh/docs/actions/public/call)
* JSON-RPC Methods: [`eth_call`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_call)

###### Parameters

| Parameter | Type |
| - | - |
| `parameters` | `CallParameters`\<`Chain`> |

###### Returns

`Promise`\<`CallReturnType`>

The call data. CallReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const data = await client.call({
  account: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
  data: '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2',
  to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
})
```

##### ccipRead?

> `optional` **ccipRead**: `false` | \{ `request`: (`parameters`) => `Promise`\<`` `0x${string}` ``>; }

[CCIP Read](https://eips.ethereum.org/EIPS/eip-3668) configuration.

###### Type Declaration

`false`

\{ `request`: (`parameters`) => `Promise`\<`` `0x${string}` ``>; }

##### chain

> **chain**: `Chain`

Chain for the client.

##### createAccessList()

> **createAccessList**: (`parameters`) => `Promise`\<\{ `accessList`: `AccessList`; `gasUsed`: `bigint`; }>

Creates an EIP-2930 access list that you can include in a transaction.

* Docs: [https://viem.sh/docs/actions/public/createAccessList](https://viem.sh/docs/actions/public/createAccessList)
* JSON-RPC Methods: `eth_createAccessList`

###### Parameters

| Parameter | Type |
| - | - |
| `parameters` | `CreateAccessListParameters`\<`Chain`> |

###### Returns

`Promise`\<\{ `accessList`: `AccessList`; `gasUsed`: `bigint`; }>

The call data. CreateAccessListReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})

const data = await client.createAccessList({
  data: '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2',
  to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
})
```

##### createBlockFilter()

> **createBlockFilter**: () => `Promise`\<\{ `id`: `` `0x${string}` ``; `request`: `EIP1193RequestFn`\<readonly \[\{ `Method`: `"eth_getFilterChanges"`; `Parameters`: \[`` `0x${string}` ``]; `ReturnType`: `` `0x${string}` ``\[] | `RpcLog`\[]; }, \{ `Method`: `"eth_getFilterLogs"`; `Parameters`: \[`` `0x${string}` ``]; `ReturnType`: `RpcLog`\[]; }, \{ `Method`: `"eth_uninstallFilter"`; `Parameters`: \[`` `0x${string}` ``]; `ReturnType`: `boolean`; }]>; `type`: `"block"`; }>

Creates a Filter to listen for new block hashes that can be used with [`getFilterChanges`](https://viem.sh/docs/actions/public/getFilterChanges).

* Docs: [https://viem.sh/docs/actions/public/createBlockFilter](https://viem.sh/docs/actions/public/createBlockFilter)
* JSON-RPC Methods: [`eth_newBlockFilter`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_newBlockFilter)

###### Returns

`Promise`\<\{ `id`: `` `0x${string}` ``; `request`: `EIP1193RequestFn`\<readonly \[\{ `Method`: `"eth_getFilterChanges"`; `Parameters`: \[`` `0x${string}` ``]; `ReturnType`: `` `0x${string}` ``\[] | `RpcLog`\[]; }, \{ `Method`: `"eth_getFilterLogs"`; `Parameters`: \[`` `0x${string}` ``]; `ReturnType`: `RpcLog`\[]; }, \{ `Method`: `"eth_uninstallFilter"`; `Parameters`: \[`` `0x${string}` ``]; `ReturnType`: `boolean`; }]>; `type`: `"block"`; }>

Filter. CreateBlockFilterReturnType

###### Example

```ts theme={null}
import { createPublicClient, createBlockFilter, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const filter = await createBlockFilter(client)
// { id: "0x345a6572337856574a76364e457a4366", type: 'block' }
```

##### createContractEventFilter()

> **createContractEventFilter**: \<`abi`, `eventName`, `args`, `strict`, `fromBlock`, `toBlock`>(`args`) => `Promise`\<`CreateContractEventFilterReturnType`\<`abi`, `eventName`, `args`, `strict`, `fromBlock`, `toBlock`>>

Creates a Filter to retrieve event logs that can be used with [`getFilterChanges`](https://viem.sh/docs/actions/public/getFilterChanges) or [`getFilterLogs`](https://viem.sh/docs/actions/public/getFilterLogs).

* Docs: [https://viem.sh/docs/contract/createContractEventFilter](https://viem.sh/docs/contract/createContractEventFilter)

###### Type Parameters

| Type Parameter | Default type |
| - | - |
| `abi` *extends* readonly `unknown`\[] \| `Abi` | - |
| `eventName` *extends* `string` \| `undefined` | - |
| `args` *extends* readonly `unknown`\[] \| `Record`\<`string`, `unknown`> \| `undefined` | - |
| `strict` *extends* `boolean` \| `undefined` | `undefined` |
| `fromBlock` *extends* `bigint` \| `BlockTag` \| `undefined` | `undefined` |
| `toBlock` *extends* `bigint` \| `BlockTag` \| `undefined` | `undefined` |

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `CreateContractEventFilterParameters`\<`abi`, `eventName`, `args`, `strict`, `fromBlock`, `toBlock`> | CreateContractEventFilterParameters |

###### Returns

`Promise`\<`CreateContractEventFilterReturnType`\<`abi`, `eventName`, `args`, `strict`, `fromBlock`, `toBlock`>>

[`Filter`](https://viem.sh/docs/glossary/types#filter). CreateContractEventFilterReturnType

###### Example

```ts theme={null}
import { createPublicClient, http, parseAbi } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const filter = await client.createContractEventFilter({
  abi: parseAbi(['event Transfer(address indexed, address indexed, uint256)']),
})
```

##### createEventFilter()

> **createEventFilter**: \<`abiEvent`, `abiEvents`, `strict`, `fromBlock`, `toBlock`, `_EventName`, `_Args`>(`args`?) => `Promise`\<\{ \[K in string | number | symbol]: Filter\<"event", abiEvents, \_EventName, \_Args, strict, fromBlock, toBlock>\[K] }>

Creates a [`Filter`](https://viem.sh/docs/glossary/types#filter) to listen for new events that can be used with [`getFilterChanges`](https://viem.sh/docs/actions/public/getFilterChanges).

* Docs: [https://viem.sh/docs/actions/public/createEventFilter](https://viem.sh/docs/actions/public/createEventFilter)
* JSON-RPC Methods: [`eth_newFilter`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_newfilter)

###### Type Parameters

| Type Parameter | Default type |
| - | - |
| `abiEvent` *extends* `AbiEvent` \| `undefined` | `undefined` |
| `abiEvents` *extends* readonly `unknown`\[] \| readonly `AbiEvent`\[] \| `undefined` | `abiEvent` *extends* `AbiEvent` ? \[`abiEvent`] : `undefined` |
| `strict` *extends* `boolean` \| `undefined` | `undefined` |
| `fromBlock` *extends* `bigint` \| `BlockTag` \| `undefined` | `undefined` |
| `toBlock` *extends* `bigint` \| `BlockTag` \| `undefined` | `undefined` |
| `_EventName` *extends* `string` \| `undefined` | `MaybeAbiEventName`\<`abiEvent`> |
| `_Args` *extends* readonly `unknown`\[] \| `Record`\<`string`, `unknown`> \| `undefined` | `undefined` |

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args`? | `CreateEventFilterParameters`\<`abiEvent`, `abiEvents`, `strict`, `fromBlock`, `toBlock`, `_EventName`, `_Args`> | CreateEventFilterParameters |

###### Returns

`Promise`\<\{ \[K in string | number | symbol]: Filter\<"event", abiEvents, \_EventName, \_Args, strict, fromBlock, toBlock>\[K] }>

[`Filter`](https://viem.sh/docs/glossary/types#filter). CreateEventFilterReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const filter = await client.createEventFilter({
  address: '0xfba3912ca04dd458c843e2ee08967fc04f3579c2',
})
```

##### createPendingTransactionFilter()

> **createPendingTransactionFilter**: () => `Promise`\<\{ `id`: `` `0x${string}` ``; `request`: `EIP1193RequestFn`\<readonly \[\{ `Method`: `"eth_getFilterChanges"`; `Parameters`: \[`` `0x${string}` ``]; `ReturnType`: `` `0x${string}` ``\[] | `RpcLog`\[]; }, \{ `Method`: `"eth_getFilterLogs"`; `Parameters`: \[`` `0x${string}` ``]; `ReturnType`: `RpcLog`\[]; }, \{ `Method`: `"eth_uninstallFilter"`; `Parameters`: \[`` `0x${string}` ``]; `ReturnType`: `boolean`; }]>; `type`: `"transaction"`; }>

Creates a Filter to listen for new pending transaction hashes that can be used with [`getFilterChanges`](https://viem.sh/docs/actions/public/getFilterChanges).

* Docs: [https://viem.sh/docs/actions/public/createPendingTransactionFilter](https://viem.sh/docs/actions/public/createPendingTransactionFilter)
* JSON-RPC Methods: [`eth_newPendingTransactionFilter`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_newpendingtransactionfilter)

###### Returns

`Promise`\<\{ `id`: `` `0x${string}` ``; `request`: `EIP1193RequestFn`\<readonly \[\{ `Method`: `"eth_getFilterChanges"`; `Parameters`: \[`` `0x${string}` ``]; `ReturnType`: `` `0x${string}` ``\[] | `RpcLog`\[]; }, \{ `Method`: `"eth_getFilterLogs"`; `Parameters`: \[`` `0x${string}` ``]; `ReturnType`: `RpcLog`\[]; }, \{ `Method`: `"eth_uninstallFilter"`; `Parameters`: \[`` `0x${string}` ``]; `ReturnType`: `boolean`; }]>; `type`: `"transaction"`; }>

[`Filter`](https://viem.sh/docs/glossary/types#filter). CreateBlockFilterReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const filter = await client.createPendingTransactionFilter()
// { id: "0x345a6572337856574a76364e457a4366", type: 'transaction' }
```

##### estimateContractGas()

> **estimateContractGas**: \<`chain`, `abi`, `functionName`, `args`>(`args`) => `Promise`\<`bigint`>

Estimates the gas required to successfully execute a contract write function call.

* Docs: [https://viem.sh/docs/contract/estimateContractGas](https://viem.sh/docs/contract/estimateContractGas)

###### Type Parameters

| Type Parameter |
| - |
| `chain` *extends* `Chain` \| `undefined` |
| `abi` *extends* readonly `unknown`\[] \| `Abi` |
| `functionName` *extends* `string` |
| `args` *extends* `unknown` |

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `EstimateContractGasParameters`\<`abi`, `functionName`, `args`, `chain`> | EstimateContractGasParameters |

###### Returns

`Promise`\<`bigint`>

The gas estimate (in wei). EstimateContractGasReturnType

###### Remarks

Internally, uses a [Public Client](https://viem.sh/docs/clients/public) to call the [`estimateGas` action](https://viem.sh/docs/actions/public/estimateGas) with [ABI-encoded `data`](https://viem.sh/docs/contract/encodeFunctionData).

###### Example

```ts theme={null}
import { createPublicClient, http, parseAbi } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const gas = await client.estimateContractGas({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: parseAbi(['function mint() public']),
  functionName: 'mint',
  account: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
})
```

##### estimateFeesPerGas()

> **estimateFeesPerGas**: \<`chainOverride`, `type`>(`args`?) => `Promise`\<`EstimateFeesPerGasReturnType`\<`type`>>

Returns an estimate for the fees per gas for a transaction to be included
in the next block.

* Docs: [https://viem.sh/docs/actions/public/estimateFeesPerGas](https://viem.sh/docs/actions/public/estimateFeesPerGas)

###### Type Parameters

| Type Parameter | Default type |
| - | - |
| `chainOverride` *extends* `Chain` \| `undefined` | `undefined` |
| `type` *extends* `FeeValuesType` | `"eip1559"` |

###### Parameters

| Parameter | Type |
| - | - |
| `args`? | `EstimateFeesPerGasParameters`\<`Chain`, `chainOverride`, `type`> |

###### Returns

`Promise`\<`EstimateFeesPerGasReturnType`\<`type`>>

An estimate (in wei) for the fees per gas. EstimateFeesPerGasReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const maxPriorityFeePerGas = await client.estimateFeesPerGas()
// { maxFeePerGas: ..., maxPriorityFeePerGas: ... }
```

##### estimateGas()

> **estimateGas**: (`args`) => `Promise`\<`bigint`>

Estimates the gas necessary to complete a transaction without submitting it to the network.

* Docs: [https://viem.sh/docs/actions/public/estimateGas](https://viem.sh/docs/actions/public/estimateGas)
* JSON-RPC Methods: [`eth_estimateGas`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_estimategas)

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `EstimateGasParameters`\<`Chain`> | EstimateGasParameters |

###### Returns

`Promise`\<`bigint`>

The gas estimate (in wei). EstimateGasReturnType

###### Example

```ts theme={null}
import { createPublicClient, http, parseEther } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const gasEstimate = await client.estimateGas({
  account: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
  to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
  value: parseEther('1'),
})
```

##### estimateMaxPriorityFeePerGas()

> **estimateMaxPriorityFeePerGas**: \<`chainOverride`>(`args`?) => `Promise`\<`bigint`>

Returns an estimate for the max priority fee per gas (in wei) for a transaction
to be included in the next block.

* Docs: [https://viem.sh/docs/actions/public/estimateMaxPriorityFeePerGas](https://viem.sh/docs/actions/public/estimateMaxPriorityFeePerGas)

###### Type Parameters

| Type Parameter | Default type |
| - | - |
| `chainOverride` *extends* `Chain` \| `undefined` | `undefined` |

###### Parameters

| Parameter | Type |
| - | - |
| `args`? | \{ `chain`: `chainOverride` \| `null`; } |
| `args.chain`? | `chainOverride` \| `null` |

###### Returns

`Promise`\<`bigint`>

An estimate (in wei) for the max priority fee per gas. EstimateMaxPriorityFeePerGasReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const maxPriorityFeePerGas = await client.estimateMaxPriorityFeePerGas()
// 10000000n
```

##### experimental\_blockTag?

> `optional` **experimental\_blockTag**: `BlockTag`

Default block tag to use for RPC requests.

##### extend()

> **extend**: \<`client`>(`fn`) => `Client`\<`HttpTransport`, `Chain`, `undefined`, `PublicRpcSchema`, \{ \[K in string | number | symbol]: client\[K] } & `PublicActions`\<`HttpTransport`, `Chain`>>

###### Type Parameters

| Type Parameter |
| - |
| `client` *extends* `object` & `ExactPartial`\<`ExtendableProtectedActions`\<`HttpTransport`, `Chain`, `undefined`>> |

###### Parameters

| Parameter | Type |
| - | - |
| `fn` | (`client`) => `client` |

###### Returns

`Client`\<`HttpTransport`, `Chain`, `undefined`, `PublicRpcSchema`, \{ \[K in string | number | symbol]: client\[K] } & `PublicActions`\<`HttpTransport`, `Chain`>>

##### getBalance()

> **getBalance**: (`args`) => `Promise`\<`bigint`>

Returns the balance of an address in wei.

* Docs: [https://viem.sh/docs/actions/public/getBalance](https://viem.sh/docs/actions/public/getBalance)
* JSON-RPC Methods: [`eth_getBalance`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getbalance)

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `GetBalanceParameters` | GetBalanceParameters |

###### Returns

`Promise`\<`bigint`>

The balance of the address in wei. GetBalanceReturnType

###### Remarks

You can convert the balance to ether units with [`formatEther`](https://viem.sh/docs/utilities/formatEther).

```ts theme={null}
const balance = await getBalance(client, {
  address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
  blockTag: 'safe'
})
const balanceAsEther = formatEther(balance)
// "6.942"
```

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const balance = await client.getBalance({
  address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
})
// 10000000000000000000000n (wei)
```

##### getBlobBaseFee()

> **getBlobBaseFee**: () => `Promise`\<`bigint`>

Returns the base fee per blob gas in wei.

* Docs: [https://viem.sh/docs/actions/public/getBlobBaseFee](https://viem.sh/docs/actions/public/getBlobBaseFee)
* JSON-RPC Methods: [`eth_blobBaseFee`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_blobBaseFee)

###### Returns

`Promise`\<`bigint`>

The blob base fee (in wei). GetBlobBaseFeeReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'
import { getBlobBaseFee } from 'viem/public'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const blobBaseFee = await client.getBlobBaseFee()
```

##### getBlock()

> **getBlock**: \<`includeTransactions`, `blockTag`>(`args`?) => `Promise`\<\{ `baseFeePerGas`: `bigint` | `null`; `blobGasUsed`: `bigint`; `difficulty`: `bigint`; `excessBlobGas`: `bigint`; `extraData`: `` `0x${string}` ``; `gasLimit`: `bigint`; `gasUsed`: `bigint`; `hash`: `blockTag` *extends* `"pending"` ? `null` : `` `0x${string}` ``; `logsBloom`: `blockTag` *extends* `"pending"` ? `null` : `` `0x${string}` ``; `miner`: `` `0x${string}` ``; `mixHash`: `` `0x${string}` ``; `nonce`: `blockTag` *extends* `"pending"` ? `null` : `` `0x${string}` ``; `number`: `blockTag` *extends* `"pending"` ? `null` : `bigint`; `parentBeaconBlockRoot`: `` `0x${string}` ``; `parentHash`: `` `0x${string}` ``; `receiptsRoot`: `` `0x${string}` ``; `sealFields`: `` `0x${string}` ``\[]; `sha3Uncles`: `` `0x${string}` ``; `size`: `bigint`; `stateRoot`: `` `0x${string}` ``; `timestamp`: `bigint`; `totalDifficulty`: `bigint` | `null`; `transactions`: `includeTransactions` *extends* `true` ? (\{ `accessList`: `undefined`; `authorizationList`: `undefined`; `blobVersionedHashes`: `undefined`; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `bigint`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `undefined`; `maxPriorityFeePerGas`: `undefined`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"legacy"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `undefined`; } | \{ `accessList`: `AccessList`; `authorizationList`: `undefined`; `blobVersionedHashes`: `undefined`; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `bigint`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `undefined`; `maxPriorityFeePerGas`: `undefined`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"eip2930"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `number`; } | \{ `accessList`: `AccessList`; `authorizationList`: `undefined`; `blobVersionedHashes`: `undefined`; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `undefined`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `bigint`; `maxPriorityFeePerGas`: `bigint`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"eip1559"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `number`; } | \{ `accessList`: `AccessList`; `authorizationList`: `undefined`; `blobVersionedHashes`: readonly `` `0x${string}` ``\[]; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `undefined`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `bigint`; `maxFeePerGas`: `bigint`; `maxPriorityFeePerGas`: `bigint`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"eip4844"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `number`; } | \{ `accessList`: `AccessList`; `authorizationList`: `SignedAuthorizationList`; `blobVersionedHashes`: `undefined`; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `undefined`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `bigint`; `maxPriorityFeePerGas`: `bigint`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"eip7702"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `number`; })\[] : `` `0x${string}` ``\[]; `transactionsRoot`: `` `0x${string}` ``; `uncles`: `` `0x${string}` ``\[]; `withdrawals`: `Withdrawal`\[]; `withdrawalsRoot`: `` `0x${string}` ``; }>

Returns information about a block at a block number, hash, or tag.

* Docs: [https://viem.sh/docs/actions/public/getBlock](https://viem.sh/docs/actions/public/getBlock)
* Examples: [https://stackblitz.com/github/wevm/viem/tree/main/examples/blocks\_fetching-blocks](https://stackblitz.com/github/wevm/viem/tree/main/examples/blocks_fetching-blocks)
* JSON-RPC Methods:
  * Calls [`eth_getBlockByNumber`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getblockbynumber) for `blockNumber` & `blockTag`.
  * Calls [`eth_getBlockByHash`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getblockbyhash) for `blockHash`.

###### Type Parameters

| Type Parameter | Default type |
| - | - |
| `includeTransactions` *extends* `boolean` | `false` |
| `blockTag` *extends* `BlockTag` | `"latest"` |

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args`? | `GetBlockParameters`\<`includeTransactions`, `blockTag`> | GetBlockParameters |

###### Returns

`Promise`\<\{ `baseFeePerGas`: `bigint` | `null`; `blobGasUsed`: `bigint`; `difficulty`: `bigint`; `excessBlobGas`: `bigint`; `extraData`: `` `0x${string}` ``; `gasLimit`: `bigint`; `gasUsed`: `bigint`; `hash`: `blockTag` *extends* `"pending"` ? `null` : `` `0x${string}` ``; `logsBloom`: `blockTag` *extends* `"pending"` ? `null` : `` `0x${string}` ``; `miner`: `` `0x${string}` ``; `mixHash`: `` `0x${string}` ``; `nonce`: `blockTag` *extends* `"pending"` ? `null` : `` `0x${string}` ``; `number`: `blockTag` *extends* `"pending"` ? `null` : `bigint`; `parentBeaconBlockRoot`: `` `0x${string}` ``; `parentHash`: `` `0x${string}` ``; `receiptsRoot`: `` `0x${string}` ``; `sealFields`: `` `0x${string}` ``\[]; `sha3Uncles`: `` `0x${string}` ``; `size`: `bigint`; `stateRoot`: `` `0x${string}` ``; `timestamp`: `bigint`; `totalDifficulty`: `bigint` | `null`; `transactions`: `includeTransactions` *extends* `true` ? (\{ `accessList`: `undefined`; `authorizationList`: `undefined`; `blobVersionedHashes`: `undefined`; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `bigint`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `undefined`; `maxPriorityFeePerGas`: `undefined`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"legacy"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `undefined`; } | \{ `accessList`: `AccessList`; `authorizationList`: `undefined`; `blobVersionedHashes`: `undefined`; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `bigint`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `undefined`; `maxPriorityFeePerGas`: `undefined`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"eip2930"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `number`; } | \{ `accessList`: `AccessList`; `authorizationList`: `undefined`; `blobVersionedHashes`: `undefined`; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `undefined`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `bigint`; `maxPriorityFeePerGas`: `bigint`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"eip1559"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `number`; } | \{ `accessList`: `AccessList`; `authorizationList`: `undefined`; `blobVersionedHashes`: readonly `` `0x${string}` ``\[]; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `undefined`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `bigint`; `maxFeePerGas`: `bigint`; `maxPriorityFeePerGas`: `bigint`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"eip4844"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `number`; } | \{ `accessList`: `AccessList`; `authorizationList`: `SignedAuthorizationList`; `blobVersionedHashes`: `undefined`; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `undefined`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `bigint`; `maxPriorityFeePerGas`: `bigint`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"eip7702"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `number`; })\[] : `` `0x${string}` ``\[]; `transactionsRoot`: `` `0x${string}` ``; `uncles`: `` `0x${string}` ``\[]; `withdrawals`: `Withdrawal`\[]; `withdrawalsRoot`: `` `0x${string}` ``; }>

Information about the block. GetBlockReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const block = await client.getBlock()
```

##### getBlockNumber()

> **getBlockNumber**: (`args`?) => `Promise`\<`bigint`>

Returns the number of the most recent block seen.

* Docs: [https://viem.sh/docs/actions/public/getBlockNumber](https://viem.sh/docs/actions/public/getBlockNumber)
* Examples: [https://stackblitz.com/github/wevm/viem/tree/main/examples/blocks\_fetching-blocks](https://stackblitz.com/github/wevm/viem/tree/main/examples/blocks_fetching-blocks)
* JSON-RPC Methods: [`eth_blockNumber`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_blocknumber)

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args`? | `GetBlockNumberParameters` | GetBlockNumberParameters |

###### Returns

`Promise`\<`bigint`>

The number of the block. GetBlockNumberReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const blockNumber = await client.getBlockNumber()
// 69420n
```

##### getBlockTransactionCount()

> **getBlockTransactionCount**: (`args`?) => `Promise`\<`number`>

Returns the number of Transactions at a block number, hash, or tag.

* Docs: [https://viem.sh/docs/actions/public/getBlockTransactionCount](https://viem.sh/docs/actions/public/getBlockTransactionCount)
* JSON-RPC Methods:
  * Calls [`eth_getBlockTransactionCountByNumber`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getblocktransactioncountbynumber) for `blockNumber` & `blockTag`.
  * Calls [`eth_getBlockTransactionCountByHash`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getblocktransactioncountbyhash) for `blockHash`.

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args`? | `GetBlockTransactionCountParameters` | GetBlockTransactionCountParameters |

###### Returns

`Promise`\<`number`>

The block transaction count. GetBlockTransactionCountReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const count = await client.getBlockTransactionCount()
```

##### ~~getBytecode()~~

> **getBytecode**: (`args`) => `Promise`\<`GetCodeReturnType`>

###### Parameters

| Parameter | Type |
| - | - |
| `args` | `GetCodeParameters` |

###### Returns

`Promise`\<`GetCodeReturnType`>

###### Deprecated

Use `getCode` instead.

##### getChainId()

> **getChainId**: () => `Promise`\<`number`>

Returns the chain ID associated with the current network.

* Docs: [https://viem.sh/docs/actions/public/getChainId](https://viem.sh/docs/actions/public/getChainId)
* JSON-RPC Methods: [`eth_chainId`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_chainid)

###### Returns

`Promise`\<`number`>

The current chain ID. GetChainIdReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const chainId = await client.getChainId()
// 1
```

##### getCode()

> **getCode**: (`args`) => `Promise`\<`GetCodeReturnType`>

Retrieves the bytecode at an address.

* Docs: [https://viem.sh/docs/contract/getCode](https://viem.sh/docs/contract/getCode)
* JSON-RPC Methods: [`eth_getCode`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getcode)

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `GetCodeParameters` | GetBytecodeParameters |

###### Returns

`Promise`\<`GetCodeReturnType`>

The contract's bytecode. GetBytecodeReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const code = await client.getCode({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
})
```

##### getContractEvents()

> **getContractEvents**: \<`abi`, `eventName`, `strict`, `fromBlock`, `toBlock`>(`args`) => `Promise`\<`GetContractEventsReturnType`\<`abi`, `eventName`, `strict`, `fromBlock`, `toBlock`>>

Returns a list of event logs emitted by a contract.

* Docs: [https://viem.sh/docs/actions/public/getContractEvents](https://viem.sh/docs/actions/public/getContractEvents)
* JSON-RPC Methods: [`eth_getLogs`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getlogs)

###### Type Parameters

| Type Parameter | Default type |
| - | - |
| `abi` *extends* readonly `unknown`\[] \| `Abi` | - |
| `eventName` *extends* `string` \| `undefined` | `undefined` |
| `strict` *extends* `boolean` \| `undefined` | `undefined` |
| `fromBlock` *extends* `bigint` \| `BlockTag` \| `undefined` | `undefined` |
| `toBlock` *extends* `bigint` \| `BlockTag` \| `undefined` | `undefined` |

###### Parameters

| Parameter | Type |
| - | - |
| `args` | `GetContractEventsParameters`\<`abi`, `eventName`, `strict`, `fromBlock`, `toBlock`> |

###### Returns

`Promise`\<`GetContractEventsReturnType`\<`abi`, `eventName`, `strict`, `fromBlock`, `toBlock`>>

A list of event logs. GetContractEventsReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'
import { wagmiAbi } from './abi'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const logs = await client.getContractEvents(client, {
 address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
 abi: wagmiAbi,
 eventName: 'Transfer'
})
```

##### getEip712Domain()

> **getEip712Domain**: (`args`) => `Promise`\<`GetEip712DomainReturnType`>

Reads the EIP-712 domain from a contract, based on the ERC-5267 specification.

###### Parameters

| Parameter | Type |
| - | - |
| `args` | `GetEip712DomainParameters` |

###### Returns

`Promise`\<`GetEip712DomainReturnType`>

The EIP-712 domain, fields, and extensions. GetEip712DomainReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})

const domain = await client.getEip712Domain({
  address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
})
// {
//   domain: {
//     name: 'ExampleContract',
//     version: '1',
//     chainId: 1,
//     verifyingContract: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
//   },
//   fields: '0x0f',
//   extensions: [],
// }
```

##### getEnsAddress()

> **getEnsAddress**: (`args`) => `Promise`\<`GetEnsAddressReturnType`>

Gets address for ENS name.

* Docs: [https://viem.sh/docs/ens/actions/getEnsAddress](https://viem.sh/docs/ens/actions/getEnsAddress)
* Examples: [https://stackblitz.com/github/wevm/viem/tree/main/examples/ens](https://stackblitz.com/github/wevm/viem/tree/main/examples/ens)

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | \{ `blockNumber`: `bigint`; `blockTag`: `BlockTag`; `coinType`: `number`; `gatewayUrls`: `string`\[]; `name`: `string`; `strict`: `boolean`; `universalResolverAddress`: `` `0x${string}` ``; } | GetEnsAddressParameters |
| `args.blockNumber`? | `bigint` | The balance of the account at a block number. |
| `args.blockTag`? | `BlockTag` | The balance of the account at a block tag. **Default** `'latest'` |
| `args.coinType`? | `number` | ENSIP-9 compliant coinType used to resolve addresses for other chains |
| `args.gatewayUrls`? | `string`\[] | Universal Resolver gateway URLs to use for resolving CCIP-read requests. |
| `args.name` | `string` | Name to get the address for. |
| `args.strict`? | `boolean` | Whether or not to throw errors propagated from the ENS Universal Resolver Contract. |
| `args.universalResolverAddress`? | `` `0x${string}` `` | Address of ENS Universal Resolver Contract. |

###### Returns

`Promise`\<`GetEnsAddressReturnType`>

Address for ENS name or `null` if not found. GetEnsAddressReturnType

###### Remarks

Calls `resolve(bytes, bytes)` on ENS Universal Resolver Contract.

Since ENS names prohibit certain forbidden characters (e.g. underscore) and have other validation rules, you likely want to [normalize ENS names](https://docs.ens.domains/contract-api-reference/name-processing#normalising-names) with [UTS-46 normalization](https://unicode.org/reports/tr46) before passing them to `getEnsAddress`. You can use the built-in [`normalize`](https://viem.sh/docs/ens/utilities/normalize) function for this.

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'
import { normalize } from 'viem/ens'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const ensAddress = await client.getEnsAddress({
  name: normalize('wevm.eth'),
})
// '0xd2135CfB216b74109775236E36d4b433F1DF507B'
```

##### getEnsAvatar()

> **getEnsAvatar**: (`args`) => `Promise`\<`GetEnsAvatarReturnType`>

Gets the avatar of an ENS name.

* Docs: [https://viem.sh/docs/ens/actions/getEnsAvatar](https://viem.sh/docs/ens/actions/getEnsAvatar)
* Examples: [https://stackblitz.com/github/wevm/viem/tree/main/examples/ens](https://stackblitz.com/github/wevm/viem/tree/main/examples/ens)

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | \{ `assetGatewayUrls`: `AssetGatewayUrls`; `blockNumber`: `bigint`; `blockTag`: `BlockTag`; `gatewayUrls`: `string`\[]; `name`: `string`; `strict`: `boolean`; `universalResolverAddress`: `` `0x${string}` ``; } | GetEnsAvatarParameters |
| `args.assetGatewayUrls`? | `AssetGatewayUrls` | Gateway urls to resolve IPFS and/or Arweave assets. |
| `args.blockNumber`? | `bigint` | The balance of the account at a block number. |
| `args.blockTag`? | `BlockTag` | The balance of the account at a block tag. **Default** `'latest'` |
| `args.gatewayUrls`? | `string`\[] | Universal Resolver gateway URLs to use for resolving CCIP-read requests. |
| `args.name` | `string` | ENS name to get Text for. |
| `args.strict`? | `boolean` | Whether or not to throw errors propagated from the ENS Universal Resolver Contract. |
| `args.universalResolverAddress`? | `` `0x${string}` `` | Address of ENS Universal Resolver Contract. |

###### Returns

`Promise`\<`GetEnsAvatarReturnType`>

Avatar URI or `null` if not found. GetEnsAvatarReturnType

###### Remarks

Calls [`getEnsText`](https://viem.sh/docs/ens/actions/getEnsText) with `key` set to `'avatar'`.

Since ENS names prohibit certain forbidden characters (e.g. underscore) and have other validation rules, you likely want to [normalize ENS names](https://docs.ens.domains/contract-api-reference/name-processing#normalising-names) with [UTS-46 normalization](https://unicode.org/reports/tr46) before passing them to `getEnsAddress`. You can use the built-in [`normalize`](https://viem.sh/docs/ens/utilities/normalize) function for this.

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'
import { normalize } from 'viem/ens'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const ensAvatar = await client.getEnsAvatar({
  name: normalize('wevm.eth'),
})
// 'https://ipfs.io/ipfs/Qma8mnp6xV3J2cRNf3mTth5C8nV11CAnceVinc3y8jSbio'
```

##### getEnsName()

> **getEnsName**: (`args`) => `Promise`\<`GetEnsNameReturnType`>

Gets primary name for specified address.

* Docs: [https://viem.sh/docs/ens/actions/getEnsName](https://viem.sh/docs/ens/actions/getEnsName)
* Examples: [https://stackblitz.com/github/wevm/viem/tree/main/examples/ens](https://stackblitz.com/github/wevm/viem/tree/main/examples/ens)

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | \{ `address`: `` `0x${string}` ``; `blockNumber`: `bigint`; `blockTag`: `BlockTag`; `gatewayUrls`: `string`\[]; `strict`: `boolean`; `universalResolverAddress`: `` `0x${string}` ``; } | GetEnsNameParameters |
| `args.address` | `` `0x${string}` `` | Address to get ENS name for. |
| `args.blockNumber`? | `bigint` | The balance of the account at a block number. |
| `args.blockTag`? | `BlockTag` | The balance of the account at a block tag. **Default** `'latest'` |
| `args.gatewayUrls`? | `string`\[] | Universal Resolver gateway URLs to use for resolving CCIP-read requests. |
| `args.strict`? | `boolean` | Whether or not to throw errors propagated from the ENS Universal Resolver Contract. |
| `args.universalResolverAddress`? | `` `0x${string}` `` | Address of ENS Universal Resolver Contract. |

###### Returns

`Promise`\<`GetEnsNameReturnType`>

Name or `null` if not found. GetEnsNameReturnType

###### Remarks

Calls `reverse(bytes)` on ENS Universal Resolver Contract to "reverse resolve" the address to the primary ENS name.

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const ensName = await client.getEnsName({
  address: '0xd2135CfB216b74109775236E36d4b433F1DF507B',
})
// 'wevm.eth'
```

##### getEnsResolver()

> **getEnsResolver**: (`args`) => `Promise`\<`` `0x${string}` ``>

Gets resolver for ENS name.

* Docs: [https://viem.sh/docs/ens/actions/getEnsResolver](https://viem.sh/docs/ens/actions/getEnsResolver)
* Examples: [https://stackblitz.com/github/wevm/viem/tree/main/examples/ens](https://stackblitz.com/github/wevm/viem/tree/main/examples/ens)

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | \{ `blockNumber`: `bigint`; `blockTag`: `BlockTag`; `name`: `string`; `universalResolverAddress`: `` `0x${string}` ``; } | GetEnsResolverParameters |
| `args.blockNumber`? | `bigint` | The balance of the account at a block number. |
| `args.blockTag`? | `BlockTag` | The balance of the account at a block tag. **Default** `'latest'` |
| `args.name` | `string` | Name to get the address for. |
| `args.universalResolverAddress`? | `` `0x${string}` `` | Address of ENS Universal Resolver Contract. |

###### Returns

`Promise`\<`` `0x${string}` ``>

Address for ENS resolver. GetEnsResolverReturnType

###### Remarks

Calls `findResolver(bytes)` on ENS Universal Resolver Contract to retrieve the resolver of an ENS name.

Since ENS names prohibit certain forbidden characters (e.g. underscore) and have other validation rules, you likely want to [normalize ENS names](https://docs.ens.domains/contract-api-reference/name-processing#normalising-names) with [UTS-46 normalization](https://unicode.org/reports/tr46) before passing them to `getEnsAddress`. You can use the built-in [`normalize`](https://viem.sh/docs/ens/utilities/normalize) function for this.

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'
import { normalize } from 'viem/ens'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const resolverAddress = await client.getEnsResolver({
  name: normalize('wevm.eth'),
})
// '0x4976fb03C32e5B8cfe2b6cCB31c09Ba78EBaBa41'
```

##### getEnsText()

> **getEnsText**: (`args`) => `Promise`\<`GetEnsTextReturnType`>

Gets a text record for specified ENS name.

* Docs: [https://viem.sh/docs/ens/actions/getEnsResolver](https://viem.sh/docs/ens/actions/getEnsResolver)
* Examples: [https://stackblitz.com/github/wevm/viem/tree/main/examples/ens](https://stackblitz.com/github/wevm/viem/tree/main/examples/ens)

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | \{ `blockNumber`: `bigint`; `blockTag`: `BlockTag`; `gatewayUrls`: `string`\[]; `key`: `string`; `name`: `string`; `strict`: `boolean`; `universalResolverAddress`: `` `0x${string}` ``; } | GetEnsTextParameters |
| `args.blockNumber`? | `bigint` | The balance of the account at a block number. |
| `args.blockTag`? | `BlockTag` | The balance of the account at a block tag. **Default** `'latest'` |
| `args.gatewayUrls`? | `string`\[] | Universal Resolver gateway URLs to use for resolving CCIP-read requests. |
| `args.key` | `string` | Text record to retrieve. |
| `args.name` | `string` | ENS name to get Text for. |
| `args.strict`? | `boolean` | Whether or not to throw errors propagated from the ENS Universal Resolver Contract. |
| `args.universalResolverAddress`? | `` `0x${string}` `` | Address of ENS Universal Resolver Contract. |

###### Returns

`Promise`\<`GetEnsTextReturnType`>

Address for ENS resolver. GetEnsTextReturnType

###### Remarks

Calls `resolve(bytes, bytes)` on ENS Universal Resolver Contract.

Since ENS names prohibit certain forbidden characters (e.g. underscore) and have other validation rules, you likely want to [normalize ENS names](https://docs.ens.domains/contract-api-reference/name-processing#normalising-names) with [UTS-46 normalization](https://unicode.org/reports/tr46) before passing them to `getEnsAddress`. You can use the built-in [`normalize`](https://viem.sh/docs/ens/utilities/normalize) function for this.

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'
import { normalize } from 'viem/ens'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const twitterRecord = await client.getEnsText({
  name: normalize('wevm.eth'),
  key: 'com.twitter',
})
// 'wevm_dev'
```

##### getFeeHistory()

> **getFeeHistory**: (`args`) => `Promise`\<`GetFeeHistoryReturnType`>

Returns a collection of historical gas information.

* Docs: [https://viem.sh/docs/actions/public/getFeeHistory](https://viem.sh/docs/actions/public/getFeeHistory)
* JSON-RPC Methods: [`eth_feeHistory`](https://docs.alchemy.com/reference/eth-feehistory)

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `GetFeeHistoryParameters` | GetFeeHistoryParameters |

###### Returns

`Promise`\<`GetFeeHistoryReturnType`>

The gas estimate (in wei). GetFeeHistoryReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const feeHistory = await client.getFeeHistory({
  blockCount: 4,
  rewardPercentiles: [25, 75],
})
```

##### getFilterChanges()

> **getFilterChanges**: \<`filterType`, `abi`, `eventName`, `strict`, `fromBlock`, `toBlock`>(`args`) => `Promise`\<`GetFilterChangesReturnType`\<`filterType`, `abi`, `eventName`, `strict`, `fromBlock`, `toBlock`>>

Returns a list of logs or hashes based on a [Filter](https://viem.sh/docs/glossary/terms#filter) since the last time it was called.

* Docs: [https://viem.sh/docs/actions/public/getFilterChanges](https://viem.sh/docs/actions/public/getFilterChanges)
* JSON-RPC Methods: [`eth_getFilterChanges`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getfilterchanges)

###### Type Parameters

| Type Parameter | Default type |
| - | - |
| `filterType` *extends* `FilterType` | - |
| `abi` *extends* readonly `unknown`\[] \| `Abi` \| `undefined` | - |
| `eventName` *extends* `string` \| `undefined` | - |
| `strict` *extends* `boolean` \| `undefined` | `undefined` |
| `fromBlock` *extends* `bigint` \| `BlockTag` \| `undefined` | `undefined` |
| `toBlock` *extends* `bigint` \| `BlockTag` \| `undefined` | `undefined` |

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `GetFilterChangesParameters`\<`filterType`, `abi`, `eventName`, `strict`, `fromBlock`, `toBlock`> | GetFilterChangesParameters |

###### Returns

`Promise`\<`GetFilterChangesReturnType`\<`filterType`, `abi`, `eventName`, `strict`, `fromBlock`, `toBlock`>>

Logs or hashes. GetFilterChangesReturnType

###### Remarks

A Filter can be created from the following actions:

* [`createBlockFilter`](https://viem.sh/docs/actions/public/createBlockFilter)
* [`createContractEventFilter`](https://viem.sh/docs/contract/createContractEventFilter)
* [`createEventFilter`](https://viem.sh/docs/actions/public/createEventFilter)
* [`createPendingTransactionFilter`](https://viem.sh/docs/actions/public/createPendingTransactionFilter)

Depending on the type of filter, the return value will be different:

* If the filter was created with `createContractEventFilter` or `createEventFilter`, it returns a list of logs.
* If the filter was created with `createPendingTransactionFilter`, it returns a list of transaction hashes.
* If the filter was created with `createBlockFilter`, it returns a list of block hashes.

###### Examples

```ts theme={null}
// Blocks
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const filter = await client.createBlockFilter()
const hashes = await client.getFilterChanges({ filter })
```

```ts theme={null}
// Contract Events
import { createPublicClient, http, parseAbi } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const filter = await client.createContractEventFilter({
  address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
  abi: parseAbi(['event Transfer(address indexed, address indexed, uint256)']),
  eventName: 'Transfer',
})
const logs = await client.getFilterChanges({ filter })
```

```ts theme={null}
// Raw Events
import { createPublicClient, http, parseAbiItem } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const filter = await client.createEventFilter({
  address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
  event: parseAbiItem('event Transfer(address indexed, address indexed, uint256)'),
})
const logs = await client.getFilterChanges({ filter })
```

```ts theme={null}
// Transactions
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const filter = await client.createPendingTransactionFilter()
const hashes = await client.getFilterChanges({ filter })
```

##### getFilterLogs()

> **getFilterLogs**: \<`abi`, `eventName`, `strict`, `fromBlock`, `toBlock`>(`args`) => `Promise`\<`GetFilterLogsReturnType`\<`abi`, `eventName`, `strict`, `fromBlock`, `toBlock`>>

Returns a list of event logs since the filter was created.

* Docs: [https://viem.sh/docs/actions/public/getFilterLogs](https://viem.sh/docs/actions/public/getFilterLogs)
* JSON-RPC Methods: [`eth_getFilterLogs`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getfilterlogs)

###### Type Parameters

| Type Parameter | Default type |
| - | - |
| `abi` *extends* readonly `unknown`\[] \| `Abi` \| `undefined` | - |
| `eventName` *extends* `string` \| `undefined` | - |
| `strict` *extends* `boolean` \| `undefined` | `undefined` |
| `fromBlock` *extends* `bigint` \| `BlockTag` \| `undefined` | `undefined` |
| `toBlock` *extends* `bigint` \| `BlockTag` \| `undefined` | `undefined` |

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `GetFilterLogsParameters`\<`abi`, `eventName`, `strict`, `fromBlock`, `toBlock`> | GetFilterLogsParameters |

###### Returns

`Promise`\<`GetFilterLogsReturnType`\<`abi`, `eventName`, `strict`, `fromBlock`, `toBlock`>>

A list of event logs. GetFilterLogsReturnType

###### Remarks

`getFilterLogs` is only compatible with **event filters**.

###### Example

```ts theme={null}
import { createPublicClient, http, parseAbiItem } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const filter = await client.createEventFilter({
  address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
  event: parseAbiItem('event Transfer(address indexed, address indexed, uint256)'),
})
const logs = await client.getFilterLogs({ filter })
```

##### getGasPrice()

> **getGasPrice**: () => `Promise`\<`bigint`>

Returns the current price of gas (in wei).

* Docs: [https://viem.sh/docs/actions/public/getGasPrice](https://viem.sh/docs/actions/public/getGasPrice)
* JSON-RPC Methods: [`eth_gasPrice`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_gasprice)

###### Returns

`Promise`\<`bigint`>

The gas price (in wei). GetGasPriceReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const gasPrice = await client.getGasPrice()
```

##### getLogs()

> **getLogs**: \<`abiEvent`, `abiEvents`, `strict`, `fromBlock`, `toBlock`>(`args`?) => `Promise`\<`GetLogsReturnType`\<`abiEvent`, `abiEvents`, `strict`, `fromBlock`, `toBlock`>>

Returns a list of event logs matching the provided parameters.

* Docs: [https://viem.sh/docs/actions/public/getLogs](https://viem.sh/docs/actions/public/getLogs)
* Examples: [https://stackblitz.com/github/wevm/viem/tree/main/examples/logs\_event-logs](https://stackblitz.com/github/wevm/viem/tree/main/examples/logs_event-logs)
* JSON-RPC Methods: [`eth_getLogs`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getlogs)

###### Type Parameters

| Type Parameter | Default type |
| - | - |
| `abiEvent` *extends* `AbiEvent` \| `undefined` | `undefined` |
| `abiEvents` *extends* readonly `unknown`\[] \| readonly `AbiEvent`\[] \| `undefined` | `abiEvent` *extends* `AbiEvent` ? \[`abiEvent`] : `undefined` |
| `strict` *extends* `boolean` \| `undefined` | `undefined` |
| `fromBlock` *extends* `bigint` \| `BlockTag` \| `undefined` | `undefined` |
| `toBlock` *extends* `bigint` \| `BlockTag` \| `undefined` | `undefined` |

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args`? | `GetLogsParameters`\<`abiEvent`, `abiEvents`, `strict`, `fromBlock`, `toBlock`> | GetLogsParameters |

###### Returns

`Promise`\<`GetLogsReturnType`\<`abiEvent`, `abiEvents`, `strict`, `fromBlock`, `toBlock`>>

A list of event logs. GetLogsReturnType

###### Example

```ts theme={null}
import { createPublicClient, http, parseAbiItem } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const logs = await client.getLogs()
```

##### getProof()

> **getProof**: (`args`) => `Promise`\<`GetProofReturnType`>

Returns the account and storage values of the specified account including the Merkle-proof.

* Docs: [https://viem.sh/docs/actions/public/getProof](https://viem.sh/docs/actions/public/getProof)
* JSON-RPC Methods:
  * Calls [`eth_getProof`](https://eips.ethereum.org/EIPS/eip-1186)

###### Parameters

| Parameter | Type |
| - | - |
| `args` | `GetProofParameters` |

###### Returns

`Promise`\<`GetProofReturnType`>

Proof data. GetProofReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const block = await client.getProof({
 address: '0x...',
 storageKeys: ['0x...'],
})
```

##### getStorageAt()

> **getStorageAt**: (`args`) => `Promise`\<`GetStorageAtReturnType`>

Returns the value from a storage slot at a given address.

* Docs: [https://viem.sh/docs/contract/getStorageAt](https://viem.sh/docs/contract/getStorageAt)
* JSON-RPC Methods: [`eth_getStorageAt`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getstorageat)

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `GetStorageAtParameters` | GetStorageAtParameters |

###### Returns

`Promise`\<`GetStorageAtReturnType`>

The value of the storage slot. GetStorageAtReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'
import { getStorageAt } from 'viem/contract'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const code = await client.getStorageAt({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  slot: toHex(0),
})
```

##### getTransaction()

> **getTransaction**: \<`blockTag`>(`args`) => `Promise`\<\{ `accessList`: `undefined`; `authorizationList`: `undefined`; `blobVersionedHashes`: `undefined`; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `bigint`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `undefined`; `maxPriorityFeePerGas`: `undefined`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"legacy"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `undefined`; } | \{ `accessList`: `AccessList`; `authorizationList`: `undefined`; `blobVersionedHashes`: `undefined`; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `bigint`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `undefined`; `maxPriorityFeePerGas`: `undefined`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"eip2930"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `number`; } | \{ `accessList`: `AccessList`; `authorizationList`: `undefined`; `blobVersionedHashes`: `undefined`; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `undefined`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `bigint`; `maxPriorityFeePerGas`: `bigint`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"eip1559"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `number`; } | \{ `accessList`: `AccessList`; `authorizationList`: `undefined`; `blobVersionedHashes`: readonly `` `0x${string}` ``\[]; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `undefined`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `bigint`; `maxFeePerGas`: `bigint`; `maxPriorityFeePerGas`: `bigint`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"eip4844"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `number`; } | \{ `accessList`: `AccessList`; `authorizationList`: `SignedAuthorizationList`; `blobVersionedHashes`: `undefined`; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `undefined`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `bigint`; `maxPriorityFeePerGas`: `bigint`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"eip7702"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `number`; }>

Returns information about a [Transaction](https://viem.sh/docs/glossary/terms#transaction) given a hash or block identifier.

* Docs: [https://viem.sh/docs/actions/public/getTransaction](https://viem.sh/docs/actions/public/getTransaction)
* Example: [https://stackblitz.com/github/wevm/viem/tree/main/examples/transactions\_fetching-transactions](https://stackblitz.com/github/wevm/viem/tree/main/examples/transactions_fetching-transactions)
* JSON-RPC Methods: [`eth_getTransactionByHash`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getTransactionByHash)

###### Type Parameters

| Type Parameter | Default type |
| - | - |
| `blockTag` *extends* `BlockTag` | `"latest"` |

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `GetTransactionParameters`\<`blockTag`> | GetTransactionParameters |

###### Returns

`Promise`\<\{ `accessList`: `undefined`; `authorizationList`: `undefined`; `blobVersionedHashes`: `undefined`; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `bigint`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `undefined`; `maxPriorityFeePerGas`: `undefined`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"legacy"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `undefined`; } | \{ `accessList`: `AccessList`; `authorizationList`: `undefined`; `blobVersionedHashes`: `undefined`; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `bigint`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `undefined`; `maxPriorityFeePerGas`: `undefined`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"eip2930"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `number`; } | \{ `accessList`: `AccessList`; `authorizationList`: `undefined`; `blobVersionedHashes`: `undefined`; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `undefined`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `bigint`; `maxPriorityFeePerGas`: `bigint`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"eip1559"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `number`; } | \{ `accessList`: `AccessList`; `authorizationList`: `undefined`; `blobVersionedHashes`: readonly `` `0x${string}` ``\[]; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `undefined`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `bigint`; `maxFeePerGas`: `bigint`; `maxPriorityFeePerGas`: `bigint`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"eip4844"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `number`; } | \{ `accessList`: `AccessList`; `authorizationList`: `SignedAuthorizationList`; `blobVersionedHashes`: `undefined`; `blockHash`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `` `0x${string}` ``; `blockNumber`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `bigint`; `chainId`: `number`; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `undefined`; `hash`: `` `0x${string}` ``; `input`: `` `0x${string}` ``; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `bigint`; `maxPriorityFeePerGas`: `bigint`; `nonce`: `number`; `r`: `` `0x${string}` ``; `s`: `` `0x${string}` ``; `to`: `` `0x${string}` `` | `null`; `transactionIndex`: `blockTag` *extends* `"pending"` ? `true` : `false` *extends* `true` ? `null` : `number`; `type`: `"eip7702"`; `typeHex`: `` `0x${string}` `` | `null`; `v`: `bigint`; `value`: `bigint`; `yParity`: `number`; }>

The transaction information. GetTransactionReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const transaction = await client.getTransaction({
  hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
})
```

##### getTransactionConfirmations()

> **getTransactionConfirmations**: (`args`) => `Promise`\<`bigint`>

Returns the number of blocks passed (confirmations) since the transaction was processed on a block.

* Docs: [https://viem.sh/docs/actions/public/getTransactionConfirmations](https://viem.sh/docs/actions/public/getTransactionConfirmations)
* Example: [https://stackblitz.com/github/wevm/viem/tree/main/examples/transactions\_fetching-transactions](https://stackblitz.com/github/wevm/viem/tree/main/examples/transactions_fetching-transactions)
* JSON-RPC Methods: [`eth_getTransactionConfirmations`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getTransactionConfirmations)

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `GetTransactionConfirmationsParameters`\<`Chain`> | GetTransactionConfirmationsParameters |

###### Returns

`Promise`\<`bigint`>

The number of blocks passed since the transaction was processed. If confirmations is 0, then the Transaction has not been confirmed & processed yet. GetTransactionConfirmationsReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const confirmations = await client.getTransactionConfirmations({
  hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
})
```

##### getTransactionCount()

> **getTransactionCount**: (`args`) => `Promise`\<`number`>

Returns the number of [Transactions](https://viem.sh/docs/glossary/terms#transaction) an Account has broadcast / sent.

* Docs: [https://viem.sh/docs/actions/public/getTransactionCount](https://viem.sh/docs/actions/public/getTransactionCount)
* JSON-RPC Methods: [`eth_getTransactionCount`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_gettransactioncount)

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `GetTransactionCountParameters` | GetTransactionCountParameters |

###### Returns

`Promise`\<`number`>

The number of transactions an account has sent. GetTransactionCountReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const transactionCount = await client.getTransactionCount({
  address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
})
```

##### getTransactionReceipt()

> **getTransactionReceipt**: (`args`) => `Promise`\<`TransactionReceipt`>

Returns the [Transaction Receipt](https://viem.sh/docs/glossary/terms#transaction-receipt) given a [Transaction](https://viem.sh/docs/glossary/terms#transaction) hash.

* Docs: [https://viem.sh/docs/actions/public/getTransactionReceipt](https://viem.sh/docs/actions/public/getTransactionReceipt)
* Example: [https://stackblitz.com/github/wevm/viem/tree/main/examples/transactions\_fetching-transactions](https://stackblitz.com/github/wevm/viem/tree/main/examples/transactions_fetching-transactions)
* JSON-RPC Methods: [`eth_getTransactionReceipt`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getTransactionReceipt)

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `GetTransactionReceiptParameters` | GetTransactionReceiptParameters |

###### Returns

`Promise`\<`TransactionReceipt`>

The transaction receipt. GetTransactionReceiptReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const transactionReceipt = await client.getTransactionReceipt({
  hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
})
```

##### key

> **key**: `string`

A key for the client.

##### multicall()

> **multicall**: \<`contracts`, `allowFailure`>(`args`) => `Promise`\<`MulticallReturnType`\<`contracts`, `allowFailure`>>

Similar to [`readContract`](https://viem.sh/docs/contract/readContract), but batches up multiple functions on a contract in a single RPC call via the [`multicall3` contract](https://github.com/mds1/multicall).

* Docs: [https://viem.sh/docs/contract/multicall](https://viem.sh/docs/contract/multicall)

###### Type Parameters

| Type Parameter | Default type |
| - | - |
| `contracts` *extends* readonly `unknown`\[] | - |
| `allowFailure` *extends* `boolean` | `true` |

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `MulticallParameters`\<`contracts`, `allowFailure`> | MulticallParameters |

###### Returns

`Promise`\<`MulticallReturnType`\<`contracts`, `allowFailure`>>

An array of results with accompanying status. MulticallReturnType

###### Example

```ts theme={null}
import { createPublicClient, http, parseAbi } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const abi = parseAbi([
  'function balanceOf(address) view returns (uint256)',
  'function totalSupply() view returns (uint256)',
])
const result = await client.multicall({
  contracts: [
    {
      address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
      abi,
      functionName: 'balanceOf',
      args: ['0xA0Cf798816D4b9b9866b5330EEa46a18382f251e'],
    },
    {
      address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
      abi,
      functionName: 'totalSupply',
    },
  ],
})
// [{ result: 424122n, status: 'success' }, { result: 1000000n, status: 'success' }]
```

##### name

> **name**: `string`

A name for the client.

##### pollingInterval

> **pollingInterval**: `number`

Frequency (in ms) for polling enabled actions & events. Defaults to 4\_000 milliseconds.

##### prepareTransactionRequest()

> **prepareTransactionRequest**: \<`request`, `chainOverride`, `accountOverride`>(`args`) => `Promise`\<\{ \[K in string | number | symbol]: (UnionRequiredBy\<Extract\<UnionOmit\<(...), (...)> & ((...) extends (...) ? (...) : (...)) & ((...) extends (...) ? (...) : (...)), IsNever\<(...)> extends true ? unknown : ExactPartial\<(...)>> & \{ chainId?: number }, ParameterTypeToParameters\<request\["parameters"] extends readonly PrepareTransactionRequestParameterType\[] ? any\[any]\[number] : "fees" | "gas" | "nonce" | "blobVersionedHashes" | "chainId" | "type">> & (unknown extends request\["kzg"] ? \{} : Pick\<request, "kzg">))\[K] }>

Prepares a transaction request for signing.

* Docs: [https://viem.sh/docs/actions/wallet/prepareTransactionRequest](https://viem.sh/docs/actions/wallet/prepareTransactionRequest)

###### Type Parameters

| Type Parameter | Default type |
| - | - |
| `request` *extends* `Omit`\<\{ `accessList`: `undefined`; `authorizationList`: `undefined`; `blobs`: `undefined`; `blobVersionedHashes`: `undefined`; `data`: `` `0x${string}` ``; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `bigint`; `kzg`: `undefined`; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `undefined`; `maxPriorityFeePerGas`: `undefined`; `nonce`: `number`; `sidecars`: `undefined`; `to`: `` `0x${string}` `` \| `null`; `type`: `"legacy"`; `value`: `bigint`; }, `"from"`> \| `Omit`\<\{ `accessList`: `AccessList`; `authorizationList`: `undefined`; `blobs`: `undefined`; `blobVersionedHashes`: `undefined`; `data`: `` `0x${string}` ``; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `bigint`; `kzg`: `undefined`; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `undefined`; `maxPriorityFeePerGas`: `undefined`; `nonce`: `number`; `sidecars`: `undefined`; `to`: `` `0x${string}` `` \| `null`; `type`: `"eip2930"`; `value`: `bigint`; }, `"from"`> \| `Omit`\<\{ `accessList`: `AccessList`; `authorizationList`: `undefined`; `blobs`: `undefined`; `blobVersionedHashes`: `undefined`; `data`: `` `0x${string}` ``; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `undefined`; `kzg`: `undefined`; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `bigint`; `maxPriorityFeePerGas`: `bigint`; `nonce`: `number`; `sidecars`: `undefined`; `to`: `` `0x${string}` `` \| `null`; `type`: `"eip1559"`; `value`: `bigint`; }, `"from"`> \| `Omit`\<\{ `accessList`: `AccessList`; `authorizationList`: `undefined`; `blobs`: readonly `` `0x${string}` ``\[] \| readonly `ByteArray`\[]; `blobVersionedHashes`: readonly `` `0x${string}` ``\[]; `data`: `` `0x${string}` ``; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `undefined`; `kzg`: `Kzg`; `maxFeePerBlobGas`: `bigint`; `maxFeePerGas`: `bigint`; `maxPriorityFeePerGas`: `bigint`; `nonce`: `number`; `sidecars`: readonly `BlobSidecar`\<`` `0x${string}` ``>\[]; `to`: `` `0x${string}` `` \| `null`; `type`: `"eip4844"`; `value`: `bigint`; }, `"from"`> \| `Omit`\<\{ `accessList`: `AccessList`; `authorizationList`: `AuthorizationList`\<`number`, `boolean`>; `blobs`: `undefined`; `blobVersionedHashes`: `undefined`; `data`: `` `0x${string}` ``; `from`: `` `0x${string}` ``; `gas`: `bigint`; `gasPrice`: `undefined`; `kzg`: `undefined`; `maxFeePerBlobGas`: `undefined`; `maxFeePerGas`: `bigint`; `maxPriorityFeePerGas`: `bigint`; `nonce`: `number`; `sidecars`: `undefined`; `to`: `` `0x${string}` `` \| `null`; `type`: `"eip7702"`; `value`: `bigint`; }, `"from"`> & `object` & `object` | - |
| `chainOverride` *extends* `Chain` \| `undefined` | `undefined` |
| `accountOverride` *extends* `` `0x${string}` `` \| `Account` \| `undefined` | `undefined` |

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `PrepareTransactionRequestParameters`\<`Chain`, `Account` \| `undefined`, `chainOverride`, `accountOverride`, `request`> | PrepareTransactionRequestParameters |

###### Returns

`Promise`\<\{ \[K in string | number | symbol]: (UnionRequiredBy\<Extract\<UnionOmit\<(...), (...)> & ((...) extends (...) ? (...) : (...)) & ((...) extends (...) ? (...) : (...)), IsNever\<(...)> extends true ? unknown : ExactPartial\<(...)>> & \{ chainId?: number }, ParameterTypeToParameters\<request\["parameters"] extends readonly PrepareTransactionRequestParameterType\[] ? any\[any]\[number] : "fees" | "gas" | "nonce" | "blobVersionedHashes" | "chainId" | "type">> & (unknown extends request\["kzg"] ? \{} : Pick\<request, "kzg">))\[K] }>

The transaction request. PrepareTransactionRequestReturnType

###### Examples

```ts theme={null}
import { createWalletClient, custom } from 'viem'
import { mainnet } from 'viem/chains'

const client = createWalletClient({
  chain: mainnet,
  transport: custom(window.ethereum),
})
const request = await client.prepareTransactionRequest({
  account: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
  to: '0x0000000000000000000000000000000000000000',
  value: 1n,
})
```

```ts theme={null}
// Account Hoisting
import { createWalletClient, http } from 'viem'
import { privateKeyToAccount } from 'viem/accounts'
import { mainnet } from 'viem/chains'

const client = createWalletClient({
  account: privateKeyToAccount('0x…'),
  chain: mainnet,
  transport: custom(window.ethereum),
})
const request = await client.prepareTransactionRequest({
  to: '0x0000000000000000000000000000000000000000',
  value: 1n,
})
```

##### readContract()

> **readContract**: \<`abi`, `functionName`, `args`>(`args`) => `Promise`\<`ReadContractReturnType`\<`abi`, `functionName`, `args`>>

Calls a read-only function on a contract, and returns the response.

* Docs: [https://viem.sh/docs/contract/readContract](https://viem.sh/docs/contract/readContract)
* Examples: [https://stackblitz.com/github/wevm/viem/tree/main/examples/contracts\_reading-contracts](https://stackblitz.com/github/wevm/viem/tree/main/examples/contracts_reading-contracts)

###### Type Parameters

| Type Parameter |
| - |
| `abi` *extends* readonly `unknown`\[] \| `Abi` |
| `functionName` *extends* `string` |
| `args` *extends* `unknown` |

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `ReadContractParameters`\<`abi`, `functionName`, `args`> | ReadContractParameters |

###### Returns

`Promise`\<`ReadContractReturnType`\<`abi`, `functionName`, `args`>>

The response from the contract. Type is inferred. ReadContractReturnType

###### Remarks

A "read-only" function (constant function) on a Solidity contract is denoted by a `view` or `pure` keyword. They can only read the state of the contract, and cannot make any changes to it. Since read-only methods do not change the state of the contract, they do not require any gas to be executed, and can be called by any user without the need to pay for gas.

Internally, uses a [Public Client](https://viem.sh/docs/clients/public) to call the [`call` action](https://viem.sh/docs/actions/public/call) with [ABI-encoded `data`](https://viem.sh/docs/contract/encodeFunctionData).

###### Example

```ts theme={null}
import { createPublicClient, http, parseAbi } from 'viem'
import { mainnet } from 'viem/chains'
import { readContract } from 'viem/contract'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const result = await client.readContract({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: parseAbi(['function balanceOf(address) view returns (uint256)']),
  functionName: 'balanceOf',
  args: ['0xA0Cf798816D4b9b9866b5330EEa46a18382f251e'],
})
// 424122n
```

##### request

> **request**: `EIP1193RequestFn`\<`PublicRpcSchema`>

Request function wrapped with friendly error handling

##### sendRawTransaction()

> **sendRawTransaction**: (`args`) => `Promise`\<`` `0x${string}` ``>

Sends a **signed** transaction to the network

* Docs: [https://viem.sh/docs/actions/wallet/sendRawTransaction](https://viem.sh/docs/actions/wallet/sendRawTransaction)
* JSON-RPC Method: [`eth_sendRawTransaction`](https://ethereum.github.io/execution-apis/api-documentation/)

###### Parameters

| Parameter | Type |
| - | - |
| `args` | `SendRawTransactionParameters` |

###### Returns

`Promise`\<`` `0x${string}` ``>

The transaction hash. SendRawTransactionReturnType

###### Example

```ts theme={null}
import { createWalletClient, custom } from 'viem'
import { mainnet } from 'viem/chains'
import { sendRawTransaction } from 'viem/wallet'

const client = createWalletClient({
  chain: mainnet,
  transport: custom(window.ethereum),
})

const hash = await client.sendRawTransaction({
  serializedTransaction: '0x02f850018203118080825208808080c080a04012522854168b27e5dc3d5839bab5e6b39e1a0ffd343901ce1622e3d64b48f1a04e00902ae0502c4728cbf12156290df99c3ed7de85b1dbfe20b5c36931733a33'
})
```

##### ~~simulate()~~

> **simulate**: \<`calls`>(`args`) => `Promise`\<`SimulateBlocksReturnType`\<`calls`>>

###### Type Parameters

| Type Parameter |
| - |
| `calls` *extends* readonly `unknown`\[] |

###### Parameters

| Parameter | Type |
| - | - |
| `args` | `SimulateBlocksParameters`\<`calls`> |

###### Returns

`Promise`\<`SimulateBlocksReturnType`\<`calls`>>

###### Deprecated

Use `simulateBlocks` instead.

##### simulateBlocks()

> **simulateBlocks**: \<`calls`>(`args`) => `Promise`\<`SimulateBlocksReturnType`\<`calls`>>

Simulates a set of calls on block(s) with optional block and state overrides.

###### Type Parameters

| Type Parameter |
| - |
| `calls` *extends* readonly `unknown`\[] |

###### Parameters

| Parameter | Type |
| - | - |
| `args` | `SimulateBlocksParameters`\<`calls`> |

###### Returns

`Promise`\<`SimulateBlocksReturnType`\<`calls`>>

Simulated blocks. SimulateReturnType

###### Example

```ts theme={null}
import { createPublicClient, http, parseEther } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})

const result = await client.simulateBlocks({
  blocks: [{
    blockOverrides: {
      number: 69420n,
    },
    calls: [{
      {
        account: '0x5a0b54d5dc17e482fe8b0bdca5320161b95fb929',
        data: '0xdeadbeef',
        to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
      },
      {
        account: '0x5a0b54d5dc17e482fe8b0bdca5320161b95fb929',
        to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
        value: parseEther('1'),
      },
    }],
    stateOverrides: [{
      address: '0x5a0b54d5dc17e482fe8b0bdca5320161b95fb929',
      balance: parseEther('10'),
    }],
  }]
})
```

##### simulateCalls()

> **simulateCalls**: \<`calls`>(`args`) => `Promise`\<`SimulateCallsReturnType`\<`calls`>>

Simulates a set of calls.

###### Type Parameters

| Type Parameter |
| - |
| `calls` *extends* readonly `unknown`\[] |

###### Parameters

| Parameter | Type |
| - | - |
| `args` | `SimulateCallsParameters`\<`calls`> |

###### Returns

`Promise`\<`SimulateCallsReturnType`\<`calls`>>

Results. SimulateCallsReturnType

###### Example

```ts theme={null}
import { createPublicClient, http, parseEther } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})

const result = await client.simulateCalls({
  account: '0x5a0b54d5dc17e482fe8b0bdca5320161b95fb929',
  calls: [{
    {
      data: '0xdeadbeef',
      to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
    },
    {
      to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
      value: parseEther('1'),
    },
  ]
})
```

##### simulateContract()

> **simulateContract**: \<`abi`, `functionName`, `args`, `chainOverride`, `accountOverride`>(`args`) => `Promise`\<`SimulateContractReturnType`\<`abi`, `functionName`, `args`, `Chain`, `Account` | `undefined`, `chainOverride`, `accountOverride`>>

Simulates/validates a contract interaction. This is useful for retrieving **return data** and **revert reasons** of contract write functions.

* Docs: [https://viem.sh/docs/contract/simulateContract](https://viem.sh/docs/contract/simulateContract)
* Examples: [https://stackblitz.com/github/wevm/viem/tree/main/examples/contracts\_writing-to-contracts](https://stackblitz.com/github/wevm/viem/tree/main/examples/contracts_writing-to-contracts)

###### Type Parameters

| Type Parameter | Default type |
| - | - |
| `abi` *extends* readonly `unknown`\[] \| `Abi` | - |
| `functionName` *extends* `string` | - |
| `args` *extends* `unknown` | - |
| `chainOverride` *extends* `Chain` \| `undefined` | - |
| `accountOverride` *extends* `` `0x${string}` `` \| `Account` \| `undefined` | `undefined` |

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `SimulateContractParameters`\<`abi`, `functionName`, `args`, `Chain`, `chainOverride`, `accountOverride`> | SimulateContractParameters |

###### Returns

`Promise`\<`SimulateContractReturnType`\<`abi`, `functionName`, `args`, `Chain`, `Account` | `undefined`, `chainOverride`, `accountOverride`>>

The simulation result and write request. SimulateContractReturnType

###### Remarks

This function does not require gas to execute and ***does not*** change the state of the blockchain. It is almost identical to [`readContract`](https://viem.sh/docs/contract/readContract), but also supports contract write functions.

Internally, uses a [Public Client](https://viem.sh/docs/clients/public) to call the [`call` action](https://viem.sh/docs/actions/public/call) with [ABI-encoded `data`](https://viem.sh/docs/contract/encodeFunctionData).

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const result = await client.simulateContract({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: parseAbi(['function mint(uint32) view returns (uint32)']),
  functionName: 'mint',
  args: ['69420'],
  account: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
})
```

##### transport

> **transport**: `TransportConfig`\<`"http"`, `EIP1193RequestFn`> & `object`

The RPC transport

###### Type Declaration

###### fetchOptions?

> `optional` **fetchOptions**: `Omit`\<`RequestInit`, `"body"`>

###### url?

> `optional` **url**: `string`

##### type

> **type**: `string`

The type of client.

##### uid

> **uid**: `string`

A unique ID for the client.

##### uninstallFilter()

> **uninstallFilter**: (`args`) => `Promise`\<`boolean`>

Destroys a Filter that was created from one of the following Actions:

* [`createBlockFilter`](https://viem.sh/docs/actions/public/createBlockFilter)

* [`createEventFilter`](https://viem.sh/docs/actions/public/createEventFilter)

* [`createPendingTransactionFilter`](https://viem.sh/docs/actions/public/createPendingTransactionFilter)

* Docs: [https://viem.sh/docs/actions/public/uninstallFilter](https://viem.sh/docs/actions/public/uninstallFilter)

* JSON-RPC Methods: [`eth_uninstallFilter`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_uninstallFilter)

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `UninstallFilterParameters` | UninstallFilterParameters |

###### Returns

`Promise`\<`boolean`>

A boolean indicating if the Filter was successfully uninstalled. UninstallFilterReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'
import { createPendingTransactionFilter, uninstallFilter } from 'viem/public'

const filter = await client.createPendingTransactionFilter()
const uninstalled = await client.uninstallFilter({ filter })
// true
```

##### verifyMessage()

> **verifyMessage**: (`args`) => `Promise`\<`boolean`>

Verify that a message was signed by the provided address.

Compatible with Smart Contract Accounts & Externally Owned Accounts via [ERC-6492](https://eips.ethereum.org/EIPS/eip-6492).

* Docs [https://viem.sh/docs/actions/public/verifyMessage](https://viem.sh/docs/actions/public/verifyMessage)

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | \{ `address`: `` `0x${string}` ``; `blockNumber`: `bigint`; `blockTag`: `BlockTag`; `factory`: `` `0x${string}` ``; `factoryData`: `` `0x${string}` ``; `message`: `SignableMessage`; `signature`: `` `0x${string}` `` \| `Signature` \| `ByteArray`; `universalSignatureVerifierAddress`: `` `0x${string}` ``; } | - |
| `args.address` | `` `0x${string}` `` | The address that signed the original message. |
| `args.blockNumber`? | `bigint` | The balance of the account at a block number. |
| `args.blockTag`? | `BlockTag` | The balance of the account at a block tag. **Default** `'latest'` |
| `args.factory`? | `` `0x${string}` `` | - |
| `args.factoryData`? | `` `0x${string}` `` | - |
| `args.message` | `SignableMessage` | The message to be verified. |
| `args.signature` | `` `0x${string}` `` \| `Signature` \| `ByteArray` | The signature that was generated by signing the message with the address's private key. |
| `args.universalSignatureVerifierAddress`? | `` `0x${string}` `` | - |

###### Returns

`Promise`\<`boolean`>

Whether or not the signature is valid. VerifyMessageReturnType

##### verifySiweMessage()

> **verifySiweMessage**: (`args`) => `Promise`\<`boolean`>

Verifies [EIP-4361](https://eips.ethereum.org/EIPS/eip-4361) formatted message was signed.

Compatible with Smart Contract Accounts & Externally Owned Accounts via [ERC-6492](https://eips.ethereum.org/EIPS/eip-6492).

* Docs [https://viem.sh/docs/siwe/actions/verifySiweMessage](https://viem.sh/docs/siwe/actions/verifySiweMessage)

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | \{ `address`: `` `0x${string}` ``; `blockNumber`: `bigint`; `blockTag`: `BlockTag`; `domain`: `string`; `message`: `string`; `nonce`: `string`; `scheme`: `string`; `signature`: `` `0x${string}` ``; `time`: `Date`; } | - |
| `args.address`? | `` `0x${string}` `` | Ethereum address to check against. |
| `args.blockNumber`? | `bigint` | The balance of the account at a block number. |
| `args.blockTag`? | `BlockTag` | The balance of the account at a block tag. **Default** `'latest'` |
| `args.domain`? | `string` | [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986) authority to check against. |
| `args.message` | `string` | EIP-4361 formatted message. |
| `args.nonce`? | `string` | Random string to check against. |
| `args.scheme`? | `string` | [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) URI scheme to check against. |
| `args.signature` | `` `0x${string}` `` | Signature to check against. |
| `args.time`? | `Date` | Current time to check optional `expirationTime` and `notBefore` fields. **Default** `new Date()` |

###### Returns

`Promise`\<`boolean`>

Whether or not the signature is valid. VerifySiweMessageReturnType

##### verifyTypedData()

> **verifyTypedData**: (`args`) => `Promise`\<`boolean`>

Verify that typed data was signed by the provided address.

* Docs [https://viem.sh/docs/actions/public/verifyTypedData](https://viem.sh/docs/actions/public/verifyTypedData)

###### Parameters

| Parameter | Type |
| - | - |
| `args` | `VerifyTypedDataParameters` |

###### Returns

`Promise`\<`boolean`>

Whether or not the signature is valid. VerifyTypedDataReturnType

##### waitForTransactionReceipt()

> **waitForTransactionReceipt**: (`args`) => `Promise`\<`TransactionReceipt`>

Waits for the [Transaction](https://viem.sh/docs/glossary/terms#transaction) to be included on a [Block](https://viem.sh/docs/glossary/terms#block) (one confirmation), and then returns the [Transaction Receipt](https://viem.sh/docs/glossary/terms#transaction-receipt). If the Transaction reverts, then the action will throw an error.

* Docs: [https://viem.sh/docs/actions/public/waitForTransactionReceipt](https://viem.sh/docs/actions/public/waitForTransactionReceipt)
* Example: [https://stackblitz.com/github/wevm/viem/tree/main/examples/transactions\_sending-transactions](https://stackblitz.com/github/wevm/viem/tree/main/examples/transactions_sending-transactions)
* JSON-RPC Methods:
  * Polls [`eth_getTransactionReceipt`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getTransactionReceipt) on each block until it has been processed.
  * If a Transaction has been replaced:
    * Calls [`eth_getBlockByNumber`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getblockbynumber) and extracts the transactions
    * Checks if one of the Transactions is a replacement
    * If so, calls [`eth_getTransactionReceipt`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getTransactionReceipt).

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `WaitForTransactionReceiptParameters`\<`Chain`> | WaitForTransactionReceiptParameters |

###### Returns

`Promise`\<`TransactionReceipt`>

The transaction receipt. WaitForTransactionReceiptReturnType

###### Remarks

The `waitForTransactionReceipt` action additionally supports Replacement detection (e.g. sped up Transactions).

Transactions can be replaced when a user modifies their transaction in their wallet (to speed up or cancel). Transactions are replaced when they are sent from the same nonce.

There are 3 types of Transaction Replacement reasons:

* `repriced`: The gas price has been modified (e.g. different `maxFeePerGas`)
* `cancelled`: The Transaction has been cancelled (e.g. `value === 0n`)
* `replaced`: The Transaction has been replaced (e.g. different `value` or `data`)

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const transactionReceipt = await client.waitForTransactionReceipt({
  hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
})
```

##### watchBlockNumber()

> **watchBlockNumber**: (`args`) => `WatchBlockNumberReturnType`

Watches and returns incoming block numbers.

* Docs: [https://viem.sh/docs/actions/public/watchBlockNumber](https://viem.sh/docs/actions/public/watchBlockNumber)
* Examples: [https://stackblitz.com/github/wevm/viem/tree/main/examples/blocks\_watching-blocks](https://stackblitz.com/github/wevm/viem/tree/main/examples/blocks_watching-blocks)
* JSON-RPC Methods:
  * When `poll: true`, calls [`eth_blockNumber`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_blocknumber) on a polling interval.
  * When `poll: false` & WebSocket Transport, uses a WebSocket subscription via [`eth_subscribe`](https://docs.alchemy.com/reference/eth-subscribe-polygon) and the `"newHeads"` event.

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `WatchBlockNumberParameters` | WatchBlockNumberParameters |

###### Returns

`WatchBlockNumberReturnType`

A function that can be invoked to stop watching for new block numbers. WatchBlockNumberReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const unwatch = await client.watchBlockNumber({
  onBlockNumber: (blockNumber) => console.log(blockNumber),
})
```

##### watchBlocks()

> **watchBlocks**: \<`includeTransactions`, `blockTag`>(`args`) => `WatchBlocksReturnType`

Watches and returns information for incoming blocks.

* Docs: [https://viem.sh/docs/actions/public/watchBlocks](https://viem.sh/docs/actions/public/watchBlocks)
* Examples: [https://stackblitz.com/github/wevm/viem/tree/main/examples/blocks\_watching-blocks](https://stackblitz.com/github/wevm/viem/tree/main/examples/blocks_watching-blocks)
* JSON-RPC Methods:
  * When `poll: true`, calls [`eth_getBlockByNumber`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getBlockByNumber) on a polling interval.
  * When `poll: false` & WebSocket Transport, uses a WebSocket subscription via [`eth_subscribe`](https://docs.alchemy.com/reference/eth-subscribe-polygon) and the `"newHeads"` event.

###### Type Parameters

| Type Parameter | Default type |
| - | - |
| `includeTransactions` *extends* `boolean` | `false` |
| `blockTag` *extends* `BlockTag` | `"latest"` |

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `WatchBlocksParameters`\<`HttpTransport`, `Chain`, `includeTransactions`, `blockTag`> | WatchBlocksParameters |

###### Returns

`WatchBlocksReturnType`

A function that can be invoked to stop watching for new block numbers. WatchBlocksReturnType

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const unwatch = await client.watchBlocks({
  onBlock: (block) => console.log(block),
})
```

##### watchContractEvent()

> **watchContractEvent**: \<`abi`, `eventName`, `strict`>(`args`) => `WatchContractEventReturnType`

Watches and returns emitted contract event logs.

* Docs: [https://viem.sh/docs/contract/watchContractEvent](https://viem.sh/docs/contract/watchContractEvent)

###### Type Parameters

| Type Parameter | Default type |
| - | - |
| `abi` *extends* readonly `unknown`\[] \| `Abi` | - |
| `eventName` *extends* `string` | - |
| `strict` *extends* `boolean` \| `undefined` | `undefined` |

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `WatchContractEventParameters`\<`abi`, `eventName`, `strict`, `HttpTransport`> | WatchContractEventParameters |

###### Returns

`WatchContractEventReturnType`

A function that can be invoked to stop watching for new event logs. WatchContractEventReturnType

###### Remarks

This Action will batch up all the event logs found within the [`pollingInterval`](https://viem.sh/docs/contract/watchContractEvent#pollinginterval-optional), and invoke them via [`onLogs`](https://viem.sh/docs/contract/watchContractEvent#onLogs).

`watchContractEvent` will attempt to create an [Event Filter](https://viem.sh/docs/contract/createContractEventFilter) and listen to changes to the Filter per polling interval, however, if the RPC Provider does not support Filters (e.g. `eth_newFilter`), then `watchContractEvent` will fall back to using [`getLogs`](https://viem.sh/docs/actions/public/getLogs) instead.

###### Example

```ts theme={null}
import { createPublicClient, http, parseAbi } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const unwatch = client.watchContractEvent({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: parseAbi(['event Transfer(address indexed from, address indexed to, uint256 value)']),
  eventName: 'Transfer',
  args: { from: '0xc961145a54C96E3aE9bAA048c4F4D6b04C13916b' },
  onLogs: (logs) => console.log(logs),
})
```

##### watchEvent()

> **watchEvent**: \<`abiEvent`, `abiEvents`, `strict`>(`args`) => `WatchEventReturnType`

Watches and returns emitted [Event Logs](https://viem.sh/docs/glossary/terms#event-log).

* Docs: [https://viem.sh/docs/actions/public/watchEvent](https://viem.sh/docs/actions/public/watchEvent)
* JSON-RPC Methods:
  * **RPC Provider supports `eth_newFilter`:**
    * Calls [`eth_newFilter`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_newfilter) to create a filter (called on initialize).
    * On a polling interval, it will call [`eth_getFilterChanges`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getfilterchanges).
  * **RPC Provider does not support `eth_newFilter`:**
    * Calls [`eth_getLogs`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getlogs) for each block between the polling interval.

###### Type Parameters

| Type Parameter | Default type |
| - | - |
| `abiEvent` *extends* `AbiEvent` \| `undefined` | `undefined` |
| `abiEvents` *extends* readonly `unknown`\[] \| readonly `AbiEvent`\[] \| `undefined` | `abiEvent` *extends* `AbiEvent` ? \[`abiEvent`] : `undefined` |
| `strict` *extends* `boolean` \| `undefined` | `undefined` |

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `WatchEventParameters`\<`abiEvent`, `abiEvents`, `strict`, `HttpTransport`> | WatchEventParameters |

###### Returns

`WatchEventReturnType`

A function that can be invoked to stop watching for new Event Logs. WatchEventReturnType

###### Remarks

This Action will batch up all the Event Logs found within the [`pollingInterval`](https://viem.sh/docs/actions/public/watchEvent#pollinginterval-optional), and invoke them via [`onLogs`](https://viem.sh/docs/actions/public/watchEvent#onLogs).

`watchEvent` will attempt to create an [Event Filter](https://viem.sh/docs/actions/public/createEventFilter) and listen to changes to the Filter per polling interval, however, if the RPC Provider does not support Filters (e.g. `eth_newFilter`), then `watchEvent` will fall back to using [`getLogs`](https://viem.sh/docs/actions/public/getLogs) instead.

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const unwatch = client.watchEvent({
  onLogs: (logs) => console.log(logs),
})
```

##### watchPendingTransactions()

> **watchPendingTransactions**: (`args`) => `WatchPendingTransactionsReturnType`

Watches and returns pending transaction hashes.

* Docs: [https://viem.sh/docs/actions/public/watchPendingTransactions](https://viem.sh/docs/actions/public/watchPendingTransactions)
* JSON-RPC Methods:
  * When `poll: true`
    * Calls [`eth_newPendingTransactionFilter`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_newpendingtransactionfilter) to initialize the filter.
    * Calls [`eth_getFilterChanges`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getFilterChanges) on a polling interval.
  * When `poll: false` & WebSocket Transport, uses a WebSocket subscription via [`eth_subscribe`](https://docs.alchemy.com/reference/eth-subscribe-polygon) and the `"newPendingTransactions"` event.

###### Parameters

| Parameter | Type | Description |
| - | - | - |
| `args` | `WatchPendingTransactionsParameters`\<`HttpTransport`> | WatchPendingTransactionsParameters |

###### Returns

`WatchPendingTransactionsReturnType`

A function that can be invoked to stop watching for new pending transaction hashes. WatchPendingTransactionsReturnType

###### Remarks

This Action will batch up all the pending transactions found within the [`pollingInterval`](https://viem.sh/docs/actions/public/watchPendingTransactions#pollinginterval-optional), and invoke them via [`onTransactions`](https://viem.sh/docs/actions/public/watchPendingTransactions#ontransactions).

###### Example

```ts theme={null}
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
})
const unwatch = await client.watchPendingTransactions({
  onTransactions: (hashes) => console.log(hashes),
})
```

***

### send()

> **send**\<`T`>(`to`, `token`, `amount`, `options`?): `Promise`\<[`Transaction`](../type-aliases/Transaction)\<`T` *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

Defined in: [packages/wallets/src/wallets/wallet.ts:335](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L335)

Send a token to a wallet or user locator

#### Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* `SendTokenTransactionOptions` \| `undefined` | `undefined` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `to` | `string` \| `UserLocator` | The recipient (address or user locator) |
| `token` | `string` | The token (address or currency symbol) |
| `amount` | `string` | The amount to send (decimal units) |
| `options`? | `T` | The options for the transaction |

#### Returns

`Promise`\<[`Transaction`](../type-aliases/Transaction)\<`T` *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

The transaction

#### Inherited from

[`Wallet`](./Wallet).[`send`](./Wallet#send)

***

### sendTransaction()

> **sendTransaction**\<`T`>(`params`): `Promise`\<[`Transaction`](../type-aliases/Transaction)\<`T`\[`"options"`] *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

Defined in: [packages/wallets/src/wallets/evm.ts:55](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/evm.ts#L55)

Send a raw EVM transaction.

#### Type Parameters

| Type Parameter |
| - |
| `T` *extends* [`EVMTransactionInput`](../type-aliases/EVMTransactionInput) |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | `T` | The transaction parameters (raw transaction, ABI call, or encoded data) |

#### Returns

`Promise`\<[`Transaction`](../type-aliases/Transaction)\<`T`\[`"options"`] *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

The transaction result

***

### signMessage()

> **signMessage**\<`T`>(`params`): `Promise`\<[`Signature`](../type-aliases/Signature)\<`T`\[`"options"`] *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

Defined in: [packages/wallets/src/wallets/evm.ts:95](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/evm.ts#L95)

Sign a message with the wallet's private key.

#### Type Parameters

| Type Parameter |
| - |
| `T` *extends* `SignMessageInput` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | `T` | The message to sign |

#### Returns

`Promise`\<[`Signature`](../type-aliases/Signature)\<`T`\[`"options"`] *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

The signature

***

### signTypedData()

> **signTypedData**\<`T`>(`params`): `Promise`\<[`Signature`](../type-aliases/Signature)\<`T`\[`"options"`] *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

Defined in: [packages/wallets/src/wallets/evm.ts:141](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/evm.ts#L141)

Sign EIP-712 typed data.

#### Type Parameters

| Type Parameter |
| - |
| `T` *extends* `SignTypedDataInput` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | `T` | The typed data parameters (domain, types, message, primaryType, chain) |

#### Returns

`Promise`\<[`Signature`](../type-aliases/Signature)\<`T`\[`"options"`] *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

The signature

***

### stagingFund()

> **stagingFund**(`amount`, `chain`?): `Promise`\<`FundWalletResponse`>

Defined in: [packages/wallets/src/wallets/wallet.ts:166](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L166)

Funds the wallet with Crossmint's stablecoin (USDXM).

**Note:** This method is only available in staging environments and exclusively supports USDXM tokens.
It cannot be used in production environments.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `amount` | `number` | The amount of USDXM to fund the wallet with |
| `chain`? | [`Chain`](../type-aliases/Chain) | Optional chain to fund on. If not provided, uses the wallet's default chain |

#### Returns

`Promise`\<`FundWalletResponse`>

The funding response

#### Throws

If the funding operation fails or if called in a production environment

#### Inherited from

[`Wallet`](./Wallet).[`stagingFund`](./Wallet#stagingfund)

***

### from()

> `static` **from**(`wallet`): `EVMWallet`

Defined in: [packages/wallets/src/wallets/evm.ts:35](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/evm.ts#L35)

#### Parameters

| Parameter | Type |
| - | - |
| `wallet` | [`Wallet`](./Wallet)\<[`Chain`](../type-aliases/Chain)> |

#### Returns

`EVMWallet`


# SolanaWallet
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/typescript/classes/SolanaWallet



<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/sdk-reference/wallets/typescript/classes/SolanaWallet) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

Defined in: [packages/wallets/src/wallets/solana.ts:17](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/solana.ts#L17)

## Extends

* [`Wallet`](./Wallet)\<[`SolanaChain`](../type-aliases/SolanaChain)>

## Constructors

### new SolanaWallet()

> **new SolanaWallet**(`wallet`): `SolanaWallet`

Defined in: [packages/wallets/src/wallets/solana.ts:18](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/solana.ts#L18)

#### Parameters

| Parameter | Type |
| - | - |
| `wallet` | [`Wallet`](./Wallet)\<`"solana"`> |

#### Returns

`SolanaWallet`

#### Overrides

[`Wallet`](./Wallet).[`constructor`](./Wallet#constructor)

## Properties

| Property | Type | Inherited from | Defined in |
| - | - | - | - |
|  `address` | `string` | [`Wallet`](./Wallet).[`address`](./Wallet#address) | [packages/wallets/src/wallets/wallet.ts:62](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L62) |
|  `alias?` | `string` | [`Wallet`](./Wallet).[`alias`](./Wallet#alias) | [packages/wallets/src/wallets/wallet.ts:64](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L64) |
|  `chain` | `"solana"` | [`Wallet`](./Wallet).[`chain`](./Wallet#chain) | [packages/wallets/src/wallets/wallet.ts:61](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L61) |
|  `owner?` | `string` | [`Wallet`](./Wallet).[`owner`](./Wallet#owner) | [packages/wallets/src/wallets/wallet.ts:63](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L63) |
|  `signer` | [`Signer`](../interfaces/Signer) | [`Wallet`](./Wallet).[`signer`](./Wallet#signer) | [packages/wallets/src/wallets/wallet.ts:65](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L65) |

## Methods

### addDelegatedSigner()

> **addDelegatedSigner**\<`T`>(`params`): `Promise`\<`T` *extends* `PrepareOnly`\<`true`> ? `object` : `void`>

Defined in: [packages/wallets/src/wallets/wallet.ts:465](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L465)

Add a delegated signer to the wallet

#### Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* `AddDelegatedSignerOptions` \| `undefined` | `undefined` |

#### Parameters

| Parameter | Type |
| - | - |
| `params` | \{ `options`: `T`; `signer`: `string` \| \{ `id`: `string`; `name`: `string`; `publicKey`: \{ `x`: `string`; `y`: `string`; }; `type`: `"passkey"`; }; } |
| `params.options`? | `T` |
| `params.signer` | `string` \| \{ `id`: `string`; `name`: `string`; `publicKey`: \{ `x`: `string`; `y`: `string`; }; `type`: `"passkey"`; } |

#### Returns

`Promise`\<`T` *extends* `PrepareOnly`\<`true`> ? `object` : `void`>

#### Inherited from

[`Wallet`](./Wallet).[`addDelegatedSigner`](./Wallet#adddelegatedsigner)

***

### approve()

> **approve**\<`T`>(`params`): `Promise`\<`ApproveResult`\<`T`>>

Defined in: [packages/wallets/src/wallets/wallet.ts:423](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L423)

Approve a transaction or signature

#### Type Parameters

| Type Parameter |
| - |
| `T` *extends* `ApproveParams` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | `T` | The parameters |

#### Returns

`Promise`\<`ApproveResult`\<`T`>>

The transaction or signature

#### Inherited from

[`Wallet`](./Wallet).[`approve`](./Wallet#approve)

***

### ~~approveTransaction()~~

> **approveTransaction**(`params`): `Promise`\<`Error`>

Defined in: [packages/wallets/src/wallets/wallet.ts:399](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L399)

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | `ApproveParams` | The parameters |

#### Returns

`Promise`\<`Error`>

The transaction

#### Deprecated

Use `approve` instead.
Approve a transaction

#### Inherited from

[`Wallet`](./Wallet).[`approveTransaction`](./Wallet#approvetransaction)

***

### balances()

> **balances**(`tokens`?): `Promise`\<[`Balances`](../type-aliases/Balances)\<`"solana"`>>

Defined in: [packages/wallets/src/wallets/wallet.ts:118](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L118)

Get the wallet balances - always includes USDC and native token (ETH/SOL)

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `tokens`? | `string`\[] | Additional tokens to request (optional: native token and usdc are always included) |

#### Returns

`Promise`\<[`Balances`](../type-aliases/Balances)\<`"solana"`>>

The balances returns nativeToken, usdc, tokens

#### Throws

If the balances cannot be retrieved

#### Inherited from

[`Wallet`](./Wallet).[`balances`](./Wallet#balances)

***

### delegatedSigners()

> **delegatedSigners**(): `Promise`\<[`DelegatedSigner`](../type-aliases/DelegatedSigner)\[]>

Defined in: [packages/wallets/src/wallets/wallet.ts:554](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L554)

List the delegated signers for this wallet.

#### Returns

`Promise`\<[`DelegatedSigner`](../type-aliases/DelegatedSigner)\[]>

The delegated signers

#### Inherited from

[`Wallet`](./Wallet).[`delegatedSigners`](./Wallet#delegatedsigners)

***

### experimental\_activity()

> **experimental\_activity**(): `Promise`\<`WalletsV1Alpha2ActivityResponseDto`>

Defined in: [packages/wallets/src/wallets/wallet.ts:312](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L312)

**`Experimental`**

Get the wallet activity

#### Returns

`Promise`\<`WalletsV1Alpha2ActivityResponseDto`>

The activity
This API is experimental and may change in the future

#### Throws

If the activity cannot be retrieved

#### Inherited from

[`Wallet`](./Wallet).[`experimental_activity`](./Wallet#experimental_activity)

***

### experimental\_apiClient()

> **experimental\_apiClient**(): [`WalletsApiClient`](./WalletsApiClient)

Defined in: [packages/wallets/src/wallets/wallet.ts:101](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L101)

**`Experimental`**

Get the API client

#### Returns

[`WalletsApiClient`](./WalletsApiClient)

The API client
This API is experimental and may change in the future

#### Inherited from

[`Wallet`](./Wallet).[`experimental_apiClient`](./Wallet#experimental_apiclient)

***

### experimental\_nfts()

> **experimental\_nfts**(`params`): `Promise`\<`WalletNftsResponseDto`>

Defined in: [packages/wallets/src/wallets/wallet.ts:272](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L272)

**`Experimental`**

Get the wallet NFTs

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | \{ `page`: `number`; `perPage`: `number`; } | The parameters |
| `params.page` | `number` | The page number |
| `params.perPage` | `number` | The number of NFTs per page |

#### Returns

`Promise`\<`WalletNftsResponseDto`>

The NFTs
This API is experimental and may change in the future

#### Inherited from

[`Wallet`](./Wallet).[`experimental_nfts`](./Wallet#experimental_nfts)

***

### experimental\_transaction()

> **experimental\_transaction**(`transactionId`): `Promise`\<`WalletsTransactionV2025ResponseDto`>

Defined in: [packages/wallets/src/wallets/wallet.ts:298](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L298)

Get a transaction by id

#### Parameters

| Parameter | Type |
| - | - |
| `transactionId` | `string` |

#### Returns

`Promise`\<`WalletsTransactionV2025ResponseDto`>

The transaction

#### Throws

If the transaction cannot be retrieved

#### Inherited from

[`Wallet`](./Wallet).[`experimental_transaction`](./Wallet#experimental_transaction)

***

### experimental\_transactions()

> **experimental\_transactions**(): `Promise`\<`GetTransactionsResponse`>

Defined in: [packages/wallets/src/wallets/wallet.ts:285](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L285)

Get the wallet transactions

#### Returns

`Promise`\<`GetTransactionsResponse`>

The transactions

#### Throws

If the transactions cannot be retrieved

#### Inherited from

[`Wallet`](./Wallet).[`experimental_transactions`](./Wallet#experimental_transactions)

***

### send()

> **send**\<`T`>(`to`, `token`, `amount`, `options`?): `Promise`\<[`Transaction`](../type-aliases/Transaction)\<`T` *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

Defined in: [packages/wallets/src/wallets/wallet.ts:335](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L335)

Send a token to a wallet or user locator

#### Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* `SendTokenTransactionOptions` \| `undefined` | `undefined` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `to` | `string` \| `UserLocator` | The recipient (address or user locator) |
| `token` | `string` | The token (address or currency symbol) |
| `amount` | `string` | The amount to send (decimal units) |
| `options`? | `T` | The options for the transaction |

#### Returns

`Promise`\<[`Transaction`](../type-aliases/Transaction)\<`T` *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

The transaction

#### Inherited from

[`Wallet`](./Wallet).[`send`](./Wallet#send)

***

### sendTransaction()

> **sendTransaction**\<`T`>(`params`): `Promise`\<[`Transaction`](../type-aliases/Transaction)\<`T` *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

Defined in: [packages/wallets/src/wallets/solana.ts:52](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/solana.ts#L52)

Send a raw Solana transaction.

#### Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* `TransactionInputOptions` \| `undefined` | `undefined` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | [`SolanaTransactionInput`](../type-aliases/SolanaTransactionInput) | The transaction parameters (serialized transaction or Transaction object) |

#### Returns

`Promise`\<[`Transaction`](../type-aliases/Transaction)\<`T` *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

The transaction result

***

### stagingFund()

> **stagingFund**(`amount`, `chain`?): `Promise`\<`FundWalletResponse`>

Defined in: [packages/wallets/src/wallets/wallet.ts:166](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L166)

Funds the wallet with Crossmint's stablecoin (USDXM).

**Note:** This method is only available in staging environments and exclusively supports USDXM tokens.
It cannot be used in production environments.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `amount` | `number` | The amount of USDXM to fund the wallet with |
| `chain`? | [`Chain`](../type-aliases/Chain) | Optional chain to fund on. If not provided, uses the wallet's default chain |

#### Returns

`Promise`\<`FundWalletResponse`>

The funding response

#### Throws

If the funding operation fails or if called in a production environment

#### Inherited from

[`Wallet`](./Wallet).[`stagingFund`](./Wallet#stagingfund)

***

### from()

> `static` **from**(`wallet`): `SolanaWallet`

Defined in: [packages/wallets/src/wallets/solana.ts:32](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/solana.ts#L32)

#### Parameters

| Parameter | Type |
| - | - |
| `wallet` | [`Wallet`](./Wallet)\<[`Chain`](../type-aliases/Chain)> |

#### Returns

`SolanaWallet`


# StellarWallet
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/typescript/classes/StellarWallet



<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/sdk-reference/wallets/typescript/classes/StellarWallet) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

Defined in: [packages/wallets/src/wallets/stellar.ts:15](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/stellar.ts#L15)

## Extends

* [`Wallet`](./Wallet)\<[`StellarChain`](../type-aliases/StellarChain)>

## Constructors

### new StellarWallet()

> **new StellarWallet**(`wallet`): `StellarWallet`

Defined in: [packages/wallets/src/wallets/stellar.ts:16](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/stellar.ts#L16)

#### Parameters

| Parameter | Type |
| - | - |
| `wallet` | [`Wallet`](./Wallet)\<`"stellar"`> |

#### Returns

`StellarWallet`

#### Overrides

[`Wallet`](./Wallet).[`constructor`](./Wallet#constructor)

## Properties

| Property | Type | Inherited from | Defined in |
| - | - | - | - |
|  `address` | `string` | [`Wallet`](./Wallet).[`address`](./Wallet#address) | [packages/wallets/src/wallets/wallet.ts:62](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L62) |
|  `alias?` | `string` | [`Wallet`](./Wallet).[`alias`](./Wallet#alias) | [packages/wallets/src/wallets/wallet.ts:64](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L64) |
|  `chain` | `"stellar"` | [`Wallet`](./Wallet).[`chain`](./Wallet#chain) | [packages/wallets/src/wallets/wallet.ts:61](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L61) |
|  `owner?` | `string` | [`Wallet`](./Wallet).[`owner`](./Wallet#owner) | [packages/wallets/src/wallets/wallet.ts:63](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L63) |
|  `signer` | [`Signer`](../interfaces/Signer) | [`Wallet`](./Wallet).[`signer`](./Wallet#signer) | [packages/wallets/src/wallets/wallet.ts:65](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L65) |

## Methods

### addDelegatedSigner()

> **addDelegatedSigner**\<`T`>(`params`): `Promise`\<`T` *extends* `PrepareOnly`\<`true`> ? `object` : `void`>

Defined in: [packages/wallets/src/wallets/wallet.ts:465](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L465)

Add a delegated signer to the wallet

#### Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* `AddDelegatedSignerOptions` \| `undefined` | `undefined` |

#### Parameters

| Parameter | Type |
| - | - |
| `params` | \{ `options`: `T`; `signer`: `string` \| \{ `id`: `string`; `name`: `string`; `publicKey`: \{ `x`: `string`; `y`: `string`; }; `type`: `"passkey"`; }; } |
| `params.options`? | `T` |
| `params.signer` | `string` \| \{ `id`: `string`; `name`: `string`; `publicKey`: \{ `x`: `string`; `y`: `string`; }; `type`: `"passkey"`; } |

#### Returns

`Promise`\<`T` *extends* `PrepareOnly`\<`true`> ? `object` : `void`>

#### Inherited from

[`Wallet`](./Wallet).[`addDelegatedSigner`](./Wallet#adddelegatedsigner)

***

### approve()

> **approve**\<`T`>(`params`): `Promise`\<`ApproveResult`\<`T`>>

Defined in: [packages/wallets/src/wallets/wallet.ts:423](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L423)

Approve a transaction or signature

#### Type Parameters

| Type Parameter |
| - |
| `T` *extends* `ApproveParams` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | `T` | The parameters |

#### Returns

`Promise`\<`ApproveResult`\<`T`>>

The transaction or signature

#### Inherited from

[`Wallet`](./Wallet).[`approve`](./Wallet#approve)

***

### ~~approveTransaction()~~

> **approveTransaction**(`params`): `Promise`\<`Error`>

Defined in: [packages/wallets/src/wallets/wallet.ts:399](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L399)

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | `ApproveParams` | The parameters |

#### Returns

`Promise`\<`Error`>

The transaction

#### Deprecated

Use `approve` instead.
Approve a transaction

#### Inherited from

[`Wallet`](./Wallet).[`approveTransaction`](./Wallet#approvetransaction)

***

### balances()

> **balances**(`tokens`?): `Promise`\<[`Balances`](../type-aliases/Balances)\<`"stellar"`>>

Defined in: [packages/wallets/src/wallets/wallet.ts:118](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L118)

Get the wallet balances - always includes USDC and native token (ETH/SOL)

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `tokens`? | `string`\[] | Additional tokens to request (optional: native token and usdc are always included) |

#### Returns

`Promise`\<[`Balances`](../type-aliases/Balances)\<`"stellar"`>>

The balances returns nativeToken, usdc, tokens

#### Throws

If the balances cannot be retrieved

#### Inherited from

[`Wallet`](./Wallet).[`balances`](./Wallet#balances)

***

### delegatedSigners()

> **delegatedSigners**(): `Promise`\<[`DelegatedSigner`](../type-aliases/DelegatedSigner)\[]>

Defined in: [packages/wallets/src/wallets/wallet.ts:554](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L554)

List the delegated signers for this wallet.

#### Returns

`Promise`\<[`DelegatedSigner`](../type-aliases/DelegatedSigner)\[]>

The delegated signers

#### Inherited from

[`Wallet`](./Wallet).[`delegatedSigners`](./Wallet#delegatedsigners)

***

### experimental\_activity()

> **experimental\_activity**(): `Promise`\<`WalletsV1Alpha2ActivityResponseDto`>

Defined in: [packages/wallets/src/wallets/wallet.ts:312](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L312)

**`Experimental`**

Get the wallet activity

#### Returns

`Promise`\<`WalletsV1Alpha2ActivityResponseDto`>

The activity
This API is experimental and may change in the future

#### Throws

If the activity cannot be retrieved

#### Inherited from

[`Wallet`](./Wallet).[`experimental_activity`](./Wallet#experimental_activity)

***

### experimental\_apiClient()

> **experimental\_apiClient**(): [`WalletsApiClient`](./WalletsApiClient)

Defined in: [packages/wallets/src/wallets/wallet.ts:101](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L101)

**`Experimental`**

Get the API client

#### Returns

[`WalletsApiClient`](./WalletsApiClient)

The API client
This API is experimental and may change in the future

#### Inherited from

[`Wallet`](./Wallet).[`experimental_apiClient`](./Wallet#experimental_apiclient)

***

### experimental\_nfts()

> **experimental\_nfts**(`params`): `Promise`\<`WalletNftsResponseDto`>

Defined in: [packages/wallets/src/wallets/wallet.ts:272](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L272)

**`Experimental`**

Get the wallet NFTs

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | \{ `page`: `number`; `perPage`: `number`; } | The parameters |
| `params.page` | `number` | The page number |
| `params.perPage` | `number` | The number of NFTs per page |

#### Returns

`Promise`\<`WalletNftsResponseDto`>

The NFTs
This API is experimental and may change in the future

#### Inherited from

[`Wallet`](./Wallet).[`experimental_nfts`](./Wallet#experimental_nfts)

***

### experimental\_transaction()

> **experimental\_transaction**(`transactionId`): `Promise`\<`WalletsTransactionV2025ResponseDto`>

Defined in: [packages/wallets/src/wallets/wallet.ts:298](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L298)

Get a transaction by id

#### Parameters

| Parameter | Type |
| - | - |
| `transactionId` | `string` |

#### Returns

`Promise`\<`WalletsTransactionV2025ResponseDto`>

The transaction

#### Throws

If the transaction cannot be retrieved

#### Inherited from

[`Wallet`](./Wallet).[`experimental_transaction`](./Wallet#experimental_transaction)

***

### experimental\_transactions()

> **experimental\_transactions**(): `Promise`\<`GetTransactionsResponse`>

Defined in: [packages/wallets/src/wallets/wallet.ts:285](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L285)

Get the wallet transactions

#### Returns

`Promise`\<`GetTransactionsResponse`>

The transactions

#### Throws

If the transactions cannot be retrieved

#### Inherited from

[`Wallet`](./Wallet).[`experimental_transactions`](./Wallet#experimental_transactions)

***

### send()

> **send**\<`T`>(`to`, `token`, `amount`, `options`?): `Promise`\<[`Transaction`](../type-aliases/Transaction)\<`T` *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

Defined in: [packages/wallets/src/wallets/wallet.ts:335](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L335)

Send a token to a wallet or user locator

#### Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* `SendTokenTransactionOptions` \| `undefined` | `undefined` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `to` | `string` \| `UserLocator` | The recipient (address or user locator) |
| `token` | `string` | The token (address or currency symbol) |
| `amount` | `string` | The amount to send (decimal units) |
| `options`? | `T` | The options for the transaction |

#### Returns

`Promise`\<[`Transaction`](../type-aliases/Transaction)\<`T` *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

The transaction

#### Inherited from

[`Wallet`](./Wallet).[`send`](./Wallet#send)

***

### sendTransaction()

> **sendTransaction**\<`T`>(`params`): `Promise`\<[`Transaction`](../type-aliases/Transaction)\<`T` *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

Defined in: [packages/wallets/src/wallets/stellar.ts:50](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/stellar.ts#L50)

Send a raw Stellar transaction (serialized transaction or contract call).

#### Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* `TransactionInputOptions` \| `undefined` | `undefined` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | `StellarTransactionInput` & `object` | The transaction parameters |

#### Returns

`Promise`\<[`Transaction`](../type-aliases/Transaction)\<`T` *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

The transaction result

***

### stagingFund()

> **stagingFund**(`amount`, `chain`?): `Promise`\<`FundWalletResponse`>

Defined in: [packages/wallets/src/wallets/wallet.ts:166](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L166)

Funds the wallet with Crossmint's stablecoin (USDXM).

**Note:** This method is only available in staging environments and exclusively supports USDXM tokens.
It cannot be used in production environments.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `amount` | `number` | The amount of USDXM to fund the wallet with |
| `chain`? | [`Chain`](../type-aliases/Chain) | Optional chain to fund on. If not provided, uses the wallet's default chain |

#### Returns

`Promise`\<`FundWalletResponse`>

The funding response

#### Throws

If the funding operation fails or if called in a production environment

#### Inherited from

[`Wallet`](./Wallet).[`stagingFund`](./Wallet#stagingfund)

***

### from()

> `static` **from**(`wallet`): `StellarWallet`

Defined in: [packages/wallets/src/wallets/stellar.ts:30](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/stellar.ts#L30)

#### Parameters

| Parameter | Type |
| - | - |
| `wallet` | [`Wallet`](./Wallet)\<[`Chain`](../type-aliases/Chain)> |

#### Returns

`StellarWallet`


# Wallet
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/typescript/classes/Wallet



<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/sdk-reference/wallets/typescript/classes/Wallet) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

Defined in: [packages/wallets/src/wallets/wallet.ts:60](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L60)

## Extended by

* [`SolanaWallet`](./SolanaWallet)
* [`EVMWallet`](./EVMWallet)
* [`StellarWallet`](./StellarWallet)

## Type Parameters

| Type Parameter |
| - |
| `C` *extends* [`Chain`](../type-aliases/Chain) |

## Constructors

### new Wallet()

> **new Wallet**\<`C`>(`args`, `apiClient`): `Wallet`\<`C`>

Defined in: [packages/wallets/src/wallets/wallet.ts:69](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L69)

#### Parameters

| Parameter | Type |
| - | - |
| `args` | `WalletContructorType`\<`C`> |
| `apiClient` | [`WalletsApiClient`](./WalletsApiClient) |

#### Returns

`Wallet`\<`C`>

## Properties

| Property | Type | Defined in |
| - | - | - |
|  `address` | `string` | [packages/wallets/src/wallets/wallet.ts:62](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L62) |
|  `alias?` | `string` | [packages/wallets/src/wallets/wallet.ts:64](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L64) |
|  `chain` | `C` | [packages/wallets/src/wallets/wallet.ts:61](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L61) |
|  `owner?` | `string` | [packages/wallets/src/wallets/wallet.ts:63](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L63) |
|  `signer` | [`Signer`](../interfaces/Signer) | [packages/wallets/src/wallets/wallet.ts:65](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L65) |

## Methods

### addDelegatedSigner()

> **addDelegatedSigner**\<`T`>(`params`): `Promise`\<`T` *extends* `PrepareOnly`\<`true`> ? `AddDelegatedSignerReturnType`\<`C`> : `void`>

Defined in: [packages/wallets/src/wallets/wallet.ts:465](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L465)

Add a delegated signer to the wallet

#### Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* `AddDelegatedSignerOptions` \| `undefined` | `undefined` |

#### Parameters

| Parameter | Type |
| - | - |
| `params` | \{ `options`: `T`; `signer`: `string` \| \{ `id`: `string`; `name`: `string`; `publicKey`: \{ `x`: `string`; `y`: `string`; }; `type`: `"passkey"`; }; } |
| `params.options`? | `T` |
| `params.signer` | `string` \| \{ `id`: `string`; `name`: `string`; `publicKey`: \{ `x`: `string`; `y`: `string`; }; `type`: `"passkey"`; } |

#### Returns

`Promise`\<`T` *extends* `PrepareOnly`\<`true`> ? `AddDelegatedSignerReturnType`\<`C`> : `void`>

***

### approve()

> **approve**\<`T`>(`params`): `Promise`\<`ApproveResult`\<`T`>>

Defined in: [packages/wallets/src/wallets/wallet.ts:423](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L423)

Approve a transaction or signature

#### Type Parameters

| Type Parameter |
| - |
| `T` *extends* `ApproveParams` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | `T` | The parameters |

#### Returns

`Promise`\<`ApproveResult`\<`T`>>

The transaction or signature

***

### ~~approveTransaction()~~

> **approveTransaction**(`params`): `Promise`\<`Error`>

Defined in: [packages/wallets/src/wallets/wallet.ts:399](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L399)

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | `ApproveParams` | The parameters |

#### Returns

`Promise`\<`Error`>

The transaction

#### Deprecated

Use `approve` instead.
Approve a transaction

***

### balances()

> **balances**(`tokens`?): `Promise`\<[`Balances`](../type-aliases/Balances)\<`C`>>

Defined in: [packages/wallets/src/wallets/wallet.ts:118](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L118)

Get the wallet balances - always includes USDC and native token (ETH/SOL)

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `tokens`? | `string`\[] | Additional tokens to request (optional: native token and usdc are always included) |

#### Returns

`Promise`\<[`Balances`](../type-aliases/Balances)\<`C`>>

The balances returns nativeToken, usdc, tokens

#### Throws

If the balances cannot be retrieved

***

### delegatedSigners()

> **delegatedSigners**(): `Promise`\<[`DelegatedSigner`](../type-aliases/DelegatedSigner)\[]>

Defined in: [packages/wallets/src/wallets/wallet.ts:554](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L554)

List the delegated signers for this wallet.

#### Returns

`Promise`\<[`DelegatedSigner`](../type-aliases/DelegatedSigner)\[]>

The delegated signers

***

### experimental\_activity()

> **experimental\_activity**(): `Promise`\<`WalletsV1Alpha2ActivityResponseDto`>

Defined in: [packages/wallets/src/wallets/wallet.ts:312](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L312)

**`Experimental`**

Get the wallet activity

#### Returns

`Promise`\<`WalletsV1Alpha2ActivityResponseDto`>

The activity
This API is experimental and may change in the future

#### Throws

If the activity cannot be retrieved

***

### experimental\_apiClient()

> **experimental\_apiClient**(): [`WalletsApiClient`](./WalletsApiClient)

Defined in: [packages/wallets/src/wallets/wallet.ts:101](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L101)

**`Experimental`**

Get the API client

#### Returns

[`WalletsApiClient`](./WalletsApiClient)

The API client
This API is experimental and may change in the future

***

### experimental\_nfts()

> **experimental\_nfts**(`params`): `Promise`\<`WalletNftsResponseDto`>

Defined in: [packages/wallets/src/wallets/wallet.ts:272](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L272)

**`Experimental`**

Get the wallet NFTs

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `params` | \{ `page`: `number`; `perPage`: `number`; } | The parameters |
| `params.page` | `number` | The page number |
| `params.perPage` | `number` | The number of NFTs per page |

#### Returns

`Promise`\<`WalletNftsResponseDto`>

The NFTs
This API is experimental and may change in the future

***

### experimental\_transaction()

> **experimental\_transaction**(`transactionId`): `Promise`\<`WalletsTransactionV2025ResponseDto`>

Defined in: [packages/wallets/src/wallets/wallet.ts:298](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L298)

Get a transaction by id

#### Parameters

| Parameter | Type |
| - | - |
| `transactionId` | `string` |

#### Returns

`Promise`\<`WalletsTransactionV2025ResponseDto`>

The transaction

#### Throws

If the transaction cannot be retrieved

***

### experimental\_transactions()

> **experimental\_transactions**(): `Promise`\<`GetTransactionsResponse`>

Defined in: [packages/wallets/src/wallets/wallet.ts:285](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L285)

Get the wallet transactions

#### Returns

`Promise`\<`GetTransactionsResponse`>

The transactions

#### Throws

If the transactions cannot be retrieved

***

### send()

> **send**\<`T`>(`to`, `token`, `amount`, `options`?): `Promise`\<[`Transaction`](../type-aliases/Transaction)\<`T` *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

Defined in: [packages/wallets/src/wallets/wallet.ts:335](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L335)

Send a token to a wallet or user locator

#### Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* `SendTokenTransactionOptions` \| `undefined` | `undefined` |

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `to` | `string` \| `UserLocator` | The recipient (address or user locator) |
| `token` | `string` | The token (address or currency symbol) |
| `amount` | `string` | The amount to send (decimal units) |
| `options`? | `T` | The options for the transaction |

#### Returns

`Promise`\<[`Transaction`](../type-aliases/Transaction)\<`T` *extends* `PrepareOnly`\<`true`> ? `true` : `false`>>

The transaction

***

### stagingFund()

> **stagingFund**(`amount`, `chain`?): `Promise`\<`FundWalletResponse`>

Defined in: [packages/wallets/src/wallets/wallet.ts:166](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/wallet.ts#L166)

Funds the wallet with Crossmint's stablecoin (USDXM).

**Note:** This method is only available in staging environments and exclusively supports USDXM tokens.
It cannot be used in production environments.

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `amount` | `number` | The amount of USDXM to fund the wallet with |
| `chain`? | [`Chain`](../type-aliases/Chain) | Optional chain to fund on. If not provided, uses the wallet's default chain |

#### Returns

`Promise`\<`FundWalletResponse`>

The funding response

#### Throws

If the funding operation fails or if called in a production environment


# WalletsApiClient
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/typescript/classes/WalletsApiClient



<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/sdk-reference/wallets/typescript/classes/WalletsApiClient) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

Defined in: [packages/wallets/src/api/client.ts:41](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L41)

## Extends

* `CrossmintApiClient`

## Constructors

### new WalletsApiClient()

> **new WalletsApiClient**(`crossmint`): `ApiClient`

Defined in: [packages/wallets/src/api/client.ts:45](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L45)

#### Parameters

| Parameter | Type |
| - | - |
| `crossmint` | `Crossmint` |

#### Returns

`ApiClient`

#### Overrides

`CrossmintApiClient.constructor`

## Properties

| Property | Type | Inherited from | Defined in |
| - | - | - | - |
|  `crossmint` | `Crossmint` | `CrossmintApiClient.crossmint` | packages/common/base/dist/apiClient/CrossmintApiClient.d.ts:18 |

## Accessors

### baseUrl

#### Get Signature

> **get** **baseUrl**(): `string`

Defined in: packages/common/base/dist/apiClient/CrossmintApiClient.d.ts:24

##### Returns

`string`

#### Inherited from

`CrossmintApiClient.baseUrl`

***

### commonHeaders

#### Get Signature

> **get** **commonHeaders**(): `object`

Defined in: packages/common/base/dist/apiClient/CrossmintApiClient.d.ts:25

##### Returns

`object`

###### Authorization?

> `optional` **Authorization**: `string`

###### x-api-key

> **x-api-key**: `string`

###### x-app-identifier?

> `optional` **x-app-identifier**: `string`

###### x-client-name

> **x-client-name**: `string`

###### x-client-version

> **x-client-version**: `string`

###### x-extension-id?

> `optional` **x-extension-id**: `string`

#### Inherited from

`CrossmintApiClient.commonHeaders`

***

### environment

#### Get Signature

> **get** **environment**(): `APIKeyEnvironmentPrefix`

Defined in: [packages/wallets/src/api/client.ts:264](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L264)

##### Returns

`APIKeyEnvironmentPrefix`

#### Overrides

`CrossmintApiClient.environment`

***

### isServerSide

#### Get Signature

> **get** **isServerSide**(): `boolean`

Defined in: [packages/wallets/src/api/client.ts:260](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L260)

##### Returns

`boolean`

## Methods

### approveSignature()

> **approveSignature**(`walletLocator`, `signatureId`, `params`): `Promise`\<`ApproveSignatureResponse`>

Defined in: [packages/wallets/src/api/client.ts:137](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L137)

#### Parameters

| Parameter | Type |
| - | - |
| `walletLocator` | `string` |
| `signatureId` | `string` |
| `params` | `SubmitApprovalV2025Dto` |

#### Returns

`Promise`\<`ApproveSignatureResponse`>

***

### approveTransaction()

> **approveTransaction**(`walletLocator`, `transactionId`, `params`): `Promise`\<`ApproveTransactionResponse`>

Defined in: [packages/wallets/src/api/client.ts:107](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L107)

#### Parameters

| Parameter | Type |
| - | - |
| `walletLocator` | `string` |
| `transactionId` | `string` |
| `params` | `SubmitApprovalV2025Dto` |

#### Returns

`Promise`\<`ApproveTransactionResponse`>

***

### buildUrl()

> **buildUrl**(`path`): `string`

Defined in: packages/common/base/dist/apiClient/ApiClient.d.ts:5

#### Parameters

| Parameter | Type |
| - | - |
| `path` | `string` |

#### Returns

`string`

#### Inherited from

`CrossmintApiClient.buildUrl`

***

### createSignature()

> **createSignature**(`walletLocator`, `params`): `Promise`\<`CreateSignatureResponse`>

Defined in: [packages/wallets/src/api/client.ts:126](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L126)

#### Parameters

| Parameter | Type |
| - | - |
| `walletLocator` | `string` |
| `params` | `CreateSignatureV2025Dto` |

#### Returns

`Promise`\<`CreateSignatureResponse`>

***

### createTransaction()

> **createTransaction**(`walletLocator`, `params`): `Promise`\<`CreateTransactionResponse`>

Defined in: [packages/wallets/src/api/client.ts:96](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L96)

#### Parameters

| Parameter | Type |
| - | - |
| `walletLocator` | `string` |
| `params` | `CreateTransactionV2025Dto` |

#### Returns

`Promise`\<`CreateTransactionResponse`>

***

### createWallet()

> **createWallet**(`params`): `Promise`\<`CreateWalletResponse`>

Defined in: [packages/wallets/src/api/client.ts:53](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L53)

#### Parameters

| Parameter | Type |
| - | - |
| `params` | `CreateWalletV2025Dto` |

#### Returns

`Promise`\<`CreateWalletResponse`>

***

### delete()

> **delete**(`path`, `params`): `Promise`\<`Response`>

Defined in: packages/common/base/dist/apiClient/ApiClient.d.ts:9

#### Parameters

| Parameter | Type |
| - | - |
| `path` | `string` |
| `params` | `Omit`\<`RequestInit`, `"method"`> |

#### Returns

`Promise`\<`Response`>

#### Inherited from

`CrossmintApiClient.delete`

***

### experimental\_activity()

> **experimental\_activity**(`walletLocator`, `params`): `Promise`\<`GetActivityResponse`>

Defined in: [packages/wallets/src/api/client.ts:179](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L179)

#### Parameters

| Parameter | Type |
| - | - |
| `walletLocator` | `string` |
| `params` | \{ `chain`: [`Chain`](../type-aliases/Chain); } |
| `params.chain` | [`Chain`](../type-aliases/Chain) |

#### Returns

`Promise`\<`GetActivityResponse`>

***

### experimental\_getNfts()

> **experimental\_getNfts**(`params`): `Promise`\<`WalletNftsResponseDto`>

Defined in: [packages/wallets/src/api/client.ts:163](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L163)

#### Parameters

| Parameter | Type |
| - | - |
| `params` | \{ `address`: `string`; `chain`: `string`; `page`: `number`; `perPage`: `number`; } |
| `params.address` | `string` |
| `params.chain` | `string` |
| `params.page` | `number` |
| `params.perPage` | `number` |

#### Returns

`Promise`\<`WalletNftsResponseDto`>

***

### fundWallet()

> **fundWallet**(`walletLocator`, `params`): `Promise`\<`FundWalletResponse`>

Defined in: [packages/wallets/src/api/client.ts:208](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L208)

#### Parameters

| Parameter | Type |
| - | - |
| `walletLocator` | `string` |
| `params` | `FundWalletAmountDto` |

#### Returns

`Promise`\<`FundWalletResponse`>

***

### get()

> **get**(`path`, `params`): `Promise`\<`Response`>

Defined in: packages/common/base/dist/apiClient/ApiClient.d.ts:6

#### Parameters

| Parameter | Type |
| - | - |
| `path` | `string` |
| `params` | `Omit`\<`RequestInit`, `"method"`> |

#### Returns

`Promise`\<`Response`>

#### Inherited from

`CrossmintApiClient.get`

***

### getBalance()

> **getBalance**(`walletLocator`, `params`): `Promise`\<`GetBalanceResponse`>

Defined in: [packages/wallets/src/api/client.ts:192](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L192)

#### Parameters

| Parameter | Type |
| - | - |
| `walletLocator` | `string` |
| `params` | \{ `chains`: [`Chain`](../type-aliases/Chain)\[]; `tokens`: `string`\[]; } |
| `params.chains` | [`Chain`](../type-aliases/Chain)\[] |
| `params.tokens` | `string`\[] |

#### Returns

`Promise`\<`GetBalanceResponse`>

***

### getSignature()

> **getSignature**(`walletLocator`, `signatureId`): `Promise`\<`GetSignatureResponse`>

Defined in: [packages/wallets/src/api/client.ts:149](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L149)

#### Parameters

| Parameter | Type |
| - | - |
| `walletLocator` | `string` |
| `signatureId` | `string` |

#### Returns

`Promise`\<`GetSignatureResponse`>

***

### getSigner()

> **getSigner**(`walletLocator`, `signer`): `Promise`\<`GetSignerResponse`>

Defined in: [packages/wallets/src/api/client.ts:227](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L227)

#### Parameters

| Parameter | Type |
| - | - |
| `walletLocator` | `string` |
| `signer` | `string` |

#### Returns

`Promise`\<`GetSignerResponse`>

***

### getTransaction()

> **getTransaction**(`walletLocator`, `transactionId`): `Promise`\<`GetTransactionResponse`>

Defined in: [packages/wallets/src/api/client.ts:119](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L119)

#### Parameters

| Parameter | Type |
| - | - |
| `walletLocator` | `string` |
| `transactionId` | `string` |

#### Returns

`Promise`\<`GetTransactionResponse`>

***

### getTransactions()

> **getTransactions**(`walletLocator`): `Promise`\<`GetTransactionsResponse`>

Defined in: [packages/wallets/src/api/client.ts:156](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L156)

#### Parameters

| Parameter | Type |
| - | - |
| `walletLocator` | `string` |

#### Returns

`Promise`\<`GetTransactionsResponse`>

***

### getWallet()

> **getWallet**(`locator`): `Promise`\<`GetWalletResponse`>

Defined in: [packages/wallets/src/api/client.ts:79](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L79)

#### Parameters

| Parameter | Type |
| - | - |
| `locator` | `string` |

#### Returns

`Promise`\<`GetWalletResponse`>

***

### patch()

> **patch**(`path`, `params`): `Promise`\<`Response`>

Defined in: packages/common/base/dist/apiClient/ApiClient.d.ts:10

#### Parameters

| Parameter | Type |
| - | - |
| `path` | `string` |
| `params` | `Omit`\<`RequestInit`, `"method"`> |

#### Returns

`Promise`\<`Response`>

#### Inherited from

`CrossmintApiClient.patch`

***

### post()

> **post**(`path`, `params`): `Promise`\<`Response`>

Defined in: packages/common/base/dist/apiClient/ApiClient.d.ts:7

#### Parameters

| Parameter | Type |
| - | - |
| `path` | `string` |
| `params` | `Omit`\<`RequestInit`, `"method"`> |

#### Returns

`Promise`\<`Response`>

#### Inherited from

`CrossmintApiClient.post`

***

### put()

> **put**(`path`, `params`): `Promise`\<`Response`>

Defined in: packages/common/base/dist/apiClient/ApiClient.d.ts:8

#### Parameters

| Parameter | Type |
| - | - |
| `path` | `string` |
| `params` | `Omit`\<`RequestInit`, `"method"`> |

#### Returns

`Promise`\<`Response`>

#### Inherited from

`CrossmintApiClient.put`

***

### registerSigner()

> **registerSigner**(`walletLocator`, `params`): `Promise`\<`RegisterSignerResponse`>

Defined in: [packages/wallets/src/api/client.ts:219](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L219)

#### Parameters

| Parameter | Type |
| - | - |
| `walletLocator` | `string` |
| `params` | `RegisterSignerParams` |

#### Returns

`Promise`\<`RegisterSignerResponse`>

***

### send()

> **send**(`walletLocator`, `tokenLocator`, `params`): `Promise`\<`WalletsV1Alpha2TransactionResponseWithSendParamsDto`>

Defined in: [packages/wallets/src/api/client.ts:234](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/client.ts#L234)

#### Parameters

| Parameter | Type |
| - | - |
| `walletLocator` | `string` |
| `tokenLocator` | `string` |
| `params` | `SendTokenDto` |

#### Returns

`Promise`\<`WalletsV1Alpha2TransactionResponseWithSendParamsDto`>

***

### normalizePath()

> `static` **normalizePath**(`path`): `string`

Defined in: packages/common/base/dist/apiClient/ApiClient.d.ts:11

#### Parameters

| Parameter | Type |
| - | - |
| `path` | `string` |

#### Returns

`string`

#### Inherited from

`CrossmintApiClient.normalizePath`


# createCrossmint
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/typescript/functions/createCrossmint



<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/sdk-reference/wallets/typescript/functions/createCrossmint) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

> **createCrossmint**(`config`, `apiKeyExpectations`?): `Crossmint`

Defined in: packages/common/base/dist/types/Crossmint.d.ts:31

## Parameters

| Parameter | Type |
| - | - |
| `config` | `CrossmintConfig` |
| `apiKeyExpectations`? | `ValidateAPIKeyPrefixExpectations` |

## Returns

`Crossmint`


# isExportableSigner
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/typescript/functions/isExportableSigner



<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/sdk-reference/wallets/typescript/functions/isExportableSignerAdapter) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

> **isExportableSigner**(`signer`): `signer is ExportableSigner`

Defined in: [packages/wallets/src/signers/types.ts:154](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L154)

## Parameters

| Parameter | Type |
| - | - |
| `signer` | [`Signer`](../interfaces/Signer) |

## Returns

`signer is ExportableSigner`


# ExportableSigner
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/typescript/interfaces/ExportableSigner



<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

Defined in: [packages/wallets/src/signers/types.ts:150](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L150)

## Extends

* [`Signer`](./Signer)

## Properties

### \_exportPrivateKey()

> **\_exportPrivateKey**: (`exportTEEConnection`) => `Promise`\<`void`>

Defined in: [packages/wallets/src/signers/types.ts:151](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L151)

#### Parameters

| Parameter | Type |
| - | - |
| `exportTEEConnection` | [`ExportSignerTEEConnection`](../type-aliases/ExportSignerTEEConnection) |

#### Returns

`Promise`\<`void`>

***

### type

> **type**: keyof `SignResultMap`

Defined in: [packages/wallets/src/signers/types.ts:143](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L143)

#### Inherited from

[`Signer`](./Signer).[`type`](./Signer#type)

## Methods

### address()?

> `optional` **address**(): `string`

Defined in: [packages/wallets/src/signers/types.ts:145](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L145)

#### Returns

`string`

#### Inherited from

[`Signer`](./Signer).[`address`](./Signer#address)

***

### locator()

> **locator**(): `string`

Defined in: [packages/wallets/src/signers/types.ts:144](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L144)

#### Returns

`string`

#### Inherited from

[`Signer`](./Signer).[`locator`](./Signer#locator)

***

### signMessage()

> **signMessage**(`message`): `Promise`\<`BaseSignResult` | `PasskeySignResult`>

Defined in: [packages/wallets/src/signers/types.ts:146](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L146)

#### Parameters

| Parameter | Type |
| - | - |
| `message` | `string` |

#### Returns

`Promise`\<`BaseSignResult` | `PasskeySignResult`>

#### Inherited from

[`Signer`](./Signer).[`signMessage`](./Signer#signmessage)

***

### signTransaction()

> **signTransaction**(`transaction`): `Promise`\<`BaseSignResult` | `PasskeySignResult`>

Defined in: [packages/wallets/src/signers/types.ts:147](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L147)

#### Parameters

| Parameter | Type |
| - | - |
| `transaction` | `string` |

#### Returns

`Promise`\<`BaseSignResult` | `PasskeySignResult`>

#### Inherited from

[`Signer`](./Signer).[`signTransaction`](./Signer#signtransaction)


# Signer
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/typescript/interfaces/Signer



<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

Defined in: [packages/wallets/src/signers/types.ts:142](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L142)

## Extended by

* [`ExportableSigner`](./ExportableSigner)

## Type Parameters

| Type Parameter | Default type |
| - | - |
| `T` *extends* keyof `SignResultMap` | keyof `SignResultMap` |

## Properties

### type

> **type**: `T`

Defined in: [packages/wallets/src/signers/types.ts:143](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L143)

## Methods

### address()?

> `optional` **address**(): `string`

Defined in: [packages/wallets/src/signers/types.ts:145](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L145)

#### Returns

`string`

***

### locator()

> **locator**(): `string`

Defined in: [packages/wallets/src/signers/types.ts:144](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L144)

#### Returns

`string`

***

### signMessage()

> **signMessage**(`message`): `Promise`\<`SignResultMap`\[`T`]>

Defined in: [packages/wallets/src/signers/types.ts:146](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L146)

#### Parameters

| Parameter | Type |
| - | - |
| `message` | `string` |

#### Returns

`Promise`\<`SignResultMap`\[`T`]>

***

### signTransaction()

> **signTransaction**(`transaction`): `Promise`\<`SignResultMap`\[`T`]>

Defined in: [packages/wallets/src/signers/types.ts:147](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L147)

#### Parameters

| Parameter | Type |
| - | - |
| `transaction` | `string` |

#### Returns

`Promise`\<`SignResultMap`\[`T`]>


# Getting Started
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/typescript/overview



<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/sdk-reference/wallets/typescript/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

A Typescript SDK to interact with Crossmint Wallets. This SDK enables developers to easily create and manage wallets on Solana and EVM chains.

<CardGroup>
  <Snippet />
</CardGroup>

<Steps>
  <Step title="Install the SDK">
    Run the following command to install the SDK:

    <Snippet />
  </Step>

  <Step title="Create a wallet">
    ```tsx index.ts theme={null}
    import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";

    const crossmint = createCrossmint({
        apiKey: "<your-client-OR-server-api-key>",
        jwt: "<your-jwt>", // required for client-side calls, optional for server-side calls
    });
    const crossmintWallets = CrossmintWallets.from(crossmint);
    const wallet = await crossmintWallets.getOrCreateWallet({
        chain: "<your-chain>",
        signer: {
            type: "email",
            email: "<your-email>",
        },
    });

    console.log(wallet.address);
    ```
  </Step>
</Steps>

## Wallet Examples

### Get wallet balances

```ts theme={null}
const balances = await wallet.balances();

console.log(balances.nativeToken.amount);
console.log(balances.usdc.amount);
```

### Transfer

```ts theme={null}
const transaction = await wallet.send(recipient, "usdc", "100");

console.log(transaction.explorerLink);
```

### Get wallet activity

```ts theme={null}
const activity = await wallet.experimental_activity();

console.log(activity.events);
```

### Operational signers

```ts theme={null}
// Add an operational signer
await wallet.addDelegatedSigner({ signer: "<signer-address>" });

const signers = await wallet.delegatedSigners();

console.log(signers);
```

### Create custom transactions

```ts theme={null}
import { SolanaWallet, EVMWallet } from "@crossmint/wallets-sdk";

// Solana
const solanaWallet = SolanaWallet.from(wallet);
const solTx = await solanaWallet.sendTransaction({ transaction: "<serialized-or-non-serialized-transaction>" });

console.log(solTx.explorerLink);

// EVM
const evmWallet = EVMWallet.from(wallet);
const evmTx = await evmWallet.sendTransaction({ transaction: "<serialized-or-non-serialized-transaction>" });

console.log(evmTx.explorerLink);
```

### Signers and custody

<CardGroup>
  <Card title="Wallet Signers" icon="rocket" href="/wallets/v0/concepts/wallet-signers">
    Learn about signer types and how to choose the right ones.
  </Card>
</CardGroup>


# Reference
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/typescript/reference



<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/sdk-reference/wallets/typescript/reference) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

## Classes

* [CrossmintWallets](./classes/CrossmintWallets)
* [EVMWallet](./classes/EVMWallet)
* [SolanaWallet](./classes/SolanaWallet)
* [StellarWallet](./classes/StellarWallet)
* [Wallet](./classes/Wallet)
* [WalletsApiClient](./classes/WalletsApiClient)

## Interfaces

* [ExportableSigner](./interfaces/ExportableSigner)
* [Signer](./interfaces/Signer)

## Type Aliases

* [Activity](./type-aliases/Activity)
* [Balances](./type-aliases/Balances)
* [Chain](./type-aliases/Chain)
* [DelegatedSigner](./type-aliases/DelegatedSigner)
* [EmailSignerConfig](./type-aliases/EmailSignerConfig)
* [EVMChain](./type-aliases/EVMChain)
* [EvmExternalWalletSignerConfig](./type-aliases/EvmExternalWalletSignerConfig)
* [EVMTransactionInput](./type-aliases/EVMTransactionInput)
* [ExportSignerTEEConnection](./type-aliases/ExportSignerTEEConnection)
* [ExternalWalletSignerConfigForChain](./type-aliases/ExternalWalletSignerConfigForChain)
* [PhoneSignerConfig](./type-aliases/PhoneSignerConfig)
* [Signature](./type-aliases/Signature)
* [SignerConfigForChain](./type-aliases/SignerConfigForChain)
* [SolanaChain](./type-aliases/SolanaChain)
* [SolanaExternalWalletSignerConfig](./type-aliases/SolanaExternalWalletSignerConfig)
* [SolanaTransactionInput](./type-aliases/SolanaTransactionInput)
* [StellarChain](./type-aliases/StellarChain)
* [StellarExternalWalletSignerConfig](./type-aliases/StellarExternalWalletSignerConfig)
* [Transaction](./type-aliases/Transaction)
* [WalletArgsFor](./type-aliases/WalletArgsFor)
* [WalletPlugin](./type-aliases/WalletPlugin)

## Functions

* [createCrossmint](./functions/createCrossmint)
* [isExportableSigner](./functions/isExportableSigner)


# Activity
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/typescript/type-aliases/Activity



<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

> **Activity** = `WalletsV1Alpha2ActivityResponseDto`

Defined in: [packages/wallets/src/api/types.ts:69](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/api/types.ts#L69)


# Balances
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/typescript/type-aliases/Balances



<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/sdk-reference/wallets/typescript/type-aliases/Balances) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

> **Balances**\<`C`> = `object`

Defined in: [packages/wallets/src/wallets/types.ts:153](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L153)

## Type Parameters

| Type Parameter | Default type |
| - | - |
| `C` *extends* [`Chain`](./Chain) | [`Chain`](./Chain) |

## Properties

### nativeToken

> **nativeToken**: `TokenBalance`\<`C`>

Defined in: [packages/wallets/src/wallets/types.ts:154](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L154)

***

### tokens

> **tokens**: `TokenBalance`\<`C`>\[]

Defined in: [packages/wallets/src/wallets/types.ts:156](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L156)

***

### usdc

> **usdc**: `TokenBalance`\<`C`>

Defined in: [packages/wallets/src/wallets/types.ts:155](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L155)


# Chain
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/typescript/type-aliases/Chain



<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/sdk-reference/wallets/typescript/type-aliases/Chain) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

> **Chain** = [`SolanaChain`](./SolanaChain) | [`EVMChain`](./EVMChain) | [`StellarChain`](./StellarChain)

Defined in: [packages/wallets/src/chains/chains.ts:151](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/chains/chains.ts#L151)


# DelegatedSigner
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/typescript/type-aliases/DelegatedSigner



<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

> **DelegatedSigner** = `object`

Defined in: [packages/wallets/src/wallets/types.ts:104](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L104)

## Properties

### signer

> **signer**: `string`

Defined in: [packages/wallets/src/wallets/types.ts:105](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L105)


# EVMChain
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/typescript/type-aliases/EVMChain



<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/sdk-reference/wallets/typescript/type-aliases/EVMChain) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

> **EVMChain** = `EVMSmartWalletChain`

Defined in: [packages/wallets/src/chains/chains.ts:149](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/chains/chains.ts#L149)


# EVMTransactionInput
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/typescript/type-aliases/EVMTransactionInput



<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/sdk-reference/wallets/typescript/type-aliases/EVMTransactionInput) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

> **EVMTransactionInput** = `EVMTransactionInputBase` & \{ `abi`: `Abi`; `args`: `unknown`\[]; `data`: `` `0x${string}` ``; `functionName`: `string`; `to`: `string`; `value`: `bigint`; } | \{ `transaction`: `string`; }

Defined in: [packages/wallets/src/wallets/types.ts:56](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L56)


# EmailSignerConfig
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/typescript/type-aliases/EmailSignerConfig



<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/sdk-reference/wallets/typescript/type-aliases/EmailSignerConfig) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

> **EmailSignerConfig** = `object`

Defined in: [packages/wallets/src/signers/types.ts:34](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L34)

## Properties

### email?

> `optional` **email**: `string`

Defined in: [packages/wallets/src/signers/types.ts:36](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L36)

***

### onAuthRequired()?

> `optional` **onAuthRequired**: (`needsAuth`, `sendEmailWithOtp`, `verifyOtp`, `reject`) => `Promise`\<`void`>

Defined in: [packages/wallets/src/signers/types.ts:37](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L37)

#### Parameters

| Parameter | Type |
| - | - |
| `needsAuth` | `boolean` |
| `sendEmailWithOtp` | () => `Promise`\<`void`> |
| `verifyOtp` | (`otp`) => `Promise`\<`void`> |
| `reject` | () => `void` |

#### Returns

`Promise`\<`void`>

***

### type

> **type**: `"email"`

Defined in: [packages/wallets/src/signers/types.ts:35](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L35)


# EvmExternalWalletSignerConfig
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/typescript/type-aliases/EvmExternalWalletSignerConfig



<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/sdk-reference/wallets/typescript/type-aliases/EvmExternalWalletSignerConfig) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

> **EvmExternalWalletSignerConfig** = `BaseExternalWalletSignerConfig` & `object`

Defined in: packages/common/base/dist/types/signers.d.ts:16

## Type Declaration

### provider?

> `optional` **provider**: `GenericEIP1193Provider` | `EIP1193Provider`

### viemAccount?

> `optional` **viemAccount**: `Account`


# ExportSignerTEEConnection
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/typescript/type-aliases/ExportSignerTEEConnection



<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/sdk-reference/wallets/typescript/type-aliases/ExportSignerTEEConnection) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

> **ExportSignerTEEConnection** = `HandshakeParent`\<*typeof* `exportSignerOutboundEvents`, *typeof* `exportSignerInboundEvents`>

Defined in: [packages/wallets/src/signers/types.ts:158](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L158)


# ExternalWalletSignerConfigForChain
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/typescript/type-aliases/ExternalWalletSignerConfigForChain



<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/sdk-reference/wallets/typescript/type-aliases/ExternalWalletSignerConfigForChain) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

> **ExternalWalletSignerConfigForChain**\<`C`> = `C` *extends* [`SolanaChain`](./SolanaChain) ? [`SolanaExternalWalletSignerConfig`](./SolanaExternalWalletSignerConfig) : `C` *extends* [`StellarChain`](./StellarChain) ? [`StellarExternalWalletSignerConfig`](./StellarExternalWalletSignerConfig) : [`EvmExternalWalletSignerConfig`](./EvmExternalWalletSignerConfig)

Defined in: [packages/wallets/src/signers/types.ts:58](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L58)

## Type Parameters

| Type Parameter |
| - |
| `C` *extends* [`Chain`](./Chain) |


# PhoneSignerConfig
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/typescript/type-aliases/PhoneSignerConfig



<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/sdk-reference/wallets/typescript/type-aliases/PhoneSignerConfig) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

> **PhoneSignerConfig** = `object`

Defined in: [packages/wallets/src/signers/types.ts:45](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L45)

## Properties

### onAuthRequired()?

> `optional` **onAuthRequired**: (`needsAuth`, `sendEmailWithOtp`, `verifyOtp`, `reject`) => `Promise`\<`void`>

Defined in: [packages/wallets/src/signers/types.ts:48](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L48)

#### Parameters

| Parameter | Type |
| - | - |
| `needsAuth` | `boolean` |
| `sendEmailWithOtp` | () => `Promise`\<`void`> |
| `verifyOtp` | (`otp`) => `Promise`\<`void`> |
| `reject` | () => `void` |

#### Returns

`Promise`\<`void`>

***

### phone?

> `optional` **phone**: `string`

Defined in: [packages/wallets/src/signers/types.ts:47](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L47)

***

### type

> **type**: `"phone"`

Defined in: [packages/wallets/src/signers/types.ts:46](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L46)


# Signature
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/typescript/type-aliases/Signature



<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/sdk-reference/wallets/typescript/type-aliases/Signature) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

> **Signature**\<`TPrepareOnly`> = `TPrepareOnly` *extends* `true` ? `object` : `object`

Defined in: [packages/wallets/src/wallets/types.ts:178](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L178)

## Type Parameters

| Type Parameter | Default type |
| - | - |
| `TPrepareOnly` *extends* `boolean` | `false` |


# SignerConfigForChain
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/typescript/type-aliases/SignerConfigForChain



<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/sdk-reference/wallets/typescript/type-aliases/SignerConfigForChain) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

> **SignerConfigForChain**\<`C`> = `C` *extends* [`SolanaChain`](./SolanaChain) ? [`EmailSignerConfig`](./EmailSignerConfig) | [`PhoneSignerConfig`](./PhoneSignerConfig) | `BaseSignerConfig`\<`C`> : `C` *extends* [`StellarChain`](./StellarChain) ? [`EmailSignerConfig`](./EmailSignerConfig) | [`PhoneSignerConfig`](./PhoneSignerConfig) | `BaseSignerConfig`\<`C`> : [`EmailSignerConfig`](./EmailSignerConfig) | [`PhoneSignerConfig`](./PhoneSignerConfig) | `PasskeySignerConfig` | `BaseSignerConfig`\<`C`>

Defined in: [packages/wallets/src/signers/types.ts:125](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/types.ts#L125)

## Type Parameters

| Type Parameter |
| - |
| `C` *extends* [`Chain`](./Chain) |


# SolanaChain
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/typescript/type-aliases/SolanaChain



<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/sdk-reference/wallets/typescript/type-aliases/SolanaChain) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

> **SolanaChain** = `"solana"`

Defined in: [packages/wallets/src/chains/chains.ts:147](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/chains/chains.ts#L147)


# SolanaExternalWalletSignerConfig
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/typescript/type-aliases/SolanaExternalWalletSignerConfig



<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/sdk-reference/wallets/typescript/type-aliases/SolanaExternalWalletSignerConfig) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

> **SolanaExternalWalletSignerConfig** = `BaseExternalWalletSignerConfig` & `object`

Defined in: packages/common/base/dist/types/signers.d.ts:20

## Type Declaration

### onSignTransaction()?

> `optional` **onSignTransaction**: (`transaction`) => `Promise`\<`VersionedTransaction`>

#### Parameters

| Parameter | Type |
| - | - |
| `transaction` | `VersionedTransaction` |

#### Returns

`Promise`\<`VersionedTransaction`>


# SolanaTransactionInput
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/typescript/type-aliases/SolanaTransactionInput



<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/sdk-reference/wallets/typescript/type-aliases/SolanaTransactionInput) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

> **SolanaTransactionInput** = \{ `transaction`: `VersionedTransaction`; } | \{ `serializedTransaction`: `string`; } & `object`

Defined in: [packages/wallets/src/wallets/types.ts:84](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L84)

## Type Declaration

### additionalSigners?

> `optional` **additionalSigners**: `Keypair`\[]

### options?

> `optional` **options**: `TransactionInputOptions`


# StellarChain
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/typescript/type-aliases/StellarChain



<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/sdk-reference/wallets/typescript/type-aliases/StellarChain) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

> **StellarChain** = `"stellar"`

Defined in: [packages/wallets/src/chains/chains.ts:148](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/chains/chains.ts#L148)


# StellarExternalWalletSignerConfig
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/typescript/type-aliases/StellarExternalWalletSignerConfig



<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/sdk-reference/wallets/typescript/type-aliases/StellarExternalWalletSignerConfig) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

> **StellarExternalWalletSignerConfig** = `BaseExternalWalletSignerConfig` & `object`

Defined in: packages/common/base/dist/types/signers.d.ts:23

## Type Declaration

### onSignStellarTransaction()?

> `optional` **onSignStellarTransaction**: (`transaction`) => `Promise`\<`string`>

#### Parameters

| Parameter | Type |
| - | - |
| `transaction` | `string` |

#### Returns

`Promise`\<`string`>


# Transaction
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/typescript/type-aliases/Transaction



<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/sdk-reference/wallets/typescript/type-aliases/Transaction) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

> **Transaction**\<`TPrepareOnly`> = `TPrepareOnly` *extends* `true` ? `object` : `object`

Defined in: [packages/wallets/src/wallets/types.ts:166](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L166)

## Type Parameters

| Type Parameter | Default type |
| - | - |
| `TPrepareOnly` *extends* `boolean` | `false` |


# WalletArgsFor
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/typescript/type-aliases/WalletArgsFor



<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/sdk-reference/wallets/typescript/type-aliases/WalletArgsFor) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

> **WalletArgsFor**\<`C`> = `object`

Defined in: [packages/wallets/src/wallets/types.ts:127](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L127)

## Type Parameters

| Type Parameter |
| - |
| `C` *extends* [`Chain`](./Chain) |

## Properties

### alias?

> `optional` **alias**: `string`

Defined in: [packages/wallets/src/wallets/types.ts:134](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L134)

***

### chain

> **chain**: `C`

Defined in: [packages/wallets/src/wallets/types.ts:128](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L128)

***

### delegatedSigners?

> `optional` **delegatedSigners**: [`DelegatedSigner`](./DelegatedSigner)\[]

Defined in: [packages/wallets/src/wallets/types.ts:133](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L133)

***

### options?

> `optional` **options**: `WalletOptions`

Defined in: [packages/wallets/src/wallets/types.ts:132](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L132)

***

### owner?

> `optional` **owner**: `string`

Defined in: [packages/wallets/src/wallets/types.ts:130](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L130)

***

### plugins?

> `optional` **plugins**: [`WalletPlugin`](./WalletPlugin)\<`C`>\[]

Defined in: [packages/wallets/src/wallets/types.ts:131](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L131)

***

### signer

> **signer**: [`SignerConfigForChain`](./SignerConfigForChain)\<`C`>

Defined in: [packages/wallets/src/wallets/types.ts:129](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L129)


# WalletPlugin
Source: https://docs.crossmint.com/sdk-reference/wallets/v0/typescript/type-aliases/WalletPlugin



<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/sdk-reference/wallets/typescript/type-aliases/WalletPlugin) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

> **WalletPlugin**\<`C`> = `C` *extends* [`StellarChain`](./StellarChain) ? `StellarWalletPlugin` : `never`

Defined in: [packages/wallets/src/wallets/types.ts:120](https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/wallets/types.ts#L120)

## Type Parameters

| Type Parameter |
| - |
| `C` *extends* [`Chain`](./Chain) |


# Global Payroll
Source: https://docs.crossmint.com/solutions/fintech/global-payroll

Pay employees and contractors worldwide instantly

## Overview

Transform your payroll operations with instant, borderless payments. Pay employees and contractors globally using
stablecoins, eliminating wire transfer delays, reducing costs by up to 90%, and providing workers with instant access
to their earnings - regardless of their location or banking infrastructure.

This solution is ideal for:

<AccordionGroup>
  <Accordion title="Remote-First Companies">
    Pay distributed teams across the globe instantly. Eliminate the complexity of managing multiple banking relationships and currency conversions for international payroll.
  </Accordion>

  <Accordion title="Contractor Management Platforms">
    Enable instant payments to freelancers and contractors worldwide. Offer competitive payment terms with same-day or real-time settlement options.
  </Accordion>

  <Accordion title="BPO & Outsourcing Firms">
    Streamline payroll for offshore teams and reduce transfer costs. Pay workers in emerging markets where traditional banking infrastructure is limited.
  </Accordion>
</AccordionGroup>

## Common Architectures

1. **Instant Payroll**: Convert fiat payroll to stablecoins and distribute to employee wallets instantly
2. **Programmable Payroll**: Automate recurring payroll distributions on custom schedules or conditions

<Info>
  Need a custom flow for your use case? Crossmint can help you design, build, and optimize it end-to-end. [Reach out to get started](https://www.crossmint.com/contact/sales).
</Info>

## How It Works

1. **Compliance**: Use Crossmint's licenses or bring your own
2. **Wallets**: Use Crossmint's wallets, which can be configured in both custodial, or non-custodial modes
3. **Onramp**: Optionally, have the user initiate the transaction with credit card or bank transfer
4. **Stablecoin Transfer**: Instant transfers, without needing to deal with gas fees, retries, sanctions checks
5. **Receive Funds**: Receive the money in stablecoin, bank account, or local payment methods

All stablecoins are supported, in over 50 supported [chains](/introduction/supported-chains).

## Integration Steps

[Contact our sales team](https://www.crossmint.com/contact/sales) to request a consultation to help you design and integrate.


# Neobanks
Source: https://docs.crossmint.com/solutions/fintech/neobanks

Launch a global stablecoin neobank product in days

This guide walks through how to build a modern stablecoin-powered neobank from scratch—or integrate stablecoin capabilities into your existing banking platform—using Crossmint's infrastructure.

## Overview

With stablecoins, you can launch global accounts and other financial products in days, build better experiences than traditional banking, and unlock new revenue streams.

<Accordion title="Key benefits">
  * **Global reach** — Serve customers in 180+ different countries from day one.
  * **New revenue streams** — Generate 3-4% of interest on deposits and offer embedded financial products including cards, trading, prediction markets, and more.
  * **Instant settlement** — Enable 24/7 instant transfers instead of 2-5 day settlement windows.
  * **Lower costs** — Reduce international transfer costs. Eliminate correspondent banking fees and reduce pre-funding requirements.
</Accordion>

Crossmint offers the full technology stack and licensing to help you launch faster, without having to orchestrate many different vendors, including wallets, on and offramps, and additional embedded finance products.

## Key Architectural Decisions

Building a stablecoin-powered neobank requires making several foundational architectural decisions. These choices shape your product capabilities, regulatory requirements, and unit economics. The optimal architecture depends on whether you are launching a new digital bank or enhancing an existing platform, your preference around custody, and what infrastructure you have already built.

### Key Components

There are three key components:

1. **Wallets** — The foundation of the system. Wallets allow users to hold, send, and receive stablecoins and other crypto assets.
2. **On and offramps** — Allow users to fund and withdraw funds from their wallets.
3. **Embedded financial services** — Additional products built on top of wallets, including yield, cards, swaps, trading, and more.

### Existing vs New Neobanks

**Existing neobanks** typically reuse their core banking and payment infrastructure, adding stablecoins as a complementary payment rail. Some expose both fiat and stablecoin balances within their current geographies, while others launch separate, globally available products built primarily around stablecoins.

**New neobanks** have the advantage of building stablecoin-first from the ground up. They can design the entire customer experience and flows around blockchain rails from day one. They also often start with plug-and-play on/offramps to go-to-market faster instead of relying on traditional payments processors.

### Custody Model

The custody decision is fundamental—it determines who controls the private keys to customer funds, which shapes your regulatory obligations, liability exposure, operational complexity, and product capabilities. Crossmint supports multiple custody models, and many neobanks use different approaches for different customer segments or account types.

The general recommendation is to use non-custodial wallets as they offer global coverage from day one, more functionality, lower cost, compliance, and operational overhead; without compromising on user experience.

<AccordionGroup>
  <Accordion title="Custodial wallets">
    Private keys are held by Crossmint, an affiliated partner, or by you on behalf of your users. You can choose between segregated wallets or an omnibus wallet structure.

    Omnibus wallets are generally not recommended. They significantly constrain future functionality and external integrations, and concentrate risk by pooling funds in a single structure.

    **Best for:** Companies focusing on only one or a small subset of geographies. Closed-loop systems. Non-financial use cases.

    **Tradeoffs:** Significantly higher operational and compliance burden and costs (KYC, insurance, additional security controls, travel rule checks in and out of the wallets). More complex and fragile external integrations (e.g., cards, banking rails, and third-party payment providers).
  </Accordion>

  <Accordion title="Non-custodial wallets">
    Users control their own private keys, accessed through intuitive web2-style authentication (email, social login, biometrics, passkeys). Behind the scenes, Crossmint handles all of the complexity so the blockchain is invisible to the user.

    **Best for:** Global products. Apps that interact with third-parties or protocols: paying merchants, signing transactions, accessing DeFi protocols.

    **Tradeoffs:** Same UX as custodial wallets. Some traditional banking features (like reversing fraudulent transactions) become difficult or impossible.
  </Accordion>

  <Accordion title="Hybrid custody">
    Crossmint allows you to define custody granularly at the user, asset, or transaction level. This allows you to combine both strategically, everything with the same API. For example, offering custodial wallets in the US and non-custodial internationally. Or start with one model and then migrate to the other one, without having to migrate vendors or change wallet addresses.
  </Accordion>
</AccordionGroup>

### Onramp Structure

How users move between fiat currency and stablecoins is critical to your product's accessibility and regulatory posture. You have flexibility in how much of this infrastructure you own vs leverage from Crossmint.

<AccordionGroup>
  <Accordion title="Stablecoin payouts">
    You pre-fund Crossmint and use a single API to deliver funds to users' wallets. This model gives you full control over the onramp experience while Crossmint handles the licensing, stablecoin settlement, and compliance checks. Best for teams that already work with their own PSPs and just need the stablecoin last-mile. Read more about [stablecoin orchestration](/stablecoin-orchestration/money-movement/overview).
  </Accordion>

  <Accordion title="End-to-end onramps/offramps">
    Crossmint provides the full onramp and offramp integration, so you do not need in-house checkout, fraud prevention, chargeback, currency conversion, or KYC/AML operations. Best for teams who want a plug-and-play solution, want to reduce their chargeback exposure, or do not have an internal anti-fraud team. Read more about the [onramp](/payments/introduction).
  </Accordion>
</AccordionGroup>

### Approach to Yield

There are multiple ways to generate yield. You can read more about [yield strategies](/wallets/guides/wallet-extensions/overview).

### Embedded Financial Services

Beyond core banking capabilities, stablecoins unlock a rich ecosystem of embedded financial products that can offer more value to your customers and unlock new revenue streams:

* **Cards** — Virtual and physical debit cards that spend directly from stablecoin balances, with instant settlement and transparent fees. Capture interchange revenue while offering customers global spending power.
* **Trading** — Enable swaps between stablecoins, cryptocurrencies, and other digital assets. Capture spread revenue while providing customers access to crypto investment opportunities.
* **Yield products** — High-yield savings accounts, automated yield optimization, and access to structured products. Generate fee revenue while offering rates that crush traditional banks.
* **Prediction markets** — Let customers participate in decentralized prediction markets for events, elections, or market outcomes—a unique offering unavailable through traditional banks.
* **DeFi access** — For crypto-savvy users, provide direct access to lending protocols, DEXs, and other DeFi primitives through your interface.

The key is selecting the right mix for your target customer segment and regulatory environment. Start with core features and add capabilities incrementally based on user demand and market readiness.

<Info>
  Need a custom solution? Crossmint's Forward Deployment Engineers can help you design, build, and optimize it end-to-end. [Reach out to set up a personalized consultation](https://www.crossmint.com/contact/sales).
</Info>

## Solution Components

Crossmint's platform provides all the building blocks needed to implement any of the architectures above via simple APIs. Key solution components include:

<CardGroup>
  <Card title="Embedded wallets" icon="wallet" href="/wallets/overview">
    Create wallets for your users.
  </Card>

  <Card title="Onramp" icon="arrow-up-to-line" href="/payments/introduction">
    Allow users to fund their wallets directly.
  </Card>

  <Card title="Stablecoin orchestration" icon="coins" href="/stablecoin-orchestration/money-movement/overview">
    Send stablecoins to users.
  </Card>

  <Card title="Cards" icon="credit-card" href="https://www.crossmint.com/contact/sales">
    Issue stablecoin-linked cards.
  </Card>

  <Card title="Yield" icon="chart-line-up" href="/wallets/guides/wallet-extensions/overview">
    Earn yield on balances.
  </Card>
</CardGroup>

## Get Started

<Snippet />


# Remittances
Source: https://docs.crossmint.com/solutions/fintech/remittances

Build modern remittance flows that are faster, lower cost, and unlock new revenue streams

This guide explains the key architectural decisions involved in building stablecoin remittance flows and how to implement them with Crossmint's infrastructure.

## Overview

Stablecoins provide remittance providers with a faster and more cost-effective alternative to traditional correspondent banking infrastructure.

Key benefits include:

* **Lower costs:** Eliminate SWIFT and correspondent banking fees. Reduce costs from 5-10% to a few basis points.
* **Faster settlement:** Provides instant settlement, improves working capital, and reduces pre-funding requirements across corridors.
* **New Revenue Streams:** Earn yield on operational treasury and user balances, and offer digital wallets and embedded financial products—such as yield, cards, and trading—through a single integration across 150+ markets.
* **Unlock Underserved Corridors:** Enable service in markets with limited banking infrastructure or where traditional correspondent banking is prohibitively expensive.

## How it Works

Stablecoin remittance products can be built in multiple ways. The right approach depends on your current infrastructure and the user experience you want to create for senders and recipients.

In practice, every remittance flow is defined by two independent decisions:

1. How funds enter the system
2. How recipients receive funds

### 1. How funds enter the system

#### Treasury-based model

In this model, the remittance provider receives fiat from senders and converts it into stablecoins, which are held in a centrally managed treasury wallet. You can pre-fund the treasury to enable instant payouts, or convert to stablecoins real time. Best for existing remittance providers without a sender wallet.

#### Sender wallet model

Senders first fund a wallet, then initiate transfers from their balance. This introduces an extra step, but unlocks additional capabilities: in-app balances for senders, peer-to-peer transfers, recurring or programmable payments, and a broader wallet-based product offering. Best for wallet-first companies.

### 2. How recipients receive funds

#### Fiat payout

Stablecoins are used purely as the settlement rail. Funds are automatically converted to local currency and delivered via bank transfer, mobile money, or cash pickup.

#### Stablecoin payout

Recipients receive funds directly into an embedded wallet. This lets them hold USD-denominated value, hedge against local currency volatility, earn yield, or cash out on their own terms—while unlocking new revenue streams for you. Wallets can be pre-generated, so recipients don't need to sign up before receiving funds; they simply log in and see their balance instantly.

### Combining these modules

These models are fully composable and can be combined to support different remittance flows, for example:

* Treasury-based funding → stablecoin payouts (most common)
* Treasury-based funding → fiat payouts
* Sender wallets → stablecoin payouts
* Sender wallets → fiat payouts

<Frame type="simple">
  <img alt="Treasury-Based Model Architecture" />
</Frame>

<Frame type="simple">
  <img alt="Sender Wallet Model Architecture" />
</Frame>

<Info>
  Need a custom flow for your use case? Crossmint can help you design, build, and optimize it end-to-end. [Reach out to set up a personalized consultation](https://www.crossmint.com/contact/sales).
</Info>

## Solution Components

Crossmint's platform provides all the building blocks needed to implement any of the architectures above via simple APIs. Key solution components include:

<CardGroup>
  <Card title="Treasury wallets" icon="vault" href="/wallets/concepts/treasury">
    Create treasury wallets to manage your own funds.
  </Card>

  <Card title="Embedded wallets" icon="wallet" href="/wallets/overview">
    Create wallets for your users: receivers and/or senders.
  </Card>

  <Card title="B2B Onramp" icon="building-columns" href="/onramp/overview">
    Fund your treasury with stablecoins.
  </Card>

  <Card title="B2C Onramp" icon="credit-card" href="/onramp/overview">
    Embed a widget on your app and allow users to fund their wallets.
  </Card>

  <Card title="Regulated payouts" icon="shield-check" href="/stablecoin-orchestration/regulated-transfers/overview">
    Send stablecoins to third-parties using Crossmint's licenses, with built-in AML, sanctions and travel rule checks.
  </Card>

  <Card title="Offramp" icon="money-bill-wave" href="https://www.crossmint.com/contact/sales">
    Convert stablecoins to local currency and deliver to bank accounts, mobile wallets, or local payment rails across key remittance corridors.
  </Card>
</CardGroup>

## Get Started

<CardGroup>
  <Card title="Contact Sales" icon="phone" href="https://www.crossmint.com/contact/sales">
    Contact our sales team to request a consultation to help you design and integrate.
  </Card>
</CardGroup>


# Stablecoin Payouts
Source: https://docs.crossmint.com/solutions/fintech/stablecoin-payouts

Instant, low-cost global payments with stablecoins

## Overview

Enable your platform to send instant payments globally using stablecoins. Convert fiat to stablecoins and distribute
funds to recipients worldwide with minimal fees, instant settlement, and 24/7 availability - eliminating the limitations
of traditional banking systems.

This solution is ideal for:

<AccordionGroup>
  <Accordion title="Marketplace Platforms">
    Pay sellers, creators, and service providers globally with instant settlements. Enable cross-border payments without the delays and high fees of traditional payment rails.
  </Accordion>

  <Accordion title="Gig Economy Apps">
    Provide instant earnings access to drivers, shoppers, and freelancers. Pay out in real-time regardless of banking hours or geographic location.
  </Accordion>

  <Accordion title="Aid disbursement">
    Low cost, global aid disbursement in stablecoins
  </Accordion>
</AccordionGroup>

## Common Architectures

1. **Fiat-to-Stablecoin Payouts**: Onramp from fiat, convert to stablecoins, and send to recipients' wallets
2. **Direct Stablecoin Distribution**: Hold treasury in stablecoins and distribute directly to recipients

<Info>
  Need a custom flow for your use case? Crossmint can help you design, build, and optimize it end-to-end. [Reach out to get started](https://www.crossmint.com/contact/sales).
</Info>

## How It Works

1. **Compliance**: Use Crossmint's licenses or bring your own
2. **Wallets**: Use Crossmint's wallets, which can be configured in both custodial, or non-custodial modes
3. **Onramp**: Optionally, have the user initiate the transaction with credit card or bank transfer
4. **Stablecoin Transfer**: Instant transfers, without needing to deal with gas fees, retries, sanctions checks
5. **Receive Funds**: Receive the money in stablecoin, bank account, or local payment methods

All stablecoins are supported, in over 50 supported [chains](/introduction/supported-chains).

## Integration Steps

[Contact our sales team](https://www.crossmint.com/contact/sales) to request a consultation to help you design and integrate.


# Checkout Trigger Node (x402 Paywall)
Source: https://docs.crossmint.com/solutions/n8n/nodes/checkout-trigger

Accept cryptocurrency payments via the x402 protocol to gate access to your n8n workflows

The Crossmint Checkout Trigger node lets you create payment-gated webhook endpoints using the <a href="https://www.x402.org/">x402 payment protocol</a>. When set to **Paywall** mode, the node acts as an x402 server: it returns a `402 Payment Required` response to any request that does not include a valid payment header, and only triggers your workflow once payment is verified and confirmed on-chain.

This node uses <a href="https://docs.faremeter.com/">Faremeter</a> under the hood for payment handling and the <a href="https://facilitator.corbits.dev/">Corbits facilitator</a> for on-chain confirmation.

<Callout type="info">
  The x402 Paywall mode works with **EVM wallets** only (e.g., Base). Crossmint wallets are on Solana, so for this trigger you need an external EVM wallet such as MetaMask or any wallet that exposes a private key on an EVM chain.
</Callout>

## Trigger Fields

When you add a **Crossmint Checkout Trigger** node and select the **Paywall** mode, the following fields are available:

<Frame type="simple">
  <img alt="x402 Paywall trigger configuration" />
</Frame>

### Credential

* **Crossmint account** — Your Crossmint API credential. See the <a href="/solutions/n8n/quickstart#get-started">Quickstart</a> for how to set this up.

### Mode

* **Paywall** — Enables x402 payment verification. Every incoming request must include a valid `X-PAYMENT` header or the node responds with `402 Payment Required`.

### Path

* **Path** — The webhook path appended to your n8n instance URL. For example, setting this to `webhook` produces a URL like `https://your-instance.app.n8n.cloud/webhook/webhook`.

### Respond

* **Respond** — Controls when the webhook sends its HTTP response back to the caller:
  * `When Last Node Finishes` — Waits until the entire workflow completes before responding
  * `Immediately` — Responds right away, before the workflow finishes
  * `Using 'Respond to Webhook' Node` — Lets you control the response manually with a dedicated node

### Response Data

* **Response Data** — Determines what data is returned in the webhook response:
  * `First Entry JSON` — Returns the JSON output of the first item produced by the workflow
  * `All Entries JSON` — Returns all items as a JSON array
  * `No Response Body` — Returns an empty body

### Tokens

The **Tokens** section defines which cryptocurrency payments the paywall accepts. You can configure one or more token entries:

* **Payment Token Name or ID** — The token to accept for payment. Select from available options such as `USDC (Base)`, `USDC (Base Sepolia)`, etc.
* **Pay To Address** — The EVM wallet address that receives the payment (e.g., `0xf446cBEC1Ad886c35A4f93e9de87e3622380554D`)
* **Payment Amount** — The amount of the token required per request (e.g., `0.100000` for 0.1 USDC)

You can add multiple token entries by clicking **Choose...** to accept different tokens or amounts.

### Allowed Origins (CORS)

* **Allowed Origins (CORS)** — Controls which origins can call the webhook. Set to `*` to allow all origins, or specify a comma-separated list of allowed domains (e.g., `https://myapp.com, https://another.com`).

## How It Works

<Steps>
  <Step title="Client sends a request">
    A client sends an HTTP request to your webhook URL. If no `X-PAYMENT` header is present, the node responds with `402 Payment Required` along with the payment requirements (token, amount, recipient).
  </Step>

  <Step title="Client signs a payment">
    The client uses an x402-compatible library (like <a href="https://docs.faremeter.com/">Faremeter</a>) to generate a signed payment proof and retries the request with the `X-PAYMENT` header.
  </Step>

  <Step title="Payment is verified and confirmed">
    The node verifies the payment proof via the Corbits facilitator and confirms the transaction on-chain. Once confirmed, your workflow executes.
  </Step>

  <Step title="Workflow responds">
    The workflow runs and returns its output to the caller, depending on your **Respond** and **Response Data** settings.
  </Step>
</Steps>

## Testing with a Client Script

Below is a complete client-side script that sends an x402 payment to your Paywall webhook. It uses Faremeter's `@faremeter/fetch`, `@faremeter/payment-evm`, and `@faremeter/wallet-evm` packages.

<Callout type="warning">
  **Private Key Security**

  Replace the placeholder private key below with your own EVM wallet private key. Never use real private keys in code — always store them in environment variables or secure vaults.
</Callout>

```javascript theme={null}
import { wrap } from '@faremeter/fetch';
import { createPaymentHandler } from '@faremeter/payment-evm/exact';
import { createLocalWallet } from '@faremeter/wallet-evm';

const PRIVATE_KEY = process.env.EVM_PRIVATE_KEY; // Your EVM wallet private key
const URL = 'https://your-instance.app.n8n.cloud/webhook/your-webhook-path';

const wallet = await createLocalWallet({ id: 8453, name: 'Base' }, PRIVATE_KEY);
const handler = createPaymentHandler(wallet);

// Server sends extra.name "USDC" but the Base USDC contract's EIP-712 domain
// uses name() = "USD Coin". Patch the 402 response so the client signs with
// the correct domain, otherwise transferWithAuthorization reverts on-chain.
async function patchedFetch(input, init) {
  const res = await fetch(input, init);
  if (res.status !== 402) return res;

  const body = await res.json();
  if (body.accepts) {
    for (const req of body.accepts) {
      if (req.extra?.name === 'USDC') {
        req.extra.name = 'USD Coin';
      }
    }
  }
  return new Response(JSON.stringify(body), {
    status: 402,
    headers: res.headers,
  });
}

const payFetch = wrap(fetch, {
  handlers: [handler],
  phase1Fetch: patchedFetch,
  returnPaymentFailure: true,
});

console.log('Wallet:', wallet.address);
console.log('Sending x402 payment to', URL);

const response = await payFetch(URL, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({}),
});

const body = await response.text();
console.log('Status:', response.status);

if (response.ok) {
  console.log('Payment succeeded!');
  console.log('Response:', body);
} else {
  console.error('Payment failed');
  try {
    const parsed = JSON.parse(body);
    if (parsed.error) console.error('Error:', parsed.error);
  } catch {
    console.error('Body:', body);
  }
}
```

To run this script:

1. Install the required packages:

```bash theme={null}
npm install @faremeter/fetch @faremeter/payment-evm @faremeter/wallet-evm
```

2. Save the script as `x402-client.mjs` and set your environment variables:

```bash theme={null}
export EVM_PRIVATE_KEY="0xYOUR_PRIVATE_KEY_HERE"
```

3. Update the `URL` constant in the script to point to your own Paywall webhook URL.

4. Run it:

```bash theme={null}
node x402-client.mjs
```

For full Faremeter documentation and additional wallet/chain options, see the <a href="https://docs.faremeter.com/">Faremeter docs</a>.

## Example Use Cases

* **Paid API Endpoints** — Monetize any n8n workflow by gating it behind a micropayment
* **AI Agent Services** — Let AI agents pay per-request for access to data or actions
* **Premium Webhooks** — Offer paid webhook integrations to third-party developers
* **Content Paywalls** — Gate access to generated content, reports, or data feeds

## Next Steps

<CardGroup>
  <Card title="Wallets Node" icon="wallet" href="/solutions/n8n/nodes/wallets">
    Learn about managing wallets for payments
  </Card>

  <Card title="Faremeter Docs" icon="book" href="https://docs.faremeter.com/">
    Full x402 protocol and Faremeter documentation
  </Card>

  <Card title="Ask ChatGPT" icon="comments" href="https://chatgpt.com/g/g-68d13ccc81ac8191a0c3716ce980faff-n8n-crossmint-expert">
    Ask Crossmint Expert GPT for n8n guidance
  </Card>
</CardGroup>


# Wallets Node
Source: https://docs.crossmint.com/solutions/n8n/nodes/wallets

Manage blockchain wallets, balances, and token transfers

The Crossmint Wallets node provides operations for managing blockchain wallets that can hold and transfer digital money like USDC.

## Operations

### Get or Create Wallet

Creates a non-custodial smart wallet or retrieves an existing one. You control it via a private key that authorizes all transactions. This operation is idempotent.

**Parameters:**

* **Chain Type** — Blockchain type (`solana`)
* **Owner Type** — Optional owner identifier type (`email`, `userId`, `phone`, `twitter`, `x`, `none`)
* **Owner Details** — Specific owner information based on the selected type
* **Admin Signer** — Private key that authorizes all transactions from this wallet (see [Admin Signer Private Key](#admin-signer-private-key) below)

### Get Wallet

Retrieves wallet details using its locator (address, email, user ID, etc.).

**Parameters:**

* **Wallet** — Wallet identifier (`address`, `email`, `userId`, `phone`, `twitter`, `x`)
* **Chain Type** — Required for non-address locators (`solana`)

### Create Transfer

Sends tokens (like USDC) between wallets. Requires the wallet's private key to sign and authorize.

**Parameters:**

* **Blockchain Type** — `solana`
* **Origin Wallet** — Source wallet
* **Recipient Wallet** — Destination wallet
* **Token Chain** — Specific network (`solana`)
* **Token Name** — Token symbol/identifier (e.g., `usdc`)
* **Amount** — Token amount

### Get Balance

Checks token balances for a wallet across one or more networks.

**Parameters:**

* **Wallet** — Locator (`address`, `email`, `userId`, `phone`, `twitter`, `x`)
* **Chain Type** — Required for non-address locators (`solana`)
* **Chains** — e.g., `solana`
* **Tokens** — Comma-separated list of token symbols

### Sign Transaction

Signs a transaction with a private key and submits the signature to complete pending transactions.

**Parameters:**

* **Chain** — Network for signing
* **Wallet Address** — From the Create Transfer response
* **Transaction ID** — ID that needs approval
* **Transaction Data** — Hash/message to sign from transfer response
* **Signer Address** — Address of the external signer
* **Signer Private Key** — Private key to sign the transaction
* **Wait for Completion** — Poll until final status

## Wallet Locators

Wallet locators provide a flexible way to identify wallets with different identifiers.

### Locator Types

| Type | Format | Example | Use Case |
| - | - | - | - |
| **Wallet Address** | Solana address | `7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU` | Direct blockchain address reference |
| **Email** | `email:{email}:{chainType}:smart` | `email:user@example.com:solana:smart` | User identification by email |
| **User ID** | `userId:{id}:{chainType}:smart` | `userId:user-123:solana:smart` | Custom user identifier |
| **Phone Number** | `phoneNumber:{phone}:{chainType}:smart` | `phoneNumber:+1234567890:solana:smart` | SMS-based identification |
| **Twitter Handle** | `twitter:{handle}:{chainType}:smart` | `twitter:username:solana:smart` | Social media identification |
| **X Handle** | `x:{handle}:{chainType}:smart` | `x:username:solana:smart` | X (formerly Twitter) identification |

For more details, see <a href="https://docs.crossmint.com/api-reference/wallets/get-wallet-by-locator">Wallet Locators</a>.

### Chain Types

* **Solana** — Solana blockchain

## Admin Signer Private Key

The **Admin Signer Private Key** is a critical security component that gives you full control over your Crossmint wallet.

### What is an Admin Signer?

The Admin Signer is the private key that acts as the "master key" for your smart wallet. It's used to:

* Authorize all transactions
* Sign transfer approvals
* Control wallet permissions and operations

### Key Requirements

**Solana**

* Base58 encoded string
* Typically 64 bytes when decoded
* Example: `5Kb8kLf9CJtPkDCe4jfE9TjC8d7X9e3Jh4F6h8F2K3h7J9F4K6h8F2K3h7J9F4K6h`

### Generating Private Keys

**Online Tools**

* **Crossmint Generator**: <a href="https://crypto-address-generator.val.run/">[https://crypto-address-generator.val.run/](https://crypto-address-generator.val.run/)</a>

**Local/Terminal (recommended for production)**

1. Install Solana CLI — <a href="https://solana.com/docs/intro/installation">Installation guide</a>
2. Generate a keypair:

```bash theme={null}
solana-keygen new --outfile ~/my-wallet.json --no-bip39-passphrase
cat ~/my-wallet.json
```

**Hardware Wallets**

* Export/derive keys securely from Ledger or other hardware wallets

<Callout type="warning">
  <b>Security best practices</b>

  <ol>
    <li>Never share your private key</li>
    <li>Store in environment variables or secure vaults</li>
    <li>Use different keys for staging vs production</li>
    <li>Back up securely (multiple locations)</li>
    <li>Test with small amounts on testnet first</li>
    <li>Rotate keys periodically</li>
  </ol>
</Callout>

### How It Works in Crossmint

1. **Wallet Creation** — Your private key becomes the admin signer for the smart wallet
2. **Transaction Flow** — Create transaction → Crossmint generates approval → Sign with private key → Submit signature
3. **Non-Custodial** — You control the key and the wallet

## Get Test USDC

For testing in the Staging environment, you can get free test USDC:

* **Circle Faucet**: <a href="https://faucet.circle.com/">[https://faucet.circle.com/](https://faucet.circle.com/)</a>

## Next Steps

<CardGroup>
  <Card title="Source Code" icon="github" href="https://github.com/crossmint/n8n-nodes-crossmint">
    Browse source code
  </Card>

  <Card title="Ask ChatGPT" icon="comments" href="https://chatgpt.com/g/g-68d13ccc81ac8191a0c3716ce980faff-n8n-crossmint-expert">
    Ask Crossmint Expert GPT for n8n guidance
  </Card>
</CardGroup>


# Overview
Source: https://docs.crossmint.com/solutions/n8n/overview

Build wallet automation and x402 payment-gated workflows with Crossmint

## What is n8n?

n8n is an open-source workflow automation tool that lets you connect different apps and services together via n8n nodes. Think of it as a way to automate tasks between different tools without writing code.

## Available Crossmint Nodes in N8N

Crossmint's n8n community package provides two nodes:

* **Crossmint Wallets** — Manage blockchain wallets, check balances, and transfer tokens
* **Crossmint Checkout Trigger** — Create payment-gated webhook endpoints using the x402 protocol

## Example Use Cases

* **Payroll System** — Automate payments to employees and contractors worldwide
* **Automated Tipping** — Tip users on X (Twitter) automatically
* **Paid Workflows** — Require an x402 payment before running a workflow

## Learn more

<CardGroup>
  <Card title="Quickstart" icon="bolt" href="/solutions/n8n/quickstart">
    Build your first workflow in under 5 minutes
  </Card>

  <Card title="Ask ChatGPT" icon="comments" href="https://chatgpt.com/g/g-68d13ccc81ac8191a0c3716ce980faff-n8n-crossmint-expert">
    Ask Crossmint Expert GPT for n8n guidance
  </Card>
</CardGroup>


# Quickstart ⚡
Source: https://docs.crossmint.com/solutions/n8n/quickstart

Build your first workflow in under 5 minutes

In this quickstart you will create a simple workflow that creates a wallet and fetches its balance.

## Installation

<Steps>
  <Step title="Create an n8n account">
    Register with n8n <a href="https://app.n8n.cloud/register">here</a>, otherwise <a href="https://app.n8n.cloud/login">log in</a> to your existing account.
  </Step>

  <Step title="Create a new workflow">
    On the top right of your n8n dashboard, click the **Create workflow** button.
  </Step>

  <Step title="Install Crossmint Wallets">
    In the middle of the screen, click <b>Add first step</b>. In the search bar, type <b>Crossmint</b> to find the Crossmint Wallets node.<br /><br />
    Click the <b>Install Node</b> button to add it to your workspace.
  </Step>
</Steps>

The **Crossmint Wallets** node is now available. Close the Settings page and get ready to build your first workflow.

## Get Started

<Steps>
  <Step title="Create a wallet node">
    <ol>
      <li>Click the <b>+</b> button on the top left of your screen to start a new workflow.</li>
      <li>Click the <b>+</b> button in the middle of your screen to add a new node.</li>

      <li>
        <p>Search for <b>Crossmint</b> and you will see:</p>

        <ul>
          <li><b>Crossmint Wallets</b></li>
        </ul>
      </li>

      <li>For this example, choose the <b>Get or Create Wallet</b> operation.</li>
    </ol>

    <img alt="Crossmint node search" />
  </Step>

  <Step title="Obtain a Crossmint credential">
    <ol>
      <li>Create an account on <a href="https://staging.crossmint.com/console/overview">Crossmint Console</a>.</li>
      <li>Copy your <b>server-side API key</b> from the project settings.</li>
    </ol>

    <img alt="Crossmint staging console" />

    <ol>
      <li>Back in n8n, in the Crossmint Wallets node, open <b>Credential to connect with</b> and choose <b>Create New</b>.</li>
      <li>Enter your Crossmint <b>API Key</b> and hit Save.</li>
    </ol>

    <img alt="Crossmint API credential form" />

    <Note>
      To test this flow in production, obtain a Crossmint API key from the <a href="https://www.crossmint.com/console/overview">Crossmint Console</a>.
    </Note>
  </Step>

  <Step title="Configure the wallet">
    Specify the wallet's required parameters:

    * **Owner Type**: Select `Email`
    * **Owner Details**: Enter an email address you control
    * **Admin Signer**: Set this to a private key you can generate from <a href="/solutions/n8n/nodes/wallets#generating-private-keys">here</a>.

    <img alt="Crossmint node configuration" />
  </Step>

  <Step title="Execute the workflow">
    Click **Execute Node** to run the workflow. You should see a successful response with your wallet details.
  </Step>

  <Step title="Fund the wallet">
    Use Circle's USDC <a href="https://faucet.circle.com/">faucet</a> to fund the wallet
  </Step>

  <Step title="Add node to get the wallet's balance">
    <ol>
      <li>Add another Crossmint Wallets node to your workflow</li>
      <li>Select the <b>Get Balance</b> operation</li>
      <li>Configure it to use the wallet address returned from the previous step</li>
    </ol>
  </Step>

  <Step title="Execute workflow">
    Execute the final workflow to see your wallet's USDC balance.
  </Step>
</Steps>

## Next Steps

Congratulations! You've created your first Crossmint workflow in n8n. Here's what you can explore next:

<CardGroup>
  <Card title="Ask ChatGPT" icon="comments" href="https://chatgpt.com/g/g-68d13ccc81ac8191a0c3716ce980faff-n8n-crossmint-expert">
    Ask Crossmint Expert GPT for n8n guidance
  </Card>
</CardGroup>


# Overview
Source: https://docs.crossmint.com/solutions/overview

Browse guides tailored to your business vertical or use case

## Fintech

<CardGroup>
  <Card title="Remittances" icon="earth-americas" href="/solutions/fintech/remittances">
    Enable fast, low-cost international money transfers with stablecoins
  </Card>

  <Card title="Stablecoin Payouts" icon="coins" href="/solutions/fintech/stablecoin-payouts">
    Instant, low-cost global payments for marketplaces and platforms
  </Card>

  <Card title="Global Payroll" icon="money-check-dollar" href="/solutions/fintech/global-payroll">
    Pay employees and contractors worldwide instantly with stablecoins
  </Card>

  <Card title="Neobanks" icon="building" href="/solutions/fintech/neobanks">
    Create stablecoin backed banking-like products, with deposits, cards, and more
  </Card>
</CardGroup>

## Automation

<CardGroup>
  <Card title="n8n" icon="diagram-project" href="/solutions/n8n/overview">
    Create workflows to automate wallets, money movement, and payment-gated services
  </Card>
</CardGroup>

## IP Tokenization

<CardGroup>
  <Card title="StoryKit" icon="play" href="/solutions/story-protocol/introduction">
    Transform intellectual property into programmable digital assets
  </Card>
</CardGroup>


# Images Quickstart ⚡
Source: https://docs.crossmint.com/solutions/story-protocol/images-quickstart

Register your designs on Story in under 5 minutes

In this quickstart, you will:

* Register a design portfolio as an IP collection
* Register a image design as an IP asset

<Note> This quickstart is under development as new features are added to the Story Protocol daily. </Note>

## Preparation Steps

<Steps>
  <Step title="Create a Developer Account and Project">
    <Snippet />
  </Step>

  <Step title="Get an API Key">
    Create a server-side API key with these scopes:
    `collection.create`,
    `collection.update`,
    `collection.read`,
    `nfts.create`,
    `nfts.read`.

    This allows your API key to perform any kind of asset registration action.
  </Step>
</Steps>

## Register Design Portfolio

<Steps>
  <Step title="Create an IP Collection">
    <CodeGroup>
      ```typescript createCollection.ts theme={null}
      const response = await fetch("https://staging.crossmint.com/api/v1/ip/collections", {
          method: "POST",
          headers: {
              "X-API-KEY": "<YOUR_API_KEY>",
              "Content-Type": "application/json"
          },
          body: JSON.stringify({
              metadata: {
                  description: "My image design portfolio",
                  name: "My Image Design Portfolio",
                  symbol: "MIDP"
              },
              chain: "story-testnet"
          })
      });

      const collection = await response.json();
      console.log("Collection created:", collection);
      ```

      ```typescript response theme={null}
      {
          id: '1ffb0fc3-b652-4a0e-b748-3e09c3608826',
          actionId: '1ffb0fc3-b652-4a0e-b748-3e09c3608826',
          metadata: {
              name: 'My Image Design Portfolio',
              symbol: 'MIDP',
              description: 'My image design portfolio'
          },
          onChain: { chain: 'story-testnet' }
      }
      ```
    </CodeGroup>

    Additional metadata can be added to the collection to help with discovery, such as a cover image. Check out the [API reference](/api-reference/ip/create-ip-collection) for more information.

    To create the portfolio, run the script:

    <CodeGroup>
      ```bash TypeScript theme={null}
      npx tsx createCollection.ts
      ```
    </CodeGroup>
  </Step>
</Steps>

## Register Image Design

<Steps>
  <Step title="Create a Design">
    Use OpenAI's DALL-E 3 to create a design:

    <CodeGroup>
      ```typescript createDesign.ts theme={null}
      import OpenAI from 'openai'

      async function main() {
      const openai = new OpenAI({
          apiKey: "<YOUR_OPENAI_API_KEY>"
      })

      const image = await openai.images.generate({
          model: 'dall-e-2',
          prompt: 'A futuristic bridge connecting two digital worlds, with a sleek mint-colored pathway'
      });

      console.log(image.data[0].url) // the url to the newly created image
      }

      main();
      ```
    </CodeGroup>

    The resulting image looks like this:

    <img alt="Create Design" />
  </Step>

  <Step title="Register Image Design on Story">
    <CodeGroup>
      ```typescript registerIPAsset.ts theme={null}
      const response = await fetch("https://staging.crossmint.com/api/v1/ip/collections/{collectionId}/ipassets", {
          method: "POST",
          headers: {
              "X-API-KEY": "<YOUR_API_KEY>",
              "Content-Type": "application/json"
          },
          body: JSON.stringify({
              owner: 'email:creator@example.com:story-testnet',
              nftMetadata: {
                  name: 'My Image Design',
                  description: 'An image designed to represent a futuristic bridge connecting two digital worlds, with a sleek mint-colored pathway',
                  image: '<YOUR_IMAGE_URL>'
              },
              ipAssetMetadata: {
                  title: 'My Image Design',
                  createdAt: '2025-02-11T11:13:00',
                  ipType: 'image',
                  creators: [
                      {
                          name: 'John Doe',
                          email: 'user@example.com',
                          crossmintUserLocator: 'email:user@example.com:story-testnet',
                          contributionPercent: 100
                      },
                  ],
                  attributes: [
                      {
                          key: 'Model',
                          value: 'dall-e-2'
                      },
                      {
                          key: 'Prompt',
                          value: 'A futuristic bridge connecting two digital worlds, with a sleek mint-colored pathway'
                      },
                  ]
              }
          })
      });

      const ipAsset = await response.json();
      console.log("IP Asset:", ipAsset);
      ```

      ```typescript response theme={null}
      {
          "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
          "actionId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
          "nftMetadata": {
              "name": "My Image Design",
              "description": "An image designed to represent a futuristic bridge connecting two digital worlds, with a sleek mint-colored pathway",
              "image": "<YOUR_IMAGE_URL>"
          },
          "ipAssetMetadata": {
              "title": "My Image Design",
              "createdAt": "2025-02-11T11:13:00",
              "ipType": "image",
              "creators": [
                  {
                      "name": "John Doe",
                      "email": "email:user@example.com",
                      "contributionPercent": 100
                  }
              ],
              "attributes": [
                  {
                      "key": "Model",
                      "value": "dall-e-2"
                  },
                  {
                      "key": "Prompt",
                      "value": "A futuristic bridge connecting two digital worlds, with a sleek mint-colored pathway"
                  }
              ]
          },
          "onChain": {
              "status": "success",
              "chain": "story-testnet",
              "contractAddress": "0x123",
              "ipAssetId": "0xAC6062FF53fa41e61Fe01B89B83d9dB96b5F9280",
              "tokenId": "1",
              "txId": "0x123",
              "explorerLink": "https://explorer.story.foundation/ipa/0xAC6062FF53fa41e61Fe01B89B83d9dB96b5F9280"
          }
      }
      ```
    </CodeGroup>

    Run the script to register the song:

    <CodeGroup>
      ```bash TypeScript theme={null}
      npx tsx registerIPAsset.ts
      ```
    </CodeGroup>
  </Step>
</Steps>

## Retrieve Your IP Asset

<Steps>
  <Step title="Get IP Asset Details">
    After registering your IP asset, you can retrieve its details to verify the information or display it in your application.

    <CodeGroup>
      ```typescript getIPAsset.ts theme={null}
      const response = await fetch("https://staging.crossmint.com/api/v1/ip/collections/{collectionId}/ipassets/{ipAssetId}", {
          method: "GET",
          headers: {
              "X-API-KEY": "<YOUR_API_KEY>",
              "Content-Type": "application/json"
          }
      });

      const ipAsset = await response.json();
      console.log("IP Asset:", ipAsset);
      ```

      ```typescript response theme={null}
      {
          "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
          "nftMetadata": {
              "name": "My Image Design",
              "description": "An image designed to represent a futuristic bridge connecting two digital worlds, with a sleek mint-colored pathway",
              "image": "<YOUR_IMAGE_URL>"
          },
          "ipAssetMetadata": {
              "title": "My Image Design",
              "createdAt": "2025-02-11T11:13:00",
              "ipType": "image",
              "creators": [
                  {
                      "name": "John Doe",
                      "email": "email:user@example.com",
                      "contributionPercent": 100
                  }
              ],
              "attributes": [
                  {
                      "key": "Model",
                      "value": "dall-e-2"
                  },
                  {
                      "key": "Prompt",
                      "value": "A futuristic bridge connecting two digital worlds, with a sleek mint-colored pathway"
                  }
              ]
          },
          "onChain": {
              "status": "success",
              "chain": "story-testnet",
              "contractAddress": "0x123",
              "ipAssetId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
              "tokenId": "1",
              "txId": "0x123",
              "explorerLink": "https://explorer.story.foundation/ipa/0xAC6062FF53fa41e61Fe01B89B83d9dB96b5F9280"
          }
      }
      ```
    </CodeGroup>

    Replace `{collectionId}` with your collection ID and `{ipAssetId}` with the IP asset ID returned when you registered the asset. Then run the script:

    <CodeGroup>
      ```bash TypeScript theme={null}
      npx tsx getIPAsset.ts
      ```
    </CodeGroup>
  </Step>
</Steps>

## Confirm Image Registration

<Steps>
  <Step title="Get Action Status">
    You can easily check the IP asset registration status to ensure the action has completed before proceeding.

    <CodeGroup>
      ```typescript getAction.ts theme={null}
      const response = await fetch("https://staging.crossmint.com/api/v1/ip/actions/{actionId}", {
          method: "GET",
          headers: {
              "X-API-KEY": "<YOUR_API_KEY>",
              "Content-Type": "application/json"
          }
      });

      const action = await response.json();
      console.log("Action:", action);
      ```

      ```typescript response theme={null}
      {
          id: '1ffb0fc3-b652-4a0e-b748-3e09c3608826',
          status: 'success'
      }
      ```
    </CodeGroup>

    Use the action ID returned in any of the previous steps and run the script:

    <CodeGroup>
      ```bash TypeScript theme={null}
      npx tsx getAction.ts
      ```
    </CodeGroup>
  </Step>
</Steps>


# Overview
Source: https://docs.crossmint.com/solutions/story-protocol/introduction

Create, manage, and monetize IP assets on Story Protocol using Crossmint

<Frame type="simple">
  <img alt="Story Protocol" />
</Frame>

Story Protocol is a decentralized platform that helps creators protect and monetize their intellectual property (IP) through blockchain technology. Crossmint simplifies the process of building applications on top of Story Protocol. With Crossmint's StoryKit, you can:

* Let content creators easily register their IP without dealing with blockchain complexities such as gas fees (handled by [gas sponsorship](/wallets/guides/gas-sponsorship) when enabled), key management, and smart contract interactions
* Help storytellers and artists tokenize their creative works (like stories, characters, or artwork) through simple API calls
* Enable creators to sell licenses and rights to their IP directly to fans and businesses, with card or crypto checkout

## Key Characteristics

<CardGroup>
  <Card title="User Auth & Wallets" icon="wallet">
    Authenticate users and create wallets for them using web3 or traditional sign-in methods
  </Card>

  <Card icon="palette" title="IP Assets">
    Create and manage IP assets using RESTful APIs
  </Card>

  <Card icon="credit-card" title="Payments">
    Monetize your IP with card and crypto checkout
  </Card>
</CardGroup>

## How Does it Work?

Crossmint's infrastructure lets developers easily plug into Story Protocol's core IP framework without dealing with blockchain complexities around user authentication and wallet creation, gas fees (handled by [gas sponsorship](/wallets/guides/gas-sponsorship) when enabled) and minting of assets at scale, as well as payments.

#### User Authentication & Wallets

* Out of the box support for user authentication and wallet management

  <Frame type="simple">
    <img alt="GIF of user login flow" />
  </Frame>

#### Create & Manage Assets

* Support for Story Protocol Groups (SPG) collection creation
* Support for minting, registration, and licensing of IP assets
* Support for co-creator specification and collaborative ownership
* Secure metadata storage using IPFS
* Support for modifying asset license terms and co-creators
* Ensure that only verified owners can update or delete data

#### Transfer Assets & Collect Royalties

* Support for NFT transfers
* Built-in royalty collection for commercially licensed assets

### Monetize your IP

* Sell your IP with card or crypto checkout using Crossmint's Checkout API

## What can I build with this?

* Create and license stories and characters for use in games, NFT collections, or other applications
* Register original beats, melodies, or vocals and license them to other artists with automated royalty distribution
* License 3D clothing elements, textures, or patterns for use across virtual worlds and games

## Get Started

<CardGroup>
  <Card title="Wallets Quickstart" icon="wallet" href="/solutions/story-protocol/wallets/server-side-wallets">
    Create user wallets on Story
  </Card>

  <Card title="Music Quickstart" icon="wallet" href="/solutions/story-protocol/music-quickstart">
    Register your music on Story
  </Card>

  <Card title="Literature Quickstart" icon="wallet" href="/solutions/story-protocol/literature-quickstart">
    Register your literature works on Story
  </Card>

  <Card title="Images Quickstart" icon="wallet" href="/solutions/story-protocol/images-quickstart">
    Register your designs on Story
  </Card>

  <Card title="API Reference" icon="wallet" href="/api-reference/ip/create-ip-collection">
    Review API routes for building on Story
  </Card>
</CardGroup>


# Literature Quickstart ⚡
Source: https://docs.crossmint.com/solutions/story-protocol/literature-quickstart

Register your literature works on Story in under 5 minutes

In this quickstart, you will:

* Register a book series as an IP collection
* Register a book as an IP asset

<Note> This quickstart is under development as new features are added to the Story Protocol daily. </Note>

## Preparation Steps

<Steps>
  <Step title="Create a Developer Account and Project">
    <Snippet />
  </Step>

  <Step title="Get an API Key">
    Create a server-side API key with these scopes:
    `collection.create`,
    `collection.update`,
    `collection.read`,
    `nfts.create`,
    `nfts.read`.

    This allows your API key to perform any kind of asset registration action.
  </Step>
</Steps>

## Register a Book Series

<Steps>
  <Step title="Create an IP Collection">
    This quickstart will register the Harry Potter book series as an IP collection.

    <CodeGroup>
      ```typescript createCollection.ts theme={null}
      const response = await fetch("https://staging.crossmint.com/api/v1/ip/collections", {
          method: "POST",
          headers: {
              "X-API-KEY": "<YOUR_API_KEY>",
              "Content-Type": "application/json"
          },
          body: JSON.stringify({
              metadata: {
                  description: "The collection of Harry Potter books",
                  name: "Harry Potter Series",
                  symbol: "HP"
              },
              chain: "story-testnet"
          })
      });

      const collection = await response.json();
      console.log("Collection created:", collection);
      ```

      ```typescript response theme={null}
      {
          id: '1ffb0fc3-b652-4a0e-b748-3e09c3608826',
          actionId: '1ffb0fc3-b652-4a0e-b748-3e09c3608826',
          metadata: {
              name: 'Harry Potter Series',
              symbol: 'HP',
              description: 'The collection of Harry Potter books'
          },
          onChain: { chain: 'story-testnet' }
      }
      ```
    </CodeGroup>

    Customize the collection's metadata according to your needs and run the script:

    <CodeGroup>
      ```bash TypeScript theme={null}
      npx tsx createCollection.ts
      ```
    </CodeGroup>
  </Step>
</Steps>

## Register a Book

<Steps>
  <Step title="Register an IP Asset">
    Every written work may have different contributors and metadata. When defining an IP asset you can:

    * Specify multiple contributors (like authors, illustrators, and publishers) with their respective revenue shares
    * Attach relevant media files
    * Include important metadata like creation dates and identifiers

    <CodeGroup>
      ```typescript registerIPAsset.ts theme={null}
      const response = await fetch("https://staging.crossmint.com/api/v1/ip/collections/{collectionId}/ipassets", {
          method: "POST",
          headers: {
              "X-API-KEY": "<YOUR_API_KEY>",
              "Content-Type": "application/json"
          },
          body: JSON.stringify({
              owner: 'email:creator@example.com:story-testnet',
              nftMetadata: {
                  name: 'Art #123',
                  description: 'A unique story NFT',
                  image: 'https://example.com/nft/123.png'
              },
              ipAssetMetadata: {
                  title: 'Harry Potter and the Philosopher\'s Stone',
                  createdAt: '1997-06-26T00:00:00',
                  ipType: 'literature',
                  image: 'link_to_epub',
                  imageHash: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
                  mediaUrl: 'link_to_epub',
                  mediaHash: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
                  mediaType: 'application/epub+zip',
                  creators: [
                      {
                          name: 'JK Rowling',
                          email: 'JKRowling@example.com',
                          address: '0x123',
                          description: 'Author',
                          contributionPercent: 80,
                          socialMedia: [
                              {
                                  platform: 'Wikipedia',
                                  url: 'https://en.wikipedia.org/wiki/J._K._Rowling'
                              }
                          ]
                      },
                      {
                          name: 'Thomas Taylor',
                          email: 'ThomasTaylor@example.com',
                          crossmintUserLocator: 'email:ThomasTaylor@example.com:story-testnet',
                          description: 'Illustrator',
                          contributionPercent: 15
                      },
                      {
                          name: 'Bloomsbury Publishing',
                          email: 'BloomsburyPublishing@example.com',
                          address: '0x123',
                          description: 'Publisher',
                          contributionPercent: 5,
                          socialMedia: [
                              {
                                  platform: 'Website',
                                  url: 'https://www.bloomsbury.com/'
                              }
                          ]
                      }
                  ],
                  media: [
                      {
                          name: 'ePub',
                          url: 'link_to_epub',
                          mimeType: 'application/epub+zip'
                      },
                      {
                          name: 'Book Summary PDF',
                          url: 'link_to_book_summary_pdf',
                          mimeType: 'application/pdf'
                      }
                  ],
                  attributes: [
                      {
                          key: 'ISBN',
                          value: '978-0-7475-3269-0'
                      },
                      {
                          key: 'Genre',
                          value: 'Fantasy'
                      }
                  ]
              }
          })
      });

      const ipAsset = await response.json();
      console.log("IP Asset:", ipAsset);
      ```

      ```typescript response theme={null}
      {
          "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
          "actionId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
          "nftMetadata": {
              "name": "Art #123",
              "description": "A unique story NFT",
              "image": "https://example.com/nft/123.png"
          },
          "ipAssetMetadata": {
              "title": "Harry Potter and the Philosopher's Stone",
              "createdAt": "1997-06-26T00:00:00",
              "ipType": "literature",
              "creators": [
              {
                  "name": "JK Rowling",
                  "email": "email:JKRowling@example.com",
                  "description": "Author",
                  "contributionPercent": 80,
                  "socialMedia": [
                  {
                      "platform": "Wikipedia",
                      "url": "https://en.wikipedia.org/wiki/J._K._Rowling"
                  }
                  ]
              },
              {
                  "name": "Thomas Taylor",
                  "email": "email:ThomasTaylor@example.com",
                  "description": "Illustrator",
                  "contributionPercent": 15
              },
              {
                  "name": "Bloomsbury Publishing",
                  "email": "email:BloomsburyPublishing@example.com",
                  "description": "Publisher",
                  "contributionPercent": 5,
                  "socialMedia": [
                  {
                      "platform": "Website",
                      "url": "https://www.bloomsbury.com/"
                  }
                  ]
              }
              ],
              "media": [
              {
                  "name": "ePub",
                  "url": "link_to_epub",
                  "mimeType": "application/epub+zip"
              },
              {
                  "name": "Book Summary PDF",
                  "url": "link_to_book_summary_pdf",
                  "mimeType": "application/pdf"
              }
              ],
              "attributes": [
              {
                  "key": "ISBN",
                  "value": "978-0-7475-3269-0"
              },
              {
                  "key": "Genre",
                  "value": "Fantasy"
              }
              ]
          },
          "onChain": {
              "status": "success",
              "chain": "story-testnet",
              "contractAddress": "0x123",
              "ipAssetId": "0xAC6062FF53fa41e61Fe01B89B83d9dB96b5F9280",
              "tokenId": "1",
              "txId": "0x123",
              "explorerLink": "https://explorer.story.foundation/ipa/0xAC6062FF53fa41e61Fe01B89B83d9dB96b5F9280"
          }
      }
      ```
    </CodeGroup>

    Now, run the script:

    <CodeGroup>
      ```bash TypeScript theme={null}
      npx tsx registerIPAsset.ts
      ```
    </CodeGroup>
  </Step>
</Steps>

## Retrieve Your IP Asset

<Steps>
  <Step title="Get IP Asset Details">
    After registering your IP asset, you can retrieve its details to verify the information or display it in your application.

    <CodeGroup>
      ```typescript getIPAsset.ts theme={null}
      const response = await fetch("https://staging.crossmint.com/api/v1/ip/collections/{collectionId}/ipassets/{ipAssetId}", {
          method: "GET",
          headers: {
              "X-API-KEY": "<YOUR_API_KEY>",
              "Content-Type": "application/json"
          }
      });

      const ipAsset = await response.json();
      console.log("IP Asset:", ipAsset);
      ```

      ```typescript response theme={null}
      {
          "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
          "nftMetadata": {
              "name": "Art #123",
              "description": "A unique story NFT",
              "image": "https://example.com/nft/123.png"
          },
          "ipAssetMetadata": {
              "title": "Harry Potter and the Philosopher's Stone",
              "createdAt": "1997-06-26T00:00:00",
              "ipType": "literature",
              "creators": [
                  {
                      "name": "JK Rowling",
                      "email": "email:JKRowling@example.com",
                      "description": "Author",
                      "contributionPercent": 80,
                      "socialMedia": [
                          {
                              "platform": "Wikipedia",
                              "url": "https://en.wikipedia.org/wiki/J._K._Rowling"
                          }
                      ]
                  },
                  {
                      "name": "Thomas Taylor",
                      "email": "email:ThomasTaylor@example.com",
                      "description": "Illustrator",
                      "contributionPercent": 15
                  },
                  {
                      "name": "Bloomsbury Publishing",
                      "email": "email:BloomsburyPublishing@example.com",
                      "description": "Publisher",
                      "contributionPercent": 5,
                      "socialMedia": [
                          {
                              "platform": "Website",
                              "url": "https://www.bloomsbury.com/"
                          }
                      ]
                  }
              ],
              "media": [
                  {
                      "name": "ePub",
                      "url": "link_to_epub",
                      "mimeType": "application/epub+zip"
                  },
                  {
                      "name": "Book Summary PDF",
                      "url": "link_to_book_summary_pdf",
                      "mimeType": "application/pdf"
                  }
              ],
              "attributes": [
                  {
                      "key": "ISBN",
                      "value": "978-0-7475-3269-0"
                  },
                  {
                      "key": "Genre",
                      "value": "Fantasy"
                  }
              ]
          },
          "onChain": {
              "status": "success",
              "chain": "story-testnet",
              "contractAddress": "0x123",
              "ipAssetId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
              "tokenId": "1",
              "txId": "0x123",
              "explorerLink": "https://explorer.story.foundation/ipa/0xAC6062FF53fa41e61Fe01B89B83d9dB96b5F9280"
          }
      }
      ```
    </CodeGroup>

    Replace `{collectionId}` with your collection ID and `{ipAssetId}` with the IP asset ID returned when you registered the asset. Then run the script:

    <CodeGroup>
      ```bash TypeScript theme={null}
      npx tsx getIPAsset.ts
      ```
    </CodeGroup>
  </Step>
</Steps>

## Confirm Book Registration

<Steps>
  <Step title="Get Action Status">
    You can easily check the IP asset registration status to ensure the action has completed before proceeding.

    <CodeGroup>
      ```typescript getAction.ts theme={null}
      const response = await fetch("https://staging.crossmint.com/api/v1/ip/actions/{actionId}", {
          method: "GET",
          headers: {
              "X-API-KEY": "<YOUR_API_KEY>",
              "Content-Type": "application/json"
          }
      });

      const action = await response.json();
      console.log("Action:", action);
      ```

      ```typescript response theme={null}
      {
          id: '1ffb0fc3-b652-4a0e-b748-3e09c3608826',
          status: 'success'
      }
      ```
    </CodeGroup>

    Use the action ID returned in any of the previous steps and run the script:

    <CodeGroup>
      ```bash TypeScript theme={null}
      npx tsx getAction.ts
      ```
    </CodeGroup>
  </Step>
</Steps>


# Music Quickstart ⚡
Source: https://docs.crossmint.com/solutions/story-protocol/music-quickstart

Register your music on Story in under 5 minutes

In this quickstart, you will:

* Register a music album as an IP collection
* Register a music track as an IP asset

<Note> This quickstart is under development as new features are added to the Story Protocol daily. </Note>

## Preparation Steps

<Steps>
  <Step title="Create a Developer Account and Project">
    <Snippet />
  </Step>

  <Step title="Get an API Key">
    Create a server-side API key with these scopes:
    `collection.create`,
    `collection.update`,
    `collection.read`,
    `nfts.create`,
    `nfts.read`.

    This allows your API key to perform any kind of asset registration action.
  </Step>
</Steps>

## Register Music Album

<Steps>
  <Step title="Create an IP Collection">
    <CodeGroup>
      ```typescript createCollection.ts theme={null}
      const response = await fetch("https://staging.crossmint.com/api/v1/ip/collections", {
          method: "POST",
          headers: {
              "X-API-KEY": "<YOUR_API_KEY>",
              "Content-Type": "application/json"
          },
          body: JSON.stringify({
              metadata: {
                  description: "My first music album",
                  name: "My First Album",
                  symbol: "MFA"
              },
              chain: "story-testnet"
          })
      });

      const collection = await response.json();
      console.log("Collection created:", collection);
      ```

      ```typescript response theme={null}
      {
          id: '1ffb0fc3-b652-4a0e-b748-3e09c3608826',
          actionId: '1ffb0fc3-b652-4a0e-b748-3e09c3608826',
          metadata: {
              name: 'My First Album',
              symbol: 'MFA',
              description: 'My first music album'
          },
          onChain: { chain: 'story-testnet' }
      }
      ```
    </CodeGroup>

    Additional metadata can be added to the collection to help with discovery, such as a cover image. Check out the [API reference](/api-reference/ip/create-ip-collection) for more information.

    To create the album, run the script:

    <CodeGroup>
      ```bash TypeScript theme={null}
      npx tsx createCollection.ts
      ```
    </CodeGroup>
  </Step>
</Steps>

## Register Song

<Steps>
  <Step title="Create a Song">
    Go to [Suno](https://suno.ai/), a music platform for AI-generated music, to create a song:

    * Input a prompt to create a song
    * Click on the final result to get the song's URL (i.e. `https://suno.com/song/c001fd6e-d6cd-474f-a7b6-6e6a9b3e2515`)
    * Copy the song ID in the URL (i.e. `c001fd6e-d6cd-474f-a7b6-6e6a9b3e2515`)
    * Copy the following URL: `https://cdn1.suno.ai/${SONG_ID}.mp3`, making sure to replace SONG\_ID with your own
  </Step>

  <Step title="Register Song on Story">
    <CodeGroup>
      ```typescript registerIPAsset.ts theme={null}
      const response = await fetch("https://staging.crossmint.com/api/v1/ip/collections/{collectionId}/ipassets", {
          method: "POST",
          headers: {
              "X-API-KEY": "<YOUR_API_KEY>",
              "Content-Type": "application/json"
          },
          body: JSON.stringify({
              owner: 'email:creator@example.com:story-testnet',
              nftMetadata: {
                  name: 'Snowflake Funk',
                  description: 'A disco groovy song for a house party during the winter time',
                  image: 'https://cdn2.suno.ai/image_large_c001fd6e-d6cd-474f-a7b6-6e6a9b3e2515.jpeg'
              },
              ipAssetMetadata: {
                  title: 'Snowflake Funk',
                  createdAt: '2025-02-11T11:13:00',
                  ipType: 'music',
                  image: 'https://cdn1.suno.ai/c001fd6e-d6cd-474f-a7b6-6e6a9b3e2515.mp3',
                  imageHash: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
                  mediaUrl: 'https://cdn1.suno.ai/c001fd6e-d6cd-474f-a7b6-6e6a9b3e2515.mp3',
                  mediaHash: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
                  mediaType: 'audio/mpeg',
                  creators: [
                      {
                          name: 'John Doe',
                          email: 'john.doe@example.com',
                          crossmintUserLocator: 'email:john.doe@example.com:story-testnet',
                          contributionPercent: 100
                      },
                  ],
                  media: [
                      {
                          name: 'Snowflake Funk',
                          url: 'https://cdn1.suno.ai/c001fd6e-d6cd-474f-a7b6-6e6a9b3e2515.mp3',
                          mimeType: 'audio/mpeg'
                      },
                  ],
                  attributes: [
                      {
                          key: 'Suno Artist',
                          value: 'InfluentialCoda427'
                      },
                      {
                          key: 'Source',
                          value: 'Suno.com'
                      }
                  ]
              }
          })
      });

      const ipAsset = await response.json();
      console.log("IP Asset:", ipAsset);
      ```

      ```typescript response theme={null}
      {
          "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
          "actionId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
          "nftMetadata": {
              "name": "Snowflake Funk",
              "description": "A disco groovy song for a house party during the winter time",
              "image": "https://cdn2.suno.ai/image_large_c001fd6e-d6cd-474f-a7b6-6e6a9b3e2515.jpeg"
          },
          "ipAssetMetadata": {
              "title": "Snowflake Funk",
              "createdAt": "2025-02-11T11:13:00",
              "ipType": "music",
              "creators": [
                  {
                      "name": "John Doe",
                      "email": "email:user@example.com",
                      "contributionPercent": 100
                  }
              ],
              "media": [
                  {
                      "name": "Snowflake Funk",
                      "url": "https://cdn1.suno.ai/c001fd6e-d6cd-474f-a7b6-6e6a9b3e2515.mp3",
                      "mimeType": "audio/mpeg"
                  }
              ],
              "attributes": [
                  {
                      "key": "Suno Artist",
                      "value": "InfluentialCoda427"
                  },
                  {
                      "key": "Source",
                      "value": "Suno.com"
                  }
              ]
          },
          "onChain": {
              "status": "success",
              "chain": "story-testnet",
              "contractAddress": "0x123",
              "ipAssetId": "0xAC6062FF53fa41e61Fe01B89B83d9dB96b5F9280",
              "tokenId": "1",
              "txId": "0x123",
              "explorerLink": "https://explorer.story.foundation/ipa/0xAC6062FF53fa41e61Fe01B89B83d9dB96b5F9280"
          }
      }
      ```
    </CodeGroup>

    Run the script to register the song:

    <CodeGroup>
      ```bash TypeScript theme={null}
      npx tsx registerIPAsset.ts
      ```
    </CodeGroup>
  </Step>
</Steps>

## Retrieve Your IP Asset

<Steps>
  <Step title="Get IP Asset Details">
    After registering your IP asset, you can retrieve its details to verify the information or display it in your application.

    <CodeGroup>
      ```typescript getIPAsset.ts theme={null}
      const response = await fetch("https://staging.crossmint.com/api/v1/ip/collections/{collectionId}/ipassets/{ipAssetId}", {
          method: "GET",
          headers: {
              "X-API-KEY": "<YOUR_API_KEY>",
              "Content-Type": "application/json"
          }
      });

      const ipAsset = await response.json();
      console.log("IP Asset:", ipAsset);
      ```

      ```typescript response theme={null}
      {
          "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
          "nftMetadata": {
              "name": "Snowflake Funk",
              "description": "A disco groovy song for a house party during the winter time",
              "image": "https://cdn2.suno.ai/image_large_c001fd6e-d6cd-474f-a7b6-6e6a9b3e2515.jpeg"
          },
          "ipAssetMetadata": {
              "title": "Snowflake Funk",
              "createdAt": "2025-02-11T11:13:00",
              "ipType": "music",
              "creators": [
                  {
                      "name": "John Doe",
                      "email": "email:user@example.com",
                      "contributionPercent": 100
                  }
              ],
              "media": [
                  {
                      "name": "Snowflake Funk",
                      "url": "https://cdn1.suno.ai/c001fd6e-d6cd-474f-a7b6-6e6a9b3e2515.mp3",
                      "mimeType": "audio/mpeg"
                  }
              ],
              "attributes": [
                  {
                      "key": "Suno Artist",
                      "value": "InfluentialCoda427"
                  },
                  {
                      "key": "Source",
                      "value": "Suno.com"
                  }
              ]
          },
          "onChain": {
              "status": "success",
              "chain": "story-testnet",
              "contractAddress": "0x123",
              "ipAssetId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
              "tokenId": "1",
              "txId": "0x123",
              "explorerLink": "https://explorer.story.foundation/ipa/0xAC6062FF53fa41e61Fe01B89B83d9dB96b5F9280"
          }
      }
      ```
    </CodeGroup>

    Replace `{collectionId}` with your collection ID and `{ipAssetId}` with the IP asset ID returned when you registered the asset. Then run the script:

    <CodeGroup>
      ```bash TypeScript theme={null}
      npx tsx getIPAsset.ts
      ```
    </CodeGroup>
  </Step>
</Steps>

## Confirm Song Registration

<Steps>
  <Step title="Get Action Status">
    You can easily check the IP asset registration status to ensure the action has completed before proceeding.

    <CodeGroup>
      ```typescript getAction.ts theme={null}
      const response = await fetch("https://staging.crossmint.com/api/v1/ip/actions/{actionId}", {
          method: "GET",
          headers: {
              "X-API-KEY": "<YOUR_API_KEY>",
              "Content-Type": "application/json"
          }
      });

      const action = await response.json();
      console.log("Action:", action);
      ```

      ```typescript response theme={null}
      {
          id: '1ffb0fc3-b652-4a0e-b748-3e09c3608826',
          status: 'success'
      }
      ```
    </CodeGroup>

    Use the action ID returned in any of the previous steps and run the script:

    <CodeGroup>
      ```bash TypeScript theme={null}
      npx tsx getAction.ts
      ```
    </CodeGroup>
  </Step>
</Steps>


# Client Wallets Quickstart ⚡
Source: https://docs.crossmint.com/solutions/story-protocol/wallets/client-side-wallets

Create client wallets and create your first NFT on Story in under 5 minutes

## Introduction

In this quickstart, you will create new user wallets on Story and use passkeys for sending transactions using this wallet. By the end of this guide, you'll be able to:

* Create client-side wallets on Story Protocol
* Configure multiple authentication methods
* Mint your first NFT using the wallet

## Preparation Steps

<Steps>
  <Step title="Create a developer account">
    <Snippet />
  </Step>

  <Step title="Get an API Key">
    Create a client-side API key with these scopes:
    `wallets.create`,
    `wallets.read`,
    `wallets:balance.read`,
    `wallets:transactions.create`,
    `wallets:transactions.read`,
    `users.read`,
    `users.create`.

    Check the "JWT Auth" box.

    This allows your API key to create new client wallets.
  </Step>
</Steps>

## Create Client Wallets

<Steps>
  <Step title="Set Up the Application">
    Follow the [React Wallets Quickstart](/wallets/quickstarts/react) guide to use Crossmint's Wallets SDK in your application.
  </Step>

  <Step title="Configure Story's Chain">
    Set `story-testnet` as the `chain` property.

    <CodeGroup>
      ```tsx providers.tsx theme={null}
      "use client";

      import { CrossmintProvider, CrossmintAuthProvider, CrossmintWalletsProvider } from "@crossmint/client-sdk-react-ui";

      const clientApiKey = process.env.NEXT_PUBLIC_CROSSMINT_CLIENT_KEY as string;

      export default function Providers({ children }: { children: React.ReactNode }) {
          return (
              <CrossmintProvider apiKey={clientApiKey}>
                  <CrossmintAuthProvider
                      loginMethods={["google", "twitter", "farcaster", "email"]}
                  >
                      <CrossmintWalletProvider
                          createOnLogin={{
                              chain: "story-testnet",
                              signer: {
                                  type: "<your-signer-type>",
                              },
                          }}
                      >
                          {children}
                      </CrossmintWalletProvider>
                  </CrossmintAuthProvider>
              </CrossmintProvider>
          );
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Format Login Component">
    Adjust the login component's style to match your application's design. You can experiment with it [here](https://playground.crossmint.com/wallets/auth).

    <Frame type="simple">
      <img alt="GIF of user login flow" />
    </Frame>
  </Step>
</Steps>

<Note>
  This quickstart uses [Crossmint Auth](/authentication/introduction) for convenience. You can [bring your own auth provider](/wallets/guides/bring-your-own-auth), which is recommended for production scenarios.
</Note>

## Send Arbitrary Transaction

<Steps>
  <Step title="Specify the NFT Contract">
    Define the address and interface (ABI) of the NFT smart contract on Story Protocol.

    <CodeGroup>
      ```tsx components/utils.ts theme={null}
      export const NFT_CONTRACT_ADDRESS = "0x937bef10ba6fb941ed84b8d249abc76031429a9a" as const;
      export const NFT_CONTRACT_ABI = [
          {
              inputs: [
                  {
                      internalType: "address",
                      name: "recipient",
                      type: "address",
                  },
                  {
                      internalType: "string",
                      name: "tokenURI",
                      type: "string",
                  },
              ],
              name: "mintNFT",
              outputs: [
                  {
                      internalType: "uint256",
                      name: "",
                      type: "uint256",
                  },
              ],
              stateMutability: "nonpayable",
              type: "function",
          },
      ];
      ```
    </CodeGroup>
  </Step>

  <Step title="Create a React Component for the Transaction">
    Create a user-friendly interface that:

    * Displays the transaction status
    * Allows users to send an arbitrary transaction to the NFT contract
    * Displays the transaction hash and a link to the Story Explorer

    <CodeGroup>
      ```tsx components/SendTransactionComponent.tsx theme={null}
      import { EVMWallet, useWallet } from "@crossmint/client-sdk-react-ui";
      import React from "react";
      import { NFT_CONTRACT_ADDRESS, NFT_CONTRACT_ABI } from "./utils";
      import { encodeFunctionData } from "viem";

      export default function SendTransactionComponent() {
          const { wallet } = useWallet();
          const [txStatus, setTxStatus] = React.useState<'idle' | 'pending' | 'success' | 'error'>('idle');
          const [txError, setTxError] = React.useState<string | null>(null);
          const [tx, setTx] = React.useState<string | null>(null);

          if (wallet) {
              return (
                  <div className="max-w-md mx-auto bg-white rounded-xl  overflow-hidden p-6 space-y-4 ">

                      <button
                          onClick={async () => {
                              try {
                                  setTxStatus('pending');
                                  setTxError(null);
                                  const data = encodeFunctionData({
                                      abi: NFT_CONTRACT_ABI,
                                      functionName: "mintNFT",
                                      args: [wallet.address, "test-uri"],
                                  });

                                  const evmWallet = EVMWallet.from(wallet);
                                  const { hash: tx } = await evmWallet.sendTransaction({
                                      to: NFT_CONTRACT_ADDRESS,
                                      data: data,
                                  });
                                  setTx(tx);
                                  setTxStatus('success');
                              } catch (error) {
                                  setTxStatus('error');
                                  setTxError(error instanceof Error ? error.message : 'Transaction failed');
                                  setTx(null);
                              }
                          }}
                          disabled={txStatus === 'pending'}
                          className="w-full flex items-center justify-center space-x-2 bg-blue-600 hover:bg-blue-700 text-white px-4 py-2 rounded-lg transition-colors"
                      >
                          {txStatus === 'pending' ? (
                              <>
                                  <svg className="animate-spin -ml-1 mr-3 h-5 w-5 text-white" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24">
                                      <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4"></circle>
                                      <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
                                  </svg>
                                  <span>Processing...</span>
                              </>
                          ) : (
                              'Send Transaction'
                          )}
                      </button>

                      <div className="mt-4">
                          {txStatus === 'pending' && (
                              <div className="flex items-center space-x-2 text-amber-500">
                                  <svg className="animate-spin h-5 w-5" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24">
                                      <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4"></circle>
                                      <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
                                  </svg>
                                  <span>Transaction in progress...</span>
                              </div>
                          )}
                          {txStatus === 'success' && (
                              <div className="flex items-center space-x-2 text-emerald-600">
                                  <svg className="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                                      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth="2" d="M5 13l4 4L19 7"></path>
                                  </svg>
                                  <span>Transaction successful!</span>
                                  {tx && (
                                      <a
                                          href={`https://www.oklink.com/story-odyssey/tx/${tx}`}
                                          target="_blank"
                                          rel="noopener noreferrer"
                                          className="underline hover:text-emerald-700"
                                      >
                                          View in explorer
                                      </a>
                                  )}
                              </div>
                          )}
                          {txStatus === 'error' && (
                              <div className="flex items-center space-x-2 text-rose-500">
                                  <svg className="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                                      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth="2" d="M6 18L18 6M6 6l12 12"></path>
                                  </svg>
                                  <span>Transaction failed: {txError}</span>
                              </div>
                          )}
                      </div>
                  </div>
              );
          }
          return null;
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Add the Transaction Component to the App">
    Incorporate the transaction component into the main wallet interface, using the `useWallet` hook to manage wallet state and pass it to the transaction component.

    <CodeGroup>
      ```tsx app/components/WalletComponent.tsx theme={null}
      export default function WalletComponent() {
          const { wallet, status, error } = useWallet();
          return (
              <>
                  <Card className="p-4">
                      <Status wallet={wallet} status={status} error={error} />
                  </Card>
                  <SendTransactionComponent wallet={wallet} />
              </>
          );
      }
      ```
    </CodeGroup>
  </Step>
</Steps>


# Server Wallets Quickstart ⚡
Source: https://docs.crossmint.com/solutions/story-protocol/wallets/server-side-wallets

Create server wallets on Story in under 5 minutes

In this quickstart, you will create new user wallets on Story.

<Note> This quickstart is under development as new features are added to the Story Protocol daily. </Note>

## Preparation Steps

<Steps>
  <Step title="Create a Developer Account and Project">
    <Snippet />
  </Step>

  <Step title="Get an API Key">
    Create a server-side API key with these scopes:
    `wallets.create`,
    `wallets:transactions.create`,
    `wallets:transactions.sign`.

    This allows your API key to create new server wallets.
  </Step>
</Steps>

## Create Server Wallets

<Steps>
  <Step title="Choose a Wallet Type">
    Below is a summary of available wallet types and their characteristics:

    | Custodial | Type | Admin Signer |
    | - | - | - |
    | True | `evm-smart-wallet` | `evm-fireblocks-custodial` |
    | False | `evm-smart-wallet` | `evm-keypair` |
  </Step>

  <Step title="Create a Wallet">
    <CodeGroup>
      ```typescript createWallet.ts theme={null}
      const response = await fetch("https://staging.crossmint.com/api/2022-06-09/wallets", {
          method: "POST",
          headers: {
              "X-API-KEY": "<YOUR_API_KEY>",
              "Content-Type": "application/json",
          },
          body: JSON.stringify({
              type: "<WALLET_TYPE>",
              // Here you can pass a user ID, email, phone number, twitter handle etc. depending on how the user is identified in your application
              linkedUser: "email:user@example.com",
              config:{
                  adminSigner: {type: "<ADMIN_SIGNER>"},
              }
          }),
      });

      const wallet = await response.json();
      console.log("Wallet created:", wallet);
      ```

      ```typescript response theme={null}
      {
          type: 'evm-smart-wallet',
          config: {
              adminSigner: {
                  type: 'evm-fireblocks-custodial',
                  address: '0xc55C0a7695DC5D9322aE5204AED91BF13c3412F2',
                  locator: 'evm-fireblocks-custodial:0xc55C0a7695DC5D9322aE5204AED91BF13c3412F2'
              }
          },
          address: '0x8B11c6D3a7115A462a91183824c83574c9190E06',
          linkedUser: 'email:user@example.com',
          createdAt: '2025-02-07T21:34:29.109Z'
      }
      ```
    </CodeGroup>

    Now, run the script:

    <CodeGroup>
      ```bash TypeScript theme={null}
      npx tsx createWallet.ts
      ```
    </CodeGroup>
  </Step>
</Steps>

## Send Arbitrary Transaction

<Steps>
  <Step title="Prepare the transaction">
    Set up a Story Protocol client using the wallet created in the previous step and prepare a transaction to create a new NFT collection

    <CodeGroup>
      ```typescript prepareTransaction.ts theme={null}
      const client = StoryClient.newClient({
          transport: http(RPC_PROVIDER_URL),
          account: wallet.address,
      });

      const creationTx = await client.nftClient.createNFTCollection({
          name: "A collection of IP fantasy assets",
          symbol: "XMT",
          contractURI: "ipfs://QmXYnQJjUxojhh6NKkxPkcXNKFo4pU2hxUyJjqzTcQL9rE",
          isPublicMinting: true,
          mintOpen: true,
          mintFeeRecipient: wallet.address,
          txOptions: {
              encodedTxDataOnly: true,
          },
      });
      ```
    </CodeGroup>
  </Step>

  <Step title="Send the transaction">
    Send the prepared transaction to Crossmint's API, which handles the blockchain interaction. The transaction creates the NFT collection on Story Protocol's network without requiring user's signature or handling of gas fees.

    <CodeGroup>
      ```typescript createTransaction.ts theme={null}
      const response = await fetch(`https://staging.crossmint.com/api/2022-06-09/wallets/${wallet.address}/transactions`, {
          method: "POST",
          headers: {
              "X-API-KEY": "<YOUR_API_KEY>",
              "Content-Type": "application/json",
          },
          body: JSON.stringify({
              params: {
                  call: {
                      // Encoded transaction data
                      data: creationTx.encodedTxData.data,
                      // Transaction destination
                      to: creationTx.encodedTxData.to,
                  },
                  chain: "story-testnet",
              },
          }),
      });

      const transaction = await response.json();
      console.log("Transaction created:", transaction.id);
      ```
    </CodeGroup>

    <Note>
      Story Protocol transactions through Crossmint smart wallets are completely gas-free! You can focus on building your
      application without worrying about managing gas fees or token balances.
    </Note>
  </Step>

  <Step title="Monitor Transaction Status">
    Check the transaction status using the transaction ID.

    <CodeGroup>
      ```javascript checkStatus.js theme={null}
      const response = await fetch(
          `https://staging.crossmint.com/api/2022-06-09/wallets/${wallet.address}/transactions/${transaction.id}`,
          {
              method: "GET",
              headers: {
                  "X-API-KEY": "<YOUR_API_KEY>",
              },
          }
      );

      const status = await response.json();
      console.log("Status:", status.status);
      ```
    </CodeGroup>
  </Step>
</Steps>


# Regulatory Landscape
Source: https://docs.crossmint.com/stablecoin-orchestration/concepts/regulatory-landscape

Why stablecoin transfers are regulated, what compliance requirements apply, and when they apply to your use case

Stablecoin transfers involve real money movement. Regulators around the world treat this like any other financial activity — which means compliance requirements can apply whenever you convert between fiat and crypto, disburse stablecoins to third parties, or facilitate transfers on behalf of your customers.

This page explains the regulatory landscape at a high level, what it typically requires, and when these rules apply to different types of stablecoin activity.

<Note>
  **Disclaimer:** This page is provided for educational and informational purposes only. It does not constitute legal, financial, or regulatory advice. Regulatory requirements vary by jurisdiction and are subject to change. Consult with qualified legal counsel to determine how specific regulations apply to your business and use case.
</Note>

<Tip>
  **You do not need to become a compliance expert to use Crossmint.** Crossmint abstracts most of the complexity below. Read the [Solution Architecture](/stablecoin-orchestration/concepts/solution-architecture) page to see how Crossmint handles these requirements on your behalf.
</Tip>

## Why Stablecoin Transfers Are Regulated

Governments regulate stablecoin activity to achieve two goals:

1. **Prevent financial crime** — money laundering, terrorist financing, sanctions evasion, and fraud
2. **Protect consumers** — ensuring that people and businesses operating with stablecoins have a secure, transparent framework to rely on

These goals are not unique to crypto. They are the same objectives behind traditional banking regulations, anti-money-laundering (AML) laws, and payment licensing frameworks. Stablecoins simply bring them into a new domain.

## Regulations by Region

Different jurisdictions have developed their own regulatory frameworks for crypto and stablecoin activity. While the specifics vary, they converge on a common set of principles: licensing, customer verification, transaction monitoring, and reporting.

The table below shows some of the most prominent examples — it is not an exhaustive list.

| Region | Example Frameworks | Summary |
| - | - | - |
| **United States** | State Money Transmitter Licenses (MTLs), GENIUS Act | States require money transmitter licenses for businesses facilitating money movement. The GENIUS Act (signed July 2025) establishes the first federal framework specifically for stablecoin issuance, treating issuers as financial institutions under the Bank Secrecy Act. |
| **European Union** | MiCA (Markets in Crypto-Assets), PSD2 | MiCA provides a comprehensive EU-wide framework for crypto-asset service providers (CASPs), including licensing, reserve requirements, and consumer protections. PSD2 applies when initiating or processing fiat transactions. |
| **Other jurisdictions** | UK (FCA oversight, EMI licensing), Singapore (MAS), Hong Kong (SFC), Dubai (VARA), and others | Many countries have introduced or are developing crypto-specific licensing requirements. Even where no crypto-specific regulation exists, general AML/CFT obligations and financial licensing requirements typically still apply. |

<Info>
  Crossmint is directly licensed and operates with licensed partners to provide coverage across 150+ jurisdictions. For the most up-to-date list of supported countries, <a href="https://www.crossmint.com/contact/sales">contact us</a>.
</Info>

## Common Compliance Requirements

Regardless of jurisdiction, regulated stablecoin activity typically involves a common set of controls. Below are some of the most common requirements — though the specifics depend on your jurisdiction, use case, and applicable regulatory framework.

### KYC and KYB (Know Your Customer / Know Your Business)

Before transferring value to or on behalf of someone, you generally need to verify their identity. For individuals, this is **KYC** — collecting and verifying name, date of birth, address, and government-issued identification. For businesses, this is **KYB** — verifying the legal entity, its beneficial owners, and its registration details.

The level of verification required depends on the use case. Low-risk activities (for example, small transfers to a verified user's own wallet) may require lighter checks, while higher-risk activities (for example, large disbursements to third parties) typically require more thorough verification.

### AML Program (Anti-Money Laundering)

An AML program goes beyond one-time identity checks. It typically includes:

* **Transaction monitoring** — continuously analyzing transfer patterns to detect suspicious activity (for example, unusually large or frequent transfers, structuring to avoid thresholds)
* **Suspicious Activity Reporting (SARs)** — filing reports with regulators when suspicious patterns are detected
* **Ongoing due diligence** — periodically requesting updated information from users, especially when their activity profile changes or when risk indicators emerge

### Sanctions Screening

Transfers generally need to be checked against global sanctions lists — including OFAC (US), EU consolidated lists, and UN sanctions. This applies to both:

* **The parties involved** — verifying that neither the sender nor the recipient is a sanctioned individual or entity
* **On-chain addresses** — screening wallet addresses against known sanctioned addresses and addresses associated with illicit activity. This is unique to crypto and requires specialized blockchain analytics tooling.

### Travel Rule

The Travel Rule is a crypto-specific regulation (derived from FATF Recommendation 16) that requires virtual asset service providers (VASPs) to transmit originator and beneficiary information alongside transfers above certain thresholds. It is already enforced in the EU, US, Singapore, and an expanding list of jurisdictions.

In practice, this means:

* Collecting sender information (name, address, account identifier) for each transfer
* Collecting and verifying recipient information before processing
* Transmitting this data to the receiving institution through a secure, compliant channel
* Maintaining records of both parties for a minimum of five years

### Safeguarding and Fund Protection

When converting between fiat and crypto — or holding fiat on behalf of customers during a conversion — regulations typically require that customer funds are **safeguarded**. This means they must be held in segregated accounts, separate from operating funds, and protected in the event of insolvency.

## When Do These Rules Apply?

Not every movement or use of stablecoins triggers regulatory requirements. The rules apply based on **what kind of activity you are performing**.

### Regulated Activities

**1. On-ramping and off-ramping**

Converting fiat to stablecoins (or vice versa) on behalf of your customers. If your platform takes in fiat from a customer and delivers stablecoins, or takes stablecoins and delivers fiat, that is a regulated conversion. This typically triggers the full range of compliance requirements — KYC/KYB, AML monitoring, sanctions screening, and Travel Rule compliance.

**2. Stablecoin payouts**

Disbursing stablecoins to external parties — whether you are paying out customer funds or sending from your own company balance to customers, contractors, suppliers, or other third parties. While payouts may not always carry the same full scope of requirements as an on/off-ramp (for example, KYC requirements may differ), they still require significant compliance checks including sanctions screening, AML monitoring, and identity verification of the recipient.

In short: **if a fiat-to-crypto conversion occurs, or if stablecoins are being sent to an external party, the activity is almost certainly regulated.**

### Typically Outside of Regulatory Scope

* **A customer holding stablecoins in their own self-custodial wallet** and choosing independently to send to others. If the user controls their own keys and initiates transfers on their own, without your platform initiating or intermediating the transfer, this is generally outside your compliance scope.
* **Internal transfers between your own wallets** (for example, moving stablecoins between two company wallets you control). No third-party interaction means no customer-facing compliance obligation, though your own internal controls and record-keeping still apply.

<Warning>
  This is a simplified overview. Your specific obligations depend on your jurisdiction, licensing status, and the exact nature of your product. Consult legal counsel for definitive guidance on your compliance requirements.
</Warning>

## How Crossmint Helps

You do not need to obtain licenses, build an AML program, or implement any of the compliance controls described above — you just call APIs.

Read the [Solution Architecture](/stablecoin-orchestration/concepts/solution-architecture) page to see exactly how the responsibilities are split and how to set up your integration.

## See Also

<CardGroup>
  <Card title="Solution Architecture" icon="sitemap" href="/stablecoin-orchestration/concepts/solution-architecture">
    How Crossmint handles compliance on your behalf and how to architect your integration
  </Card>

  <Card title="Users and Compliance" icon="user-check" href="/identity/overview">
    Register identities and verify users through the Crossmint APIs
  </Card>
</CardGroup>


# Solution Architecture
Source: https://docs.crossmint.com/stablecoin-orchestration/concepts/solution-architecture

How Crossmint handles stablecoin compliance on your behalf and how to architect your integration

Crossmint's infrastructure is designed so that you do not need to [build or run compliance systems](/stablecoin-orchestration/concepts/regulatory-landscape) yourself. Instead, Crossmint acts as the regulated party and handles all compliance on your behalf — you orchestrate your flows by calling APIs.

This page explains the architecture behind this approach and the three steps involved in setting up a compliant stablecoin integration.

<Tip>
  Every production customer gets access to a forward-deployed solutions architecture team. Before go-live, the team reviews the full flow of funds, identifies edge cases, and ensures the integration is structured correctly from a compliance standpoint. <a href="https://www.crossmint.com/contact">Contact the team</a> to get started.
</Tip>

## How Crossmint Handles Compliance

Rather than providing compliance tooling for customers to operate themselves, Crossmint structures the flow of funds so that **Crossmint is the regulated party** — the entity that holds the licenses, runs the AML program, and assumes the legal liability. You call APIs; Crossmint handles the rest.

| Your Responsibilities | Crossmint Responsibilities |
| - | - |
| Design an appropriate flow of funds for your use case | Review your flow of funds |
| Call Crossmint APIs to create wallets, register identities, and trigger transfers, on-ramps, and off-ramps | KYC/KYB identity verification |
| | Sanctions screening |
| | AML program (SARs, transaction monitoring, ongoing due diligence) |
| | Obtain and maintain licenses and licensed vendor relationships |
| | Travel Rule compliance |
| | Safeguarding and fund protection |

## Building Your Integration

Using Crossmint's stablecoin APIs generally follows three steps.

### 1. Create Wallets for Relevant Entities

Use the [Wallets API](/wallets/overview) to create wallets for every entity in your system:

* **Company wallets** for your own holdings and operations
* **User wallets** for your customers (or they can connect their own external wallets)
* **Agent wallets** for AI agents that need to hold or move stablecoins autonomously

Wallets are the foundation — they represent the accounts that send and receive stablecoins.

### 2. Register Identities for Every External Party

Every external third party that interacts with your system — whether it is a customer using your platform, a contractor receiving a payout, or any other counterparty — must be registered using Crossmint's [Identity APIs](/identity/overview).

When you register an identity, Crossmint's APIs automatically determine what level of verification is needed based on:

* The activity they will perform (receiving a payout vs. on-ramping fiat)
* The jurisdictions involved

You do not need to decide the KYC level yourself. The API tells you what is required and guides the verification flow.

<Note>
  The Identity APIs register individuals. If your counterparties are businesses, reach out to your Customer Success Engineer (CSE).
</Note>

### 3. Call Money Movement APIs — Crossmint Handles the Checks

Use the money movement APIs to execute your stablecoin flows:

* [Payouts](/stablecoin-orchestration/regulated-transfers/overview) for wallet-to-wallet stablecoin transfers
* [On-ramp](/onramp/overview) to convert fiat to stablecoins
* Off-ramp to convert stablecoins back to fiat

Crossmint performs all the compliance checks necessary on your behalf on every call.

## See Also

<CardGroup>
  <Card title="Regulatory Landscape" icon="scale-balanced" href="/stablecoin-orchestration/concepts/regulatory-landscape">
    Why stablecoin transfers are regulated and what compliance requirements apply
  </Card>

  <Card title="Treasury Wallet Guide" icon="rocket" href="/wallets/guides/treasury-wallets">
    Create a wallet and check balances in minutes
  </Card>
</CardGroup>


# Treasury Wallets
Source: https://docs.crossmint.com/stablecoin-orchestration/guides/create-treasury-wallet

Set up a company-owned wallet for stablecoin operations

A treasury wallet is a company-owned wallet used to hold, send, and receive stablecoins. It serves as the central account for all Stablecoin Orchestration operations: funding and withdrawals, internal transfers, pay-ins, payouts, and swaps.

You can create as many treasury wallets as needed, for example to separate funds by project, business line, or legal entity.

Before using the guides in this section, you must create a treasury wallet. Follow the steps below to get started.

## Guides

<CardGroup>
  <Card title="Quickstart" icon="bolt" href="/wallets/guides/treasury-wallets">
    Create a Treasury Wallet
  </Card>

  <Card title="Treasury Overview" icon="building-columns" href="/wallets/concepts/treasury">
    Learn more about treasury wallets
  </Card>
</CardGroup>


# Internal Transfers
Source: https://docs.crossmint.com/stablecoin-orchestration/guides/internal-transfers

Move stablecoins between your own treasury wallets

This guide shows how to move stablecoins between your own treasury wallets. Common use cases include transferring funds between different legal entities, funding operational accounts, and managing internal treasury movements.

## Prerequisites

* Two or more **treasury wallets** — create them using the [Treasury Wallets guide](/wallets/guides/treasury-wallets)
* A Crossmint **server API key** with the scopes `wallets.create`, `wallets.read`, `wallets:transactions.create`, `wallets:transactions.sign`

<Snippet />

***

## Step 1: Create Treasury Wallets

Create two treasury wallets representing different entities or purposes. In this example, you will create wallets for a US entity and a European entity.

<CodeGroup>
  ```bash cURL theme={null}
  # Create US entity treasury wallet
  curl --request POST \
      --url 'https://staging.crossmint.com/api/2025-06-09/wallets' \
      --header 'X-API-KEY: <your-server-api-key>' \
      --header 'Content-Type: application/json' \
      --data '{
          "chainType": "evm",
          "type": "smart",
          "config": {
              "recoveryMethods": [
                  {
                      "type": "server",
                      "address": "<your-server-signer-address>"
                  }
              ]
          },
          "owner": "COMPANY",
          "alias": "entity-us"
      }'

  # Create European entity treasury wallet
  curl --request POST \
      --url 'https://staging.crossmint.com/api/2025-06-09/wallets' \
      --header 'X-API-KEY: <your-server-api-key>' \
      --header 'Content-Type: application/json' \
      --data '{
          "chainType": "evm",
          "type": "smart",
          "config": {
              "recoveryMethods": [
                  {
                      "type": "server",
                      "address": "<your-server-signer-address>"
                  }
              ]
          },
          "owner": "COMPANY",
          "alias": "entity-europe"
      }'
  ```

  ```typescript Node.js theme={null}
  import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";

  const crossmint = createCrossmint({
      apiKey: "<your-server-api-key>",
  });

  const crossmintWallets = CrossmintWallets.from(crossmint);

  // Create US entity treasury wallet
  const usWallet = await crossmintWallets.createWallet({
      chain: "base-sepolia",
      recoveryMethods: [{ type: "server", secret: process.env.WALLET_RECOVERY_SECRET! }],
      owner: "COMPANY",
      alias: "entity-us",
  });

  // Create European entity treasury wallet
  const euWallet = await crossmintWallets.createWallet({
      chain: "base-sepolia",
      recoveryMethods: [{ type: "server", secret: process.env.WALLET_RECOVERY_SECRET! }],
      owner: "COMPANY",
      alias: "entity-europe",
  });

  console.log("US wallet:", usWallet.address);
  console.log("EU wallet:", euWallet.address);
  ```

  ```python Python theme={null}
  import requests

  api_key = "<your-server-api-key>"
  url = "https://staging.crossmint.com/api/2025-06-09/wallets"
  headers = {
      "X-API-KEY": api_key,
      "Content-Type": "application/json"
  }

  # Create US entity treasury wallet
  us_payload = {
      "chainType": "evm",
      "type": "smart",
      "config": {
          "recoveryMethods": [
              {
                  "type": "server",
                  "address": "<your-server-signer-address>"
              }
          ]
      },
      "owner": "COMPANY",
      "alias": "entity-us"
  }
  us_response = requests.post(url, json=us_payload, headers=headers)
  print("US wallet:", us_response.json().get("address"))

  # Create European entity treasury wallet
  eu_payload = {
      "chainType": "evm",
      "type": "smart",
      "config": {
          "recoveryMethods": [
              {
                  "type": "server",
                  "address": "<your-server-signer-address>"
              }
          ]
      },
      "owner": "COMPANY",
      "alias": "entity-europe"
  }
  eu_response = requests.post(url, json=eu_payload, headers=headers)
  print("EU wallet:", eu_response.json().get("address"))
  ```
</CodeGroup>

***

## Step 2: Transfer Between Treasury Wallets

Use the standard token transfer API to move funds. Since this is an internal transfer between your own wallets, no compliance checks are required.

<CodeGroup>
  ```bash cURL theme={null}
  # Transfer 500 USDC from US entity to European entity
  curl --request POST \
      --url 'https://staging.crossmint.com/api/2025-06-09/wallets/evm:smart:alias:entity-us/tokens/base-sepolia:usdc/transfers' \
      --header 'X-API-KEY: <your-server-api-key>' \
      --header 'Content-Type: application/json' \
      --data '{
          "recipient": "evm:smart:alias:entity-europe",
          "amount": "500"
      }'
  ```

  ```typescript Node.js theme={null}
  // Get the US entity wallet
  const usWallet = await crossmintWallets.getWallet("evm:smart:alias:entity-us", {
      chain: "base-sepolia",
  });

  await usWallet.useSigner({
      type: "server",
      secret: process.env.WALLET_RECOVERY_SECRET!,
  });

  // Transfer 500 USDC from US entity to European entity
  const { hash, explorerLink } = await usWallet.send(
      "evm:smart:alias:entity-europe", // recipient wallet locator
      "usdc",
      "500"
  );

  console.log("Transfer hash:", hash);
  console.log("Explorer:", explorerLink);
  ```

  ```python Python theme={null}
  import requests

  us_wallet_locator = "evm:smart:alias:entity-us"
  token_locator = "base-sepolia:usdc"

  url = f"https://staging.crossmint.com/api/2025-06-09/wallets/{us_wallet_locator}/tokens/{token_locator}/transfers"

  payload = {
      "recipient": "evm:smart:alias:entity-europe",
      "amount": "500"
  }
  headers = {
      "X-API-KEY": "<your-server-api-key>",
      "Content-Type": "application/json"
  }

  response = requests.post(url, json=payload, headers=headers)

  print("Transfer hash:", response.json().get("onChain", {}).get("txId"))
  ```
</CodeGroup>

<Note>
  **Signing transactions (REST API):** The cURL and Python examples above use the simplified [Transfer Token](/api-reference/wallets/transfer-token) endpoint. If your integration requires custom transaction signing, see the full create → sign → approve flow in [Send a Transaction (EVM) — REST tab](/wallets/guides/send-transaction-evm#rest).
</Note>

For the full transfer API reference, see the [Transfer Tokens](/wallets/guides/transfer-tokens) guide.

***

## Step 3: Monitor Transfers with Webhooks

Set up webhooks to receive real-time notifications when transfers complete. Configure the `wallets.transfer.out` and `wallets.transfer.in` event types in the <a href="https://www.crossmint.com/console">Crossmint Console</a>.

For setup instructions and the full event schema, see the [Transfer Webhooks](/wallets/guides/webhooks) guide.

***

## Next Steps

<CardGroup>
  <Card title="Transfer Tokens Guide" icon="arrow-right-arrow-left" href="/wallets/guides/transfer-tokens">
    Full reference for the token transfer API
  </Card>

  <Card title="Transfer Webhooks" icon="bell" href="/wallets/guides/webhooks">
    Monitor transfers real-time
  </Card>

  <Card title="Payouts" icon="money-bill-transfer" href="/stablecoin-orchestration/regulated-transfers/overview">
    Send payouts to external wallets
  </Card>

  <Card title="Check Balances" icon="wallet" href="/wallets/guides/check-balances">
    Query token balances
  </Card>
</CardGroup>


# Fund a Treasury Wallet
Source: https://docs.crossmint.com/stablecoin-orchestration/guides/on-off-ramps/funding-company-wallets

Add funds to your treasury wallet by bank transfer

This guide explains how to fund a treasury wallet via bank transfer. To fund your wallet with stablecoins instead, see the [Pay-ins guide](/stablecoin-orchestration/guides/pay-ins).

## Funding in Staging

There are two ways to fund a treasury wallet in staging:

### Using a Faucet

Use <a href="https://faucet.circle.com/">Circle's USDC faucet</a> to send test tokens directly into your treasury wallet.

### Using the Fund Wallet API

Use the Fund Wallet API to add USDXM (Crossmint's testnet token) to your wallet.

<Note>Available in staging only. Supports USDXM only.</Note>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
      --url 'https://staging.crossmint.com/api/v1-alpha2/wallets/<your-wallet-address>/balances' \
      --header 'X-API-KEY: <your-server-api-key>' \
      --header 'Content-Type: application/json' \
      --data '{
          "amount": 10,
          "token": "usdxm",
          "chain": "base-sepolia"
      }'
  ```

  ```typescript Node.js theme={null}
  import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";

  const crossmint = createCrossmint({
      apiKey: "<your-server-api-key>",
  });

  const crossmintWallets = CrossmintWallets.from(crossmint);

  const wallet = await crossmintWallets.getWallet("<your-wallet-address>", {
      chain: "base-sepolia",
  });

  // Fund with 10 USDXM (staging only)
  await wallet.stagingFund(10);

  console.log("Wallet funded successfully");
  ```

  ```python Python theme={null}
  import requests

  wallet_address = "<your-wallet-address>"
  url = f"https://staging.crossmint.com/api/v1-alpha2/wallets/{wallet_address}/balances"

  payload = {
      "amount": 10,
      "token": "usdxm",
      "chain": "base-sepolia"
  }
  headers = {
      "X-API-KEY": "<your-server-api-key>",
      "Content-Type": "application/json"
  }

  response = requests.post(url, json=payload, headers=headers)

  print(response.json())
  ```
</CodeGroup>

See the [API reference](/api-reference/wallets/fund-wallet) for more details.

## Funding in Production via Bank Transfer

<Note>Production only. Requires an active contract and bank account verification. <a href="https://www.crossmint.com/contact/sales">Contact Crossmint</a> to enable bank transfer funding.</Note>

Fund your treasury wallet with a bank transfer. Crossmint automatically converts incoming funds into stablecoins and deposits them into your wallet.

### 1. Configure Your Bank Account

Share your banking details with Crossmint. Crossmint will provide:

* Bank transfer instructions
* A unique routing memo for your treasury wallet

### 2. Send Funds

Send a bank transfer with the memo provided by the CSE team. Each memo code is associated with a specific treasury wallet and chain, ensuring funds are routed correctly.

<Info>
  Only USDC is supported for B2B onramp. If you send funds with an incorrect memo or transfer details, <a href="https://portal.usepylon.com/crossmint/forms/contact-support">contact support</a> for help recovering the transfer.
</Info>

### 3. Listen for Events

Once the transfer settles, Crossmint converts the funds into the configured stablecoin and deposits them into your treasury wallet on the selected chain.

Track incoming deposits and settlement status using wallet transfer webhooks.

1. [Configure a webhook endpoint](/introduction/platform/webhooks/add-endpoint) for the `wallets.transfer.in` event type.
2. [Verify webhook signatures](/introduction/platform/webhooks/verify-webhooks) to ensure events originate from Crossmint.
3. Monitor fields such as `data.status` to track deposit and settlement progress.

## Next Steps

<CardGroup>
  <Card title="Withdrawals" icon="building-columns" href="/stablecoin-orchestration/guides/on-off-ramps/withdrawing-from-company-wallets">
    Learn how to withdraw stablecoins to your bank account
  </Card>

  <Card title="Payouts" icon="coins" href="/stablecoin-orchestration/regulated-transfers/overview">
    Send stablecoins using Crossmint's regulated infrastructure
  </Card>
</CardGroup>


# Treasury Withdrawals
Source: https://docs.crossmint.com/stablecoin-orchestration/guides/on-off-ramps/withdrawing-from-company-wallets

Offramp stablecoins from your treasury wallet to your bank account

Withdrawals allow you to offramp stablecoins from your treasury wallet directly to your bank account. This is the reverse of the [funding process](/stablecoin-orchestration/guides/on-off-ramps/funding-company-wallets#funding-in-production-via-bank-transfer).

This guide shows you how to withdraw stablecoins from your company wallet directly to your bank account.

<Note>
  Looking for embedded offramps for your customers? Read the [Offramp guide](/offramp/overview).
</Note>

Treasury offramps are designed for company-owned wallets. They:

* Work with treasury wallets managed in the Crossmint Console or API
* Do not require per-user KYC, since the business is the verified entity
* Can be initiated programmatically via the [Create Order API](/api-reference/headless/create-order)

## Offramp via API

1. Contact Crossmint to register a bank account and obtain the `paymentMethodId`.
2. Initiate a stablecoin transfer from your treasury wallet to a bank account using the [Create Order API](/api-reference/headless/create-order).

<Accordion title="View code example">
  <CodeGroup>
    ```js Node.js theme={null}
    const serverApiKey = process.env.CROSSMINT_SERVER_SIDE_API_KEY;
    const payerAddress = "YOUR_TREASURY_WALLET_ADDRESS";
    const paymentMethodId = "YOUR_PAYMENT_METHOD_ID";
    const amount = "100";

    const response = await fetch(
        "https://www.crossmint.com/api/2022-06-09/orders",
        {
            method: "POST",
            headers: {
                "Content-Type": "application/json",
                "x-api-key": serverApiKey,
            },
            body: JSON.stringify({
                payment: {
                    method: "base",
                    currency: "usdc",
                    payerAddress: payerAddress,
                },
                recipient: {
                    paymentMethodId: paymentMethodId,
                },
                lineItems: [
                    {
                        currencyLocator: "fiat:usd",
                        executionParameters: {
                            mode: "exact-in",
                            amount: amount,
                        },
                    },
                ],
            }),
        }
    );

    const data = await response.json();
    console.log(data);
    ```

    ```bash cURL theme={null}
    curl --request POST \
      --url 'https://www.crossmint.com/api/2022-06-09/orders' \
      --header 'Content-Type: application/json' \
      --header 'x-api-key: YOUR_SERVER_SIDE_API_KEY' \
      --data '{
        "payment": {
          "method": "base",
          "currency": "usdc",
          "payerAddress": "YOUR_TREASURY_WALLET_ADDRESS"
        },
        "recipient": {
          "paymentMethodId": "YOUR_PAYMENT_METHOD_ID"
        },
        "lineItems": [
          {
            "currencyLocator": "fiat:usd",
            "executionParameters": {
              "mode": "exact-in",
              "amount": "100"
            }
          }
        ]
      }'
    ```

    ```python Python theme={null}
    import os
    import requests

    server_api_key = os.getenv("CROSSMINT_SERVER_SIDE_API_KEY")
    payer_address = "YOUR_TREASURY_WALLET_ADDRESS"
    payment_method_id = "YOUR_PAYMENT_METHOD_ID"
    amount = "100"

    url = "https://www.crossmint.com/api/2022-06-09/orders"
    headers = {
        "Content-Type": "application/json",
        "x-api-key": server_api_key,
    }
    payload = {
        "payment": {
            "method": "base",
            "currency": "usdc",
            "payerAddress": payer_address,
        },
        "recipient": {
            "paymentMethodId": payment_method_id,
        },
        "lineItems": [
            {
                "currencyLocator": "fiat:usd",
                "executionParameters": {
                    "mode": "exact-in",
                    "amount": amount,
                },
            },
        ],
    }

    response = requests.post(url, headers=headers, json=payload)
    data = response.json()
    print(data)
    ```
  </CodeGroup>

  Replace `YOUR_TREASURY_WALLET_ADDRESS` with your company wallet address and `YOUR_PAYMENT_METHOD_ID` with the payment method ID provided by your CSE contact.
</Accordion>

## How It Works

After the withdrawal is initiated:

* Stablecoins are debited from your treasury wallet
* Crossmint converts them into the selected fiat currency
* Funds are sent to your bank account through the selected rail, such as ACH, RTP, or SEPA
* You can track status in the Console or by polling the order status endpoint

### Monitor Withdrawal Status

You can track the status of your withdrawal by polling the order status endpoint:

<Accordion title="View code example">
  <CodeGroup>
    ```js Node.js theme={null}
    const apiKey = process.env.CROSSMINT_SERVER_SIDE_API_KEY;
    const orderId = "YOUR_ORDER_ID";

    const response = await fetch(
        `https://www.crossmint.com/api/2022-06-09/orders/${orderId}`,
        {
            method: "GET",
            headers: {
                "Content-Type": "application/json",
                "x-api-key": apiKey,
            },
        }
    );

    if (!response.ok) {
        throw new Error(`Failed to get order: ${response.status} ${response.statusText}`);
    }

    const data = await response.json();
    console.log(data);
    ```

    ```bash cURL theme={null}
    API_KEY="YOUR_SERVER_SIDE_API_KEY"
    ORDER_ID="YOUR_ORDER_ID"

    curl --request GET \
      --url "https://www.crossmint.com/api/2022-06-09/orders/${ORDER_ID}" \
      --header "Content-Type: application/json" \
      --header "x-api-key: ${API_KEY}"
    ```

    ```python Python theme={null}
    import os
    import requests

    api_key = os.getenv("CROSSMINT_SERVER_SIDE_API_KEY")
    order_id = "YOUR_ORDER_ID"

    url = f"https://www.crossmint.com/api/2022-06-09/orders/{order_id}"
    headers = {
        "Content-Type": "application/json",
        "x-api-key": api_key,
    }

    response = requests.get(url, headers=headers)

    if not response.ok:
        raise Exception(f"Failed to get order: {response.status_code} {response.reason}")

    print(response.json())
    ```
  </CodeGroup>
</Accordion>

## Next Steps

<CardGroup>
  <Card title="Product Overview" icon="arrow-right-from-bracket" href="/offramp/overview">
    Full offramp documentation
  </Card>

  <Card title="Payment Schemes" icon="credit-card" href="/offramp/payment-methods">
    Supported payment methods and schemes
  </Card>

  <Card title="Offramp Quickstart" icon="bolt" href="/offramp/quickstarts/rest-api">
    Get started with the Offramp API
  </Card>
</CardGroup>


# Pay-ins
Source: https://docs.crossmint.com/stablecoin-orchestration/guides/pay-ins

Receive stablecoin payments from customers and partners

This guide walks you through how to receive payments from third parties. By the end, you will be able to:

* Generate a wallet address to receive funds
* Assign dedicated addresses to payers or payment requests
* Track incoming transfers in real time
* Sweep deposits into a central treasury for reconciliation

## Prerequisites

* A Crossmint **server API key** with the scopes `wallets.create`, `wallets.read`, `wallets:transactions.create`, `wallets:transactions.sign`
* The <a href="https://www.npmjs.com/package/@crossmint/wallets-sdk">Crossmint Wallets SDK</a> installed

<Snippet />

***

## Step 1 — Choose a Collection Strategy

There are two common ways to receive payments:

* **Shared treasury address:** Use a single wallet address for all incoming payments. This is the simplest approach but may require additional reconciliation work.
* **Dedicated deposit addresses:** Create a unique wallet for each payer or payment request, then sweep funds into your treasury wallet via webhooks and internal transfers. This simplifies reconciliation by associating each address with a specific customer or invoice.

***

## Step 2 — Create a Receiving Wallet

Create a wallet to receive stablecoin payments:

* For a **shared treasury address**, set up a company-owned wallet using the [Treasury Wallets](/wallets/guides/treasury-wallets) guide
* For **dedicated deposit addresses**, create a wallet per payer using the [Create Wallet](/wallets/guides/create-wallet) guide

***

## Step 3 — Share the Payment Address

Provide the wallet address to the payer. Once the transaction settles on-chain, the funds become available in the receiving wallet.

***

## Step 4 — Listen for Incoming Payments with Webhooks

Once a payer sends stablecoins to the wallet address, Crossmint fires a `wallets.transfer.in` webhook event. Set up a webhook endpoint to receive these notifications in real time.

1. **Configure a webhook endpoint** in the <a href="https://www.crossmint.com/console">Crossmint Console</a> by following the [Add an Endpoint](/introduction/platform/webhooks/add-endpoint) guide. Select the `wallets.transfer.in` event type.

2. **Verify the webhook signature** to ensure the request is legitimate. See [Verify Webhooks](/introduction/platform/webhooks/verify-webhooks).

3. **Process the event** in your handler. The payload includes the sender address, recipient address, token, amount, and on-chain transaction details:

<Accordion title="Example webhook payload">
  ```json theme={null}
  {
    "id": "whevnt_12324",
    "type": "wallets.transfer.in",
    "data": {
      "transferId": "660e8400-e29b-41d4-a716-446655440002",
      "sender": {
        "address": "0x1234567890123456789012345678901234567890",
        "chain": "base-sepolia",
        "locator": "base-sepolia:0x1234567890123456789012345678901234567890"
      },
      "recipient": {
        "address": "0x0987654321098765432109876543210987654321",
        "chain": "base-sepolia",
        "locator": "base-sepolia:0x0987654321098765432109876543210987654321",
        "owner": "email:customer@example.com"
      },
      "token": {
        "type": "fungible",
        "chain": "base-sepolia",
        "locator": "base-sepolia:0x036CbD53842c5426634e7929541eC2318f3dCF7e",
        "amount": "250.00",
        "rawAmount": "250000000",
        "contractAddress": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
        "decimals": 6,
        "symbol": "USDC"
      },
      "status": "succeeded",
      "completedAt": "2025-10-21T12:34:56.789Z",
      "onChain": {
        "txId": "0xabc123def456abc123def456abc123def456abc123def456abc123def456abc1",
        "explorerLink": "https://sepolia.basescan.org/tx/0xabc123def456abc123def456abc123def456abc123def456abc123def456abc1"
      }
    }
  }
  ```
</Accordion>

For the full webhook schema and best practices, see the [Wallet Webhooks](/wallets/guides/webhooks) guide.

***

## (Optional) Step 5 — Sweep Deposits into Your Treasury

If you created dedicated deposit addresses, you may want to consolidate received funds into a single treasury wallet. To do this, transfer tokens from each deposit wallet to your treasury whenever a payment arrives.

A common pattern is to trigger a sweep automatically from your webhook handler: when you receive a `wallets.transfer.in` event for a deposit wallet, initiate a transfer from that wallet to your treasury.

<Accordion title="Example sweep transfer">
  <CodeGroup>
    ```typescript Node.js theme={null}
    import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";

    const crossmint = createCrossmint({
        apiKey: "YOUR_SERVER_API_KEY",
    });

    const crossmintWallets = CrossmintWallets.from(crossmint);

    const depositWallet = await crossmintWallets.getWallet(
        "DEPOSIT_WALLET_ADDRESS",
        { chain: "base-sepolia" }
    );

    await depositWallet.useSigner({
        type: "server",
        secret: process.env.WALLET_SIGNER_SECRET!,
    });

    const { hash, explorerLink } = await depositWallet.send(
        "evm:smart:alias:treasury",
        "usdc",
        "250"
    );
    ```

    ```bash cURL theme={null}
    curl --request POST \
        --url 'https://staging.crossmint.com/api/2025-06-09/wallets/DEPOSIT_WALLET_ADDRESS/tokens/base-sepolia:usdc/transfers' \
        --header 'X-API-KEY: YOUR_SERVER_API_KEY' \
        --header 'Content-Type: application/json' \
        --data '{
            "recipient": "evm:smart:alias:treasury",
            "amount": "250"
        }'
    ```

    ```python Python theme={null}
    import requests

    deposit_wallet = "DEPOSIT_WALLET_ADDRESS"
    token_locator = "base-sepolia:usdc"

    url = f"https://staging.crossmint.com/api/2025-06-09/wallets/{deposit_wallet}/tokens/{token_locator}/transfers"

    payload = {
        "recipient": "evm:smart:alias:treasury",
        "amount": "250"
    }
    headers = {
        "X-API-KEY": "YOUR_SERVER_API_KEY",
        "Content-Type": "application/json"
    }

    response = requests.post(url, json=payload, headers=headers)
    ```
  </CodeGroup>
</Accordion>

For more details on transferring tokens between wallets, see the [Internal Transfers](/stablecoin-orchestration/guides/internal-transfers) guide.

***

## Next Steps

<CardGroup>
  <Card title="Wallet Webhooks" icon="bell" href="/wallets/guides/webhooks">
    Full schema and best practices for monitoring transfers
  </Card>

  <Card title="Check Balances" icon="wallet" href="/wallets/guides/check-balances">
    Query token balances across your wallets
  </Card>

  <Card title="Payouts" icon="arrow-right" href="/stablecoin-orchestration/regulated-transfers/overview">
    Send stablecoins to your customers
  </Card>

  <Card title="Internal Transfers" icon="arrow-right-arrow-left" href="/stablecoin-orchestration/guides/internal-transfers">
    Move funds between your own treasury wallets
  </Card>
</CardGroup>


# Swaps
Source: https://docs.crossmint.com/stablecoin-orchestration/guides/swaps

Convert stablecoins between tokens and across chains

Crossmint wallets support token swaps and cross-chain bridging, allowing you to programmatically convert between stablecoins (e.g., USDT to USDC), exchange stablecoins for other digital assets, and move funds across blockchains.

For a full overview of swapping and bridging capabilities, see the [Swapping & Bridging Overview](/wallets/guides/wallet-extensions/swapping-and-bridging).


# Overview
Source: https://docs.crossmint.com/stablecoin-orchestration/overview

Move stablecoins using Crossmint's regulated infrastructure

Stablecoin Orchestration provides everything businesses need to move money globally with stablecoins through a single API. Manage treasury operations, collect payments, convert between fiat and stablecoins, and send payouts worldwide—all through one integration.

Crossmint provides the regulated infrastructure layer behind the scenes. Developers integrate a simple API, while Crossmint handles licensing, compliance, global fiat connectivity, key management, and liquidity.

## Building Blocks

Crossmint offers the following core building blocks for money movement. Use them independently or combine them to build end-to-end products and flows:

| Building Block | Description |
| - | - |
| [**Treasury Wallets**](/wallets/guides/treasury-wallets) | Create and manage company wallets |
| [**Funding**](/stablecoin-orchestration/guides/on-off-ramps/funding-company-wallets) & [**Withdrawals**](/stablecoin-orchestration/guides/on-off-ramps/withdrawing-from-company-wallets) | Fund treasury wallets with fiat and withdraw funds to bank accounts |
| [**Pay-ins**](/stablecoin-orchestration/guides/pay-ins) | Collect stablecoin payments globally |
| [**Payouts**](/stablecoin-orchestration/regulated-transfers/overview) | Send stablecoin payouts globally through Crossmint's regulated infrastructure |
| [**Internal Transfers**](/stablecoin-orchestration/guides/internal-transfers) | Rebalance funds across entities, wallets, or regions |
| [**Swaps**](/stablecoin-orchestration/guides/swaps) | Convert stablecoins and other tokens across supported chains |

<Info>Building a consumer-facing experience? See the [wallet](/wallets/overview), [onramp](/onramp/overview), and [offramp](/offramp/overview) guides.</Info>

***

## Key Features

<CardGroup>
  <Card title="All-in-one" icon="layer-group">
    Fully integrated stablecoin platform
  </Card>

  <Card title="Regulated APIs" icon="scale-balanced">
    Full US coverage, MiCA, and more
  </Card>

  <Card title="Global Coverage" icon="globe">
    Support in 160+ countries
  </Card>

  <Card title="Fiat Connectivity" icon="building-columns">
    Move between fiat and stablecoins
  </Card>

  <Card title="Compliance Built-in" icon="shield-check">
    Onboarding, sanctions, AML, and Travel Rule
  </Card>

  <Card title="Deployment Support" icon="users">
    Dedicated FDEs for launch
  </Card>
</CardGroup>

***

## Get Started

<CardGroup>
  <Card title="Create a Treasury" icon="wallet" href="/wallets/guides/treasury-wallets">
    Open and manage a treasury wallet
  </Card>

  <Card title="Fund Your Treasury" icon="credit-card" href="/stablecoin-orchestration/guides/on-off-ramps/funding-company-wallets">
    Onramp into your treasury
  </Card>

  <Card title="Make a Payout" icon="paper-plane" href="/stablecoin-orchestration/regulated-transfers/overview">
    Send a regulated payout
  </Card>

  <Card title="Pay-ins" icon="arrow-down-to-bracket" href="/stablecoin-orchestration/guides/pay-ins">
    Receive stablecoin deposits
  </Card>

  <Card title="Internal Transfers" icon="arrow-right-arrow-left" href="/stablecoin-orchestration/guides/internal-transfers">
    Move money in between treasuries
  </Card>

  <Card title="Talk to Sales" icon="headset" href="https://crossmint.com/contact">
    Get production access and expert support
  </Card>
</CardGroup>


# Making a Payout
Source: https://docs.crossmint.com/stablecoin-orchestration/regulated-transfers/guides/transfers

Execute compliant payouts and handle compliance errors

The [Transfer Token API](/api-reference/wallets/transfer-token) enables you to trigger payouts from your treasury wallet to user wallets. The API automatically performs compliance checks and will return specific errors if the recipient has not provided the appropriate information or did not pass the necessary compliance checks.

<Warning>
  You must include `"transactionType": "regulated-transfer"` in your transfer request to enable compliance checks. Without it, the transfer defaults to `direct` mode, which skips all compliance screening. See [Supported Transfer Types](#supported-transfer-types) for all options.
</Warning>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
      --url 'https://staging.crossmint.com/api/2025-06-09/wallets/<your-treasury-wallet-locator>/tokens/base-sepolia:usdc/transfers' \
      --header 'X-API-KEY: <your-server-api-key>' \
      --header 'Content-Type: application/json' \
      --data '{
          "recipient": "<recipient-wallet-address>",
          "amount": "100",
          "transactionType": "regulated-transfer"
      }'
  ```

  ```typescript Node.js theme={null}
  import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";

  const crossmint = createCrossmint({
      apiKey: "<your-server-api-key>",
  });

  const crossmintWallets = CrossmintWallets.from(crossmint);

  const treasuryLocator = "<your-treasury-wallet-locator>";

  const treasuryWallet = await crossmintWallets.getWallet(treasuryLocator, {
      chain: "base-sepolia",
  });

  await treasuryWallet.useSigner({ type: "server", secret: process.env.WALLET_SIGNER_SECRET! });

  try {
      const { hash, explorerLink } = await treasuryWallet.send(
          "<recipient-wallet-address>",
          "usdc",
          "100",
          { transactionType: "regulated-transfer" }
      );

      console.log(`Transfer successful: ${hash}`);
      console.log(`Explorer: ${explorerLink}`);
  } catch (error) {
      console.error("Transfer failed:", error.message);
      // Handle compliance errors - see error codes below
  }
  ```

  ```python Python theme={null}
  import requests

  treasury_locator = "<your-treasury-wallet-locator>"
  token_locator = "base-sepolia:usdc"

  url = f"https://staging.crossmint.com/api/2025-06-09/wallets/{treasury_locator}/tokens/{token_locator}/transfers"

  payload = {
      "recipient": "<recipient-wallet-address>",
      "amount": "100",
      "transactionType": "regulated-transfer"
  }
  headers = {
      "X-API-KEY": "<your-server-api-key>",
      "Content-Type": "application/json"
  }

  response = requests.post(url, json=payload, headers=headers)

  print(response.json())
  ```
</CodeGroup>

<Note>
  **Signing transactions (REST API):** The cURL and Python examples above use the simplified [Transfer Token](/api-reference/wallets/transfer-token) endpoint. If your integration requires custom transaction signing, see the full create → sign → approve flow in [Send a Transaction (EVM) — REST tab](/wallets/guides/send-transaction-evm#rest).
</Note>

Wallet locator options for a treasury wallet:

* `<walletAddress>` (e.g., `0x1234...5678`)
* `chainType[:<walletType>]:alias:<alias>` (e.g., `evm:smart:alias:treasury`)

<Warning>
  Transfers are irreversible once executed. Clients must ensure that all transaction details are correct before submitting a transfer request.
</Warning>

## Compliance Errors

If a payout fails compliance checks, the API returns an error response with a top-level `error` flag and a human-readable `message`. No machine-readable reason code is returned, so display or log the message rather than matching on its text in your code. The possible failures are:

<AccordionGroup>
  <Accordion title="Recipient personal data is missing" icon="user-xmark">
    **Error Message:** "Required personal data is missing to complete regulated transfer"

    **Description:** The recipient wallet has not provided all personal data required for compliance screening. The recipient must complete their profile with first name, last name, date of birth, and country of residence.

    **Resolution:** Ensure the recipient has attached their personal data using the [user onboarding API](/identity/register-user-data#step-2-register-user-data).

    <Expandable title="How to test">
      In staging, send a transfer to any user wallet that has not had [personal data registered](/identity/register-user-data#step-2-register-user-data).
    </Expandable>

    ```jsonc theme={null}
    // Example error response
    {
        "error": true,
        "message": "Required personal data is missing to complete regulated transfer"
    }
    ```
  </Accordion>

  <Accordion title="Recipient wallet failed risk screening" icon="shield-xmark">
    **Error Message:** "Recipient wallet was marked as unsafe. It can't receive assets."

    **Description:** The recipient's wallet address was marked as unsafe by Crossmint's wallet screening. This is returned for any blocking screening outcome, not only sanctions matches: a high-risk result from the screening provider (TRM Labs), an active transaction-monitoring alert on the address, or a manual block set by Crossmint. The message is the same for every cause.

    **Resolution:** The payout cannot proceed. The recipient's wallet address is blocked from receiving payouts.

    <Expandable title="How to test">
      In staging, you can trigger this error by using the following special addresses across different chains as the recipient:

      * EVM: `0xc9b888e8f2c9c60f72f84e97e4416c3aca3e1f7c`
      * Solana: `7H7Dph61J9W9WzvRUQbM1tsPJpEQhaQ3GVxPSj1EnSuw`
      * Stellar: `G5CLUPQPRWQXKHASBYSYMIPHE2ZMIFLMEH3ROBTOQMR24YWQIFQW2RY5`
    </Expandable>

    ```jsonc theme={null}
    // Example error response
    {
        "error": true,
        "message": "Recipient wallet was marked as unsafe. It can't receive assets."
    }
    ```
  </Accordion>

  <Accordion title="Recipient failed identity verification" icon="user-shield">
    **Error Message:** "User does not meet the verification requirements to proceed. Check the user's verification status via GET /users/\{userLocator}/identity-verification."

    **Description:** The recipient did not pass the verification checks required to proceed. This is returned for any blocking KYC outcome, including sanctions/PEP screening matches, watchlist hits, banned users, restricted geographies, or failed full/light KYC.

    **Resolution:** The payout cannot proceed. Inspect the recipient's verification status via [`GET /users/{userLocator}/identity-verification`](/api-reference/users/get-identity-verification) to determine the specific reason and any next steps.

    <Expandable title="How to test">
      In staging, if you create a user profile with the name "Sanctioned User Name", Crossmint will consider them sanctioned. You can use this for testing.

      To trigger this error, [create a user](/identity/register-user-data#step-2-register-user-data) with the following data:

      ```json theme={null}
      {
          "personalData": {
              "firstName": "Sanctioned User Name",
              // ... any value for other required fields
          }
      }
      ```

      Then attempt a payout to that user's wallet.
    </Expandable>

    ```jsonc theme={null}
    // Example error response
    {
        "error": true,
        "message": "User does not meet the verification requirements to proceed. Check the user's verification status via GET /users/{userLocator}/identity-verification."
    }
    ```
  </Accordion>

  <Accordion title="Recipient wallet type is not supported" icon="circle-xmark">
    **Error Message:** "Regulated transfers can only be sent to Crossmint-managed wallets or external wallets linked to a Crossmint user."

    **Description:** The destination address is not a Crossmint-managed wallet and is not linked to a Crossmint user. Payouts support transfers to Crossmint user wallets and to external wallets that a Crossmint user has linked to their account.

    **Resolution:** Ensure the recipient has a Crossmint wallet, or link the external wallet address to the recipient's Crossmint user with the [Link External Wallet API](/api-reference/users/link-wallet) before initiating the payout. After linking, the recipient may also need to prove ownership by signing the verification challenge (see the unverified wallet ownership entry below):

    ```bash theme={null}
    curl --request PUT \
        --url https://staging.crossmint.com/api/2025-06-09/users/YOUR_USER_LOCATOR/linked-wallets/YOUR_WALLET_ADDRESS \
        --header 'X-API-KEY: YOUR_API_KEY' \
        --header 'Content-Type: application/json' \
        --data '{
            "chain": "base-sepolia"
        }'
    ```

    ```jsonc theme={null}
    // Example error response
    {
        "error": true,
        "message": "Regulated transfers can only be sent to Crossmint-managed wallets or external wallets linked to a Crossmint user."
    }
    ```
  </Accordion>

  <Accordion title="Recipient wallet ownership is not verified" icon="signature">
    **Error Message:** "Recipient external wallet ownership has not been verified. The recipient must sign the wallet ownership challenge before receiving regulated transfers."

    **Description:** The destination address is an external wallet linked to a Crossmint user, but the user has not proven ownership of the wallet by signing the ownership verification challenge.

    **Resolution:** Have the recipient sign the `verificationChallenge` returned when the wallet was linked (or retrieve it anytime via the [Get Linked Wallet](/api-reference/users/get-linked-wallet) endpoint), then submit the signature as `proof` using the same [Link External Wallet API](/api-reference/users/link-wallet):

    ```bash theme={null}
    curl --request PUT \
        --url https://staging.crossmint.com/api/2025-06-09/users/YOUR_USER_LOCATOR/linked-wallets/YOUR_WALLET_ADDRESS \
        --header 'X-API-KEY: YOUR_API_KEY' \
        --header 'Content-Type: application/json' \
        --data '{
            "chain": "base-sepolia",
            "proof": "YOUR_SIGNATURE"
        }'
    ```

    Once the response shows `"ownership": { "verified": true }`, retry the payout. The verification flow is the same one used for onramp — see [Onramp to Non-Crossmint Wallets](/onramp/guides/onramp-to-external-wallets) for how all wallets, including externally owned accounts (EOAs) and smart contract wallets, use the same flow.

    ```jsonc theme={null}
    // Example error response
    {
        "error": true,
        "message": "Recipient external wallet ownership has not been verified. The recipient must sign the wallet ownership challenge before receiving regulated transfers."
    }
    ```
  </Accordion>
</AccordionGroup>

## Error Handling Best Practices

When implementing payouts, follow these best practices for error handling:

<Steps>
  <Step title="Validate recipient before transfer">
    Before initiating a payout, verify that the recipient has completed their onboarding and provided all required personal data. This can help prevent the missing personal data error.
  </Step>

  <Step title="Implement retry logic for transient errors">
    Some errors may be transient (e.g., temporary API issues). Implement appropriate retry logic with exponential backoff for non-compliance errors.
  </Step>

  <Step title="Log compliance failures">
    Log all compliance-related errors for audit purposes. These logs are important for regulatory reporting and investigating failed transfers.
  </Step>

  <Step title="Notify users of compliance issues">
    When a payout fails due to compliance issues, notify the affected users with clear instructions on how to resolve the issue (e.g., completing their profile, contacting support).
  </Step>
</Steps>

## Supported Transfer Types

When calling the Transfer Token API, you must specify the `transactionType` field to indicate whether the transfer requires compliance checks:

| Type | Description |
| - | - |
| `regulated-transfer` | The transaction is routed through Crossmint's regulated infrastructure. This enables compliance with regulatory requirements and performs AML screening, sanctions checks, and travel rule validation. **Required for payouts to customers.** |
| `onramp` | The transaction is routed through Crossmint's regulated infrastructure, similar to `regulated-transfer`. Used for fiat-to-crypto onramp flows that require compliance checks. |
| `direct` | Standard transfer with no compliance checks. Used for internal treasury-to-treasury transfers. This is the default if `transactionType` is omitted. |

<Warning>
  Omitting the `transactionType` field defaults to `direct`, which **skips all compliance checks**. Always set `transactionType` to `regulated-transfer` (or `onramp` for fiat-to-crypto flows) when sending payouts to customer wallets.
</Warning>

<Note>
  Compliant payouts work for transfers from **Crossmint treasury wallets** to **Crossmint user wallets** and to **external wallets linked to a Crossmint user** with verified ownership. Payouts to unlinked external wallets are not supported.
</Note>

## Additional Resources

<CardGroup>
  <Card title="API Reference" icon="terminal" href="/api-reference/wallets/transfer-token">
    Deep dive into the transfer API reference
  </Card>

  <Card title="Talk to an expert" icon="message" href="https://www.crossmint.com/contact/sales">
    Contact the Crossmint sales team for support
  </Card>
</CardGroup>


# Overview
Source: https://docs.crossmint.com/stablecoin-orchestration/regulated-transfers/overview

Compliant stablecoin payouts through a single API

Crossmint Payouts allow you to send stablecoins to users, businesses, or other third parties without obtaining money-transmission licenses or building your own compliance infrastructure.

Crossmint handles the regulated infrastructure behind the scenes, including licensing, AML screening, sanctions checks, Travel Rule, and reliable blockchain execution. You create the payout through a single API; Crossmint takes care of the rest.

## Key Features

<CardGroup>
  <Card title="Pre-fund" icon="wallet">
    Fund your treasury with fiat or stablecoins
  </Card>

  <Card title="Global coverage" icon="globe">
    Send payouts to 160+ countries
  </Card>

  <Card title="Licensed Infrastruct." icon="scale-balanced">
    Full US coverage, MiCA, and more
  </Card>

  <Card title="AML Screening" icon="shield-check">
    Powered by TRM Labs
  </Card>

  <Card title="Travel Rule" icon="paper-plane">
    When applicable, powered by NotaBene
  </Card>

  <Card title="Bring Your KYC" icon="share-nodes">
    Import user data (optional)
  </Card>
</CardGroup>

## When to Use Payouts

| Scenario | Product |
| - | - |
| Moving funds between your own wallets | Standard transfer |
| Paying a 3rd-party where no regulated flow is required | Standard transfer |
| Sending regulated payouts to third parties | Payouts (`regulated-transfer`) |

<Tip>You can use the same treasury wallet for regulated and non-regulated payouts. For regulated flows, set `"transactionType": "regulated-transfer"` when calling the transfer API.</Tip>

## How It Works

1. Create and fund your Treasury Wallet
2. Register the recipient
3. Initiate a payout
4. Crossmint runs compliance checks
5. Funds are routed through a Crossmint custodial wallet and delivered if the transfer passes all regulatory requirements

## What Crossmint Handles

* **Licensing**: Regulated infrastructure for compliant stablecoin payouts, without the burden of obtaining and maintaining licenses yourself.
* **Wallet Screening and KYT**: Every payout is automatically screened against sanctions lists and risk signals before execution, using TRM Labs.
* **Transaction Monitoring**: Ongoing monitoring for suspicious activity, risk signals, and AML compliance using Unit21 and Sardine.
* **Travel Rule Compliance**: When required, Crossmint automatically exchanges IVMS101 data with counterparties.
* **Blockchain Reliability**: Crossmint operates a reliability layer for transaction submission with multi-RPC failover, queuing, retries, and priority fee optimization to ensure payouts are delivered consistently.

## Get Started

<CardGroup>
  <Card title="Quickstart" icon="bolt" href="/stablecoin-orchestration/regulated-transfers/quickstart">
    Get started with payouts in minutes
  </Card>

  <Card title="Making a Payout" icon="money-bill-transfer" href="/stablecoin-orchestration/regulated-transfers/guides/transfers">
    Step-by-step payout guide
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.crossmint.com/stablecoin-orchestration/regulated-transfers/quickstart

Send payouts from your treasury wallet

<CardGroup>
  <Snippet />
</CardGroup>

<Snippet />

Crossmint Payouts enable you to send compliant stablecoin payouts from your treasury wallet, using the [Transfer Token API](/api-reference/wallets/transfer-token). Crossmint automatically handles compliance so if the payout does not meet regulatory requirements, the call will fail.

<Steps>
  <Step title="Install the SDK">
    Run the following command to install the SDK:

    <Snippet />
  </Step>

  <Step title="Get your treasury wallet">
    Retrieve your treasury wallet using the alias:

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request GET \
          --url 'https://staging.crossmint.com/api/2025-06-09/wallets/evm:smart:alias:treasury' \
          --header 'X-API-KEY: <your-server-api-key>'
      ```

      ```typescript Node.js theme={null}
      import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";

      const crossmint = createCrossmint({
          apiKey: "<your-server-api-key>",
      });

      const crossmintWallets = CrossmintWallets.from(crossmint);

      const treasuryLocator = "evm:smart:alias:treasury"; // your treasury wallet alias

      const treasuryWallet = await crossmintWallets.getWallet(treasuryLocator, {
          chain: "base-sepolia",
      });

      await treasuryWallet.useSigner({ type: "server", secret: process.env.WALLET_SIGNER_SECRET! });
      ```

      ```python Python theme={null}
      import requests

      treasury_locator = "evm:smart:alias:treasury"  # your treasury wallet alias

      url = f"https://staging.crossmint.com/api/2025-06-09/wallets/{treasury_locator}"

      headers = {
          "X-API-KEY": "<your-server-api-key>"
      }

      response = requests.get(url, headers=headers)

      print(response.json())
      ```
    </CodeGroup>

    <Note> Create a treasury wallet if you do not have one already [here](/wallets/guides/treasury-wallets). </Note>
  </Step>

  <Step title="Create recipient wallet">
    Create a wallet for the recipient to receive funds in:

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request POST \
          --url 'https://staging.crossmint.com/api/2025-06-09/wallets' \
          --header 'X-API-KEY: <your-server-api-key>' \
          --header 'Content-Type: application/json' \
          --data '{
              "chainType": "evm",
              "type": "smart",
              "config": {
                  "recoveryMethods": [
                      {
                          "type": "email",
                          "email": "johnd@example.com"
                      }
                  ]
              },
              "owner": "userId:johnd-123"
          }'
      ```

      ```typescript Node.js theme={null}
      const userLocator = "userId:johnd-123";

      const wallet = await crossmintWallets.createWallet({
          chain: "base-sepolia",
          recoveryMethods: [
              {
                  type: "email",
                  email: "johnd@example.com"
              },
          ],
          owner: userLocator
      });

      console.log(wallet.address);
      ```

      ```python Python theme={null}
      import requests

      url = "https://staging.crossmint.com/api/2025-06-09/wallets"

      payload = {
          "chainType": "evm",
          "type": "smart",
          "config": {
              "recoveryMethods": [
                  {
                      "type": "email",
                      "email": "johnd@example.com"
                  }
              ]
          },
          "owner": "userId:johnd-123"
      }
      headers = {
          "X-API-KEY": "<your-server-api-key>",
          "Content-Type": "application/json"
      }

      response = requests.post(url, json=payload, headers=headers)

      print(response.json())
      ```
    </CodeGroup>

    <Note>
      **Paying out to an external wallet?** Instead of creating a Crossmint wallet, you can link the recipient's own wallet to their Crossmint user with the [Link External Wallet API](/api-reference/users/link-wallet). The recipient can then prove ownership by signing the returned verification challenge — this is required to transact with higher limits.
    </Note>
  </Step>

  <Step title="Register recipient as user">
    Register the recipient as a user with Crossmint and provide the required user details to facilitate a compliant money transfer:

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request PUT \
          --url 'https://staging.crossmint.com/api/2025-06-09/users/userId:johnd-123' \
          --header 'X-API-KEY: <your-server-api-key>' \
          --header 'Content-Type: application/json' \
          --data '{
              "userDetails": {
                  "firstName": "John",
                  "lastName": "Doe",
                  "dateOfBirth": "1995-01-01",
                  "countryOfResidence": "DE"
              }
          }'
      ```

      ```javascript Node.js theme={null}
      const userLocator = "userId:johnd-123";

      const options = {
          method: 'PUT',
          headers: {'X-API-KEY': '<your-server-api-key>', 'Content-Type': 'application/json'},
          body: JSON.stringify({
              userDetails: {
                  firstName: "John",
                  lastName: "Doe",
                  dateOfBirth: "1995-01-01",
                  countryOfResidence: "DE"
              }
          })
      };

      fetch(`https://staging.crossmint.com/api/2025-06-09/users/${userLocator}`, options)
          .then(response => response.json())
          .then(response => console.log(response))
          .catch(err => console.error(err));
      ```

      ```python Python theme={null}
      import requests

      user_locator = "userId:johnd-123"

      url = f"https://staging.crossmint.com/api/2025-06-09/users/{user_locator}"

      payload = {
          "userDetails": {
              "firstName": "John",
              "lastName": "Doe",
              "dateOfBirth": "1995-01-01",
              "countryOfResidence": "DE"
          }
      }
      headers = {
          "X-API-KEY": "<your-server-api-key>",
          "Content-Type": "application/json"
      }

      response = requests.put(url, json=payload, headers=headers)

      print(response.json())
      ```
    </CodeGroup>
  </Step>

  <Step title="Send payout">
    Send a payout from your treasury wallet. The API will automatically check compliance requirements. If the payout does not meet regulatory requirements (e.g., missing KYC/KYB, sanctions issues, travel rule violations), the call will fail with an error.

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request POST \
          --url 'https://staging.crossmint.com/api/2025-06-09/wallets/evm:smart:alias:treasury/tokens/base-sepolia:usdc/transfers' \
          --header 'X-API-KEY: <your-server-api-key>' \
          --header 'Content-Type: application/json' \
          --data '{
              "recipient": "userId:johnd-123",
              "amount": "100",
              "transactionType": "regulated-transfer"
          }'
      ```

      ```typescript Node.js theme={null}
      try {
          const { hash, explorerLink } = await treasuryWallet.send(
              userLocator,
              "usdc",
              "100",
              { transactionType: "regulated-transfer" }
          );
          
          console.log(`Transfer successful: ${hash}`);
          console.log(`Explorer: ${explorerLink}`);
      } catch (error) {
          // The payout will fail if compliance requirements are not met
          // Common reasons: missing KYC/KYB, sanctions checks, travel rule violations
          console.error("Transfer failed:", error.message);
      }
      ```

      ```python Python theme={null}
      import requests

      treasury_locator = "evm:smart:alias:treasury"
      token_locator = "base-sepolia:usdc"

      url = f"https://staging.crossmint.com/api/2025-06-09/wallets/{treasury_locator}/tokens/{token_locator}/transfers"

      payload = {
          "recipient": "userId:johnd-123",
          "amount": "100",
          "transactionType": "regulated-transfer"
      }
      headers = {
          "X-API-KEY": "<your-server-api-key>",
          "Content-Type": "application/json"
      }

      response = requests.post(url, json=payload, headers=headers)

      print(response.json())
      ```
    </CodeGroup>

    <Note>
      **Signing transactions (REST API):** The cURL and Python examples above use the simplified [Transfer Token](/api-reference/wallets/transfer-token) endpoint. If your integration requires custom transaction signing, see the full create → sign → approve flow in [Send a Transaction (EVM) — REST tab](/wallets/guides/send-transaction-evm#rest).
    </Note>

    <Note> The transfer API automatically performs compliance checks. If the payout fails due to compliance issues, you will receive an error message indicating what requirements were not met.</Note>
  </Step>
</Steps>

## Compliance Requirements

Payouts will fail if they do not meet regulatory requirements:

* **AML Screening**: Automatic screening against sanctions lists and watchlists
* **Travel Rule Compliance**: Required data exchange for cross-border transfers
* **Transaction Limits**: Adherence to regulatory thresholds and limits

If a payout fails, check the error message for specific compliance requirements that need to be addressed.

## Launching in Production

<Snippet />

Once production access is enabled, the integration steps are almost identical to staging:

1. Create a developer account on the <a href="https://www.crossmint.com/console">production console</a>
2. Create a production server API key on the <a href="https://www.crossmint.com/console/projects/apiKeys">API Keys</a> page with the API scopes `wallets.read`, `wallets:transactions.create`, `wallets:transactions.sign`
3. Replace your test API key with the production key
4. Ensure all compliance requirements are configured for your production environment

## Learn More

<CardGroup>
  <Card title="Payouts Overview" icon="shield-check" href="/stablecoin-orchestration/regulated-transfers/overview">
    Learn more about payouts and compliance features.
  </Card>

  <Card title="Transfer Tokens Guide" icon="coins" href="/wallets/guides/transfer-tokens">
    Detailed guide on transferring tokens between wallets.
  </Card>

  <Card title="Treasury Wallet" icon="vault" href="/wallets/concepts/treasury">
    Learn about managing your treasury wallet.
  </Card>
</CardGroup>

## Other Links

<CardGroup>
  <Card title="API Reference" icon="terminal" href="/api-reference/wallets/transfer-token">
    Deep dive into API reference docs.
  </Card>

  <Card title="Talk to an expert" icon="message" href="https://www.crossmint.com/contact/sales">
    Contact the Crossmint sales team for support.
  </Card>
</CardGroup>


# Architecture
Source: https://docs.crossmint.com/wallets/architecture

Crossmint Wallets Architecture

Crossmint wallets are designed to provide:

1. **Flexibility**: A single wallet primitive that supports many use cases — end-user wallets, treasury management, disbursements, and more.
2. **High throughput and availability**: Wallets scale to the maximum throughput available per chain, at the fastest speeds possible.
3. **True ownership**: You and your users fully own every wallet. Even if Crossmint were to disappear, wallets continue to function — no vendor lock-in, no dependency on Crossmint infrastructure.

All while abstracting out all blockchain complexity — operate with them via simple REST APIs and SDKs.

## Dual Layer Architecture

Crossmint achieves this by separating two concerns: **the wallet itself** and **the authorization methods that control it**.

<img alt="Crossmint wallet architecture separating operational signers from recovery methods" />

### The Core: Smart Contract Wallets

On EVM chains, Crossmint wallets are **smart contract wallets** implementing <a href="https://eips.ethereum.org/EIPS/eip-4337">ERC-4337</a> with <a href="https://eips.ethereum.org/EIPS/eip-7579">ERC-7579</a> modular extensions. Because the wallet is a smart contract, it lives natively on the blockchain — not in a private third-party server that you cannot audit or control.

On Solana, wallets use <a href="https://solana.com/docs/core/pda">program-derived addresses (PDAs)</a> with equivalent programmatic control.

On Stellar, wallets use Soroban smart contracts, with equivalent functionality and additional cost and developer experience improvements around the use of trustlines.

This smart contract foundation enables:

* **Seamless provider migration**: If you wish to migrate, you can update the wallet's recovery methods without changing the wallet address. Your users keep their address, balances, and transaction history regardless of infrastructure changes.
* **Programmable authorization logic**: Add multiple operational signers, with optional scoped permissions, plus multiple recovery methods, with logic fully auditable onchain.
* **Flexible gas sponsorship**: Wallets can pay gas in USDC, native token, or billed to your Crossmint account. See [Gas Sponsorship](/wallets/guides/gas-sponsorship).
* **Easier post-quantum migration**: Unlike wallets that couple wallet address with the underlying signer, Crossmint wallets will continue to operate with the same address once keys are upgraded to post-quantum cryptography.

All permissions are enforced **onchain and fully auditable**, removing the need to trust opaque infrastructure or Crossmint's backend. The wallet logic stays visible, enforceable, and portable.

<Info>
  Because the wallet is a smart contract on a public blockchain, it does not depend on Crossmint's servers to function. If Crossmint were to stop operating, you can interact with the wallet's smart contract directly — adding new signers, transferring assets, or migrating to another provider — using standard blockchain tools.
</Info>

### The Control Layer

A **signer** is a cryptographic identity — such as a device key, passkey, server signer, or external wallet — authorized to approve actions on the wallet's behalf.

Crossmint wallets use two kinds of authorization:

* **Operational signers** approve day-to-day transactions and messages.
* **Recovery methods** prove ownership of the wallet in order to change its operational signers or recovery methods.

| | Operational signer | Recovery method |
| - | - | - |
| What it is for | Day-to-day transactions and message signing | Proving wallet ownership in order to change signers or recovery methods |
| Expected use | Frequent | Occasional |
| Examples | Device key, passkey, server signer, Cloud KMS key, external wallet | Email, phone |
| Can be added or removed | Yes | Yes |
| Restrictions | Can have scopes and an expiration time | Control access to the wallet |

<Accordion title="How it works onchain">
  Operational signers and recovery methods are both entries in the wallet's onchain signer set. The smart contract enforces their permissions, not Crossmint's backend.
</Accordion>

**For end-user wallets**, Crossmint uses the native key enclaves already present on your users' devices: the Secure Enclave on iOS and the Keystore on Android. Signatures happen directly on user hardware with no network round-trip to Crossmint or any third-party server. This means signing adds zero latency compared to a direct blockchain transaction — unlike MPC-based architectures that require key reconstruction across distributed infrastructure before every signature, or cloud TEEs which require a network round trip.

**For server-side and AI agent wallets**, Crossmint supports server signers — a secret held in your own infrastructure that derives keypairs deterministically by chain type (EVM, Solana, or Stellar). Signing happens entirely in-process with no external calls.

**For company and treasury wallets**, Crossmint integrates with your existing cloud infrastructure — AWS KMS, Azure Key Vault, or GCP Cloud HSM. These Cloud KMS signers keep private keys non-extractable inside the provider's hardware security module, supporting up to 1,000 cryptographic signing operations per second per key.

**For recovery**, Crossmint provides recovery methods based on email or phone number OTP. These recovery methods are added to the wallet's onchain signer set, meaning recovery is enforced by the smart contract itself — not by Crossmint's backend. See [Signers](/wallets/concepts/signers) for operational signer guidance, [Recovery Methods](/wallets/concepts/recovery) for the recovery concept, and [Wallet Recovery](/wallets/guides/recovery/wallet-recovery) for the recovery flow.

## What This Means in Practice

**For end-user wallets**, this architecture enables completely invisible, self-custodial wallets. Users sign transactions on their own device hardware without knowing a blockchain is involved. Gas can be fully sponsored when [gas sponsorship](/wallets/guides/gas-sponsorship) is enabled. There is no dependency on a third-party server to sign in or transact. And because the wallet is a smart contract, you have a clear migration path away from any provider — update the recovery method and move on, keeping the same wallet address and all its assets.

**For server-side and AI agent wallets**, you get low-latency, deterministic signing from your own infrastructure. A server signer costs nothing per signing operation and supports throughput limited only by your backend. Separate recovery and signing secrets give you key rotation without wallet migration.

## Why Smart Contract Wallets

Wallets are becoming a foundational primitive for the entire economy and not just for crypto users, but for every person, company, AI agent, and connected device that needs to hold value or authorize payments. At that scale, wallet infrastructure must be extremely cheap to operate, flexible enough to support any custody model, and publicly auditable so that security is a matter of proof, not trust.

### The Problem with Off-Chain Key Storage

Most wallet infrastructure today stores keys off-chain, inside proprietary enclaves or distributed across MPC networks. This means:

* **Provider dependency**: Wallets depend on a specific provider's infrastructure to function.
* **Latency overhead**: Key reconstruction adds latency to every signature.
* **Painful migration**: Moving to a new provider means exporting keys and creating new wallet addresses.

These are reasonable trade-offs for certain use cases — but they are not the right foundation for millions of wallets transacting continuously.

### A Different Approach

Smart contract wallets take a different approach. The wallet is a program deployed on a public blockchain — it does not live in anyone's private infrastructure. The signer is completely separate and can be anything: a passkey on a user's phone, an AWS KMS key in your cloud, or a recovery credential.

The key stays whole. No splitting, no reconstruction, no added latency.

* **Security** comes from authorization logic that is verifiable onchain.
* **Recovery** rotates the wallet's onchain signers.
* **Migration** swaps signers instead of exporting keys.

### Why We Chose This Architecture

We chose this architecture because it is the only one that scales to the future we are building toward: **wallets as ubiquitous and permanent as email addresses, but programmable, auditable, and owned by no one except the people and systems that use them.**

<CardGroup>
  <Card title="Operational Signers" icon="key" href="/wallets/concepts/signers">
    Choose who can transact day to day
  </Card>

  <Card title="Recovery Methods" icon="shield-halved" href="/wallets/concepts/recovery">
    Choose how wallet ownership is verified
  </Card>

  <Card title="Wallet Recovery" icon="arrows-rotate" href="/wallets/guides/recovery/wallet-recovery">
    Learn how wallet recovery works
  </Card>
</CardGroup>


# Custody Models
Source: https://docs.crossmint.com/wallets/concepts/custody-models

How signer choices map to custody architectures — fully custodial, non-custodial, and hybrid models

Custody determines who holds the cryptographic keys that control a wallet. In traditional finance, custody is binary — either the institution holds the assets or the customer does. In blockchain-based systems, custody is more nuanced because key management, transaction authorization, and asset storage can be separated across multiple parties.

Crossmint's [signer architecture](/wallets/concepts/signers) gives you fine-grained control over custody. The signers you choose — and who holds them — define your custody model.

<Warning>
  This page is provided for informational purposes only and does not constitute legal advice.
</Warning>

## What Is Custody?

Custody, in the context of digital assets, refers to **who has the ability to authorize transactions** on a wallet. It is not about where the wallet "lives" (it lives onchain) but about who holds the keys that can move assets.

The question is straightforward: **can your organization unilaterally sign a transaction on this wallet?**

* If **yes** — the wallet is custodial. Your organization is the custodian.
* If **no, only the end user can** — the wallet is non-custodial (also called self-custodial)
* If **both parties must cooperate, or different operations require different parties** — the wallet uses a hybrid model

## Why Custody Matters

Custody classification affects multiple dimensions of your product:

| Dimension | Impact |
| - | - |
| **Regulatory compliance** | Many jurisdictions impose licensing requirements on custodial wallet providers. Non-custodial wallets generally face fewer regulatory obligations because the provider never controls user assets. |
| **Liability** | A custodian is responsible for safeguarding assets. If a custodial wallet is compromised, the custodian may bear liability. Non-custodial providers shift this responsibility to the end user. |
| **User trust** | Some users prefer self-custody for sovereignty and privacy. Others prefer custodial solutions for simplicity and recoverability. Your audience determines which model builds more trust. |
| **Operational control** | Custodial wallets let your organization enforce business rules — spending limits, approval workflows, compliance checks — at the signing layer. Non-custodial wallets delegate all authorization to the user. |
| **Recovery** | In custodial models, your organization can recover access to a wallet using its server signers. In non-custodial models, recovery depends entirely on the user's recovery method (email OTP, phone OTP, or external wallet). |

## Custody Models in Crossmint

Crossmint does not impose a single custody model. Instead, your signer configuration determines custody. The three models below represent the most common patterns.

### Non-Custodial (Self-Custodial)

In a non-custodial configuration, **only the end user holds signing keys**. Crossmint has no ability to authorize transactions or access the wallet's assets.

**Typical signer configuration:**

| Role | Signer | Held by |
| - | - | - |
| Signer | Device signer | User's device (secure enclave) |
| Recovery | Email or phone OTP | User (via their email/phone) |

The device signer is generated inside the user's hardware security module. The private key never leaves the device and is not extractable — not by your application, not by Crossmint, and not by the device operating system. The recovery method (email or phone OTP) is similarly controlled by the user.

**When to use:**

* Consumer applications where users expect self-sovereignty over their assets
* Products where regulatory classification as a non-custodial provider is important
* Applications where minimizing your organization's liability for user assets is a priority

### Custodial

In a custodial configuration, **your organization holds all signing keys**. You have full control over the wallet and can authorize transactions without user involvement.

**Typical signer configuration:**

| Role | Signer | Held by |
| - | - | - |
| Signer | Server signer or Cloud KMS | Your infrastructure |
| Recovery | Server signer or Cloud KMS (different key) | Your infrastructure |

Both signers are server-side keys held in your backend. The primary key handles day-to-day signing. The recovery key (using a different secret or KMS key) provides key rotation and disaster recovery capability. Organizations with existing cloud KMS infrastructure can use Cloud KMS signers for stronger key isolation.

**When to use:**

* Treasury, escrow, and operational wallets owned by your organization
* Products where you need programmatic control over transaction approval (spending limits, compliance checks, multi-step workflows)
* AI agent wallets where the agent is platform-hosted and acts on behalf of your organization
* Scenarios where your organization is already a licensed custodian or plans to become one

### Hybrid

Hybrid models distribute signing authority across multiple parties. Neither your organization nor the user can act unilaterally — both must participate in some capacity.

**Example signer configuration:**

| Role | Signer | Held by |
| - | - | - |
| Signer | Device signer | User's device |
| Additional signer | Server signer | Your infrastructure |
| Recovery | External wallet | User's existing wallet |

Hybrid configurations are useful when you need to enforce organizational policies (compliance, rate limiting, fraud detection) while preserving user sovereignty over their assets. The specific signer combination depends on which operations require user consent versus organizational approval.

**When to use:**

* Enterprise applications with compliance requirements that demand organizational oversight
* Platforms that need to enforce transaction policies while giving users self-custody
* Multi-signature workflows where different parties authorize different operations

## Mapping Signers to Custody

The table below summarizes how common signer configurations map to custody models.

| Operational signer | Recovery method | Custody model | Who can sign transactions? |
| - | - | - | - |
| Device signer | Email/phone OTP | Non-custodial | User only |
| Device signer | Server signer | Hybrid | User signs; organization can also sign via recovery |
| Server signer | Server signer | Custodial | Organization only |
| Cloud KMS | Cloud KMS (different key) | Custodial | Organization only |
| Passkey | Email/phone OTP | Non-custodial | User only |
| External wallet | Server signer | Hybrid | User signs; organization can also sign via recovery |
| Server signer | Email/phone OTP | Hybrid | Organization signs; user can also sign via recovery |

<Info>
  Custody is not just about the operational signer. The recovery method matters too — recovery methods can authorize transactions directly (they are not limited to recovery operations), and whoever controls recovery can also add or remove operational signers on the wallet. A wallet with a user-controlled signer but an organization-controlled recovery method is a hybrid model, not non-custodial.
</Info>

## Compliance Considerations

Custody classification varies by jurisdiction and is subject to evolving regulation. The following are general considerations — not legal advice.

* **Non-custodial providers** generally face fewer licensing requirements, but some jurisdictions are introducing regulations that apply to non-custodial wallet providers as well (for example, requirements around transaction monitoring or user identity verification).
* **Custodial providers** in most jurisdictions need some form of financial services license (money transmitter license in the US, MiCA authorization in the EU, etc.). The specific requirements depend on the jurisdiction, the types of assets held, and the services offered.
* **Hybrid models** are the most complex from a regulatory perspective. Classification depends on the specific signer configuration and the degree of control each party has.

Crossmint's architecture gives you the flexibility to adjust your custody model as regulatory requirements evolve — you can add, remove, or change signers without migrating wallets or changing wallet addresses.

## See Also

<CardGroup>
  <Card title="Signers" icon="key" href="/wallets/concepts/signers">
    The full signer type reference and recommended configurations
  </Card>

  <Card title="Architecture" icon="sitemap" href="/wallets/architecture">
    How the dual-layer architecture separates wallet logic from signer control
  </Card>
</CardGroup>


# Embedded Wallets
Source: https://docs.crossmint.com/wallets/concepts/embedded-wallets

Deploy white-label wallets directly inside your app for any use case

Embedded Wallets are Crossmint [smart contract wallets](/wallets/architecture) designed for applications that want to give users wallets without leaving the app. They share the same underlying [architecture](/wallets/architecture) and [signer model](/wallets/concepts/signers) as all Crossmint wallets, but are configured for end-user ownership and everyday consumer interactions.

This page explains what makes a wallet an embedded wallet and its key capabilities. If you are ready to get started with implementation, head over to the [Wallets Quickstarts](/wallets/quickstarts/react).

## What Makes a Wallet "Embedded"?

An Embedded Wallet is a Crossmint wallet owned by an end user and integrated directly into your application. You reference it by a user-identity [wallet locator](/wallets/concepts/wallet-locators) like an email, user ID, phone number, etc. A few key characteristics set it apart:

| Dimension | User Wallet | Treasury Wallet (`owner: "COMPANY"`) |
| - | - | - |
| **Visibility** | Appears under the **Users** tab in the Console | Appears under the **Company** tab in the Console |
| **Intended operator** | End user or agent | Your finance/ops team or backend systems |
| **Typical signer** | Device signer, passkey, or email OTP | Server signer or [Cloud KMS](/wallets/guides/signers/cloud-kms) |
| **Custody model** | Non-custodial or hybrid | [Custodial](/wallets/concepts/custody-models#custodial) — your organization holds all keys |
| **Common extensions** | Swaps, staking, cards | On/off-ramp, regulated transfers, internal transfers |

## Key Capabilities

### Programmable Controls

Embedded Wallets use the same [signer architecture](/wallets/concepts/signers) as all Crossmint wallets. For embedded use cases, this lets you:

* **Offer passkey or biometric sign-in** using device signers or passkeys.
* **Enable recovery** through email, phone, or social recovery options.
* **Rotate signers** over time without changing wallet addresses or moving assets.
* **Set policy rules** such as spending limits or allowed destinations.

### Multi-Chain Support

Embedded Wallets work across all [supported chains](/introduction/supported-chains) — Solana, 20+ EVM chains (Ethereum, Base, Polygon, and others), and Stellar. You can build one integration and let users hold and transact assets on the chains they prefer.

### Security and Compliance

* **Smart contract wallets**: Each embedded wallet is backed by its own smart contract, providing enhanced security and programmability compared to traditional MPC or TEE-based custody.
* **SOC-2 compliance**: Independently audited security controls and processes.
* **Audit trails**: Immutable logs of all wallet operations for compliance and debugging.
* **Transaction monitoring**: Real-time monitoring via dashboards, APIs, and [webhooks](/wallets/guides/webhooks).

### Consumer-Grade Experience

* **No seed phrases or gas fees**: Crossmint abstracts blockchain complexity so users do not need to manage keys or network-specific fees.
* **Gas sponsorship**: You can sponsor gas for your users and bill costs in fiat.
* **Built-in onramps**: Users can fund wallets directly from cards, Apple Pay, or Google Pay.
* **Account recovery**: Users can recover access even if they lose their main signer.

## Quickstarts

<CardGroup>
  <Card title="React" icon="react" href="/wallets/quickstarts/react" />

  <Card title="Node.js" icon="node-js" href="/wallets/quickstarts/nodejs" />

  <Card title="REST API" icon="server" href="/wallets/quickstarts/restapi" />

  <Card title="React Native" icon="mobile-notch" href="/wallets/quickstarts/react-native" />

  <Card title="Flutter" icon="mobile" href="/wallets/quickstarts/flutter" />

  <Card title="Swift" icon="swift" href="/wallets/quickstarts/swift" />

  <Card title="Kotlin" icon="android" href="/wallets/quickstarts/kotlin" />
</CardGroup>

## See Also

<CardGroup>
  <Card title="Create a Wallet" icon="plus" href="/wallets/guides/create-wallet">
    Step-by-step guide to create and fund an embedded wallet
  </Card>

  <Card title="Signers" icon="key" href="/wallets/concepts/signers">
    The full signer type reference and recommended configurations
  </Card>

  <Card title="Custody Models" icon="shield-halved" href="/wallets/concepts/custody-models">
    How signer choices map to custody architectures
  </Card>

  <Card title="Architecture" icon="layer-group" href="/wallets/architecture">
    How Crossmint smart contract wallets work
  </Card>
</CardGroup>


# Quorum (multi-approval) Signer
Source: https://docs.crossmint.com/wallets/concepts/quorum-signers

How an m-of-n quorum signer requires several members to approve a wallet action

<Snippet />

A **quorum signer** has several member signers. A threshold of them must approve each transaction — for example, any 2 of 3 company officers. With a threshold of at least 2, one lost or stolen member key cannot move funds or change the wallet's signers on its own.

Quorum signers are available on EVM, Solana, and Stellar.

## How a Quorum Works

A quorum has three parts:

* **Members** — regular signers, such as email, phone, external wallet, server, or passkey signers.
* **Threshold** — the number of members that must sign, from 1 to the number of members.
* **Locator** — a `quorum:<id>` identifier that Crossmint assigns when you add the quorum. You use it wherever the API takes a signer locator.

The quorum is the signer that acts. Its members only approve: each member signs its own approval message and submits it under its own locator. When the last required member signs, the transaction executes.

## Where You Can Use a Quorum

A quorum can fill any slot that a single signer can fill.

| Use | Example | Effect |
| - | - | - |
| Recovery method | The only recovery method is a 2-of-3 quorum | Recovery and signer changes need 2 members. One stolen credential cannot take over the wallet. |
| Recovery method, next to other methods | A 2-of-3 quorum plus an independent server recovery method | The server method acts alone. The quorum is a second path that needs 2 members. |
| Operational signer | A treasury wallet whose operational signer is a 3-of-5 quorum | Every transaction needs 3 of the 5 members. |

For the difference between the two roles, see [Recovery Methods](/wallets/concepts/recovery) and [Signers](/wallets/concepts/signers).

## Approval Flow by Chain

The approval flow is the same on every chain, except for who can approve.

| Chain | Who can approve |
| - | - |
| EVM | Any `threshold` members. All members are listed as pending. |
| Solana | Only the members you name in `approvingMembers` when you create the transaction. You must name exactly `threshold` members. |
| Stellar | Any `threshold` members. All members are listed as pending. |

On Solana, each approval message includes the set of signing members, so you choose that set before the members sign. If one of the named members cannot sign, create the transaction again with a different set.

A transaction that waits for approvals does not stay open forever. On Stellar, all required members must sign within about 8 minutes. On EVM and Solana, the transaction stays open for longer, up to a maximum lifetime that Crossmint sets. If the transaction expires, create it again.

## Rules and Limits

| Rule | Value |
| - | - |
| Members | 2 to 10, no duplicates |
| Member types | `email`, `phone`, `external-wallet`, `server`, `passkey` (no `passkey` on Solana) |
| Threshold | 1 to the number of members, at most 10 (at most 6 on Solana) |
| Nested quorums | Not supported |
| Member roles | A member can be in more than one quorum on the same wallet, and can also be a standalone recovery method or operational signer on that wallet |

A member that is also a standalone signer can act alone through that entry. The quorum then does not protect against theft of that member's key.

A quorum's members and threshold cannot change. To rotate a member or change the threshold, add a new quorum and then remove the old one. The new quorum gets a new locator. A recovery method approves each change, like any signer change. If that recovery method is a quorum, `threshold` of its members approve. When the old quorum is removed, its members can no longer approve, and transactions that wait for the old quorum fail.

## See Also

<CardGroup>
  <Card title="Use a Quorum Signer" icon="users" href="/wallets/guides/signers/quorum-signer">
    Create a quorum and approve transactions with it
  </Card>

  <Card title="Recovery Methods" icon="shield-halved" href="/wallets/concepts/recovery">
    Understand how recovery methods restore access
  </Card>

  <Card title="Signers" icon="key" href="/wallets/concepts/signers">
    Choose signers for day-to-day wallet actions
  </Card>
</CardGroup>


# Recovery Methods
Source: https://docs.crossmint.com/wallets/concepts/recovery

How recovery methods prove wallet ownership and restore access.

Recovery is the process of regaining signing access to a wallet when the original signer is no longer available. The most common trigger is a user switching to a new device — the device signer on the old phone or laptop cannot be transferred, so the user must authenticate with their recovery method and enroll a new device key.

Operational signers handle day-to-day wallet actions. See [Signers](/wallets/concepts/signers) for that side of the model.

## What a Recovery Method Is For

A recovery method can authorize:

* Adding a new operational signer, such as a new device.
* Removing an operational signer.
* Adding or removing another recovery method.
* Restoring access when no operational signer is available.

For the recovery flow, including detection, authentication, and device re-enrollment, see [Recover a Wallet](/wallets/guides/recovery/wallet-recovery).

## Recovery Method Types

| Method | Best For | How Access Is Verified |
| - | - | - |
| Email | Consumer applications | One-time code sent to the user's email address |
| Phone | Mobile applications | One-time code sent by SMS |
| Passkey | Biometric recovery | Face, fingerprint, or device PIN through WebAuthn |
| Server signer | Company wallets, backend applications, and agents | A secret stored in your infrastructure |
| External wallet | Applications where the user already controls a wallet | Signature from the external wallet |
| Cloud KMS | Company and treasury wallets | Signature from a key held in your cloud key management service |
| [Quorum](/wallets/concepts/quorum-signers) | Company wallets and theft protection | Signatures from `threshold` of the quorum's members (enterprise feature) |

## Multiple Recovery Methods

Wallets can have one or more recovery methods — for example several email addresses and phone numbers — and a single method is enough to authorize any recovery operation. Recovery methods are configured through the wallet's `recoveryMethods` configuration.

In the SDK, `wallet.signers()` returns the wallet's operational signers and `wallet.recoveryMethods` returns the wallet's recovery methods.

<Snippet />

## Recovery and Custody

Recovery authorization is enforced onchain. Crossmint cannot bypass the configured recovery methods.

Whoever controls a recovery method can also change signers and send transactions. Account for that authority when choosing a [Custody Model](/wallets/concepts/custody-models).

<Accordion title="How it works onchain">
  Recovery methods are registered in the wallet's onchain signer set. The REST API field is `recoveryMethods`. Authorization is enforced by the smart contract. Email and phone methods derive their key inside a TEE.
</Accordion>

## See Also

<CardGroup>
  <Card title="Configure Recovery" icon="shield-halved" href="/wallets/guides/recovery/configure-recovery">
    Set up recovery methods for a wallet
  </Card>

  <Card title="Wallet Recovery" icon="rotate" href="/wallets/guides/recovery/wallet-recovery">
    Recover wallet access when an operational signer is unavailable
  </Card>

  <Card title="Operational Signers" icon="key" href="/wallets/concepts/signers">
    Choose signers for day-to-day wallet actions
  </Card>
</CardGroup>


# Signer Types
Source: https://docs.crossmint.com/wallets/concepts/signer-types

Reference for signer capabilities, supported chains, and common uses.

Use this page to compare signer capabilities and supported chains. See [Signers](/wallets/concepts/signers) for day-to-day wallet control and [Recovery Methods](/wallets/concepts/recovery) for changing wallet control.

## Capability Matrix

| Type | Operational signer? | Recovery method? | Chains | Notes |
| - | - | - | - | - |
| Device | ✅ | ❌ | EVM, Solana, Stellar | Default for client-side wallets; per-device, not portable |
| Passkey | ✅ | ✅ (EVM, Stellar) | EVM, Solana, Stellar | Biometric or PIN on every signature |
| Server | ✅ | ✅ | EVM, Solana, Stellar | Deterministic derivation from a secret you hold |
| Email | ✅ | ✅ | All | One-time code |
| Phone | ✅ | ✅ | All | One-time code over SMS or WhatsApp |
| External wallet | ✅ | ✅ | EVM, Solana, Stellar | User signs with a wallet they already control |
| Cloud KMS | ✅ | ✅ | EVM, Solana, Stellar | Non-extractable key in AWS KMS, Azure Key Vault, GCP Cloud HSM |

## Device Signer

The device signer generates a P256 keypair inside the device's secure enclave — such as iOS Secure Enclave, Android Keystore, or a browser-based credential store. The private key stays inside the hardware security boundary.

The device signer is the default for client-side wallets. Each device gets its own signer, and device signers are not synced or portable across devices. Signing is silent or uses an optional biometric prompt.

## Passkey Signer

Passkeys use the <a href="https://www.w3.org/TR/webauthn-3/">WebAuthn</a> standard to create a hardware-backed credential that can sync across devices through the platform's passkey provider, such as iCloud Keychain or Google Password Manager.

Passkey signers are available on EVM, Solana, and Stellar. On EVM and Stellar a passkey can be an operational signer or a recovery method; on Solana it can only be an operational signer. Each signing operation requires biometric or PIN authentication. If a wallet has multiple passkeys, specify the passkey `id`; a single passkey is selected automatically.

## Server Signer

A server signer is backed by a secret held in your infrastructure. The secret deterministically derives keypairs by chain type. The same secret produces one signer address across EVM chains within a project and environment, with separate addresses for Solana and Stellar.

Server signers are designed for backend applications, treasury wallets, and AI agents. Signing happens in process without external calls.

See the [server-side quickstart](/wallets/quickstarts/nodejs) for a server-only wallet.

## Email OTP Signer

The email OTP signer sends a one-time code to the user's email address. The user enters the code to authorize the operation. Email OTP uses a familiar authentication pattern and works across supported chains.

## SMS / Phone OTP Signer

The phone OTP signer sends a one-time code by SMS or WhatsApp. The user enters the code to authorize the operation. Phone OTP works across supported chains.

## External Wallet Signer

The external wallet signer delegates signing to a wallet the user already controls, such as MetaMask or Phantom. The user provides the wallet address and a signing callback. The callback receives a chain-specific payload: a hex string for EVM, a `VersionedTransaction` for Solana, or a string payload for Stellar.

## Cloud KMS Signer

A Cloud KMS signer uses a non-extractable key stored in AWS KMS, Azure Key Vault, or GCP Cloud HSM. The private key stays inside the cloud provider's hardware security module.

Cloud KMS signers provide cloud IAM controls, audit logging, and optional multi-party approval. They are designed for company wallets, treasury operations, and custodial architectures controlled by your infrastructure.

See the [Cloud KMS implementation guide](/wallets/guides/signers/cloud-kms).

## See Also

<CardGroup>
  <Card title="Operational Signers" icon="key" href="/wallets/concepts/signers">
    Choose signers for day-to-day wallet control
  </Card>

  <Card title="Recovery Methods" icon="shield-halved" href="/wallets/concepts/recovery">
    Understand how wallet ownership is verified
  </Card>

  <Card title="Add Signers" icon="plus" href="/wallets/guides/signers/add-signers">
    Register additional operational signers
  </Card>
</CardGroup>


# Signers
Source: https://docs.crossmint.com/wallets/concepts/signers

Understand operational signers for day-to-day wallet control.

A **signer** is a cryptographic identity authorized to approve actions on a Crossmint wallet. An **operational signer** is the identity that transacts day to day. Recovery methods are the other half of this model; see [Recovery Methods](/wallets/concepts/recovery).

## Operational Signers

Operational signers authorize transactions, sign messages, and interact with protocols. You can add operational signers to a wallet, remove them when they are no longer needed, and restrict them with scopes.

Client-side wallets use a **device signer** by default. It uses the device's secure enclave to sign silently or with an optional biometric prompt. Each device has its own device signer.

Changes to the set of operational signers are authorized by one of the wallet's [recovery methods](/wallets/concepts/recovery).

## Signer Types

Signer types have different capabilities and chain support. See the [Signer Types](/wallets/concepts/signer-types) reference for the capability matrix and notes for each type.

<Card title="Signer Types" icon="list" href="/wallets/concepts/signer-types">
  Compare signer capabilities, chains, and implementation details
</Card>

## Choosing Your Signers

The right signer configuration depends on who controls the wallet and how it will be used.

### Who Is the Wallet For?

Start by identifying the wallet owner:

* **End users** — your application's users, each with their own wallet. The user should control their own keys.
* **Your company** — treasury, operational, or escrow wallets controlled by your organization.
* **AI agents** — wallets controlled by autonomous agents, either user-hosted or platform-hosted.

### End-User Wallets

For wallets owned by end users, the primary decision is the custody model:

**Non-custodial (recommended for most consumer apps)**

The user holds their own keys. On supported chains, the device signer is the default — it is created automatically, signs silently, and requires no configuration. Pair it with an email or phone recovery method so the user can recover their wallet on a new device.

This is the simplest configuration and provides the best user experience for most applications.

**Custodial**

Your organization holds the signing keys on behalf of the user. Use a server signer as the primary signer. This gives you full control over transaction approval and is appropriate when regulatory or business requirements demand it.

See [Custody Models](/wallets/concepts/custody-models) for a deeper discussion of the compliance and architectural implications.

### Company and Treasury Wallets

For wallets controlled by your organization — treasury, escrow, disbursement, or operational wallets — use a server signer or Cloud KMS signer as the primary signer. Server signers derive keys deterministically from a secret in your infrastructure. Cloud KMS signers use non-extractable keys in AWS KMS, Azure Key Vault, or GCP Cloud HSM for stronger isolation.

For key rotation and disaster recovery, configure a second signer (with a different secret or KMS key) as the recovery method. This allows you to rotate the primary key without losing access to the wallet.

To require several people to approve each transaction, use a [quorum signer](/wallets/concepts/quorum-signers) as the operational signer — for example, any 3 of 5 company officers. Quorum signers are an enterprise feature.

### AI Agent Wallets

AI agent wallets follow one of two patterns:

* **User-hosted agents** — the agent acts on behalf of a specific user. The user's wallet uses a device or passkey signer for operations, and the agent interacts through the user's authenticated session. Recovery uses the user's email or phone OTP.
* **Platform-hosted agents** — the agent is controlled by your platform. Use a server signer for operations, similar to a company wallet. The platform holds the secret and controls signing.

For both patterns, [signer scopes](/wallets/guides/signers/scopes) can limit what the agent is allowed to do. For example, you can cap the amount of a specific token it can transfer or restrict transfers to a whitelist of recipients.

## Recommended Configurations

The table below summarizes common signer configurations for different use cases.

| Use case | Operational signer | Recovery method | Custody model |
| - | - | - | - |
| Consumer app (non-custodial) | Device signer (default) | Email or phone | Non-custodial |
| Treasury / escrow wallet | Server signer or Cloud KMS | Server signer or Cloud KMS (different key) | Custodial |
| AI agent (user-hosted) | Device or passkey | Email or phone | Non-custodial |
| AI agent (platform-hosted) | Server signer | Server signer (different secret) | Custodial |

<Info>
  These are starting points. The modular signer architecture lets you combine operational signers and recovery methods to match your specific security, compliance, and UX requirements.
</Info>

## Removing a Signer

Operational signers can be removed from a wallet when they are no longer needed. Removal revokes the signer's onchain authority and hides it from the wallet's active signer list, while preserving audit history so the signer can be re-enabled in the future if required.

<Note>
  Only operational signers are removed this way. Recovery methods are managed separately — see [Recovery Methods](/wallets/concepts/recovery).
</Note>

One of the wallet's recovery methods must approve the removal. In the SDK this is handled automatically with the selected recovery method; when using the REST API you must explicitly approve the resulting transaction.

For step-by-step instructions, see [Remove a Signer](/wallets/guides/signers/remove-signer).

## Restricting a Signer with Scopes

A signer added to a wallet after creation (through `addSigner()` or the [register delegated key](/api-reference/wallets/register-delegated-key) endpoint) has the same transaction authority as the wallet's recovery methods by default.

When you add a signer, its onchain installation timing is configurable: the signer can be installed immediately or on its first transaction. See [Installation Timing](/wallets/guides/signers/add-signers#installation-timing) for details.

To grant narrower authority (for example, when adding a signer for an AI agent or a third party), attach **scopes** and an `expiresAt` to the signer at registration time:

* **Scopes** restrict the signer to specific tokens, optional spending limits, and an optional recipient whitelist
* **`expiresAt`** is an ISO 8601 timestamp after which the signer is denied

Scopes are immutable for the lifetime of the signer. See [Restrict a Signer with Scopes](/wallets/guides/signers/scopes) for the full guide.

## See Also

<CardGroup>
  <Card title="Recovery Methods" icon="shield-halved" href="/wallets/concepts/recovery">
    Understand how the wallet owner proves ownership
  </Card>

  <Card title="Wallet Recovery" icon="rotate" href="/wallets/guides/recovery/wallet-recovery">
    How wallet recovery works when a user switches devices or loses access
  </Card>

  <Card title="Custody Models" icon="shield-halved" href="/wallets/concepts/custody-models">
    How signer choices map to custodial, non-custodial, and hybrid models
  </Card>

  <Card title="Signer Scopes" icon="lock" href="/wallets/guides/signers/scopes">
    Restrict a signer to specific tokens, amounts, recipients, and expiry
  </Card>
</CardGroup>


# Treasury Wallets
Source: https://docs.crossmint.com/wallets/concepts/treasury

Programmable wallets for managing your company's stablecoin treasury

Treasury Wallets are Crossmint [smart contract wallets](/wallets/architecture) designed for businesses that need to hold, move, and manage stablecoins at scale. They share the same underlying [architecture](/wallets/architecture) and [signer model](/wallets/concepts/signers) as all Crossmint wallets, but are configured for company ownership, enterprise-grade controls, and integration with Crossmint's [Stablecoin Orchestration](/stablecoin-orchestration/overview) infrastructure.

This page explains what makes a wallet a treasury wallet, its key capabilities, common use cases, and how it fits within the Crossmint platform. If you are ready to get started with implementation, head over to the [Treasury Wallets guide](/wallets/guides/treasury-wallets).

<Snippet />

## What Makes a Wallet a "Treasury Wallet"?

A Treasury Wallet is any Crossmint wallet created with `owner: "COMPANY"`. This single parameter changes how the wallet behaves:

| Dimension | User Wallet | Treasury Wallet (`owner: "COMPANY"`) |
| - | - | - |
| **Visibility** | Appears under the **Users** tab in the Console | Appears under the **Company** tab in the Console |
| **Intended operator** | End user or agent | Your finance/ops team or backend systems |
| **Typical signer** | Device signer, passkey, or email OTP | Server signer or [Cloud KMS](/wallets/guides/signers/cloud-kms) |
| **Custody model** | Non-custodial or hybrid | [Custodial](/wallets/concepts/custody-models#custodial) — your organization holds all keys |
| **Common extensions** | Swaps, staking, cards | On/off-ramp, regulated transfers, internal transfers |

Under the hood, both wallet types are identical smart contracts. The difference is operational: Treasury Wallets are meant to be controlled by your organization's infrastructure, not by an end user's device.

## Key Capabilities

### Programmable Controls

Treasury Wallets support the same [signer architecture](/wallets/concepts/signers) as all Crossmint wallets. For treasury use cases, this means you can:

* **Set role-based access** by assigning different server signers to different backend services.
* **Enforce multi-signature requirements** by configuring multiple signers that must co-approve high-value transactions.
* **Automate workflows** by combining server signers with your backend logic for scheduled payments, rebalancing, or threshold-based actions.

### Multi-Chain Support

Treasury Wallets work across all [supported chains](/introduction/supported-chains) — Solana, 20+ EVM chains (Ethereum, Base, Polygon, and others), and Stellar. You can hold stablecoins like USDC and USDT across multiple chains from a single integration.

### Security and Compliance

* **Smart contract wallets**: Each treasury wallet is backed by its own smart contract, providing enhanced security and programmability compared to traditional MPC or TEE-based custody.
* **SOC-2 compliance**: Independently audited security controls and processes.
* **Audit trails**: Immutable logs of all treasury operations for compliance and auditing.
* **Transaction monitoring**: Real-time monitoring via dashboards, APIs, and [webhooks](/wallets/guides/webhooks).

### Liquidity Management

Treasury Wallets integrate with Crossmint's on-ramp and off-ramp infrastructure:

* **Fund via bank transfer**: Convert fiat to stablecoins using Crossmint's [onramp](/stablecoin-orchestration/guides/on-off-ramps/funding-company-wallets).
* **Fund via crypto**: Send assets directly to the treasury wallet address.
* **Withdraw to bank**: Convert stablecoins back to fiat via Crossmint's [offramp](/stablecoin-orchestration/guides/on-off-ramps/withdrawing-from-company-wallets).

## Common Use Cases

<AccordionGroup>
  <Accordion title="Corporate Treasury Management" icon="building-columns">
    Manage your company's stablecoin reserves with enterprise-grade controls and automation.

    * **Multi-currency reserves**: Hold USDC, USDT, and other stablecoins across multiple chains.
    * **Automated workflows**: Set up rules for rebalancing and disbursements.
    * **Access controls**: Configure role-based permissions and multi-signature requirements.
    * **Audit trails**: Complete transaction history and compliance reporting.
  </Accordion>

  <Accordion title="Payment Operations" icon="money-bill-transfer">
    Power your disbursements with programmable treasury wallets.

    * **Automated disbursements**: Schedule or trigger payments based on business logic.
    * **Batch processing**: Execute multiple payments efficiently.
    * **Compliance integration**: Built-in AML screening and transaction monitoring via [Stablecoin Orchestration](/stablecoin-orchestration/overview).
    * **Reconciliation**: Automatic matching of payments to invoices and records.
  </Accordion>

  <Accordion title="Liquidity Management" icon="chart-line">
    Optimize treasury operations by managing liquidity across chains and protocols.

    * **Cross-chain rebalancing**: Move funds between chains based on preset rules or triggers.
    * **Liquidity aggregation**: Consolidate funds from multiple sources into your treasury.
    * **Automated conversion**: Set rules to maintain target balances across different stablecoins.
    * **Gas optimization**: Crossmint's [gas sponsorship](/wallets/guides/gas-sponsorship) handles transaction fees.
  </Accordion>
</AccordionGroup>

## How Treasury Wallets Fit the Crossmint Platform

Treasury Wallets sit at the intersection of two Crossmint products:

* **[Wallets](/wallets/overview)**: Treasury Wallets use the same SDK, API, and signer model. Everything you learn about Crossmint wallets — creating them, managing signers, checking balances, transferring tokens — applies directly.
* **[Stablecoin Orchestration](/stablecoin-orchestration/overview)**: Treasury Wallets are the accounts from which regulated transfers, pay-ins, payouts, swaps, and on/off-ramp flows originate. If you are building stablecoin transfer flows, your Treasury Wallet is the starting point.

## See Also

<CardGroup>
  <Card title="Treasury Wallets Guide" icon="bolt" href="/wallets/guides/treasury-wallets">
    Step-by-step guide to create a treasury wallet and check balances
  </Card>

  <Card title="Custody Models" icon="lock" href="/wallets/concepts/custody-models">
    How signer choices map to custody architectures
  </Card>

  <Card title="Stablecoin Orchestration" icon="arrows-rotate" href="/stablecoin-orchestration/overview">
    Regulated infrastructure for moving stablecoins at scale
  </Card>

  <Card title="Signers" icon="key" href="/wallets/concepts/signers">
    The full signer type reference and recommended configurations
  </Card>
</CardGroup>


# Wallet Locators
Source: https://docs.crossmint.com/wallets/concepts/wallet-locators

Identifiers to reference and manage your wallets across chains, environments, and users

A **wallet locator** is a string that identifies a specific wallet across all Crossmint APIs and SDKs. Instead of tracking raw blockchain addresses, you reference wallets by a user identity (email, user ID, phone number, or social handle) combined with chain and wallet type information.

The general format is:

```text theme={null}
<userType>:<userIdentifier>:<chainType>:<walletType>
```

For example, `email:alice@example.com:evm:smart` identifies the EVM smart wallet owned by `alice@example.com`.

## Components

### User Type

The user type specifies how the wallet owner is identified. You can use an email, your app's internal user ID, a phone number, a social handle, or the `me` shorthand for client-side contexts. You can also pass a raw wallet address directly.

| User type | Description | Example |
| - | - | - |
| `email` | Email address | `email:alice@example.com` |
| `userId` | Your app's internal user ID or a DID | `userId:507f1f77bcf86cd799439011` |
| `phoneNumber` | Phone number in E.164 format | `phoneNumber:+12125551234` |
| `twitter` | Twitter/X handle | `twitter:johndoe` |
| `x` | Alias for `twitter` | `x:johndoe` |
| `me` | Authenticated user (client-side only) | `me` |
| (none) | Direct wallet address | `0x1234...abcd` |

The `userId` type accepts any string, including Decentralized Identifiers (DIDs) with colons (e.g., `userId:did:key:z6Mk...abc:evm:smart`). The API parses the chain and wallet type from the end of the locator correctly.

### Chain Type

The chain type specifies which blockchain ecosystem the wallet belongs to. It is required for all user-based locators. For direct wallet addresses, the chain is inferred from the address format.

| Chain type | Blockchains |
| - | - |
| `evm` | Ethereum, Base, Polygon, Arbitrum, and other EVM-compatible chains |
| `solana` | Solana |
| `stellar` | Stellar |
| `aptos` | Aptos |
| `sui` | Sui |

### Wallet Type

The wallet type specifies the wallet's underlying architecture. **It is optional and defaults to `smart` when omitted.** For most integrations, `smart` is the recommended type.

| Wallet type | Description |
| - | - |
| `smart` | Smart contract wallet (ERC-4337 on EVM, Swig on Solana, Soroban on Stellar) |
| `mpc` | MPC (multi-party computation) wallet |

### Alias

An alias is an optional label that lets you create **multiple wallets** for the same user on the same chain. Aliases are appended with the `:alias:<name>` suffix.

Alias constraints:

* Alphanumeric characters, hyphens, and underscores only
* Maximum 36 characters
* Only supported with the `smart` wallet type

## Formats

Optional segments are shown in square brackets.

| Format | Description |
| - | - |
| `<address>` | Direct wallet address (EVM, Solana, or Stellar) |
| `email:<email>:<chainType>[:<walletType>][:alias:<alias>]` | Wallet by email |
| `userId:<userId>:<chainType>[:<walletType>][:alias:<alias>]` | Wallet by user ID |
| `phoneNumber:<phone>:<chainType>[:<walletType>][:alias:<alias>]` | Wallet by phone number |
| `twitter:<handle>:<chainType>[:<walletType>][:alias:<alias>]` | Wallet by Twitter handle |
| `x:<handle>:<chainType>[:<walletType>][:alias:<alias>]` | Wallet by X handle |
| `me:<chainType>[:<walletType>][:alias:<alias>]` | Authenticated user's wallet (client-side) |
| `<chainType>[:<walletType>]:alias:<alias>` | Wallet by alias only |

## Examples

```text theme={null}
# Basic — walletType defaults to smart
email:alice@example.com:evm
userId:user-abc-123:solana:smart
me:evm:smart

# Direct addresses — no user identifier needed
0x1234567890123456789012345678901234567890
7EcDhSYGxXyscszYEp35KHN8vvw3svAuLKTzXwCFLtV

# With aliases — multiple wallets per user on the same chain
email:alice@example.com:evm:smart:alias:treasury
me:solana:smart:alias:savings
evm:alias:treasury

# Other identifier types
phoneNumber:+44207946123:evm:smart
twitter:satoshi:solana
userId:my-app-user-456:evm
```

## Client-Side vs. Server-Side

### Client-Side (Client API Key + JWT)

The authenticated user's identity is derived from the JSON Web Token (JWT). On the client side, `me` is the recommended prefix to reference the current user's wallet:

```text theme={null}
me:evm:smart
me:solana
```

You cannot reference other users' wallets from the client side.

When using the SDK's `getWallet()` on the client side, you don't build the locator manually. The SDK constructs it automatically from the `chain` you provide — it builds a locator in the format `me:<chainType>:smart`, always using `smart` as the wallet type. If you need a wallet with an alias, pass the `alias` option in your wallet args and the SDK appends `:alias:<name>` for you.

```typescript theme={null}
// Client-side: just pass the chain — the SDK builds the locator for you
const wallet = await wallets.getWallet({ chain: "evm", /* signer config */ });

// With an alias
const treasury = await wallets.getWallet({ chain: "evm", alias: "treasury", /* signer config */ });
```

### Server-Side (Server API Key)

You must specify the full user identifier since there is no authenticated session:

```text theme={null}
email:alice@example.com:evm:smart
userId:user-abc-123:solana:smart
```

The `me` prefix is not available server-side. When using the SDK's `getWallet()`, pass the wallet locator string as the first argument:

```typescript theme={null}
// Server-side: pass the full locator string
const wallet = await wallets.getWallet("email:alice@example.com:evm:smart", { chain: "evm", /* signer config */ });
```

## Where Wallet Locators Are Used

Wallet locators appear in REST API paths, SDK methods, and transfer operations:

* **REST API** — `GET /api/2025-06-09/wallets/{walletLocator}`, `.../transactions`, `.../balances`, `.../signers`
* **Token transfers** — both the source wallet and the `recipient` field accept locators
* **SDK methods** — `getWallet()`, `createWallet()`, and other wallet operations

<Info>
  When calling the REST API directly, standard URL encoding rules apply for characters like `@` or `+`. The SDK handles encoding automatically.
</Info>

## Wallet Locators vs. Signer Locators

**Wallet locators** identify a wallet — they combine a user identity, chain, and wallet type.

**Signer locators** identify a signer attached to a wallet — they follow the format `<signerType>:<identifier>` (e.g., `email:alice@example.com`, `server:0xabc...`, `device:<publicKeyBase64>`). Signer types include: `passkey`, `api-key`, `external-wallet`, `server`, `email`, `phone`, and `device`.

See [Signers](/wallets/concepts/signers) for details.

## See Also

<CardGroup>
  <Card title="Create a Wallet" icon="plus" href="/wallets/guides/create-wallet">
    Step-by-step guide to creating wallets using the SDK and REST API
  </Card>

  <Card title="Architecture" icon="sitemap" href="/wallets/architecture">
    How the dual-layer architecture separates wallet logic from signer control
  </Card>
</CardGroup>


# Use Your Own Auth Provider
Source: https://docs.crossmint.com/wallets/guides/bring-your-own-auth

Integrate Crossmint with Auth0, Firebase, Supabase, Stytch, Cognito, or your own JWT-based auth

Crossmint provides connectors for the most popular auth providers, including Auth0, Firebase, Supabase, Stytch, Cognito, and Kinde.

When you bring your own auth, Crossmint automatically extracts the user ID from your provider's JWT and assigns it to the wallet's `owner` property. Wallet creation, transaction signing, and balance reads all work the same way regardless of which auth provider you use.

If you are just getting started or prototyping, [Crossmint Auth](/authentication/introduction) is a great way to move fast in staging before connecting your own provider.

## Prerequisites

* **API Key**: Ensure you have an API key with the scopes: `wallets.create`.

## Using your own auth provider

<Tabs>
  <Tab title="React">
    <Steps>
      <Step title="Configure JWT Authentication in the Crossmint Console">
        1. Navigate to your project in the Crossmint Console.
        2. Go to the API Keys section from the sidebar.
        3. Scroll down to the JWT authentication section.
        4. Choose your preferred authentication method:

        * **3P Auth providers**: Select from supported providers such as Auth0, Stytch, Cognito, Firebase, Kinde, or Supabase. Enter any required environment IDs or configuration details.
        * **Custom tokens**: Opt to issue and manage your own JWTs.

        5. After making your selection and providing any necessary details, click **Save JWT auth settings** to apply your configuration.

        <img alt="JWT Authentication Settings" />
      </Step>

      <Step title="Add the Crossmint providers to your app">
        Add the necessary Crossmint providers to your app together with your own auth provider.

        <CodeGroup>
          ```tsx next.js theme={null}
          "use client";

          import { useEffect } from "react";
          import {
              CrossmintProvider,
              CrossmintWalletProvider,
              useCrossmint,
          } from "@crossmint/client-sdk-react-ui";

          import { YourAuthProvider, useYourAuthProviderHook } from "@your-auth-provider";

          export function Providers({ children }: { children: React.ReactNode }) {
              return (
                  <YourAuthProvider>
                      <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
                          <CrossmintWalletProvider>
                              <JwtSync />
                              {children}
                          </CrossmintWalletProvider>
                      </CrossmintProvider>
                  </YourAuthProvider>
              );
          }

          // Get the JWT from your auth provider and pass it to the Crossmint provider
          function JwtSync() {
              const { jwt } = useYourAuthProviderHook();
              const { setJwt } = useCrossmint();

              useEffect(() => {
                  setJwt(jwt);
              }, [jwt]);

              return null;
          }
          ```
        </CodeGroup>
      </Step>

      <Step title="Pass the JWT and create or retrieve the wallet">
        Once the JWT is available, use `getWallet` to retrieve an existing wallet. If no wallet exists, it throws a `WalletNotAvailableError` — catch it and call `createWallet` instead.

        <CodeGroup>
          ```tsx next.js theme={null}
          "use client";

          import { useYourAuthProviderHook } from "@your-auth-provider";
          import { useEffect } from "react";
          import { useCrossmint, useWallet } from "@crossmint/client-sdk-react-ui";
          import { WalletNotAvailableError } from "@crossmint/wallets-sdk";

          export function YourComponent() {
              const { email } = useYourAuthProviderHook();
              const { jwt } = useCrossmint();
              const { getWallet, createWallet } = useWallet();

              useEffect(() => {
                  if (email != null && jwt != null) {
                      getWallet({ chain: "base-sepolia" }).catch((error) => {
                          if (error instanceof WalletNotAvailableError) {
                              createWallet({
                                  chain: "base-sepolia",
                                  recoveryMethods: [{ type: "email", email }],
                              }).catch(console.error);
                          }
                      });
                  }
              }, [email, jwt]);

              // your component logic here
              return (
                  <div>
                      <h1>Your Component</h1>
                  </div>
              );
          }
          ```
        </CodeGroup>

        <Note>
          `getOrCreateWallet` has been removed in V1. Use `getWallet` to retrieve an existing wallet. If it throws a `WalletNotAvailableError`, call `createWallet` instead. See the [migration guide](/wallets/guides/migrate-to-v1) for details.
        </Note>
      </Step>

      See the [React SDK reference](/sdk-reference/wallets/react/get-started) for more details on providers and hooks.
    </Steps>
  </Tab>

  <Tab title="React Native">
    <Steps>
      <Step title="Configure JWT Authentication in the Crossmint Console">
        1. Navigate to your project in the Crossmint Console.
        2. Go to the API Keys section from the sidebar.
        3. Scroll down to the JWT authentication section.
        4. Choose your preferred authentication method:

        * **3P Auth providers**: Select from supported providers such as Auth0, Stytch, Cognito, Firebase, Kinde, or Supabase. Enter any required environment IDs or configuration details.
        * **Custom tokens**: Opt to issue and manage your own JWTs.

        5. After making your selection and providing any necessary details, click **Save JWT auth settings** to apply your configuration.

        <img alt="JWT Authentication Settings" />
      </Step>

      <Step title="Add the Crossmint providers to your app">
        Add the necessary Crossmint providers to your app together with your own auth provider.

        ```tsx theme={null}
        import { useEffect } from "react";
        import {
            CrossmintProvider,
            CrossmintWalletProvider,
            useCrossmint,
        } from "@crossmint/client-sdk-react-native-ui";

        import { YourAuthProvider, useYourAuthProviderHook } from "@your-auth-provider";

        type ProvidersProps = {
            children: React.ReactNode;
        };

        export default function Providers({ children }: ProvidersProps) {
            return (
                <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
                    <YourAuthProvider>
                        <CrossmintWalletProvider>
                            <JwtSync />
                            {children}
                        </CrossmintWalletProvider>
                    </YourAuthProvider>
                </CrossmintProvider>
            );
        }

        // Get the JWT from your auth provider and pass it to the Crossmint provider
        function JwtSync() {
            const { jwt } = useYourAuthProviderHook();
            const { setJwt } = useCrossmint();

            useEffect(() => {
                setJwt(jwt);
            }, [jwt]);

            return null;
        }
        ```
      </Step>

      <Step title="Pass the JWT and create or retrieve the wallet">
        Once the JWT is available, use `getWallet` to retrieve an existing wallet. If no wallet exists, it throws a `WalletNotAvailableError` — catch it and call `createWallet` instead.

        ```tsx theme={null}
        import { useYourAuthProviderHook } from "@your-auth-provider";
        import { useEffect } from "react";
        import { View, Text } from "react-native";
        import { useCrossmint, useWallet } from "@crossmint/client-sdk-react-native-ui";
        import { WalletNotAvailableError } from "@crossmint/wallets-sdk";

        export function YourAuthComponent() {
            const { email } = useYourAuthProviderHook();
            const { jwt } = useCrossmint();
            const { getWallet, createWallet } = useWallet();

            useEffect(() => {
                if (jwt != null && email != null) {
                    getWallet({ chain: "base-sepolia" }).catch((error) => {
                        if (error instanceof WalletNotAvailableError) {
                            createWallet({
                                chain: "base-sepolia",
                                recoveryMethods: [{ type: "email", email }],
                            }).catch(console.error);
                        }
                    });
                }
            }, [jwt, email]);

            // your component logic here
            return (
                <View>
                    <Text>Your Auth Component</Text>
                </View>
            );
        }
        ```

        <Note>
          `getOrCreateWallet` has been removed in V1. Use `getWallet` to retrieve an existing wallet. If it throws a `WalletNotAvailableError`, call `createWallet` instead. See the [migration guide](/wallets/guides/migrate-to-v1) for details.
        </Note>
      </Step>

      See the [React Native SDK reference](/sdk-reference/wallets/react-native/get-started) for more details on providers and hooks.
    </Steps>
  </Tab>

  <Tab title="Kotlin">
    <Steps>
      <Step title="Configure JWT Authentication in the Crossmint Console">
        1. Navigate to your project in the Crossmint Console.
        2. Go to the API Keys section from the sidebar.
        3. Scroll down to the JWT authentication section.
        4. Choose your preferred authentication method and save your settings.

        <img alt="JWT Authentication Settings" />
      </Step>

      <Step title="Set up the SDK with your JWT">
        Initialize the SDK in your `Application.onCreate` and pass your provider's JWT to the auth manager.

        ```kotlin theme={null}
        import com.crossmint.kotlin.CrossmintSDK
        import com.crossmint.kotlin.compose.LocalCrossmintSDK

        // In Application.onCreate:
        CrossmintSDK.configure(apiKey = "YOUR_CROSSMINT_API_KEY", appContext = this)

        // In your composable or ViewModel:
        val sdk = LocalCrossmintSDK.current

        // Pass the JWT from your auth provider. Call this again with a fresh
        // JWT whenever yours expires — the SDK does not refresh it for you.
        sdk.setJWT("YOUR_PROVIDER_JWT")
        ```
      </Step>

      <Step title="Create or retrieve the wallet">
        Once authenticated, create or retrieve the wallet.

        ```kotlin theme={null}
        import com.crossmint.kotlin.types.EVMChain
        import com.crossmint.kotlin.signers.SignerType
        import com.crossmint.kotlin.types.Result
        import com.crossmint.kotlin.types.WalletError
        import com.crossmint.kotlin.types.getOrThrow

        val wallet = when (val result = sdk.wallets.getWallet(chain = EVMChain.BaseSepolia)) {
            is Result.Success -> result.value
            is Result.Failure -> if (result.error is WalletError.WalletNotFound) {
                sdk.wallets.createWallet(
                    chain = EVMChain.BaseSepolia,
                    recoveryMethods = listOf(SignerType.Email("user@example.com"))
                ).getOrThrow()
            } else {
                throw Exception(result.error.toString())
            }
        }

        println("Wallet address: ${wallet.address}")
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Swift">
    <Steps>
      <Step title="Configure JWT Authentication in the Crossmint Console">
        1. Navigate to your project in the Crossmint Console.
        2. Go to the API Keys section from the sidebar.
        3. Scroll down to the JWT authentication section.
        4. Choose your preferred authentication method and save your settings.

        <img alt="JWT Authentication Settings" />
      </Step>

      <Step title="Set up the SDK with your JWT">
        Initialize the SDK and pass your provider's JWT to the auth manager before creating or fetching a wallet.

        ```swift theme={null}
        import CrossmintClient

        // In your app's entry point:
        CrossmintSDK.configure(apiKey: crossmintApiKey)

        // Pass the JWT from your auth provider
        let sdk = CrossmintSDK.shared
        await sdk.setJWT("YOUR_PROVIDER_JWT")
        ```
      </Step>

      <Step title="Create or retrieve the wallet">
        Once the JWT is set, create or retrieve the wallet as usual.

        ```swift theme={null}
        let wallet: EVMWallet
        if let existing = try await sdk.crossmintWallets.getWallet(
            chain: EVMChain.baseSepolia
        ) {
            wallet = existing
        } else {
            wallet = try await sdk.crossmintWallets.createWallet(
                chain: EVMChain.baseSepolia,
                recoveryMethods: [EVMSigners.email("user@example.com")]
            )
        }
        print("Wallet address:", wallet.address)
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Flutter">
    <Steps>
      <Step title="Configure JWT Authentication in the Crossmint Console">
        1. Navigate to your project in the Crossmint Console.
        2. Go to the API Keys section from the sidebar.
        3. Scroll down to the JWT authentication section.
        4. Choose your preferred authentication method:

        * **3P Auth providers**: Select from supported providers such as Auth0, Stytch, Cognito, Firebase, Kinde, or Supabase. Enter any required environment IDs or configuration details.
        * **Custom tokens**: Opt to issue and manage your own JWTs.

        5. After making your selection and providing any necessary details, click **Save JWT auth settings** to apply your configuration.

        <img alt="JWT Authentication Settings" />
      </Step>

      <Step title="Pass the JWT and create or retrieve the wallet">
        Flutter's auth client is headless. Use your own auth provider to obtain the JWT, then pass it to `client.auth.setJwt(jwt)`. The wallet controller auto-loads or creates a wallet when `createOnLogin` is configured.

        ```dart theme={null}
        import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

        // Whenever your auth provider produces (or refreshes) a JWT:
        Future<void> syncCrossmintAuth(BuildContext context, String? jwt) async {
          final walletContext = CrossmintWalletContext.of(context);
          await walletContext.requireAuth.setJwt(jwt);

          // Optional — lookup or create a wallet once authenticated.
          if (jwt == null) return;
          final controller = walletContext.requireWalletController;
          final existing = await controller.getWallet(
            const CrossmintWalletLookupRequest(chain: 'base-sepolia'),
          );
          if (existing == null) {
            await controller.createWallet(
              const CrossmintWalletCreateRequest(
                chain: 'base-sepolia',
                recovery: CrossmintEmailSignerConfig(email: 'YOUR_USER_EMAIL'),
              ),
            );
          }
        }
        ```
      </Step>

      See the [Flutter SDK reference](/sdk-reference/wallets/flutter/controllers#crossmintauthclient) for details on `setJwt` and the auth client surface.
    </Steps>
  </Tab>
</Tabs>


# Check Balances
Source: https://docs.crossmint.com/wallets/guides/check-balances

Retrieve and manage wallet balances using Crossmint's APIs

<Tabs>
  <Tab title="Token Balances">
    ## Prerequisites

    * Ensure you have a wallet created.
    * **API Key**: Ensure you have an API key with the scopes: `wallets.read` and `wallets:balance.read`.

    ## Retrieving Wallet Balances

    <Tabs>
      <Tab title="React">
        ```typescript theme={null}
        import { useWallet } from '@crossmint/client-sdk-react-ui';

        const { wallet } = useWallet();

        const { nativeToken, usdc, tokens } = await wallet.balances(["usdc"]);
        ```

        See the [React SDK reference](/sdk-reference/wallets/react/hooks#wallet-methods) for more details.
      </Tab>

      <Tab title="Node.js">
        ```typescript theme={null}
        import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";

        const crossmint = createCrossmint({
            apiKey: "<your-server-api-key>",
        });

        const crossmintWallets = CrossmintWallets.from(crossmint);

        const wallet = await crossmintWallets.getWallet(
            "<wallet-address>",
            { chain: "base-sepolia" }
        );

        const { nativeToken, usdc, tokens } = await wallet.balances(["usdc"]);
        ```

        See the [SDK reference](/sdk-reference/wallets/typescript/classes/Wallet#balances) for all parameters and return types.
      </Tab>

      <Tab title="React Native">
        ```typescript theme={null}
        import { useWallet } from '@crossmint/client-sdk-react-native-ui';

        const { wallet } = useWallet();

        const { nativeToken, usdc, tokens } = await wallet.balances(["usdc"]);
        ```

        See the [React Native SDK reference](/sdk-reference/wallets/react-native/hooks#wallet-methods) for more details.
      </Tab>

      <Tab title="Kotlin">
        ```kotlin theme={null}
        import com.crossmint.kotlin.CrossmintSDK
        import com.crossmint.kotlin.types.EVMChain
        import com.crossmint.kotlin.types.getOrThrow

        CrossmintSDK.configure(apiKey = "YOUR_CROSSMINT_API_KEY")
        val sdk = CrossmintSDK.shared
        val wallet = sdk.wallets.getWallet(chain = EVMChain.BaseSepolia).getOrThrow()

        val balances = wallet.balances(listOf("usdc")).getOrThrow()
        println("Native: ${balances.nativeToken.amount}")
        println("USDC: ${balances.usdc.amount}")
        for (token in balances.tokens) {
            println("${token.symbol}: ${token.amount}")
        }
        ```
      </Tab>

      <Tab title="Swift">
        ```swift theme={null}
        import CrossmintClient
        import Wallet

        CrossmintSDK.configure(apiKey: "<YOUR_API_KEY>")
        let sdk = CrossmintSDK.shared

        guard let wallet = try await sdk.crossmintWallets.getWallet(
            chain: .baseSepolia
        ) else {
            return
        }

        let balances = try await wallet.balances()
        ```

        ### Parameters

        <ResponseField name="tokens" type="string[]">
          The tokens to get the balances for. This can be a token symbol or a token address.
        </ResponseField>

        ### Returns

        <ResponseField name="balances" type="Balances">
          The balances of the wallet.

          <Expandable title="properties">
            <ResponseField name="nativeToken" type="TokenBalance">
              The native token balance.

              <Snippet />
            </ResponseField>

            <ResponseField name="usdc" type="TokenBalance">
              The USDC balance.

              <Snippet />
            </ResponseField>

            <ResponseField name="tokens" type="TokenBalance[]">
              The tokens balances.

              <Snippet />
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Tab>

      <Tab title="Flutter">
        ```dart theme={null}
        import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

        final controller = CrossmintWalletContext.of(context).requireWalletController;
        final wallet = controller.createEvmWallet();

        final balances = await wallet.balances(tokens: <String>['usdc']);
        print('USDC: ${balances.usdc.amount}');
        print('Native: ${balances.nativeToken.amount}');
        ```

        Swap `createEvmWallet` for `createSolanaWallet` or `createStellarWallet` on
        the matching chain. See the
        [Flutter SDK reference](/sdk-reference/wallets/flutter/controllers#wallet-methods)
        for more details.
      </Tab>

      <Tab title="REST">
        <CodeGroup>
          ```bash cURL theme={null}
          curl --request GET \
              --url 'https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/balances?tokens=usdc&chains=base-sepolia' \
              --header 'X-API-KEY: <x-api-key>'
          ```

          ```js Node.js theme={null}
          const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/balances?tokens=usdc&chains=base-sepolia';

          const options = {
              method: 'GET',
              headers: {
                  'X-API-KEY': '<x-api-key>'
              }
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/balances"

          querystring = {"tokens":"usdc","chains":"base-sepolia"}

          headers = {"X-API-KEY": "<x-api-key>"}

          response = requests.get(url, params=querystring, headers=headers)

          print(response.json())
          ```
        </CodeGroup>

        See the [API reference](/api-reference/wallets/get-wallet-balance) for more details.
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="NFT Balances">
    ## Prerequisites

    * Ensure you have a wallet created.
    * **API Key**: Ensure you have an API key with the scopes: `wallets.read`, `wallets.nfts.read`.

    ## Retrieving NFTs

    <Tabs>
      <Tab title="React">
        ```typescript theme={null}
        import { useWallet } from '@crossmint/client-sdk-react-ui';

        const { wallet } = useWallet();

        const nfts = await wallet.nfts({ page: 1, perPage: 10 });
        ```

        See the [React SDK reference](/sdk-reference/wallets/react/hooks#wallet-methods) for more details.
      </Tab>

      <Tab title="Node.js">
        ```typescript theme={null}
        import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";

        const crossmint = createCrossmint({
            apiKey: "<your-server-api-key>",
        });

        const crossmintWallets = CrossmintWallets.from(crossmint);

        const wallet = await crossmintWallets.getWallet(
            "<wallet-address>",
            { chain: "base-sepolia" }
        );

        const nfts = await wallet.nfts({ page: 1, perPage: 10 });
        ```

        See the [SDK reference](/sdk-reference/wallets/typescript/classes/Wallet#nfts) for all parameters and return types.
      </Tab>

      <Tab title="React Native">
        ```typescript theme={null}
        import { useWallet } from '@crossmint/client-sdk-react-native-ui';

        const { wallet } = useWallet();

        const nfts = await wallet.nfts({ page: 1, perPage: 10 });
        ```

        See the [React Native SDK reference](/sdk-reference/wallets/react-native/hooks#wallet-methods) for more details.
      </Tab>

      <Tab title="Flutter">
        ```dart theme={null}
        import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

        final controller = CrossmintWalletContext.of(context).requireWalletController;
        final wallet = controller.createEvmWallet();

        final nfts = await wallet.nfts(page: 1, perPage: 10);
        ```

        See the [Flutter SDK reference](/sdk-reference/wallets/flutter/controllers#wallet-methods) for more details.
      </Tab>

      <Tab title="Swift">
        ```swift theme={null}
        import CrossmintClient
        import Wallet

        CrossmintSDK.configure(apiKey: "<YOUR_API_KEY>")
        let sdk = CrossmintSDK.shared

        guard let wallet = try await sdk.crossmintWallets.getWallet(
            chain: .baseSepolia
        ) else {
            return
        }

        let nfts = try await wallet.nfts(page: 1, nftsPerPage: 10)
        ```

        ### Parameters

        <ParamField type="number">
          The number of NFTs to return per page.
        </ParamField>

        <ParamField type="number">
          The page number to return.
        </ParamField>

        ### Returns

        <ParamField type="Promise<GetNftsResponse>">
          The NFTs.
        </ParamField>
      </Tab>

      <Tab title="REST">
        <CodeGroup>
          ```bash cURL theme={null}
          curl --request GET \
              --url 'https://staging.crossmint.com/api/2022-06-09/wallets/email:user@example.com:base/nfts?page=1&perPage=20' \
              --header 'X-API-KEY: <x-api-key>'
          ```

          ```js Node.js theme={null}
          const url = 'https://staging.crossmint.com/api/2022-06-09/wallets/email:user@example.com:base/nfts?page=1&perPage=20';

          const options = {
              method: 'GET',
              headers: {
                  'X-API-KEY': '<x-api-key>'
              }
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2022-06-09/wallets/email:user@example.com:base/nfts"

          querystring = {"page":"1","perPage":"20"}

          headers = {"X-API-KEY": "<x-api-key>"}

          response = requests.get(url, params=querystring, headers=headers)

          print(response.json())
          ```
        </CodeGroup>

        See the [API reference](/api-reference/wallets/get-nfts-from-wallet) for more details.
      </Tab>
    </Tabs>
  </Tab>
</Tabs>


# Create Wallet
Source: https://docs.crossmint.com/wallets/guides/create-wallet

Create a wallet using Crossmint's APIs

## Prerequisites

* **API Key**: Ensure you have an API key with the scopes: `wallets.create`.

## Try it Live

Experience wallet creation in action with this interactive demo. Create a Solana testnet wallet using just your email address:

<WalletCreationDemo />

## Creating a Wallet

Wallet creation requires a **recovery method** — used for account recovery and adding new signers. On client-side SDKs, a [device signer](/wallets/concepts/signers) is automatically added as the default operational signer.

<Snippet />

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet } from '@crossmint/client-sdk-react-ui';

    const { createWallet } = useWallet();

    const wallet = await createWallet({
        chain: "base-sepolia",
        recoveryMethods: [
            {
                type: "email",
                email: "user@example.com",
            },
        ],
    });
    ```

    See the [React SDK reference](/sdk-reference/wallets/react/hooks#usewallet) for all parameters.
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";

    const crossmint = createCrossmint({
        apiKey: "<your-server-api-key>",
    });

    const crossmintWallets = CrossmintWallets.from(crossmint);

    const wallet = await crossmintWallets.createWallet({
        chain: "base-sepolia",
        recoveryMethods: [
            {
                type: "server",
                secret: process.env.RECOVERY_SIGNER_SECRET,
            },
        ],
        signers: [
            { type: "server", secret: process.env.WALLET_SIGNER_SECRET },
        ],
    });

    ```

    See the [SDK reference](/sdk-reference/wallets/typescript/classes/CrossmintWallets) for all parameters and return types.
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { useWallet } from '@crossmint/client-sdk-react-native-ui';

    const { createWallet } = useWallet();

    const wallet = await createWallet({
        chain: "base-sepolia",
        recoveryMethods: [
            {
                type: "email",
                email: "user@example.com",
            },
        ],
    });
    ```

    See the [React Native SDK reference](/sdk-reference/wallets/react-native/hooks#usewallet) for all parameters.
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    import com.crossmint.kotlin.CrossmintSDK
    import com.crossmint.kotlin.types.EVMChain
    import com.crossmint.kotlin.signers.SignerType
    import com.crossmint.kotlin.types.getOrThrow

    CrossmintSDK.configure(apiKey = "YOUR_CROSSMINT_API_KEY")
    val sdk = CrossmintSDK.shared
    val result = sdk.wallets.createWallet(
        chain = EVMChain.BaseSepolia,
        recoveryMethods = listOf(SignerType.Email("user@example.com"))
    )
    val wallet = result.getOrThrow()
    println("Wallet address: ${wallet.address}")
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    import CrossmintClient

    CrossmintSDK.configure(apiKey: "<YOUR_API_KEY>")
    let sdk = CrossmintSDK.shared

    let wallet = try await sdk.crossmintWallets.createWallet(
        chain: EVMChain.baseSepolia,
        recoveryMethods: [EVMSigners.email("user@example.com")]
    )
    print("Wallet address:", wallet.address)
    ```
  </Tab>

  <Tab title="Flutter">
    ```dart theme={null}
    import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

    final controller = CrossmintWalletContext.of(context).requireWalletController;

    final wallet = await controller.createWallet(
      const CrossmintWalletCreateRequest(
        chain: 'base-sepolia',
        recovery: CrossmintEmailSignerConfig(email: 'user@example.com'),
      ),
    );
    ```

    With `CrossmintWalletProvider` + `createOnLogin`, the wallet is created
    automatically after login. See the
    [Flutter SDK reference](/sdk-reference/wallets/flutter/controllers#crossmintwalletcontroller)
    for all parameters.
  </Tab>

  <Tab title="REST">
    <CodeGroup>
      ```bash cURL theme={null}
      curl --request POST \
          --url https://staging.crossmint.com/api/2025-06-09/wallets \
          --header 'Content-Type: application/json' \
          --header 'X-API-KEY: <x-api-key>' \
          --data '{
              "chainType": "evm",
              "config": {
                  "recoveryMethods": [
                      {
                          "type": "email",
                          "email": "user@example.com"
                      }
                  ]
              },
              "owner": "email:user@example.com"
          }'
      ```

      ```js Node.js theme={null}
      const url = 'https://staging.crossmint.com/api/2025-06-09/wallets';

      const payload = {
          chainType: "evm",
          config: {
              recoveryMethods: [
                  {
                      type: "email",
                      email: "user@example.com"
                  }
              ]
          },
          owner: "email:user@example.com"
      };

      const options = {
          method: 'POST',
          headers: {
              'X-API-KEY': '<x-api-key>',
              'Content-Type': 'application/json'
          },
          body: JSON.stringify(payload)
      };

      try {
          const response = await fetch(url, options);
          const data = await response.json();
          console.log(data);
      } catch (error) {
          console.error(error);
      }
      ```

      ```python Python theme={null}
      import requests

      url = "https://staging.crossmint.com/api/2025-06-09/wallets"

      payload = {
          "chainType": "evm",
          "config": {
              "recoveryMethods": [
                  {
                      "type": "email",
                      "email": "user@example.com"
                  }
              ]
          },
          "owner": "email:user@example.com"
      }
      headers = {
          "X-API-KEY": "<x-api-key>",
          "Content-Type": "application/json"
      }

      response = requests.post(url, json=payload, headers=headers)

      print(response.json())
      ```
    </CodeGroup>

    See the [API reference](/api-reference/wallets/create-wallet) for more details.
  </Tab>
</Tabs>

<Note>
  The REST API uses `config.recoveryMethods` (recovery methods) and `config.delegatedSigners` (operational signers). These map to `recoveryMethods` and `signers` in the TypeScript SDKs. The REST `adminSigner` field is deprecated: it accepts a single recovery method and cannot be combined with `recoveryMethods`.
</Note>

## Retrieving an Existing Wallet

Use `getWallet()` to retrieve a wallet that was previously created. If the wallet does not exist, it throws a `WalletNotAvailableError`.

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet } from '@crossmint/client-sdk-react-ui';

    const { getWallet } = useWallet();

    const wallet = await getWallet({ chain: "base-sepolia" });
    ```
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";

    const crossmint = createCrossmint({
        apiKey: "<your-server-api-key>",
    });

    const crossmintWallets = CrossmintWallets.from(crossmint);

    const wallet = await crossmintWallets.getWallet(
        "<wallet-address>",
        { chain: "base-sepolia" }
    );

    await wallet.useSigner({
        type: "server",
        secret: process.env.WALLET_SIGNER_SECRET!,
    });

    ```
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { useWallet } from '@crossmint/client-sdk-react-native-ui';

    const { getWallet } = useWallet();

    const wallet = await getWallet({ chain: "base-sepolia" });
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    import com.crossmint.kotlin.CrossmintSDK
    import com.crossmint.kotlin.types.EVMChain
    import com.crossmint.kotlin.types.getOrThrow

    CrossmintSDK.configure(apiKey = "YOUR_CROSSMINT_API_KEY")
    val sdk = CrossmintSDK.shared
    val result = sdk.wallets.getWallet(chain = EVMChain.BaseSepolia)
    val wallet = result.getOrThrow()
    println("Wallet address: ${wallet.address}")
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    import CrossmintClient

    CrossmintSDK.configure(apiKey: "<YOUR_API_KEY>")
    let sdk = CrossmintSDK.shared

    let wallet = try await sdk.crossmintWallets.getWallet(
        chain: EVMChain.baseSepolia
    )
    ```
  </Tab>

  <Tab title="Flutter">
    ```dart theme={null}
    import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

    final controller = CrossmintWalletContext.of(context).requireWalletController;

    final wallet = await controller.getWallet(
      const CrossmintWalletLookupRequest(chain: 'base-sepolia'),
    );
    ```
  </Tab>

  <Tab title="REST">
    <CodeGroup>
      ```bash cURL theme={null}
      curl --request GET \
          --url https://staging.crossmint.com/api/2025-06-09/wallets/<wallet-locator> \
          --header 'X-API-KEY: <x-api-key>'
      ```

      ```js Node.js theme={null}
      const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/<wallet-locator>';

      const options = {
          method: 'GET',
          headers: {
              'X-API-KEY': '<x-api-key>'
          }
      };

      try {
          const response = await fetch(url, options);
          const data = await response.json();
          console.log(data);
      } catch (error) {
          console.error(error);
      }
      ```

      ```python Python theme={null}
      import requests

      url = "https://staging.crossmint.com/api/2025-06-09/wallets/<wallet-locator>"

      headers = {"X-API-KEY": "<x-api-key>"}

      response = requests.get(url, headers=headers)

      print(response.json())
      ```
    </CodeGroup>

    See the [API reference](/api-reference/wallets/get-wallet-by-locator) for more details.
  </Tab>
</Tabs>

## Get-or-Create Pattern

If you want to retrieve an existing wallet or create one if it does not exist, use `WalletNotAvailableError` to implement the pattern:

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet, WalletNotAvailableError } from '@crossmint/client-sdk-react-ui';

    const { getWallet, createWallet } = useWallet();

    let wallet;
    try {
        wallet = await getWallet({ chain: "base-sepolia" });
    } catch (error) {
        if (error instanceof WalletNotAvailableError) {
            wallet = await createWallet({
                chain: "base-sepolia",
                recoveryMethods: [
                    {
                        type: "email",
                        email: "user@example.com",
                    },
                ],
            });
        } else {
            throw error;
        }
    }
    ```
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import {
        CrossmintWallets,
        WalletNotAvailableError,
        createCrossmint,
    } from "@crossmint/wallets-sdk";

    const crossmint = createCrossmint({
        apiKey: "<your-server-api-key>",
    });

    const crossmintWallets = CrossmintWallets.from(crossmint);

    let wallet;
    try {
        wallet = await crossmintWallets.getWallet(
            "<wallet-address>",
            { chain: "base-sepolia" }
        );
        await wallet.useSigner({
            type: "server",
            secret: process.env.WALLET_SIGNER_SECRET!,
        });
    } catch (error) {
        if (error instanceof WalletNotAvailableError) {
            wallet = await crossmintWallets.createWallet({
                chain: "base-sepolia",
                recoveryMethods: [
                    {
                        type: "server",
                        secret: process.env.RECOVERY_SIGNER_SECRET,
                    },
                ],
                signers: [
                    {
                        type: "server",
                        secret: process.env.WALLET_SIGNER_SECRET,
                    },
                ],
            });
        } else {
            throw error;
        }
    }

    ```
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { useWallet, WalletNotAvailableError } from '@crossmint/client-sdk-react-native-ui';

    const { getWallet, createWallet } = useWallet();

    let wallet;
    try {
        wallet = await getWallet({ chain: "base-sepolia" });
    } catch (error) {
        if (error instanceof WalletNotAvailableError) {
            wallet = await createWallet({
                chain: "base-sepolia",
                recoveryMethods: [
                    {
                        type: "email",
                        email: "user@example.com",
                    },
                ],
            });
        } else {
            throw error;
        }
    }
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    import com.crossmint.kotlin.CrossmintSDK
    import com.crossmint.kotlin.types.EVMChain
    import com.crossmint.kotlin.signers.SignerType
    import com.crossmint.kotlin.types.Result
    import com.crossmint.kotlin.types.WalletError
    import com.crossmint.kotlin.types.getOrThrow

    CrossmintSDK.configure(apiKey = "YOUR_CROSSMINT_API_KEY")
    val sdk = CrossmintSDK.shared
    val wallet = when (val result = sdk.wallets.getWallet(chain = EVMChain.BaseSepolia)) {
        is Result.Success -> result.value
        is Result.Failure -> if (result.error is WalletError.WalletNotFound) {
            sdk.wallets.createWallet(
                chain = EVMChain.BaseSepolia,
                recoveryMethods = listOf(SignerType.Email("user@example.com"))
            ).getOrThrow()
        } else {
            throw Exception(result.error.toString())
        }
    }
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    import CrossmintClient

    CrossmintSDK.configure(apiKey: "<YOUR_API_KEY>")
    let sdk = CrossmintSDK.shared

    let wallet: EVMWallet
    if let existing = try await sdk.crossmintWallets.getWallet(
        chain: EVMChain.baseSepolia
    ) {
        wallet = existing
    } else {
        wallet = try await sdk.crossmintWallets.createWallet(
            chain: EVMChain.baseSepolia,
            recoveryMethods: [EVMSigners.email("user@example.com")]
        )
    }
    ```
  </Tab>

  <Tab title="Flutter">
    ```dart theme={null}
    import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

    final controller = CrossmintWalletContext.of(context).requireWalletController;

    // Controller.getWallet returns null when the wallet does not exist.
    var wallet = await controller.getWallet(
      const CrossmintWalletLookupRequest(chain: 'base-sepolia'),
    );
    wallet ??= await controller.createWallet(
      const CrossmintWalletCreateRequest(
        chain: 'base-sepolia',
        recovery: CrossmintEmailSignerConfig(email: 'user@example.com'),
      ),
    );
    ```
  </Tab>
</Tabs>

<Note>
  On client-side SDKs (React, React Native), if you use `CrossmintWalletProvider` with the `createOnLogin` prop, the wallet is created automatically when the user logs in — no manual `createWallet` call is needed.
</Note>

## Next Steps

<CardGroup>
  <Card title="Transfer tokens" icon="arrow-right-arrow-left" href="/wallets/guides/transfer-tokens">
    Send tokens between wallets
  </Card>

  <Card title="Add signers" icon="key" href="/wallets/guides/signers/add-signers">
    Register operational signers on your wallet
  </Card>

  <Card title="Fund your wallet" icon="coins" href="/wallets/guides/fund-staging-wallet">
    Get testnet tokens to start testing
  </Card>
</CardGroup>


# Export Private Key
Source: https://docs.crossmint.com/wallets/guides/export-private-key

Allow users to export private keys using email or phone signers

## Introduction

Exporting a private key allows users to extract the cryptographic key that controls their non-custodial wallet. This key can be imported into other wallet applications, enabling users to access their assets across different platforms.

The `ExportPrivateKeyButton` component provides a secure interface for users to export their private keys from wallets that use email or phone signers. Other signer types (passkey, external wallet, API key) do not expose private keys by design, so export does not apply to them.

<Warning>
  **Security Warning**: Exporting a private key is a sensitive operation that should be handled with extreme care. Anyone who obtains the private key has full control over the wallet and all its assets. Users should:

  * Never share their private key with anyone
  * Store exported keys securely in password managers or hardware wallets
  * Consider the security implications before exporting
</Warning>

### When to Export Private Keys

Users might need to export their private key in scenarios such as:

* Creating a backup of their wallet credentials
* Migrating to a different wallet provider
* Accessing their wallet through alternative interfaces

## Prerequisites

Before using the `ExportPrivateKeyButton` component, ensure:

* Your client-side API key has the **`wallets.export`** scope enabled. You can configure this in the <a href="https://www.crossmint.com/console/projects/apiKeys">Crossmint Console</a>
* The wallet is using an **email or phone signer type**
* The wallet has been successfully created and is accessible

## Implementation Examples

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { ExportPrivateKeyButton, useWallet } from '@crossmint/client-sdk-react-ui';

    function WalletSettings() {
        const { wallet } = useWallet();

        if (!wallet) {
            return <p>Loading wallet...</p>;
        }

        return (
            <div>
                <h2>Wallet Settings</h2>
                <p>Address: {wallet.address}</p>
                
                <ExportPrivateKeyButton />
            </div>
        );
    }
    ```

    See the [React SDK reference](/sdk-reference/wallets/react/components#exportprivatekeybutton) for more details.
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { ExportPrivateKeyButton, useWallet } from '@crossmint/client-sdk-react-native-ui';
    import { View, Text } from 'react-native';

    function WalletSettings() {
        const { wallet } = useWallet();

        if (!wallet) {
            return <Text>Loading wallet...</Text>;
        }

        return (
            <View>
                <Text>Wallet Settings</Text>
                <Text>Address: {wallet.address}</Text>
                
                <ExportPrivateKeyButton />
            </View>
        );
    }
    ```

    See the [React Native SDK reference](/sdk-reference/wallets/react-native/components#exportprivatekeybutton) for more details.
  </Tab>

  <Tab title="Flutter">
    ```dart theme={null}
    import 'package:flutter/material.dart';
    import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

    class WalletSettings extends StatelessWidget {
      const WalletSettings({super.key});

      @override
      Widget build(BuildContext context) {
        return CrossmintWalletStatusBuilder(
          builder: (context, data) {
            final wallet = data.state.currentWallet;
            if (wallet == null) {
              return const Text('Loading wallet...');
            }
            // Wrap the domain model in a runtime wallet so the export button
            // can inspect its signer type.
            final runtimeWallet = data.requireWalletController.createEvmWallet();
            return Column(
              children: [
                Text('Address: ${wallet.address}'),
                CrossmintExportPrivateKeyButton(wallet: runtimeWallet),
              ],
            );
          },
        );
      }
    }
    ```

    See the [Flutter SDK reference](/sdk-reference/wallets/flutter/widgets#crossmintexportprivatekeybutton) for more details.
  </Tab>
</Tabs>

## Webhook Notification

When a user exports a private key for the first time, Crossmint sends a `wallets.signer.exported` webhook event to your configured endpoint. This allows you to monitor export activity across your project wallets for compliance and alerting purposes.

The webhook is sent **once per wallet** — subsequent exports of the same wallet do not trigger additional events. The payload contains no private key material.

```json theme={null}
{
  "id": "evt_abc123",
  "type": "wallets.signer.exported",
  "data": {
    "owner": "email:user@example.com",
    "walletAddress": "0x0987654321098765432109876543210987654321",
    "chain": "evm",
    "signerType": "email"
  }
}
```

To receive this event, add a webhook endpoint in the <a href="https://www.crossmint.com/console/webhooks">Crossmint Console</a> and select the `wallets.signer.exported` event type. For the full event schema and setup details, see the [Wallet Webhooks](/wallets/guides/webhooks#signer-export-webhook) reference.

## Security Considerations

When exporting private keys, users should store them securely using password managers or hardware wallets. Anyone with access to a private key has full control over the associated wallet.

As a developer integrating this component, it is important to communicate these security implications clearly to your users. Consider displaying warnings or educational content before allowing users to export their private keys, ensuring they understand the risks and best practices for secure key storage.

## How It Works

The `ExportPrivateKeyButton` component uses a secure multi-step process to export private keys:

### 1. Signer Validation

The component first checks if the wallet uses an exportable signer type (email or phone). If the wallet uses a different signer type, the component renders nothing.

### 2. Secure Iframe/WebView Loading

The component loads a secure iframe (web) or WebView (mobile) from Crossmint's TEE infrastructure. This isolated environment ensures that the private key is never exposed to the host application.

### 3. TEE Communication Protocol

The component establishes a secure communication channel with the TEE using the handshake protocol:

* The parent application initiates a handshake with the secure iframe/WebView
* Authentication credentials (JWT and API key) are passed through the secure channel
* The TEE verifies the user's identity and authorization

### 4. Private Key Derivation

Inside the TEE, the private key is derived from the master secret:

* The master secret is reconstructed from the device share and auth share
* The private key is derived using HKDF (HMAC-based Key Derivation Function)
* Supported cryptographic schemes: **ed25519** (Solana, Stellar) and **secp256k1** (EVM chains)
* Supported encoding formats: **base58**, **hex**, and **strkey**

### 5. Clipboard Copy

When the user clicks the export button, the private key is:

* Formatted in the appropriate encoding for the blockchain
* Copied directly to the user's clipboard
* Never exposed to the host application or stored in memory outside the TEE

For more details on the TEE architecture, see the [Configure Recovery](/wallets/guides/recovery/configure-recovery) section in the Wallet Signers guide.

## Related Documentation

* [Wallet Webhooks](/wallets/guides/webhooks) - Webhook event reference for wallets including signer exports
* [Signers](/wallets/concepts/signers) - Learn about different signer types and custody models
* [Create Wallet](/wallets/guides/create-wallet) - Create wallets with email or phone signers
* [Bring Your Own Auth](/wallets/guides/bring-your-own-auth) - Integrate custom authentication systems
* [Wallets Quickstart](/wallets/quickstarts/react) - Get started with Crossmint Wallets


# Fund a Staging Wallet
Source: https://docs.crossmint.com/wallets/guides/fund-staging-wallet

Fund your staging wallets with testnet tokens using Crossmint's USDXM stablecoin

## What are testnet tokens?

Testnet tokens are tokens deployed on blockchain testnets for development and testing purposes. These tokens do not have real-world monetary value, allowing you to simulate onchain behavior—such as sending, receiving, and paying gas fees—without financial risk. You can use testnet tokens to validate your integration before moving to production.

Staging wallets live only on testnets, and their addresses do not carry over to production. See [Staging vs Production](/introduction/platform/staging-vs-production) for how the environments differ before you go live.

## What is USDXM?

USDXM is Crossmint's staging/testnet stablecoin, designed specifically for testing. Think about USDXM as the USDC of testnets. Crossmint has deployed the USDXM contract on all supported testnets making it easier for you to test tokens in staging.

USDXM is only available in staging environments and is not available in production.

## How to Fund Your Wallet

There are several options to fund your wallets on staging with USDXM

## Option 1: Fund with the SDK

The SDK is the easiest way to add USDXM to your wallet programmatically. Use `stagingFund` (React, React Native, Node.js) or `fund` (Kotlin, Swift, Flutter) depending on your platform. This method funds the wallet with USDXM only and is only available in staging environments.

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet } from '@crossmint/client-sdk-react-ui';

    const { wallet } = useWallet();

    const balances = await wallet.stagingFund(10);
    console.log("Wallet funded! New balances:", balances);
    ```

    See the [React SDK reference](/sdk-reference/wallets/react/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { useWallet } from '@crossmint/client-sdk-react-native-ui';

    const { wallet } = useWallet();

    const balances = await wallet.stagingFund(10);
    console.log("Wallet funded! New balances:", balances);
    ```

    See the [React Native SDK reference](/sdk-reference/wallets/react-native/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    import com.crossmint.kotlin.CrossmintSDK
    import com.crossmint.kotlin.types.EVMChain
    import com.crossmint.kotlin.types.getOrThrow

    CrossmintSDK.configure(apiKey = "YOUR_CROSSMINT_API_KEY")
    val sdk = CrossmintSDK.shared
    val wallet = sdk.wallets.getWallet(chain = EVMChain.BaseSepolia).getOrThrow()

    wallet.fund(token = "usdxm", amount = 10, chain = "base-sepolia").getOrThrow() // fund() takes chain as a string, not EVMChain
    println("Wallet funded!")
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    import CrossmintClient

    CrossmintSDK.configure(apiKey: "<YOUR_API_KEY>")
    let sdk = CrossmintSDK.shared

    guard let wallet = try await sdk.crossmintWallets.getWallet(
        chain: EVMChain.baseSepolia
    ) else {
        return
    }

    try await wallet.fund(token: .usdxm, amount: 10)
    print("Wallet funded!")
    ```
  </Tab>

  <Tab title="Flutter">
    ```dart theme={null}
    import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

    final controller = CrossmintWalletContext.of(context).requireWalletController;
    final wallet = controller.createEvmWallet();

    await wallet.fund(
      const CrossmintWalletFundRequest(
        amount: 10,
        token: 'usdxm',
        chain: 'base-sepolia',
      ),
    );
    ```

    See the [Flutter SDK reference](/sdk-reference/wallets/flutter/controllers#wallet-methods) for more details.
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";

    const crossmint = createCrossmint({
        apiKey: "<your-server-api-key>",
    });

    const crossmintWallets = CrossmintWallets.from(crossmint);

    const wallet = await crossmintWallets.getWallet(
        "<wallet-address>",
        { chain: "base-sepolia" }
    );
    await wallet.useSigner({
        type: "server",
        secret: process.env.WALLET_SIGNER_SECRET,
    });

    const balances = await wallet.stagingFund(10);
    console.log("Wallet funded! New balances:", balances);
    ```

    See the [SDK reference](/sdk-reference/wallets/typescript/classes/Wallet#stagingfund) for all parameters and return types.
  </Tab>
</Tabs>

## Option 2: Fund via API

You can also fund staging wallets directly using the HTTP API. This is useful for server-side integrations or when you need more control over the funding process.

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
      --url https://staging.crossmint.com/api/v1-alpha2/wallets/{walletLocator}/balances \
      --header 'Content-Type: application/json' \
      --header 'X-API-KEY: <x-api-key>' \
      --data '{
          "amount": 10,
          "token": "usdxm",
          "chain": "base-sepolia"
      }'
  ```

  ```js Node.js theme={null}
  const walletLocator = "email:user@example.com:evm";
  const url = `https://staging.crossmint.com/api/v1-alpha2/wallets/${walletLocator}/balances`;

  const payload = {
      amount: 10,
      token: "usdxm",
      chain: "base-sepolia"
  };

  const options = {
      method: 'POST',
      headers: {
          'X-API-KEY': '<x-api-key>',
          'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
  };

  try {
      const response = await fetch(url, options);
      const data = await response.json();
      console.log(data);
  } catch (error) {
      console.error(error);
  }
  ```

  ```python Python theme={null}
  import requests

  wallet_locator = "email:user@example.com:evm"
  url = f"https://staging.crossmint.com/api/v1-alpha2/wallets/{wallet_locator}/balances"

  payload = {
      "amount": 10,
      "token": "usdxm",
      "chain": "base-sepolia"
  }
  headers = {
      "X-API-KEY": "<x-api-key>",
      "Content-Type": "application/json"
  }

  response = requests.post(url, json=payload, headers=headers)

  print(response.json())
  ```
</CodeGroup>

### Request parameters

<ParamField type="string">
  The wallet to fund. Can be a wallet address or a locator like `email:user@example.com:evm`.
</ParamField>

<ParamField type="number">
  The amount of USDXM to add.
</ParamField>

<ParamField type="string">
  The token to fund with. Use `usdxm` for staging environments.
</ParamField>

<ParamField type="string">
  The chain to fund on (e.g., `base-sepolia`, `polygon-amoy`).
</ParamField>

### Getting your API key

You can get your staging API key from the [Crossmint Console](https://staging.crossmint.com). Navigate to your project settings and create an API key with the `wallets:balance.create` scope.

See the [API reference](/api-reference/wallets/fund-wallet) for more details.

## Option 3: Use the faucet web app

For quick manual testing without writing code, you can use Crossmint's hosted faucet web app to get staging tokens.

<Card title="USDXM Faucet" icon="faucet" href="https://usdc-faucet.vercel.app/">
  Get testnet USDXM tokens instantly through a simple web interface.
</Card>

To use the faucet:

1. Visit <a href="https://usdc-faucet.vercel.app/">[https://usdc-faucet.vercel.app/](https://usdc-faucet.vercel.app/)</a>
2. Enter your wallet address or connect your wallet
3. Select the chain you want to receive tokens on
4. Request tokens

<Note>The faucet is intended for development use only and may have rate limits to prevent abuse.</Note>

## When should I use which option?

| Option | Best for |
| - | - |
| **SDK (`stagingFund` / `fund`)** | Automated flows, integration tests, and when you are already using the Crossmint SDK |
| **API** | Server-side integrations, custom tooling, or when you need direct HTTP access |
| **Faucet web app** | Quick manual testing, getting started quickly, or when you do not want to write code |

## Related guides

<CardGroup>
  <Card title="Transfer Tokens" icon="arrow-right-arrow-left" href="/wallets/guides/transfer-tokens">
    Learn how to transfer tokens between wallets
  </Card>

  <Card title="Check Balances" icon="wallet" href="/wallets/guides/check-balances">
    Retrieve and manage wallet balances
  </Card>
</CardGroup>


# Cover Transaction Fees for Your Users
Source: https://docs.crossmint.com/wallets/guides/gas-sponsorship

Sponsor gas fees so users can transact without holding native tokens

Gas sponsorship lets you cover the transaction fees (gas) for your users' blockchain interactions. By removing the need for users to hold native tokens for gas, you can reduce friction and improve conversion rates for both human users and AI agents interacting with your application.

For Solana smart wallets, gas sponsorship is **enabled** by default in staging so you can test without holding tokens. For new production projects, it is **disabled** by default; transactions are paid by the executing wallet unless you enable project-sponsored fees. To enable project-sponsored fees in production, <a href="https://www.crossmint.com/contact/sales">contact Crossmint sales</a>.

<Note>This Console fee-payer setting applies only to Solana smart wallets.</Note>

Crossmint handles:

* Sponsoring the transaction fees on your behalf
* Maintaining a treasury to cover the gas costs
* Securely verifying and rate-limiting each transaction to prevent abuse
* Protecting against common attack vectors when sponsoring gas on chains like Solana
* Calculating optimal fees to ensure transactions land without overpaying

## Prerequisites

* A Crossmint project with wallets enabled
* Access to the <a href="https://www.crossmint.com/console">Crossmint Console</a>

## Change the Fee Payer

You can change the fee payer for Solana smart wallets in the Console.

<Steps>
  <Step title="Navigate to Wallets Settings">
    Open the <a href="https://www.crossmint.com/console">Crossmint Console</a> and go to **Wallets → Settings**.
  </Step>

  <Step title="Choose the Fee Payer">
    Select who pays transaction fees:

    * **You** — project-sponsored fees. Crossmint covers the gas with your project's credits and bills your project, so your users never have gas friction.
      <Snippet />
    * **Executing Wallet** — the wallet that performs the transaction pays the gas

    <Frame type="simple">
      <img alt="Gas Sponsorship Settings" />
    </Frame>
  </Step>
</Steps>

<Note>
  When the **Executing Wallet** is selected as the fee payer for Solana, you can choose whether it pays gas in SOL or USDC.

  <Frame type="simple">
    <img alt="Solana Payment Currency Options" />
  </Frame>
</Note>

## Set Spending Limits

<Note>
  Configuring per-user spending limits for gas sponsorship is available under private access. <a href="https://www.crossmint.com/contact/sales">Contact Crossmint</a> to enable this feature for your project.
</Note>

## Monitor Sponsored Transactions

You can track gas sponsorship usage and costs through the Crossmint Console and webhooks.

### View usage in the Console

The Crossmint Console provides an overview of your gas sponsorship usage, including total gas sponsored, number of transactions, and costs over time. Navigate to **Wallets → Settings** to view your current usage statistics.

### Track transactions with webhooks

For real-time monitoring, set up webhooks to receive notifications when transactions are sponsored. The `wallets.transfer.out` event includes information about the transaction and its gas costs.

```typescript theme={null}
// Partial type showing fields used in this example.
// See /wallets/guides/webhooks for the full schema.
type TransferWebhookEvent = {
    type: string;
    data: {
        status: string;
        recipient: { address: string };
        token: { amount: string; symbol: string };
        onChain: { explorerLink: string };
    };
};

async function processTransferEvent(
    event: TransferWebhookEvent
) {
    const { type, data } = event;

    if (
        type === "wallets.transfer.out" &&
        data.status === "succeeded"
    ) {
        console.log("Sponsored transaction completed:");
        console.log(`  To: ${data.recipient.address}`);
        console.log(`  Amount: ${data.token.amount} ${data.token.symbol}`);
        console.log(`  Explorer: ${data.onChain.explorerLink}`);
    }
}
```

For complete webhook setup instructions, see the [Transfer Webhooks Setup](/wallets/guides/webhooks) guide.

## Best Practices

* **Review the default fee payer before launch**: For Solana smart wallets, new production projects start with user-paid fees. Make sure the selected mode matches your user experience and budget.
* **Monitor usage regularly**: Keep track of your gas sponsorship costs to ensure they align with your budget
* **Set appropriate limits**: Once spending limits are enabled for your project, configure them based on your expected user behavior to prevent abuse
* **Use webhooks for real-time tracking**: Set up webhooks to monitor sponsored transactions and detect any unusual patterns

## Learn More

<CardGroup>
  <Card title="Transfer Webhooks Setup" icon="bell" href="/wallets/guides/webhooks">
    Set up real-time notifications for wallet transfers
  </Card>

  <Card title="Transfer Tokens" icon="paper-plane" href="/wallets/guides/transfer-tokens">
    Learn how to send tokens between wallets
  </Card>

  <Card title="Check Balances" icon="wallet" href="/wallets/guides/check-balances">
    Query token balances across your wallets
  </Card>

  <Card title="Webhooks Overview" icon="webhook" href="/introduction/platform/webhooks/overview">
    Learn about Crossmint webhooks
  </Card>
</CardGroup>


# List Wallet Transfers
Source: https://docs.crossmint.com/wallets/guides/list-transfers

Retrieve inbound and outbound transfer history for a wallet

<Warning>
  This is an **unstable API** that may change with time. The `unstable` prefix indicates that breaking changes may occur in future releases.
</Warning>

## Overview

The List Wallet Transfers API allows you to retrieve the transfer history for a wallet, including both inbound and outbound token transfers. This endpoint supports multiple blockchains and provides cursor-based pagination for efficient data retrieval.

## Prerequisites

* You have a wallet created.
* **API Key**: You have an API key with the scope: `wallets:transactions.read`. In staging, all scopes are included.

## Retrieving Wallet Transfers

<Tabs>
  <Tab title="EVM Chains">
    ### Get Ethereum Sepolia USDC Transfers

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request GET \
        --url 'https://staging.crossmint.com/api/unstable/wallets/WALLET_LOCATOR/transfers?chain=ethereum-sepolia&tokens=usdc&status=successful&limit=10' \
        --header 'X-API-KEY: YOUR_SERVER_API_KEY'
      ```

      ```javascript Node.js theme={null}
      const url = "https://staging.crossmint.com/api/unstable/wallets/WALLET_LOCATOR/transfers";
      const params = new URLSearchParams({
          chain: "ethereum-sepolia",
          tokens: "usdc",
          status: "successful",
          limit: "10"
      });

      const response = await fetch(`${url}?${params}`, {
          method: "GET",
          headers: {
              "X-API-KEY": "YOUR_SERVER_API_KEY"
          }
      });

      if (!response.ok) {
          throw new Error(`HTTP error: ${response.status}`);
      }

      const data = await response.json();
      console.log(data);
      ```

      ```python Python theme={null}
      import requests

      url = "https://staging.crossmint.com/api/unstable/wallets/WALLET_LOCATOR/transfers"
      params = {
          "chain": "ethereum-sepolia",
          "tokens": "usdc",
          "status": "successful",
          "limit": "10"
      }
      headers = {"X-API-KEY": "YOUR_SERVER_API_KEY"}

      response = requests.get(url, params=params, headers=headers)
      response.raise_for_status()
      data = response.json()
      print(data)
      ```
    </CodeGroup>

    ### Paginating Through Results

    When your wallet has a lot of transactions, results are split into pages. Use the `nextCursor` value from each response in your next API call to get the next page of results.

    <CodeGroup>
      ```javascript Node.js theme={null}
      async function getAllTransfers(walletLocator, chain, tokens) {
          const baseUrl = `https://staging.crossmint.com/api/unstable/wallets/${walletLocator}/transfers`;
          const allTransfers = [];
          let cursor = null;

          do {
              const params = new URLSearchParams({
                  chain,
                  tokens,
                  status: "successful",
                  limit: "30"
              });

              if (cursor) {
                  params.set("cursor", cursor);
              }

              const response = await fetch(`${baseUrl}?${params}`, {
                  headers: { "X-API-KEY": "YOUR_SERVER_API_KEY" }
              });

              if (!response.ok) {
                  throw new Error(`HTTP error: ${response.status}`);
              }

              const result = await response.json();
              allTransfers.push(...result.data);
              cursor = result.nextCursor;
          } while (cursor);

          return allTransfers;
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Solana">
    ### Get Solana USDC Transfers

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request GET \
        --url 'https://staging.crossmint.com/api/unstable/wallets/WALLET_LOCATOR/transfers?chain=solana&tokens=usdc&status=successful&limit=10' \
        --header 'X-API-KEY: YOUR_SERVER_API_KEY'
      ```

      ```javascript Node.js theme={null}
      const url = "https://staging.crossmint.com/api/unstable/wallets/WALLET_LOCATOR/transfers";
      const params = new URLSearchParams({
          chain: "solana",
          tokens: "usdc",
          status: "successful",
          limit: "10"
      });

      const response = await fetch(`${url}?${params}`, {
          method: "GET",
          headers: {
              "X-API-KEY": "YOUR_SERVER_API_KEY"
          }
      });

      if (!response.ok) {
          throw new Error(`HTTP error: ${response.status}`);
      }

      const data = await response.json();
      console.log(data);
      ```

      ```python Python theme={null}
      import requests

      url = "https://staging.crossmint.com/api/unstable/wallets/WALLET_LOCATOR/transfers"
      params = {
          "chain": "solana",
          "tokens": "usdc",
          "status": "successful",
          "limit": "10"
      }
      headers = {"X-API-KEY": "YOUR_SERVER_API_KEY"}

      response = requests.get(url, params=params, headers=headers)
      response.raise_for_status()
      data = response.json()
      print(data)
      ```
    </CodeGroup>

    ### Paginating Through Results

    When your wallet has a lot of transactions, results are split into pages. Use the `nextCursor` value from each response in your next API call to get the next page of results.

    <CodeGroup>
      ```javascript Node.js theme={null}
      async function getAllTransfers(walletLocator, chain, tokens) {
          const baseUrl = `https://staging.crossmint.com/api/unstable/wallets/${walletLocator}/transfers`;
          const allTransfers = [];
          let cursor = null;

          do {
              const params = new URLSearchParams({
                  chain,
                  tokens,
                  status: "successful",
                  limit: "30"
              });

              if (cursor) {
                  params.set("cursor", cursor);
              }

              const response = await fetch(`${baseUrl}?${params}`, {
                  headers: { "X-API-KEY": "YOUR_SERVER_API_KEY" }
              });

              if (!response.ok) {
                  throw new Error(`HTTP error: ${response.status}`);
              }

              const result = await response.json();
              allTransfers.push(...result.data);
              cursor = result.nextCursor;
          } while (cursor);

          return allTransfers;
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Stellar">
    ### Get Stellar USDC Transfers

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request GET \
        --url 'https://staging.crossmint.com/api/unstable/wallets/STELLAR_WALLET_ADDRESS/transfers?chain=stellar&tokens=usdc&status=successful' \
        --header 'X-API-KEY: YOUR_SERVER_API_KEY'
      ```

      ```javascript Node.js theme={null}
      const url = "https://staging.crossmint.com/api/unstable/wallets/STELLAR_WALLET_ADDRESS/transfers";
      const params = new URLSearchParams({
          chain: "stellar",
          tokens: "usdc",
          status: "successful"
      });

      const response = await fetch(`${url}?${params}`, {
          method: "GET",
          headers: {
              "X-API-KEY": "YOUR_SERVER_API_KEY"
          }
      });

      if (!response.ok) {
          throw new Error(`HTTP error: ${response.status}`);
      }

      const data = await response.json();
      console.log(data);
      ```
    </CodeGroup>

    ### Paginating Through Results

    When your wallet has a lot of transactions, results are split into pages. Use the `nextCursor` value from each response in your next API call to get the next page of results.

    <CodeGroup>
      ```javascript Node.js theme={null}
      async function getAllTransfers(walletLocator, chain, tokens) {
          const baseUrl = `https://staging.crossmint.com/api/unstable/wallets/${walletLocator}/transfers`;
          const allTransfers = [];
          let cursor = null;

          do {
              const params = new URLSearchParams({
                  chain,
                  tokens,
                  status: "successful",
                  limit: "30"
              });

              if (cursor) {
                  params.set("cursor", cursor);
              }

              const response = await fetch(`${baseUrl}?${params}`, {
                  headers: { "X-API-KEY": "YOUR_SERVER_API_KEY" }
              });

              if (!response.ok) {
                  throw new Error(`HTTP error: ${response.status}`);
              }

              const result = await response.json();
              allTransfers.push(...result.data);
              cursor = result.nextCursor;
          } while (cursor);

          return allTransfers;
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## API Reference

Two endpoints are available:

* `GET /unstable/wallets/{walletLocator}/transfers` — Server-side API key authentication
* `GET /unstable/wallets/me:walletLocator/transfers` — JWT authentication for the current user's wallet

You can also use the SDK to retrieve transfers. The `tokens` and `status` filters are optional.

```typescript theme={null}
const transfers = await wallet.transfers({ tokens: "usdc", status: "successful" });
```

See the [API reference](/api-reference/wallets/list-transfers) for full parameter details and to test requests in the playground.

## Important Notes

<AccordionGroup>
  <Accordion title="Chain Support">
    * **EVM chains**: Fully supported. Results are cached for 10 minutes to improve performance.
    * **Solana**: Supported. Includes native SOL and SPL token transfers (e.g., USDC). Results are cached for 10 minutes.
    * **Stellar**: Supported for all Soroban and SEP-41 tokens.
  </Accordion>

  <Accordion title="EVM Limitations">
    Outgoing native-token transfers (e.g., ETH, MATIC) initiated by a smart wallet are only tracked on Ethereum, Polygon, and Ethereum Sepolia. On other EVM chains, these specific transfers won't appear in the transfer history. This is unrelated to token support — ERC-20 transfers and incoming native-token transfers are tracked on every EVM chain; only outgoing smart-wallet-initiated native transfers are affected.
  </Accordion>

  <Accordion title="Pagination">
    * Uses cursor-based pagination for efficient data retrieval
    * Supports bidirectional pagination with `nextCursor` and `previousCursor`
    * The cursor encodes the sort order, so you don't need to re-specify it when paginating
    * Cached results expire after 10 minutes on EVM and Solana chains; refresh to load the latest data if the cursor expires
  </Accordion>

  <Accordion title="Timestamps">
    All timestamps are returned in ISO 8601 format (e.g., `2025-01-15T10:30:00.000Z`).
  </Accordion>

  <Accordion title="Transfer Types">
    The API returns both inbound (`wallets.transfer.in`) and outbound (`wallets.transfer.out`) transfers. Transfers initiated through Crossmint include a `transferId` that can be used with the [Get Transaction API](/api-reference/wallets/get-transaction).
  </Accordion>
</AccordionGroup>


# Migrate to V1
Source: https://docs.crossmint.com/wallets/guides/migrate-to-v1

Complete migration guide for existing clients — all breaking changes with before/after examples.

This guide covers every breaking change in the Wallets SDK V1 release. It is organized by audience — client-side (React / React Native, Swift, Kotlin), server-side (Node.js), and REST API — so you can jump to the section that applies to you.

<Note>
  V1 is a major release with breaking changes. Read through the relevant sections before upgrading your packages.
</Note>

## Terminology changes

V1 renames several concepts. Use this table as a find-and-replace checklist across your codebase.

| Old term | New term | Notes |
| - | - | - |
| `adminSigner` | Recovery method | Recovery methods are high-friction (OTP-based). They can also sign transactions when selected explicitly. |
| `delegatedSigner` | Signer (operational) | Day-to-day signers: device, passkey, server, external-wallet. |
| `getOrCreateWallet()` | `createWallet()` + `getWallet()` | Separate calls. `getWallet()` throws `WalletNotAvailableError` if no wallet exists. |
| `addDelegatedSigner()` | `addSigner()` | Signature also changed — accepts config objects, not just locator strings. |
| `experimental_activity()` | `transfers(params)` | Name and signature changed. `tokens` and `status` params are optional. |
| `experimental_` prefix | Removed | `experimental_prepareOnly` → `prepareOnly`, `experimental_signer` → `signer`, `experimental_approval` → `approval`, `experimental_nfts()` → `nfts()`, `experimental_transactions()` → `transactions()`, `experimental_transaction(id)` → `transaction(id)`. |
| `customAuth` / `experimental_setCustomAuth` | `setJwt()` | `setJwt(jwt)` replaces the old `experimental_setCustomAuth({ jwt, email, externalWalletSigner })`. |
| `useWalletEmailSigner` | `useWalletOtpSigner` | Now works for both email and phone OTP signers. |
| `createOnLogin.signer` | `createOnLogin.recoveryMethods` | The `signer` field in `createOnLogin` is now `recoveryMethods`, a list of recovery methods. |
| `createOnLogin.delegatedSigners` | `createOnLogin.signers` | Array of operational signers to register at wallet creation. |
| `Activity` type | `Transfers` type | Find-and-replace import. |

## Client-side migration (React / React Native)

### 1. Update packages

Update all `@crossmint` packages to V1 versions:

```bash theme={null}
npm install @crossmint/client-sdk-react-ui@latest @crossmint/wallets-sdk@latest
```

### 2. Update `createOnLogin` in your provider

The `signer` field is now `recoveryMethods` (a list, even for a single recovery method), and `delegatedSigners` is now `signers`.

<Snippet />

<CodeGroup>
  ```tsx Before theme={null}
  <CrossmintWalletProvider
    createOnLogin={{
      chain: "base-sepolia",
      signer: { type: "email" },
      delegatedSigners: [{ type: "passkey" }],
    }}
  >
    {/* ... */}
  </CrossmintWalletProvider>
  ```

  ```tsx After theme={null}
  <CrossmintWalletProvider
    createOnLogin={{
      chain: "base-sepolia",
      recoveryMethods: [{ type: "email" }],
      signers: [{ type: "passkey" }],
    }}
  >
    {/* ... */}
  </CrossmintWalletProvider>
  ```
</CodeGroup>

<Note>
  Device signers are now the default operational signer. If you do not specify `signers`, a device signer is created automatically.
</Note>

### 3. Replace `getOrCreateWallet` with `getWallet` + `createWallet`

`getOrCreateWallet` has been removed. Use `getWallet` to retrieve an existing wallet. If it throws `WalletNotAvailableError`, call `createWallet`.

<CodeGroup>
  ```tsx Before theme={null}
  import { useWallet } from "@crossmint/client-sdk-react-ui";

  const { getOrCreateWallet } = useWallet();

  const wallet = await getOrCreateWallet({
      signer: { type: "email", email: "user@example.com" },
  });
  ```

  ```tsx After theme={null}
  import { useWallet } from "@crossmint/client-sdk-react-ui";
  import { WalletNotAvailableError } from "@crossmint/wallets-sdk";

  const { getWallet, createWallet } = useWallet();

  try {
      const wallet = await getWallet({ chain: "base-sepolia" });
  } catch (error) {
      if (error instanceof WalletNotAvailableError) {
          const wallet = await createWallet({
              chain: "base-sepolia",
              recoveryMethods: [{ type: "email", email: "user@example.com" }], // Replace with user's email
          });
      }
  }
  ```
</CodeGroup>

### 4. Replace `customAuth` with `setJwt`

If you use a third-party auth provider (BYOA), replace `experimental_setCustomAuth` with `setJwt`.

<CodeGroup>
  ```tsx Before theme={null}
  const { experimental_setCustomAuth } = useCrossmint();

  useEffect(() => {
      experimental_setCustomAuth({ jwt, email, externalWalletSigner });
  }, [jwt]);
  ```

  ```tsx After theme={null}
  const { setJwt } = useCrossmint();

  useEffect(() => {
      setJwt(jwt);
  }, [jwt]);
  ```
</CodeGroup>

See the [Bring Your Own Auth](/wallets/guides/bring-your-own-auth) guide for complete setup instructions.

### 5. Remove `experimental_` prefixes

All `experimental_` prefixes have been removed from wallet methods and options.

<CodeGroup>
  ```tsx Before theme={null}
  // Methods
  const activity = await wallet.experimental_activity();
  const nfts = await wallet.experimental_nfts();
  const txs = await wallet.experimental_transactions();
  const tx = await wallet.experimental_transaction(txId);

  // Options
  await wallet.send(to, token, amount, {
      experimental_prepareOnly: true,
      experimental_signer: `external-wallet:${address}`,
  });

  await wallet.approve({
      transactionId,
      options: {
          experimental_approval: { signature, signer: locator },
      },
  });
  ```

  ```tsx After theme={null}
  // Methods
  const transfers = await wallet.transfers({ tokens: "usdc", status: "successful" });
  const nfts = await wallet.nfts();
  const txs = await wallet.transactions();
  const tx = await wallet.transaction(txId);

  // Options
  await wallet.send(to, token, amount, {
      prepareOnly: true,
      signer: `external-wallet:${address}`,
  });

  await wallet.approve({
      transactionId,
      options: {
          approval: { signature, signer: locator },
      },
  });
  ```
</CodeGroup>

### 6. Replace `useWalletEmailSigner` with `useWalletOtpSigner`

The `useWalletEmailSigner` hook has been replaced by `useWalletOtpSigner`, which works for both email and phone OTP flows.

<CodeGroup>
  ```tsx Before theme={null}
  import { useWalletEmailSigner } from "@crossmint/client-sdk-react-native-ui";

  const { needsAuth, sendOtp, verifyOtp, reject } = useWalletEmailSigner();
  ```

  ```tsx After theme={null}
  import { useWalletOtpSigner } from "@crossmint/client-sdk-react-native-ui";

  const { needsAuth, sendOtp, verifyOtp, reject } = useWalletOtpSigner();
  ```
</CodeGroup>

### 7. Replace `addDelegatedSigner` with `addSigner`

The method name and signature have changed. `addSigner` now accepts signer config objects in addition to locator strings.

<CodeGroup>
  ```tsx Before theme={null}
  await wallet.addDelegatedSigner({
      signer: "passkey:abc123",
  });
  ```

  ```tsx After theme={null}
  await wallet.addSigner({
      signer: { type: "passkey" },
  });
  ```
</CodeGroup>

### 8. Remove Farcaster and Dynamic login references

Farcaster sign-in and Dynamic wallet login have been removed entirely. If you used either, migrate to an alternative auth method.

* Remove `"farcaster"` from `loginMethods` in `CrossmintAuthProvider`.
* Remove `"web3"` from `loginMethods`.
* Remove any `FarcasterSignIn`, `Web3AuthFlow`, or `DynamicWalletProvider` imports.

### 9. Understand device signers

Device signers are a new signer type backed by the device's hardware security module (Secure Enclave on mobile, IndexedDB on web). They are the default operational signer — no OTP is required for day-to-day signing.

Key points:

* No code change is needed if you want the default device signer behavior.
* Call `wallet.needsRecovery()` to check if the device signer needs to be re-established (e.g. after the user switches devices).
* Call `wallet.recover()` to trigger recovery using the recovery method.

### 10. Use `useSigner()` for non-device signers

If you need to sign with a non-device signer (e.g. passkey, external wallet, server), call `wallet.useSigner()` first.

```tsx theme={null}
// Select a passkey signer for subsequent operations
wallet.useSigner({ type: "passkey" });

// Now send will use the passkey signer
await wallet.send(to, token, amount);
```

<Note>
  `useSigner()` only accepts signer config objects — locator strings (e.g. `"external-wallet:0x..."`) are no longer accepted.
</Note>

### 11. Update external wallet signer to use `onSign`

V1 replaces chain-specific signing props (`provider`, `viemAccount`, `onSignTransaction`, `onSignStellarTransaction`) with a single unified `onSign` callback. When **using** an external-wallet signer (via `useSigner`), both `address` and `onSign` are required.

<CodeGroup>
  ```tsx Before theme={null}
  const wallet = await wallets.getOrCreateWallet("<user-email>", {
      chain: "base-sepolia",
      signer: { type: "email", email: "user@example.com" },
      delegatedSigners: [{
          type: "external-wallet",
          address: "0xABC",
          provider: window.ethereum,
          // or: viemAccount, onSignTransaction (Solana), onSignStellarTransaction (Stellar)
      }],
  });
  ```

  ```tsx After theme={null}
  // Register the signer (address only — no onSign needed)
  const wallet = await wallets.createWallet({
      chain: "base-sepolia",
      recoveryMethods: [{ type: "email", email: "user@example.com" }], // Replace with user's email
      signers: [
          { type: "external-wallet", address: "0xABC" },
      ],
  });

  // Use the signer (onSign is required for signing operations)
  wallet.useSigner({
      type: "external-wallet",
      address: "0xABC",
      onSign: async (payload) => {
          return await myWallet.sign(payload);
      },
  });
  ```
</CodeGroup>

<Note>
  **Registration vs. usage**: When registering an external-wallet signer (in `createWallet({ signers: [...] })` or `addSigner()`), only `address` is needed — no `onSign`. The `onSign` callback is only required when actively signing via `useSigner()`.
</Note>

## Client-side migration (Swift)

### 1. Update the SDK version

In Xcode, go to your package dependency for `crossmint-swift-sdk` and update the version requirement:

<CodeGroup>
  ```text Before theme={null}
  Up to Next Major Version: 0.10.2
  ```

  ```text After theme={null}
  Up to Next Major Version: 1.0.0
  ```
</CodeGroup>

### 2. Replace `getOrCreateWallet` with `getWallet` + `createWallet`

`getOrCreateWallet` has been removed. Use `getWallet` to retrieve an existing wallet. If it returns `nil`, call `createWallet`. The `signer` parameter is now `recoveryMethods` (a list, even for a single recovery method).

<CodeGroup>
  ```swift Before theme={null}
  let wallet = try await sdk.crossmintWallets.getOrCreateWallet(
      chain: EVMChain.baseSepolia,
      signer: EVMSigners.email(email)
  )
  ```

  ```swift After theme={null}
  let wallet: Wallet
  if let existing = try await sdk.crossmintWallets.getWallet(chain: EVMChain.baseSepolia) {
      wallet = existing
  } else {
      wallet = try await sdk.crossmintWallets.createWallet(
          chain: EVMChain.baseSepolia,
          recoveryMethods: [EVMSigners.email(email)]
      )
  }
  ```
</CodeGroup>

### 3. Update OTP authentication

The single `otpAuthentication()` method has been replaced with two explicit steps: `sendEmailOtp` and `confirmEmailOtp`.

<CodeGroup>
  ```swift Before theme={null}
  // Send OTP (code: nil triggers the send)
  try await crossmintAuthManager.otpAuthentication(email: email, code: nil)

  // Verify OTP
  try await crossmintAuthManager.otpAuthentication(email: email, code: otpCode)
  ```

  ```swift After theme={null}
  // Step 1: Send OTP
  try await crossmintAuthManager.sendEmailOtp(email: email)

  // Step 2: Verify OTP
  let status = try await crossmintAuthManager.confirmEmailOtp(
      email: email,
      code: otpCode
  )
  if case .authenticationStatus(.authenticated) = status {
      // User is authenticated, proceed to create wallet
  }
  ```
</CodeGroup>

### 4. Understand device signers

Device signers are a new signer type backed by the device's hardware security module (Secure Enclave). They are the default operational signer — no OTP is required for day-to-day signing.

Key points:

* No code change is needed if you want the default device signer behavior.
* Opt in explicitly via `WalletOptions(deviceSigner: true)` if you need to control it.
* Call `wallet.needsRecovery()` to check if the device signer needs to be re-established (e.g. after the user reinstalls the app or switches devices).
* Call `wallet.recover()` to trigger recovery using the recovery method.

### 5. Add and manage signers

Signer management is available on `Wallet`.

```swift theme={null}
// Add a signer
try await wallet.addSigner(SignerConfig.passkey)

// Switch to a specific signer for subsequent operations
try await wallet.useSigner(SignerConfig.passkey)

// Check and trigger recovery if needed
let needsRecovery = await wallet.needsRecovery()
if needsRecovery {
    try await wallet.recover()
}
```

### 6. Update `ApiKeySigner` initialization

`ApiKeySigner` no longer provides a default `ApiKeySignerData` — you must pass one explicitly.

<CodeGroup>
  ```swift Before theme={null}
  let signer = ApiKeySigner()
  ```

  ```swift After theme={null}
  let signer = ApiKeySigner(adminSigner: ApiKeySignerData())
  ```
</CodeGroup>

### 7. Replace the deprecated `Signers` enum

The `Signers` enum is deprecated. Use `EVMSigners` or `SolanaSigners` for type-safe chain compatibility.

<CodeGroup>
  ```swift Before theme={null}
  let signer = Signers.email(email)
  ```

  ```swift After theme={null}
  let signer = EVMSigners.email(email)     // for EVM chains
  // or
  let signer = SolanaSigners.email(email) // for Solana
  ```
</CodeGroup>

## Client-side migration (Kotlin)

### 1. Update the SDK version

Update the version in your `libs.versions.toml` or `build.gradle.kts`:

<CodeGroup>
  ```toml Before theme={null}
  [versions]
  crossmint-sdk = "0.0.16" # or your current pre-1.0.0 version
  ```

  ```toml After theme={null}
  [versions]
  crossmint-sdk = "1.0.1"
  ```
</CodeGroup>

### 2. Replace `getOrCreateWallet` with `getWallet` + `createWallet`

`getOrCreateWallet` has been removed. Use `getWallet` to retrieve an existing wallet. If it returns a failure, call `createWallet`. The `signer` parameter is now `recoveryMethods` (a list, even for a single recovery method).

<CodeGroup>
  ```kotlin Before theme={null}
  when (val result = crossmintWallets.getOrCreateWallet(
      chain = EVMChain.BaseSepolia,
      signer = SignerType.Email(email)
  )) {
      is Result.Success -> { val wallet = result.value }
      is Result.Failure -> { /* handle error */ }
  }
  ```

  ```kotlin After theme={null}
  val wallet = when (val getResult = crossmintWallets.getWallet(EVMChain.BaseSepolia)) {
      is Result.Success -> getResult.value
      is Result.Failure -> {
          when (val createResult = crossmintWallets.createWallet(
              chain = EVMChain.BaseSepolia,
              recoveryMethods = listOf(SignerType.Email(email))
          )) {
              is Result.Success -> createResult.value
              is Result.Failure -> return // handle error
          }
      }
  }
  ```
</CodeGroup>

### 3. Understand device signers

Device signers are a new signer type backed by the device's hardware security module (Android Keystore). They are the default operational signer — no OTP is required for day-to-day signing.

Key points:

* No code change is needed if you want the default device signer behavior.
* Call `wallet.needsRecovery()` to check if the device signer needs to be re-established (e.g. after the user reinstalls the app or switches devices).
* Call `wallet.recover()` to trigger recovery using the recovery method.

### 4. Add and manage signers

Signer management is a first-class API on `Wallet`.

```kotlin theme={null}
// Add a signer
wallet.addSigner(DelegatedSigner.Passkey)

// Switch to a specific signer for subsequent operations
wallet.useSigner(DelegatedSigner.Passkey)

// Remove a signer
wallet.removeSigner(DelegatedSigner.Passkey)

// Check and trigger recovery if needed
if (wallet.needsRecovery()) {
    wallet.recover()
}
```

### 5. Use `SignerSelection` in `send` and `approve`

`send()` and `approve()` now accept an optional `signer: SignerSelection` parameter. It defaults to `SignerSelection.Admin` (the recovery method), so existing call sites without the parameter continue to work. Pass `SignerSelection.Delegated(...)` to sign with an operational signer.

```kotlin theme={null}
when (val sendResult = wallet.send(
    recipient,
    tokenLocator,
    amount,
    signer = SignerSelection.Delegated(delegatedSignerData)
)) {
    is Result.Success -> { /* proceed to approve */ }
    is Result.Failure -> { /* handle error */ }
}
```

### 6. Check balances and list transfers

`balances()`, `fund()`, and `listTransfers()` are available directly on `Wallet`.

```kotlin theme={null}
// Check balances
when (val result = wallet.balances()) {
    is Result.Success -> {
        println("ETH: ${result.value.nativeToken.amount}")
        println("USDC: ${result.value.usdc.amount}")
    }
    is Result.Failure -> { /* handle */ }
}

// List transfers
when (val result = wallet.listTransfers(emptyList())) {
    is Result.Success -> { val transfers = result.value.transfers }
    is Result.Failure -> { /* handle */ }
}
```

## Server-side migration (Node.js)

<Warning>
  **`owner` field behavior:**

  * **Client-side**: `owner` must NOT be provided — it is automatically derived from the JWT. The client-side types (`ClientSideWalletArgsFor`, `ClientSideWalletCreateArgs`) omit it entirely.
  * **Server-side with email/phone signers**: `owner` is **required** — must be manually set.
  * **Server-side with any other signer** (device, passkey, API key, external wallet, server signer): `owner` is **optional**.
</Warning>

### 1. Update packages

```bash theme={null}
npm install @crossmint/wallets-sdk@latest
```

### 2. Replace `getOrCreateWallet` with `createWallet` / `getWallet`

<CodeGroup>
  ```typescript Before theme={null}
  import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";

  const crossmint = createCrossmint({ apiKey: "<server-api-key>" });
  const wallets = CrossmintWallets.from(crossmint);

  const wallet = await wallets.getOrCreateWallet("<user-email>", {
      chain: "base-sepolia",
      signer: { type: "email", email: "user@example.com" },
  });
  ```

  ```typescript After theme={null}
  import { CrossmintWallets, createCrossmint, WalletNotAvailableError } from "@crossmint/wallets-sdk";

  const USER_EMAIL = "user@example.com"; // Replace with actual user email
  const crossmint = createCrossmint({ apiKey: "<server-api-key>" });
  const wallets = CrossmintWallets.from(crossmint);

  let wallet;
  try {
      wallet = await wallets.getWallet(`email:${USER_EMAIL}`, { chain: "base-sepolia" });
  } catch (error) {
      if (error instanceof WalletNotAvailableError) {
          wallet = await wallets.createWallet({
              chain: "base-sepolia",
              owner: `email:${USER_EMAIL}`,
              recoveryMethods: [{ type: "email", email: USER_EMAIL }],
          });
      }
  }
  ```
</CodeGroup>

### 3. Update signer configuration

The old `signer` field (admin signer) is now `recoveryMethods` (a list, even for a single recovery method), and `delegatedSigners` is now `signers`. The legacy admin signer term refers to the recovery method.

<Snippet />

<CodeGroup>
  ```typescript Before theme={null}
  const wallet = await wallets.getOrCreateWallet("<user-email>", {
      chain: "base-sepolia",
      signer: { type: "email", email: "user@example.com" },
      delegatedSigners: [
          { type: "external-wallet", address: "0x..." },
      ],
  });
  ```

  ```typescript After theme={null}
  const USER_EMAIL = "user@example.com"; // Replace with actual user email
  const wallet = await wallets.createWallet({
      chain: "base-sepolia",
      owner: `email:${USER_EMAIL}`,
      recoveryMethods: [{ type: "email", email: USER_EMAIL }],
      signers: [
          { type: "external-wallet", address: "0x..." },
      ],
  });
  ```
</CodeGroup>

### 4. Migrate from API key signer to server signer

If you were using the API key as a signer for server-side operations, migrate to the new server signer. Server signers use deterministic key derivation from a secret you control.

<CodeGroup>
  ```typescript Before theme={null}
  // API key signer was implicit — the server API key was used to sign
  const wallet = await wallets.getOrCreateWallet("<user-email>", {
      chain: "base-sepolia",
      signer: { type: "email", email: "user@example.com" },
  });

  // Transactions were signed with the API key automatically
  await wallet.send(to, token, amount);
  ```

  ```typescript After theme={null}
  import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";

  const USER_EMAIL = "user@example.com"; // Replace with actual user email
  // SERVER_SIGNER_SECRET: your server signer secret (set in environment variables)
  const crossmint = createCrossmint({ apiKey: "<server-api-key>" });
  const wallets = CrossmintWallets.from(crossmint);

  const wallet = await wallets.createWallet({
      chain: "base-sepolia",
      owner: `email:${USER_EMAIL}`,
      recoveryMethods: [{ type: "email", email: USER_EMAIL }],
      signers: [
          { type: "server", secret: process.env.SERVER_SIGNER_SECRET! },
      ],
  });

  // Select the server signer for signing
  wallet.useSigner({ type: "server", secret: process.env.SERVER_SIGNER_SECRET! });

  await wallet.send(to, token, amount);
  ```
</CodeGroup>

<Warning>
  Store your server signer secret securely. The same secret always derives the same key, so losing it means losing signing access. Crossmint never has access to your secret.
</Warning>

### 5. Remove `experimental_` prefixes

Same as client-side — remove all `experimental_` prefixes from method names and option fields.

## REST API migration

The REST API changes in V1 are additive — there are no breaking changes to existing endpoints. The main addition is **server signer support**.

### Switch to the `2025-06-09` API version

Server signers require the `2025-06-09` API version. Update your base URL:

```
https://staging.crossmint.com/api/2025-06-09/wallets/...
```

### Create a wallet with a server signer

Previously, server-managed signing used the `external-wallet` type. V1 introduces a dedicated `server` signer type.

<CodeGroup>
  ```bash Before theme={null}
  curl -X POST https://staging.crossmint.com/api/2025-06-09/wallets \
    -H "Content-Type: application/json" \
    -H "X-API-KEY: YOUR_SERVER_API_KEY" \
    -d '{
      "type": "evm-smart-wallet",
      "config": {
        "adminSigner": {
          "type": "evm-keypair",
          "address": "ADMIN_WALLET_ADDRESS"
        },
        "delegatedSigners": [
          { "type": "external-wallet", "address": "EXTERNAL_WALLET_ADDRESS" }
        ]
      }
    }'
  ```

  ```bash After theme={null}
  curl -X POST https://staging.crossmint.com/api/2025-06-09/wallets \
    -H "Content-Type: application/json" \
    -H "X-API-KEY: YOUR_SERVER_API_KEY" \
    -d '{
      "chainType": "evm",
      "type": "smart",
      "config": {
        "recoveryMethods": [
          {
            "type": "server",
            "address": "SERVER_SIGNER_ADDRESS"
          }
        ],
        "delegatedSigners": [
          { "type": "server", "address": "SERVER_SIGNER_ADDRESS" }
        ]
      }
    }'
  ```
</CodeGroup>

<Note>
  The REST API accepts `address` (not `secret`) for server signers. Derive the address from your secret in your backend before passing it to the API.
</Note>

### Submit approvals with a server signer

Use the `server:<address>` locator format when submitting approvals.

<CodeGroup>
  ```bash Before theme={null}
  curl -X POST https://staging.crossmint.com/api/2025-06-09/wallets/<WALLET_LOCATOR>/transactions/<TRANSACTION_ID>/approvals \
    -H "Content-Type: application/json" \
    -H "X-API-KEY: YOUR_SERVER_API_KEY" \
    -d '{
      "approvals": [{
        "signer": "external-wallet:EXTERNAL_WALLET_ADDRESS",
        "signature": "TX_SIGNATURE"
      }]
    }'
  ```

  ```bash After theme={null}
  curl -X POST https://staging.crossmint.com/api/2025-06-09/wallets/<WALLET_LOCATOR>/transactions/<TRANSACTION_ID>/approvals \
    -H "Content-Type: application/json" \
    -H "X-API-KEY: YOUR_SERVER_API_KEY" \
    -d '{
      "approvals": [{
        "signer": "server:SERVER_SIGNER_ADDRESS",
        "signature": "TX_SIGNATURE"
      }]
    }'
  ```
</CodeGroup>

### REST ↔ SDK signer type mapping

Use this table to map between REST API signer types and SDK signer config objects.

| REST API signer type | REST locator format | SDK signer config |
| - | - | - |
| `evm-keypair` / `solana-keypair` | `external-wallet:<address>` | `{ type: "external-wallet", address }` |
| `server` | `server:<address>` | `{ type: "server", secret: "..." }` |
| `evm-passkey` | `passkey:<credentialId>` | `{ type: "passkey" }` |
| N/A (client-only) | `device:<publicKey>` | `{ type: "device" }` |
| `evm-email-otp` | `email:<email>` | `{ type: "email", email: "..." }` |
| `evm-phone-otp` | `phone:<number>` | `{ type: "phone", phone: "..." }` |

## Checklist

Use this checklist to verify your migration is complete:

* [ ] Updated all `@crossmint` packages to V1 versions
* [ ] Replaced `getOrCreateWallet` with `createWallet` / `getWallet`
* [ ] **(Android)** Updated SDK to `1.0.1`
* [ ] **(Android/iOS)** Replaced `getOrCreateWallet` with `createWallet` / `getWallet`, renamed `signer` → `recoveryMethods`
* [ ] **(iOS)** Replaced `otpAuthentication` with `sendEmailOtp` + `confirmEmailOtp`
* [ ] **(iOS)** Updated `ApiKeySigner` initialization — no longer has a default parameter
* [ ] **(iOS)** Replaced deprecated `Signers` enum with `EVMSigners` / `SolanaSigners`
* [ ] Updated `createOnLogin`: `signer` → `recoveryMethods`, `delegatedSigners` → `signers`
* [ ] Replaced `experimental_setCustomAuth` with `setJwt` (if using BYOA)
* [ ] Removed all `experimental_` prefixes from methods and options
* [ ] Replaced `useWalletEmailSigner` with `useWalletOtpSigner`
* [ ] Replaced `addDelegatedSigner` with `addSigner`
* [ ] Removed Farcaster / Dynamic login references (if applicable)
* [ ] Updated REST API calls to use `server` signer type (if applicable)
* [ ] Searched codebase for old terms: `adminSigner`, `getOrCreateWallet`, `delegatedSigner`, `experimental_`

## Next steps

<CardGroup>
  <Card title="Troubleshooting" icon="triangle-exclamation" href="/wallets/guides/troubleshooting">
    Handle WalletNotAvailableError and other common errors
  </Card>

  <Card title="Add a signer" icon="key" href="/wallets/guides/signers/add-signers">
    Register operational signers on your wallet
  </Card>
</CardGroup>


# Configure Wallet Recovery
Source: https://docs.crossmint.com/wallets/guides/recovery/configure-recovery

Configure recovery methods so users can regain wallet access from a new device.

A recovery method lets users regain access to their wallet when their operational (device) signer is no longer available — for example, when they switch to a new phone or clear their browser data. The recovery method authorizes the enrollment of a new device signer on the new device.

You can choose from email OTP, SMS OTP, or a server signer depending on your application's needs, and a wallet can have [more than one recovery method](#multiple-recovery-methods). This guide covers setting recovery methods when the wallet is created.

<Snippet />

## Prerequisites

* A Crossmint API key with `wallets.create` scope
* For email OTP: the user's email address
* For SMS OTP: the user's phone number in E.164 format (e.g., `+1234567890`)
* For server signer: a [signer secret](/wallets/guides/signers/server-signer#generate-a-signer-secret) stored on your server

## Email OTP Recovery Method

The user verifies ownership of their email address via a one-time password sent by Crossmint. This is the most common recovery method for consumer applications.

<Tabs>
  <Tab title="React">
    Using `createOnLogin` on the provider (recommended):

    ```tsx theme={null}
    import {
        CrossmintProvider,
        CrossmintAuthProvider,
        CrossmintWalletProvider,
    } from "@crossmint/client-sdk-react-ui";

    function App({ children }) {
        return (
            <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
                <CrossmintAuthProvider
                    loginMethods={["email", "google"]}
                >
                    <CrossmintWalletProvider
                        createOnLogin={{
                            chain: "base-sepolia",
                            recoveryMethods: [{ type: "email" }],
                        }}
                    >
                        {children}
                    </CrossmintWalletProvider>
                </CrossmintAuthProvider>
            </CrossmintProvider>
        );
    }
    ```

    Or using `createWallet` directly:

    ```typescript theme={null}
    import { useWallet } from "@crossmint/client-sdk-react-ui";

    const { createWallet } = useWallet();

    const wallet = await createWallet({
        chain: "base-sepolia",
        recoveryMethods: [
            {
                type: "email",
                email: "user@example.com", // Omit when using CrossmintAuthProvider (auto-populated)
            },
        ],
    });
    ```
  </Tab>

  <Tab title="Node.js">
    ```ts theme={null}
    import {
        createCrossmint,
        CrossmintWallets,
    } from "@crossmint/wallets-sdk";

    const crossmint = createCrossmint({
        apiKey: "YOUR_SERVER_API_KEY",
    });
    const crossmintWallets = CrossmintWallets.from(crossmint);

    try {
        const wallet = await crossmintWallets.createWallet({
            chain: "base-sepolia",
            owner: "email:user@example.com",
            recoveryMethods: [
                {
                    type: "email",
                    email: "user@example.com",
                },
            ],
        });
    } catch (error) {
        console.error("Failed to create wallet:", error);
    }
    ```
  </Tab>

  <Tab title="React Native">
    ```tsx theme={null}
    import {
        CrossmintProvider,
        CrossmintAuthProvider,
        CrossmintWalletProvider,
    } from "@crossmint/client-sdk-react-native-ui";

    function App({ children }) {
        return (
            <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
                <CrossmintAuthProvider
                    loginMethods={["email", "google"]}
                >
                    <CrossmintWalletProvider
                        createOnLogin={{
                            chain: "base-sepolia",
                            recoveryMethods: [{ type: "email" }],
                        }}
                    >
                        {children}
                    </CrossmintWalletProvider>
                </CrossmintAuthProvider>
            </CrossmintProvider>
        );
    }
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    import CrossmintClient

    let sdk = CrossmintSDK.shared

    let wallet = try await sdk.crossmintWallets.createWallet(
        chain: EVMChain.baseSepolia,
        recoveryMethods: [EVMSigners.email("user@example.com")]
    )
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    import com.crossmint.kotlin.CrossmintSDK
    import com.crossmint.kotlin.types.EVMChain
    import com.crossmint.kotlin.signers.SignerType

    val sdk = CrossmintSDK.shared
    val result = sdk.wallets.createWallet(
        chain = EVMChain.BaseSepolia,
        recoveryMethods = listOf(SignerType.Email("user@example.com"))
    )
    val wallet = result.getOrThrow()
    ```
  </Tab>

  <Tab title="Flutter">
    ```dart theme={null}
    import 'package:flutter/material.dart';
    import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

    class MyApp extends StatelessWidget {
      const MyApp({super.key});

      @override
      Widget build(BuildContext context) {
        return MaterialApp(
          home: CrossmintWalletProvider(
            config: CrossmintWalletProviderConfig(
              clientConfig: const CrossmintClientConfig(
                apiKey: 'YOUR_CLIENT_API_KEY',
                appScheme: 'myapp',
              ),
              walletControllerConfig: const CrossmintWalletControllerConfig(
                createOnLogin: CrossmintCreateOnLoginConfig(
                  chain: 'base-sepolia',
                  recovery: CrossmintEmailSignerConfig(),
                ),
              ),
              otpPromptBuilder: crossmintDefaultOtpPromptBuilder,
            ),
            child: const HomeScreen(),
          ),
        );
      }
    }
    ```

    When `CrossmintEmailSignerConfig()` is used with `createOnLogin`, the email is
    auto-populated from the authenticated user.
  </Tab>

  <Tab title="REST">
    <CodeGroup>
      ```bash cURL theme={null}
      curl --request POST \
          --url https://staging.crossmint.com/api/2025-06-09/wallets \
          --header 'Content-Type: application/json' \
          --header 'X-API-KEY: YOUR_SERVER_API_KEY' \
          --data '{
              "chainType": "evm",
              "owner": "email:user@example.com",
              "config": {
                  "recoveryMethods": [
                      {
                          "type": "email",
                          "email": "user@example.com"
                      }
                  ]
              }
          }'
      ```

      ```js Node.js theme={null}
      const url =
          "https://staging.crossmint.com/api/2025-06-09/wallets";

      const payload = {
          chainType: "evm",
          owner: "email:user@example.com",
          config: {
              recoveryMethods: [
                  {
                      type: "email",
                      email: "user@example.com",
                  },
              ],
          },
      };

      const response = await fetch(url, {
          method: "POST",
          headers: {
              "X-API-KEY": "YOUR_SERVER_API_KEY",
              "Content-Type": "application/json",
          },
          body: JSON.stringify(payload),
      });

      const data = await response.json();
      console.log(data);
      ```

      ```python Python theme={null}
      import requests

      url = "https://staging.crossmint.com/api/2025-06-09/wallets"

      payload = {
          "chainType": "evm",
          "owner": "email:user@example.com",
          "config": {
              "recoveryMethods": [
                  {
                      "type": "email",
                      "email": "user@example.com"
                  }
              ]
          }
      }
      headers = {
          "X-API-KEY": "YOUR_SERVER_API_KEY",
          "Content-Type": "application/json"
      }

      response = requests.post(url, json=payload, headers=headers)
      print(response.json())
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## SMS OTP Recovery Method

The user verifies ownership of their phone number via a one-time password delivered by SMS (or optionally WhatsApp). This is ideal for mobile-first applications.

By default, OTPs are sent via SMS. Set `channel: "whatsapp"` in the phone signer config to deliver the OTP through WhatsApp instead.

<Note>
  WhatsApp delivery is not supported in Brazil, Mexico, India, or Indonesia. Phone numbers in those countries receive the OTP over SMS even when `channel: "whatsapp"` is set.
</Note>

<Tabs>
  <Tab title="React">
    Using `createOnLogin` on the provider:

    ```tsx theme={null}
    import {
        CrossmintProvider,
        CrossmintAuthProvider,
        CrossmintWalletProvider,
    } from "@crossmint/client-sdk-react-ui";

    function App({ children }) {
        return (
            <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
                <CrossmintAuthProvider
                    loginMethods={["email", "google"]}
                >
                    <CrossmintWalletProvider
                        createOnLogin={{
                            chain: "base-sepolia",
                            recoveryMethods: [
                                {
                                    type: "phone",
                                    phone: "+1234567890",
                                    channel: "whatsapp",
                                },
                            ],
                        }}
                    >
                        {children}
                    </CrossmintWalletProvider>
                </CrossmintAuthProvider>
            </CrossmintProvider>
        );
    }
    ```

    Or using `createWallet` directly:

    ```typescript theme={null}
    import { useWallet } from "@crossmint/client-sdk-react-ui";

    const { createWallet } = useWallet();

    const wallet = await createWallet({
        chain: "base-sepolia",
        recoveryMethods: [
            {
                type: "phone",
                phone: "+1234567890", // E.164 format required
                channel: "whatsapp",
            },
        ],
    });
    ```
  </Tab>

  <Tab title="Node.js">
    ```ts theme={null}
    import {
        createCrossmint,
        CrossmintWallets,
    } from "@crossmint/wallets-sdk";

    const crossmint = createCrossmint({
        apiKey: "YOUR_SERVER_API_KEY",
    });
    const crossmintWallets = CrossmintWallets.from(crossmint);

    try {
        const wallet = await crossmintWallets.createWallet({
            chain: "base-sepolia",
            owner: "phone:+12223334444",
            recoveryMethods: [
                {
                    type: "phone",
                    phone: "+12223334444", // E.164 format required
                    channel: "whatsapp",
                },
            ],
        });
    } catch (error) {
        console.error("Failed to create wallet:", error);
    }
    ```
  </Tab>

  <Tab title="React Native">
    ```tsx theme={null}
    import {
        CrossmintProvider,
        CrossmintAuthProvider,
        CrossmintWalletProvider,
    } from "@crossmint/client-sdk-react-native-ui";

    function App({ children }) {
        return (
            <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
                <CrossmintAuthProvider
                    loginMethods={["email", "google"]}
                >
                    <CrossmintWalletProvider
                        createOnLogin={{
                            chain: "base-sepolia",
                            recoveryMethods: [
                                {
                                    type: "phone",
                                    phone: "+1234567890",
                                    channel: "whatsapp",
                                },
                            ],
                        }}
                    >
                        {children}
                    </CrossmintWalletProvider>
                </CrossmintAuthProvider>
            </CrossmintProvider>
        );
    }
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    import CrossmintClient

    let sdk = CrossmintSDK.shared

    let wallet = try await sdk.crossmintWallets.createWallet(
        chain: EVMChain.baseSepolia,
        recoveryMethods: [EVMSigners.phone("+1234567890", channel: .whatsapp)]
    )
    ```

    Phone numbers must be in E.164 format (e.g. `+1234567890`).
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    import com.crossmint.kotlin.CrossmintSDK
    import com.crossmint.kotlin.types.EVMChain
    import com.crossmint.kotlin.signers.SignerType
    import com.crossmint.kotlin.signers.OTPDeliveryChannel

    val sdk = CrossmintSDK.shared
    val result = sdk.wallets.createWallet(
        chain = EVMChain.BaseSepolia,
        recoveryMethods = listOf(SignerType.Phone("+1234567890", channel = OTPDeliveryChannel.WHATSAPP))
    )
    val wallet = result.getOrThrow()
    ```

    Phone numbers must be in E.164 format (e.g. `+1234567890`).
  </Tab>

  <Tab title="Flutter">
    ```dart theme={null}
    import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

    CrossmintWalletProvider(
      config: CrossmintWalletProviderConfig(
        clientConfig: const CrossmintClientConfig(
          apiKey: 'YOUR_CLIENT_API_KEY',
          appScheme: 'myapp',
        ),
        walletControllerConfig: const CrossmintWalletControllerConfig(
          createOnLogin: CrossmintCreateOnLoginConfig(
            chain: 'base-sepolia',
            recovery: CrossmintPhoneSignerConfig(phone: 'YOUR_E164_PHONE_NUMBER'),
          ),
        ),
        otpPromptBuilder: crossmintDefaultOtpPromptBuilder,
      ),
      child: const HomeScreen(),
    )
    ```

    Phone numbers must be in E.164 format (e.g. `+1234567890`).
  </Tab>

  <Tab title="REST">
    <CodeGroup>
      ```bash cURL theme={null}
      curl --request POST \
          --url https://staging.crossmint.com/api/2025-06-09/wallets \
          --header 'Content-Type: application/json' \
          --header 'X-API-KEY: YOUR_SERVER_API_KEY' \
          --data '{
              "chainType": "evm",
              "owner": "phone:+1234567890",
              "config": {
                  "recoveryMethods": [
                      {
                          "type": "phone",
                          "phone": "+1234567890"
                      }
                  ]
              }
          }'
      ```

      ```js Node.js theme={null}
      const url =
          "https://staging.crossmint.com/api/2025-06-09/wallets";

      const payload = {
          chainType: "evm",
          owner: "phone:+1234567890",
          config: {
              recoveryMethods: [
                  {
                      type: "phone",
                      phone: "+1234567890",
                  },
              ],
          },
      };

      const response = await fetch(url, {
          method: "POST",
          headers: {
              "X-API-KEY": "YOUR_SERVER_API_KEY",
              "Content-Type": "application/json",
          },
          body: JSON.stringify(payload),
      });

      const data = await response.json();
      console.log(data);
      ```

      ```python Python theme={null}
      import requests

      url = "https://staging.crossmint.com/api/2025-06-09/wallets"

      payload = {
          "chainType": "evm",
          "owner": "phone:+1234567890",
          "config": {
              "recoveryMethods": [
                  {
                      "type": "phone",
                      "phone": "+1234567890"
                  }
              ]
          }
      }
      headers = {
          "X-API-KEY": "YOUR_SERVER_API_KEY",
          "Content-Type": "application/json"
      }

      response = requests.post(url, json=payload, headers=headers)
      print(response.json())
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Server Recovery Method

Use a server signer as the recovery method when your backend should manage recovery without a user-facing OTP flow. This fits company wallets, agents, backend automation, and hybrid architectures.

```ts theme={null}
import {
    createCrossmint,
    CrossmintWallets,
} from "@crossmint/wallets-sdk";

const crossmint = createCrossmint({
    apiKey: "YOUR_SERVER_API_KEY",
});
const crossmintWallets = CrossmintWallets.from(crossmint);

const wallet = await crossmintWallets.createWallet({
    chain: "base-sepolia",
    recoveryMethods: [
        {
            type: "server",
            secret: process.env.CROSSMINT_SIGNER_SECRET,
        },
    ],
});
```

For more on generating and managing server signer secrets, see the [Server Signer guide](/wallets/guides/signers/server-signer).

## Multiple Recovery Methods

Add more than one entry to `recoveryMethods` to register several recovery methods on the same wallet. You can combine multiple email and phone recovery methods, and a single one of them is enough to authorize recovery, add or remove signers, and add or remove other recovery methods. See [Manage Recovery Methods](/wallets/guides/recovery/manage-recovery-methods) for changing recovery methods after creation, and for `useRecoveryMethod()`, which selects the one that authorizes an operation when a wallet has several.

<Snippet />

<Tabs>
  <Tab title="React">
    Using `createOnLogin` on the provider:

    ```tsx theme={null}
    import {
        CrossmintProvider,
        CrossmintAuthProvider,
        CrossmintWalletProvider,
    } from "@crossmint/client-sdk-react-ui";

    function App({ children }) {
        return (
            <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
                <CrossmintAuthProvider
                    loginMethods={["email", "google"]}
                >
                    <CrossmintWalletProvider
                        createOnLogin={{
                            chain: "solana",
                            recoveryMethods: [
                                { type: "email" },
                                {
                                    type: "phone",
                                    phone: "+1234567890",
                                },
                            ],
                        }}
                    >
                        {children}
                    </CrossmintWalletProvider>
                </CrossmintAuthProvider>
            </CrossmintProvider>
        );
    }
    ```
  </Tab>

  <Tab title="Node.js">
    ```ts theme={null}
    import {
        createCrossmint,
        CrossmintWallets,
    } from "@crossmint/wallets-sdk";

    const crossmint = createCrossmint({
        apiKey: "YOUR_SERVER_API_KEY",
    });
    const crossmintWallets = CrossmintWallets.from(crossmint);

    try {
        const wallet = await crossmintWallets.createWallet({
            chain: "solana",
            owner: "email:user@example.com",
            recoveryMethods: [
                { type: "email", email: "user@example.com" },
                {
                    type: "phone",
                    phone: "+12223334444", // E.164 format required
                },
            ],
        });

        console.log(wallet.recoveryMethods.map((method) => method.type)); // ["email", "phone"]
    } catch (error) {
        console.error("Failed to create wallet:", error);
    }
    ```
  </Tab>

  <Tab title="React Native">
    ```tsx theme={null}
    import {
        CrossmintProvider,
        CrossmintAuthProvider,
        CrossmintWalletProvider,
    } from "@crossmint/client-sdk-react-native-ui";

    function App({ children }) {
        return (
            <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
                <CrossmintAuthProvider
                    loginMethods={["email", "google"]}
                >
                    <CrossmintWalletProvider
                        createOnLogin={{
                            chain: "solana",
                            recoveryMethods: [
                                { type: "email" },
                                {
                                    type: "phone",
                                    phone: "+1234567890",
                                },
                            ],
                        }}
                    >
                        {children}
                    </CrossmintWalletProvider>
                </CrossmintAuthProvider>
            </CrossmintProvider>
        );
    }
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    import CrossmintClient

    let sdk = CrossmintSDK.shared

    let wallet = try await sdk.crossmintWallets.createWallet(
        chain: .solana,
        recoveryMethods: [.email("user@example.com"), .phone("+12223334444")]
    )
    ```

    Only Solana and Stellar accept more than one recovery signer.
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    import com.crossmint.kotlin.CrossmintSDK
    import com.crossmint.kotlin.types.SolanaChain
    import com.crossmint.kotlin.signers.SignerType

    val sdk = CrossmintSDK.shared
    val result = sdk.wallets.createWallet(
        chain = SolanaChain.Solana,
        recoveryMethods = listOf(
            SignerType.Email("user@example.com"),
            SignerType.Phone("+12223334444"),
        )
    )
    val wallet = result.getOrThrow()
    ```

    Only Solana and Stellar accept more than one recovery signer.
  </Tab>

  <Tab title="Flutter">
    The Flutter SDK does not yet accept a list of recovery methods at creation time. Create the wallet with several recovery methods from your server (Node.js or REST) and load it in Flutter.
  </Tab>

  <Tab title="REST">
    <CodeGroup>
      ```bash cURL theme={null}
      curl --request POST \
          --url https://staging.crossmint.com/api/2025-06-09/wallets \
          --header 'Content-Type: application/json' \
          --header 'X-API-KEY: YOUR_SERVER_API_KEY' \
          --data '{
              "chainType": "solana",
              "owner": "email:user@example.com",
              "config": {
                  "recoveryMethods": [
                      {
                          "type": "email",
                          "email": "user@example.com"
                      },
                      {
                          "type": "phone",
                          "phone": "+1234567890"
                      }
                  ]
              }
          }'
      ```

      ```js Node.js theme={null}
      const url =
          "https://staging.crossmint.com/api/2025-06-09/wallets";

      const payload = {
          chainType: "solana",
          owner: "email:user@example.com",
          config: {
              recoveryMethods: [
                  { type: "email", email: "user@example.com" },
                  { type: "phone", phone: "+1234567890" },
              ],
          },
      };

      const response = await fetch(url, {
          method: "POST",
          headers: {
              "X-API-KEY": "YOUR_SERVER_API_KEY",
              "Content-Type": "application/json",
          },
          body: JSON.stringify(payload),
      });

      const data = await response.json();
      console.log(data.config.recoveryMethods);
      ```

      ```python Python theme={null}
      import requests

      url = "https://staging.crossmint.com/api/2025-06-09/wallets"

      payload = {
          "chainType": "solana",
          "owner": "email:user@example.com",
          "config": {
              "recoveryMethods": [
                  {"type": "email", "email": "user@example.com"},
                  {"type": "phone", "phone": "+1234567890"}
              ]
          }
      }
      headers = {
          "X-API-KEY": "YOUR_SERVER_API_KEY",
          "Content-Type": "application/json"
      }

      response = requests.post(url, json=payload, headers=headers)
      print(response.json())
      ```
    </CodeGroup>
  </Tab>
</Tabs>

### Server Wallets

Server wallets cannot use email or phone recovery methods. Combine a `server` signer with an `external-wallet` recovery method instead — for example a key held in your cloud KMS — so that either one can recover the wallet:

```ts theme={null}
import {
    createCrossmint,
    CrossmintWallets,
} from "@crossmint/wallets-sdk";

const crossmint = createCrossmint({
    apiKey: "YOUR_SERVER_API_KEY",
});
const crossmintWallets = CrossmintWallets.from(crossmint);

const wallet = await crossmintWallets.createWallet({
    chain: "solana",
    recoveryMethods: [
        {
            type: "server",
            secret: process.env.CROSSMINT_SIGNER_SECRET,
        },
        {
            type: "external-wallet",
            address: "YOUR_KMS_KEY_ADDRESS",
        },
    ],
});
```

See [Cloud KMS](/wallets/guides/signers/cloud-kms) for how to set up a KMS-held key.

## How Recovery Works on a New Device

When a user accesses their wallet from a new device where no device signer exists:

1. The user authenticates via your app — the SDK retrieves the wallet
2. The SDK detects no local device signer on this device
3. On the first transaction (or when `recover()` is called), the SDK triggers the recovery flow with the selected recovery method:
   * **Email OTP**: Crossmint sends a one-time code to the user's email
   * **SMS OTP**: Crossmint sends a one-time code to the user's phone
   * **Server signer**: your backend signs the recovery approval automatically
4. The recovery method authorizes a new device signer for this device
5. All subsequent transactions on the new device are frictionless

```typescript theme={null}
import { useWallet } from "@crossmint/client-sdk-react-ui";

const { wallet } = useWallet();

// Check if recovery is needed on this device
if (wallet.needsRecovery()) {
    // Trigger recovery proactively (optional)
    await wallet.recover();
}
```

<Note>
  The previous device's signer remains valid. Each device maintains its own independent device signer.
</Note>

## Choosing a Recovery Method

| Method | Best For | User Friction | Server Required |
| - | - | - | - |
| Email OTP | Consumer apps with email-based auth | Medium (OTP prompt) | No |
| SMS OTP | Mobile-first apps | Medium (OTP prompt) | No |
| Server signer | AI agents, backend automation, hybrid apps | None (automatic) | Yes |

<Snippet />

## Next Steps

<CardGroup>
  <Card title="Device Signer" icon="microchip" href="/wallets/guides/signers/device-signer">
    Understand how the default client-side signer works
  </Card>

  <Card title="Server Signer" icon="server" href="/wallets/guides/signers/server-signer">
    Set up server-side signing with key derivation
  </Card>

  <Card title="Manage Recovery Methods" icon="key" href="/wallets/guides/recovery/manage-recovery-methods">
    Add or remove recovery methods on an existing wallet
  </Card>
</CardGroup>


# Manage Recovery Methods
Source: https://docs.crossmint.com/wallets/guides/recovery/manage-recovery-methods

Add or remove recovery methods on an existing wallet, and choose which recovery method authorizes signer changes.

Recovery methods are set when a wallet is created, but they are not fixed. You can add a recovery method to an existing wallet — for example a backup phone number or a new server key — and remove one the user no longer controls. Every change is approved by one of the wallet's existing recovery methods, and that approval is enforced onchain.

Adding and removing recovery methods is supported on **Solana** and **Stellar**. EVM is coming soon; contact support if you would like early access. See [Recovery Methods](/wallets/concepts/recovery) for the concept, and [Configure Wallet Recovery](/wallets/guides/recovery/configure-recovery) for setting recovery methods at creation time.

## Prerequisites

* **Wallet:** An existing Solana or Stellar wallet with at least one recovery method.
* **API key:** An API key with `wallets.create` and `wallets:transactions.create` scopes. In staging, all scopes are included by default.

## How It Works

Adding or removing a recovery method creates a transaction that one of the wallet's existing recovery methods must approve. With the SDK, `addRecoveryMethod()` and `removeRecoveryMethod()` handle the approval for you: an email or phone method prompts the user for a one-time code, a server method signs with its secret, and an external wallet signs through its `onSign` callback. Once the transaction confirms, `wallet.recoveryMethods` reflects the change. With the REST API, you submit the change and then approve the returned transaction yourself.

<Accordion title="Rules enforced by the API">
  * A wallet always keeps at least one recovery method: removing the last one is rejected.
  * A recovery method whose add transaction has not confirmed yet cannot be removed. Adding the same method again returns the in-flight transaction, or starts a new one once it has expired.
  * Only a recovery method can authorize these changes. Operational signers added with `addSigner()` cannot.
  * On Solana, only Crossmint smart wallets support these operations. On Stellar, removing a recovery method requires the wallet to run the latest contract version.
</Accordion>

## Select the Authorizing Recovery Method

When a wallet has a single recovery method, the SDK uses it to authorize `addSigner()`, `removeSigner()`, `addRecoveryMethod()`, and `removeRecoveryMethod()`. When a wallet has several, select the one to authorize with first by calling `useRecoveryMethod()` with one of the entries in `wallet.recoveryMethods`; otherwise the operation throws `SignerRequiredError`. Here, the phone recovery method authorizes adding an email signer:

```typescript theme={null}
await wallet.useRecoveryMethod({ type: "phone", phone: "+12223334444" });

await wallet.addSigner({ type: "email", email: "user@example.com" });
```

Pass the full config when the method needs it to sign: the `secret` for a server method, or the `onSign` callback for an external wallet.

```typescript theme={null}
await wallet.useRecoveryMethod({
    type: "server",
    secret: process.env.CROSSMINT_SIGNER_SECRET,
});
```

Passing a config that does not match any entry in `wallet.recoveryMethods` throws `InvalidRecoveryConfigError`.

<Note>
  `useRecoveryMethod()` is experimental and may change in a future release.
</Note>

## Add a Recovery Method

The new method accepts the same configuration objects as `recoveryMethods` at wallet creation — `email`, `phone`, `external-wallet`, or `server`. Phone numbers use E.164 format.

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet } from "@crossmint/client-sdk-react-ui";

    const { wallet } = useWallet();

    const result = await wallet.addRecoveryMethod({
        type: "phone",
        phone: "+12223334444",
    });

    console.log("Recovery method added:", result.transactionId);
    console.log(wallet.recoveryMethods.map((method) => method.type));
    ```

    For a wallet with a single email recovery method, the user enters the email one-time code to approve the change, and the last line logs `["email", "phone"]`. With several recovery methods, call `useRecoveryMethod()` first.
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import {
        createCrossmint,
        CrossmintWallets,
    } from "@crossmint/wallets-sdk";

    const crossmint = createCrossmint({
        apiKey: "YOUR_SERVER_API_KEY",
    });
    const crossmintWallets = CrossmintWallets.from(crossmint);

    const wallet = await crossmintWallets.getWallet(
        "<wallet-address>",
        {
            chain: "solana",
            signer: {
                type: "server",
                secret: process.env.CROSSMINT_SIGNER_SECRET,
            },
        }
    );

    const result = await wallet.addRecoveryMethod({
        type: "external-wallet",
        address: "GbA2NZfpAnRVM2G2BG29qooqsYbdV5c2WVFymJ8MMir7",
    });

    console.log("Recovery method added:", result.transactionId);
    ```

    Here the server signer is the wallet's recovery method, so it approves the change without user interaction. Only the `address` is needed to register an external wallet; the `onSign` callback is required later, when that recovery method is used to authorize an operation.
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { useWallet } from "@crossmint/client-sdk-react-native-ui";

    const { wallet } = useWallet();

    const result = await wallet.addRecoveryMethod({
        type: "phone",
        phone: "+12223334444",
    });

    console.log("Recovery method added:", result.transactionId);
    ```
  </Tab>

  <Tab title="REST">
    When using the REST API, the change must be approved by one of the wallet's recovery methods. You must [approve the transaction](/api-reference/wallets/approve-transaction) to complete it.

    <Steps>
      <Step title="Add the recovery method">
        Call the [add recovery method](/api-reference/wallets/add-recovery-method) endpoint. The `recoveryMethods` field takes one recovery method per request, as a signer object or a signer locator. Set `approver` to the locator of the recovery method that authorizes the change. Omit `chain` for Solana and Stellar wallets.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:solana/recovery-methods \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: <x-api-key>' \
              --data '{
                  "recoveryMethods": {
                      "type": "external-wallet",
                      "address": "GbA2NZfpAnRVM2G2BG29qooqsYbdV5c2WVFymJ8MMir7"
                  },
                  "approver": "email:user@example.com"
              }'
          ```

          ```js Node.js theme={null}
          const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:solana/recovery-methods';

          const payload = {
              recoveryMethods: {
                  type: "external-wallet",
                  address: "GbA2NZfpAnRVM2G2BG29qooqsYbdV5c2WVFymJ8MMir7"
              },
              approver: "email:user@example.com"
          };

          const options = {
              method: 'POST',
              headers: {
                  'X-API-KEY': '<x-api-key>',
                  'Content-Type': 'application/json'
              },
              body: JSON.stringify(payload)
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:solana/recovery-methods"

          payload = {
              "recoveryMethods": {
                  "type": "external-wallet",
                  "address": "GbA2NZfpAnRVM2G2BG29qooqsYbdV5c2WVFymJ8MMir7"
              },
              "approver": "email:user@example.com"
          }
          headers = {
              "X-API-KEY": "<x-api-key>",
              "Content-Type": "application/json"
          }

          response = requests.post(url, json=payload, headers=headers)

          print(response.json())
          ```
        </CodeGroup>

        The response contains the registered method under `recoveryMethods` and the pending transaction under `tx`.
      </Step>

      <Step title="Sign and approve the transaction">
        Sign the approval message returned inside `tx.approvals` with the recovery method named in `approver`, then submit the signature to the [approve transaction](/api-reference/wallets/approve-transaction) endpoint using the transaction ID from `tx.id`. Once the transaction succeeds, the new method appears in the wallet's `config.recoveryMethods`.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Remove a Recovery Method

Identify the method to remove with the same configuration object you would pass to `useRecoveryMethod()`. Any of the wallet's recovery methods can authorize the removal, as long as at least one method remains afterwards. In the React and React Native examples below, the email method authorizes removing the phone method.

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet } from "@crossmint/client-sdk-react-ui";

    const { wallet } = useWallet();

    await wallet.useRecoveryMethod({ type: "email", email: "user@example.com" });

    const result = await wallet.removeRecoveryMethod({
        type: "phone",
        phone: "+12223334444",
    });

    console.log("Recovery method removed:", result.transactionId);
    ```
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import {
        createCrossmint,
        CrossmintWallets,
    } from "@crossmint/wallets-sdk";

    const crossmint = createCrossmint({
        apiKey: "YOUR_SERVER_API_KEY",
    });
    const crossmintWallets = CrossmintWallets.from(crossmint);

    const wallet = await crossmintWallets.getWallet(
        "<wallet-address>",
        {
            chain: "solana",
            signer: {
                type: "server",
                secret: process.env.CROSSMINT_SIGNER_SECRET,
            },
        }
    );

    const result = await wallet.removeRecoveryMethod({
        type: "external-wallet",
        address: "GbA2NZfpAnRVM2G2BG29qooqsYbdV5c2WVFymJ8MMir7",
    });

    console.log("Recovery method removed:", result.transactionId);
    ```
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { useWallet } from "@crossmint/client-sdk-react-native-ui";

    const { wallet } = useWallet();

    await wallet.useRecoveryMethod({ type: "email", email: "user@example.com" });

    const result = await wallet.removeRecoveryMethod({
        type: "phone",
        phone: "+12223334444",
    });

    console.log("Recovery method removed:", result.transactionId);
    ```
  </Tab>

  <Tab title="REST">
    <Steps>
      <Step title="Remove the recovery method">
        Call the [remove recovery method](/api-reference/wallets/remove-recovery-method) endpoint with the locator of the method to remove in the path, and the locator of the authorizing method in the `approver` query parameter. Omit `chain` for Solana and Stellar wallets.

        <Tip>
          Recovery method locators (for example `phone:+12223334444` or `external-wallet:GbA2NZfpAnRVM2G2BG29qooqsYbdV5c2WVFymJ8MMir7`) are listed under `config.recoveryMethods` when you [get the wallet](/api-reference/wallets/get-wallet-by-locator).
        </Tip>

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request DELETE \
              --url 'https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:solana/recovery-methods/external-wallet:GbA2NZfpAnRVM2G2BG29qooqsYbdV5c2WVFymJ8MMir7?approver=email:user@example.com' \
              --header 'X-API-KEY: <x-api-key>'
          ```

          ```js Node.js theme={null}
          const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:solana/recovery-methods/external-wallet:GbA2NZfpAnRVM2G2BG29qooqsYbdV5c2WVFymJ8MMir7?approver=email:user@example.com';

          const options = {
              method: 'DELETE',
              headers: {
                  'X-API-KEY': '<x-api-key>'
              }
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:solana/recovery-methods/external-wallet:GbA2NZfpAnRVM2G2BG29qooqsYbdV5c2WVFymJ8MMir7?approver=email:user@example.com"

          headers = {"X-API-KEY": "<x-api-key>"}

          response = requests.delete(url, headers=headers)

          print(response.json())
          ```
        </CodeGroup>

        The response is the pending removal transaction, in the same shape as the [get transaction](/api-reference/wallets/get-transaction) endpoint.
      </Step>

      <Step title="Sign and approve the transaction">
        Sign the approval message returned inside `approvals` with the recovery method named in `approver`, then submit the signature to the [approve transaction](/api-reference/wallets/approve-transaction) endpoint. The method is removed from `config.recoveryMethods` once the transaction succeeds.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Next Steps

<CardGroup>
  <Card title="Configure Recovery" icon="shield-halved" href="/wallets/guides/recovery/configure-recovery">
    Set recovery methods when creating a wallet
  </Card>

  <Card title="List Signers" icon="list" href="/wallets/guides/signers/list-signers">
    Inspect the wallet's signers and recovery methods
  </Card>

  <Card title="Recover a Wallet" icon="rotate" href="/wallets/guides/recovery/wallet-recovery">
    Regain access from a new device with a recovery method
  </Card>
</CardGroup>


# Recover a Wallet
Source: https://docs.crossmint.com/wallets/guides/recovery/wallet-recovery

Regain access to a wallet when your operational signer is lost — use a recovery method to enroll a new signer or transfer funds.

When the operational signer for a wallet is no longer available — you switched to a new device, cleared browser storage, lost a server secret, or a private key was compromised — you can use one of the wallet's **recovery methods** to regain control. Recovery methods are configured at wallet creation time specifically for this scenario.

This guide walks through the full recovery flow for the most common case: a **device signer wallet** with an **email OTP recovery method**, both on the client side. The same principles apply to other signer and recovery combinations.

## When You Need This

Recovery is needed whenever you lose access to the signer that was used for day-to-day wallet operations:

* **Switched devices** — you set up a wallet on your laptop and now need to use it on a new computer or phone. The device signer from the original machine cannot be transferred.
* **Cleared browser data** — you cleared cookies, local storage, or reinstalled the app, which deleted the locally stored device key.
* **Lost server signer secret** — the secret used to derive your server signer was lost, rotated, or compromised.
* **Lost private key** — the private key for an external wallet signer is no longer accessible.
* **Infrastructure migration** — you need to move signing authority to new infrastructure.

In all of these cases, a recovery method lets you authorize a new operational signer without needing the original one.

## Prerequisites

* A wallet that was created with at least one recovery method (email, phone, server, or cloud KMS). To configure recovery methods, see [Configure Wallet Recovery](/wallets/guides/recovery/configure-recovery).
* A Crossmint **client-side API key** with `wallets.read`, `wallets:signatures.create`, and `wallets:transactions.create` scopes
* Access to the email address or phone number associated with one of the wallet's recovery methods (for OTP-based recovery)

<Warning>
  If your wallet has a single recovery method and you have lost access to it as well, you cannot recover the wallet through the SDK. Contact <a href="https://www.crossmint.com/contact/sales">Crossmint support</a> to discuss enterprise recovery options.
</Warning>

## How Recovery Works

When the SDK loads the wallet on a new device, it detects that no local device signer exists. The recovery method verifies the user and approves adding a signer for the new device. The new signer then handles routine wallet actions.

The original device signer remains registered. Recovery adds a signer for the new device; it does not revoke existing signers.

The most common recovery scenario is switching to a new device. The flow is:

1. **Wallet fetch** — `createOnLogin` loads the wallet when the user logs in on the new device.
2. **Detection** — the SDK finds no valid local device key and automatically attempts to add a new device signer.
3. **OTP prompt** — the pending signer enrollment triggers the recovery flow. For email OTP, the user receives a one-time code and enters it to authorize the new key.
4. **New key generation** — the SDK generates a new P256 keypair in the device's secure enclave (or browser credential store).
5. **Signer registration** — the SDK calls `addSigner()` to register the new device key onchain, authorized by one of the wallet's recovery methods. A wallet with several recovery methods needs one selected with `useRecoveryMethod()` first — see [Manage Recovery Methods](/wallets/guides/recovery/manage-recovery-methods#select-the-authorizing-recovery-method).
6. **Activation** — the new device signer becomes the active signer. All subsequent transactions on this device are frictionless.

<Info>
  The SDK automatically attempts to add a device signer whenever one is missing. This triggers the recovery flow transparently — the user experiences a one-time OTP prompt, after which all transactions on that device sign silently.
</Info>

## Step 1: Recover on a New Device

When you open your app on a new device (or after clearing browser data), the device signer from the original device is not present. Use `createOnLogin` on `CrossmintWalletProvider` so the SDK fetches the wallet automatically when the user logs in — no explicit `getWallet()` call needed.

Once the wallet is loaded, the SDK detects that no local device signer exists and automatically attempts to add one. This pending signer enrollment triggers the recovery flow, prompting the user to verify via OTP before the new device key is registered.

### Automatic Recovery (Recommended)

With `createOnLogin` and `showOtpSignerPrompt={true}` (the default), recovery happens automatically:

1. The user logs in on the new device — `createOnLogin` fetches the wallet
2. The SDK detects no local device key and attempts to add a new device signer
3. The pending signer enrollment triggers the OTP prompt — the user enters the code from their email
4. The new device signer is registered for this device
5. All future transactions on this device are frictionless

No additional code is needed beyond the standard provider setup.

### Preemptive Recovery

To avoid interrupting the user's first transaction with an OTP prompt, trigger recovery on app startup:

```tsx theme={null}
"use client";

import { useWallet } from "@crossmint/client-sdk-react-ui";
import { useEffect, useState } from "react";

function WalletRecovery() {
    const { wallet } = useWallet();
    const [recovering, setRecovering] = useState(false);

    useEffect(() => {
        const checkRecovery = async () => {
            if (wallet && wallet.needsRecovery()) {
                setRecovering(true);
                await wallet.recover();
                setRecovering(false);
            }
        };
        checkRecovery();
    }, [wallet]);

    if (recovering) {
        return <p>Verifying your identity to set up this device...</p>;
    }

    return (
        <div>
            <p>Wallet ready: {wallet?.address}</p>
        </div>
    );
}
```

<Note>
  `recover()` triggers the same OTP flow as automatic recovery — the only difference is timing. The user sees the OTP prompt immediately on load rather than on their first transaction.
</Note>

### Manual Recovery Flow

For full control over the recovery UI, disable the built-in OTP prompt and manage the flow yourself:

```tsx theme={null}
"use client";

import { useWallet, useWalletOtpSigner } from "@crossmint/client-sdk-react-ui";
import { useState } from "react";

function ManualRecovery() {
    const { wallet } = useWallet();
    const { needsAuth, verifyOtp, reject } = useWalletOtpSigner();
    const [otpCode, setOtpCode] = useState("");

    if (!wallet || !wallet.needsRecovery()) {
        return <p>Wallet is ready — no recovery needed.</p>;
    }

    if (!needsAuth) {
        return (
            <button onClick={() => wallet.recover()}>
                Start Recovery
            </button>
        );
    }

    return (
        <div>
            <p>Enter the verification code sent to your email:</p>
            <input
                value={otpCode}
                onChange={(e) => setOtpCode(e.target.value)}
                placeholder="Enter OTP code"
            />
            <button onClick={() => verifyOtp(otpCode)}>Verify</button>
            <button onClick={reject}>Cancel</button>
        </div>
    );
}
```

<Note>
  To use the manual flow, set `showOtpSignerPrompt={false}` on `CrossmintWalletProvider`. The `useWalletOtpSigner` hook gives you full control over the OTP UI.
</Note>

## Step 2: Choose a Recovery Action

After recovery, the new device signer is registered and the wallet resumes normal operations on the new device. In most cases, **no additional action is needed** — the recovery flow handles everything automatically.

However, if you want to explicitly add a different type of signer or move funds, you can do so while a recovery method is active.

### Option A: Add a Different Signer Type

If you want to add a signer other than a device signer (which is handled automatically by the recovery flow), you can do so from the client side.

You can also explicitly create a device signer by calling `createDeviceSigner()` from the `useWallet` hook — this is optional since the SDK handles device signer creation automatically during recovery.

<Tabs>
  <Tab title="Add a passkey">
    Call `wallet.addSigner({ type: "passkey" })` to trigger a WebAuthn biometric prompt and register a new passkey signer:

    ```tsx theme={null}
    import { useWallet } from "@crossmint/client-sdk-react-ui";

    function AddPasskeySigner() {
        const { wallet } = useWallet();

        const handleAddPasskey = async () => {
            if (!wallet) return;

            const signer = await wallet.addSigner({ type: "passkey" });
            console.log("Passkey added:", signer.locator);

            await wallet.useSigner({ type: "passkey" });
        };

        return (
            <button onClick={handleAddPasskey}>
                Add Passkey as New Signer
            </button>
        );
    }
    ```

    <Note>
      Passkey signers are supported on EVM, Solana, and Stellar. They require a browser that supports WebAuthn, or the `passkeys` prop in React Native (see [Passkey Signer](/wallets/guides/signers/passkey)).
    </Note>
  </Tab>

  <Tab title="Add an external wallet">
    Use a private key with <a href="https://viem.sh">viem</a> to add an external wallet signer:

    ```tsx theme={null}
    import { useWallet } from "@crossmint/client-sdk-react-ui";
    import { privateKeyToAccount } from "viem/accounts";

    function AddExternalWalletSigner() {
        const { wallet } = useWallet();

        const handleAddExternalWallet = async () => {
            if (!wallet) return;

            const privateKeyEVM = "YOUR_PRIVATE_KEY" as `0x${string}`;
            const account = privateKeyToAccount(privateKeyEVM);

            const signerConfig = {
                type: "external-wallet" as const,
                address: account.address,
                onSign: async (message: string) => {
                    return await account.signMessage({
                        message: { raw: message as `0x${string}` },
                    });
                },
            };

            const signer = await wallet.addSigner(signerConfig);
            console.log("External wallet added:", signer.locator);

            await wallet.useSigner(signerConfig);
        };

        return (
            <button onClick={handleAddExternalWallet}>
                Add External Wallet as Signer
            </button>
        );
    }
    ```
  </Tab>

  <Tab title="Add a server signer">
    If you want to add a server signer from the client side (after recovery), pass the new secret securely from your backend:

    ```tsx theme={null}
    import { useWallet } from "@crossmint/client-sdk-react-ui";

    function AddServerSigner() {
        const { wallet } = useWallet();

        const handleAddServerSigner = async () => {
            if (!wallet) return;

            const newSigner = await wallet.addSigner({
                type: "server",
                secret: "YOUR_NEW_SERVER_SIGNER_SECRET",
            });

            console.log("New server signer added:", newSigner.locator);
        };

        return (
            <button onClick={handleAddServerSigner}>
                Add Server Signer
            </button>
        );
    }
    ```

    <Note>
      Pass the new server signer secret from your backend to the client securely (e.g., via an API endpoint). Do not hard-code secrets in client code. For generating a new secret, see the [Server Signer guide](/wallets/guides/signers/server-signer#generate-a-signer-secret).
    </Note>
  </Tab>
</Tabs>

### Option B: Transfer Funds to a Safe Wallet

If you suspect the original signer was compromised (not just lost), move assets out of the wallet immediately. Select a recovery method explicitly to send funds directly:

```tsx theme={null}
import { useWallet } from "@crossmint/client-sdk-react-ui";

function EmergencyTransfer() {
    const { wallet } = useWallet();

    const handleTransfer = async () => {
        if (!wallet) return;

        await wallet.useSigner({ type: "email", email: "user@example.com" });

        const result = await wallet.send(
            "YOUR_SAFE_WALLET_ADDRESS",
            "usdc",
            "100"
        );

        console.log("Transfer complete:", result.explorerLink);
    };

    return (
        <button onClick={handleTransfer}>
            Transfer Funds to Safe Wallet
        </button>
    );
}
```

<Tip>
  Check your balance first with `wallet.balances()` to confirm the available amount before transferring. You can also transfer native tokens and other assets — see [Transfer Tokens](/wallets/guides/transfer-tokens) for the full API.
</Tip>

## Alternative: Recovery with Phone OTP

The flow is identical to email recovery — replace the email recovery method with a phone recovery method when creating the wallet. At recovery time, the user receives an SMS with a verification code instead of an email. Everything else — automatic recovery, preemptive recovery, manual flow — works the same way.

See [Configure Recovery](/wallets/guides/recovery/configure-recovery) for details on setting up phone OTP as the recovery method.

## Alternative: Server-to-Server Recovery

If your wallet uses a **server signer** as both the operational signer and a recovery method (common for AI agent wallets and backend automation), and you still have access to the recovery secret (which should be different from the operational secret), recovery is fully server-side:

```typescript theme={null}
import { createCrossmint, CrossmintWallets } from "@crossmint/wallets-sdk";

const crossmint = createCrossmint({
    apiKey: "YOUR_SERVER_API_KEY",
});
const crossmintWallets = CrossmintWallets.from(crossmint);

const wallet = await crossmintWallets.getWallet(
    "YOUR_WALLET_ADDRESS",
    { chain: "base-sepolia" }
);

// Activate the recovery server signer
await wallet.useSigner({
    type: "server",
    secret: process.env.RECOVERY_SIGNER_SECRET,
});

// Add a new operational server signer
const newSigner = await wallet.addSigner({
    type: "server",
    secret: process.env.NEW_OPERATIONAL_SECRET,
});

console.log("New operational signer added:", newSigner.locator);
```

<Warning>
  Always use **different secrets** for your operational signer and recovery method. If both use the same secret, losing it means losing access to both — making recovery impossible through the SDK.
</Warning>

## Best Practices

* **Always configure a recovery method at wallet creation time.** This ensures users can regain access to their wallet on a new device.
* **Use preemptive recovery** on app startup to give users a smoother experience — they verify once on load rather than being interrupted mid-transaction.
* **Use different secrets** for your operational signer and recovery server method. Store them in separate secure locations.
* **After recovery, the new device signer works automatically.** You do not need to manually call `addSigner()` for device signers — the `recover()` flow handles this.
* **The old device signer remains valid.** Each device has its own independent device key. Recovery adds a new key; it does not revoke the old one.
* **Consider more than one recovery method.** Because a single method is enough to recover the wallet, a second method removes the single point of failure without adding friction to day-to-day signing.
* **Consider adding multiple signer types** for defense in depth — for example, a device signer for daily use and a passkey as a backup.
* **For compromised signers**, transfer funds to a safe wallet first, then set up new signers on the original wallet (or create a fresh wallet).

## Managed Support Center

Managed support center recovery is a white-glove recovery option for enterprise customers: the wallet owner contacts a specialized support center, completes identity verification (KYC), and a trained agent facilitates the enrollment of a new operational signer. This is the most robust recovery option available and is best reserved as a last resort for situations where all other recovery methods have been exhausted.

<Info>
  Managed support center recovery requires an enterprise agreement. <a href="https://www.crossmint.com/contact/sales">Contact Crossmint</a> to set up managed recovery for your project.
</Info>

## Common Gotchas

<AccordionGroup>
  <Accordion title="Recovery adds a signer but does not remove the old signer">
    Each device has its own signer. Recovering on a new device leaves the previous device signer registered.
  </Accordion>

  <Accordion title="The configured recovery method is unavailable">
    Recovery requires access to at least one configured recovery method. If the wallet has several, use any remaining one. If none is available, see the managed support center options below.
  </Accordion>

  <Accordion title="The OTP prompt interrupts the first transaction">
    Call `recover()` when the application starts so the user completes verification before initiating a transaction.
  </Accordion>
</AccordionGroup>

## See Also

<CardGroup>
  <Card title="Recovery Concepts" icon="rotate" href="/wallets/concepts/recovery">
    How recovery works — detection, authentication, and signer registration
  </Card>

  <Card title="Configure Recovery" icon="shield-halved" href="/wallets/guides/recovery/configure-recovery">
    Set up email, phone, or server recovery at wallet creation time
  </Card>

  <Card title="Device Signer" icon="microchip" href="/wallets/guides/signers/device-signer">
    Understand how the default client-side signer works
  </Card>

  <Card title="Add Signers" icon="key" href="/wallets/guides/signers/add-signers">
    Add passkeys, external wallets, or device signers to a wallet
  </Card>
</CardGroup>


# Custom EVM Transactions
Source: https://docs.crossmint.com/wallets/guides/send-transaction-evm

Send arbitrary EVM contract calls (to, value, data) from a Crossmint wallet

## Prerequisites

* Ensure you have a wallet created.
* **Signer**: The signing wallet must be registered as a signer on the wallet. You can do this [at wallet creation](/wallets/guides/create-wallet) by passing `signers`, or afterward by [adding a signer](/wallets/guides/signers/add-signers).
* **API Key**: Ensure you have an API key with the scopes: `wallets:transactions.create`.

## What is sending a custom transaction?

Sending a custom transaction lets you interact with any smart contract on the blockchain beyond simple transfers. Common use cases include minting free tokens, claiming rewards, or registering for allowlists—all without needing to manage private keys yourself.

## Sending a Transaction

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet, EVMWallet } from '@crossmint/client-sdk-react-ui';

    const { wallet } = useWallet();

    const evmWallet = EVMWallet.from(wallet);

    const TARGET_CONTRACT = "0x...";
    const CALL_DATA = "0x...";

    const { hash, explorerLink } = await evmWallet.sendTransaction({
        to: TARGET_CONTRACT,
        value: BigInt(0),
        data: CALL_DATA,
    });
    ```

    See the [React SDK reference](/sdk-reference/wallets/react/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { CrossmintWallets, createCrossmint, EVMWallet } from "@crossmint/wallets-sdk";

    const SERVER_API_KEY = process.env.SERVER_API_KEY!;
    const CROSSMINT_SIGNER_SECRET = process.env.CROSSMINT_SIGNER_SECRET!;
    const WALLET_ADDRESS = "0x...";
    const TARGET_CONTRACT = "0x...";
    const CALL_DATA = "0x...";

    const crossmint = createCrossmint({
        apiKey: SERVER_API_KEY,
    });

    const crossmintWallets = CrossmintWallets.from(crossmint);

    const wallet = await crossmintWallets.getWallet(
        WALLET_ADDRESS,
        { chain: "base-sepolia" }
    );

    await wallet.useSigner({ type: "server", secret: CROSSMINT_SIGNER_SECRET });

    const evmWallet = EVMWallet.from(wallet);

    try {
        const { hash, explorerLink } = await evmWallet.sendTransaction({
            to: TARGET_CONTRACT,
            value: BigInt(0),
            data: CALL_DATA,
        });
        console.log("Transaction sent:", hash, explorerLink);
    } catch (error) {
        console.error("Failed to send transaction:", error);
        throw error;
    }
    ```

    See the [SDK reference](/sdk-reference/wallets/typescript/classes/EVMWallet#sendtransaction) for all parameters and return types.
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { useWallet, EVMWallet } from '@crossmint/client-sdk-react-native-ui';

    const { wallet } = useWallet();

    const evmWallet = EVMWallet.from(wallet);

    const TARGET_CONTRACT = "0x...";
    const CALL_DATA = "0x...";

    const { hash, explorerLink } = await evmWallet.sendTransaction({
        to: TARGET_CONTRACT,
        value: BigInt(0),
        data: CALL_DATA,
    });
    ```

    See the [React Native SDK reference](/sdk-reference/wallets/react-native/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="Flutter">
    ```dart theme={null}
    import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

    final controller = CrossmintWalletContext.of(context).requireWalletController;
    final evmWallet = controller.createEvmWallet();

    const targetContract = '0x...';
    const callData = '0x...';

    final tx = await evmWallet.sendTransaction(
      const CrossmintEvmTransactionRequest(
        calls: <CrossmintEvmTransactionCall>[
          CrossmintEvmTransactionCall(to: targetContract, value: '0', data: callData),
        ],
      ),
    );
    print('Transaction: ${tx.id}');
    ```

    See the [Flutter SDK reference](/sdk-reference/wallets/flutter/controllers#wallet-methods) for more details.
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    import CrossmintClient
    import Wallet

    CrossmintSDK.configure(apiKey: "<YOUR_API_KEY>")
    let sdk = CrossmintSDK.shared

    guard let wallet = try await sdk.crossmintWallets.getWallet(
        chain: .baseSepolia
    ) else {
        return
    }

    let evmWallet = try EVMWallet.from(wallet: wallet)

    let targetContract = "0x..."
    let callData = "0x..."

    let result = try await evmWallet.sendTransaction(
        to: targetContract,
        value: "0",
        data: callData
    )
    ```

    ### Parameters

    <ParamField type="string">
      Recipient contract or EOA address.
    </ParamField>

    <ParamField type="string">
      Native token value in wei as a decimal string. Pass `nil` or `"0"` for contract calls that transfer no ETH.
    </ParamField>

    <ParamField type="string">
      ABI-encoded call data as a `0x`-prefixed hex string. Pass `nil` or `"0x"` for plain ETH transfers.
    </ParamField>

    ### Returns

    <ParamField type="string">
      The hash of the transaction.
    </ParamField>

    <ParamField type="string">
      The explorer link of the transaction.
    </ParamField>
  </Tab>

  <Tab title="REST">
    Transactions must be approved by one of the wallet's [signers](/wallets/concepts/signers).
    The SDK handles this automatically, but with the REST API you must [approve the transaction](/api-reference/wallets/approve-transaction) to complete it.

    <Steps>
      <Step title="Create the transaction">
        Call the [create transaction](/api-reference/wallets/create-transaction) endpoint.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets/<wallet-locator>/transactions \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: YOUR_API_KEY' \
              --data '{
                  "params": {
                      "calls": [{
                          "to": "0x...",
                          "value": "0x",
                          "data": "0x..."
                      }],
                      "chain": "base-sepolia",
                      "signer": "server:YOUR_SERVER_SIGNER_ADDRESS"
                  }
              }'
          ```

          ```js Node.js theme={null}
          // Replace with your wallet locator
          const WALLET_LOCATOR = "YOUR_WALLET_LOCATOR";
          const url = `https://staging.crossmint.com/api/2025-06-09/wallets/${WALLET_LOCATOR}/transactions`;

          const SERVER_API_KEY = process.env.SERVER_API_KEY;
          // Replace with your server signer address
          const SIGNER_ADDRESS = "YOUR_SERVER_SIGNER_ADDRESS";

          const payload = {
              params: {
                  calls: [{
                      to: "0x...",
                      value: "0x",
                      data: "0x..."
                  }],
                  chain: "base-sepolia",
                  signer: `server:${SIGNER_ADDRESS}`
              }
          };

          const options = {
              method: 'POST',
              headers: {
                  'X-API-KEY': SERVER_API_KEY,
                  'Content-Type': 'application/json'
              },
              body: JSON.stringify(payload)
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```python Python theme={null}
          import os
          import requests

          SERVER_API_KEY = os.environ["SERVER_API_KEY"]
          # Replace with your wallet locator
          WALLET_LOCATOR = "YOUR_WALLET_LOCATOR"
          # Replace with your server signer address
          SIGNER_ADDRESS = "YOUR_SERVER_SIGNER_ADDRESS"

          url = f"https://staging.crossmint.com/api/2025-06-09/wallets/{WALLET_LOCATOR}/transactions"

          payload = {
              "params": {
                  "calls": [{
                      "to": "0x...",
                      "value": "0x",
                      "data": "0x..."
                  }],
                  "chain": "base-sepolia",
                  "signer": f"server:{SIGNER_ADDRESS}"
              }
          }
          headers = {
              "X-API-KEY": SERVER_API_KEY,
              "Content-Type": "application/json"
          }

          response = requests.post(url, json=payload, headers=headers)

          print(response.json())
          ```
        </CodeGroup>

        See the [API reference](/api-reference/wallets/create-transaction) for more details.
      </Step>

      <Step title="Choose your signer type">
        The next steps depend on which signer type you specified in the previous step.

        <Tabs>
          <Tab title="Server Signer">
            [Server](/wallets/guides/signers/server-signer) signers derive a private key from your signer secret using HKDF-SHA256 and sign transactions locally.

            When using the **SDK**, signing and approval are handled automatically — no additional steps are needed.

            When using the **REST API** directly, you must:

            1. Derive the signing key from your signer secret (scoped to your project, environment, and chain type). See the <a href="https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/server/helpers/derive-server-signer.ts">derive-server-signer helper</a> for a reference implementation.
            2. Sign the approval message returned from the transaction creation step.
            3. Submit the signature via the [approve transaction](/api-reference/wallets/approve-transaction) endpoint.

            <Warning>
              Crossmint recommends using the <a href="https://www.npmjs.com/package/@crossmint/wallets-sdk">Wallets SDK</a> for server signer flows. The SDK handles key derivation and signing automatically.
            </Warning>

            See the [Server Signer guide](/wallets/guides/signers/server-signer) for full configuration and setup details.
          </Tab>

          <Tab title="Device Signer">
            [Device](/wallets/guides/signers/device-signer) signers generate a P256 keypair inside the device's secure hardware (Secure Enclave, Android Keystore, or browser Web Crypto API). Because the private key never leaves the device, device signers are **client-side only** and cannot be used directly with the REST API.

            <Warning>
              Crossmint recommends using the React, React Native, or Swift SDK for device signer flows. The SDK handles device key generation, storage, and signing automatically.
            </Warning>

            See the [Device Signer guide](/wallets/guides/signers/device-signer) for setup instructions.
          </Tab>

          <Tab title="External Wallet">
            For [External Wallet](/wallets/guides/signers/add-signers) signers, you must manually sign the approval message and submit it via the API. The response from Step 1 includes a pending approval with a `message` field that must be signed exactly as returned.

            From the previous step's response, extract:

            * `id` - The transaction ID (used in the next step)
            * `approvals.pending[0].message` - The hex message to sign

            Sign the message using your external wallet. The message is a raw hex string and must be signed exactly as returned. Here's an example using an EVM wallet with [Viem](https://viem.sh/):

            ```typescript theme={null}
            import { privateKeyToAccount } from "viem/accounts";

            // The message from tx.approvals.pending[0].message
            const messageToSign = "<messageFromResponse>";

            // Sign the message exactly as returned (raw hex)
            const account = privateKeyToAccount(`0x${"<privateKey>"}`);
            const signature = await account.signMessage({
                message: { raw: messageToSign },
            });
            ```
          </Tab>

          <Tab title="Email and Phone">
            [Email and phone](/wallets/guides/recovery/configure-recovery) signers require client-side OTP verification and key derivation, which the Crossmint SDK handles automatically. While REST API signing is technically possible, you still need client-side SDK integration for the signing step.

            <Warning>
              Crossmint recommends using the React, React Native, Swift, or Node.js SDK examples instead. The SDK handles the full signing flow for email and phone signers.
            </Warning>
          </Tab>

          <Tab title="Passkey">
            [Passkey](/wallets/guides/signers/add-signers) signers use WebAuthn for biometric or password manager authentication, which requires browser interaction. While REST API signing is technically possible, Crossmint does not recommend it because you would still need client-side SDK integration for the WebAuthn signing step.

            <Warning>
              Crossmint recommends using the React, React Native, Swift, or Node.js SDK examples instead. The SDK handles the full passkey signing flow automatically.
            </Warning>
          </Tab>
        </Tabs>
      </Step>

      <Step title="Submit the approval">
        <Note>
          Skip this step if using the **SDK with a server signer** — the SDK handles signing and approval automatically.
        </Note>

        Call the [approve transaction](/api-reference/wallets/approve-transaction) endpoint with the signature from Step 2 and the transaction ID from Step 1. Set `approvals[].signer` to the locator of the signer or recovery method that produced the signature.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions/<txId>/approvals \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: <x-api-key>' \
              --data '{
                  "approvals": [{
                      "signer": "external-wallet:<externalWalletAddress>",
                      "signature": "<signature>"
                  }]
              }'
          ```

          ```js Node.js theme={null}
          const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions/<txId>/approvals';

          const payload = {
              approvals: [{
                  signer: "external-wallet:<externalWalletAddress>",
                  signature: "<signature>"
              }]
          };

          const options = {
              method: 'POST',
              headers: {
                  'X-API-KEY': '<x-api-key>',
                  'Content-Type': 'application/json'
              },
              body: JSON.stringify(payload)
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions/<txId>/approvals"

          payload = {
              "approvals": [{
                  "signer": "external-wallet:<externalWalletAddress>",
                  "signature": "<signature>"
              }]
          }
          headers = {
              "X-API-KEY": "<x-api-key>",
              "Content-Type": "application/json"
          }

          response = requests.post(url, json=payload, headers=headers)

          print(response.json())
          ```
        </CodeGroup>

        See the [API reference](/api-reference/wallets/approve-transaction) for more details.
      </Step>
    </Steps>
  </Tab>
</Tabs>


# Custom Solana Transactions
Source: https://docs.crossmint.com/wallets/guides/send-transaction-solana

Send arbitrary Solana versioned transactions from a Crossmint wallet

## Prerequisites

* Ensure you have a wallet created.
* **Signer**: The signing wallet must be registered as a signer on the wallet. You can do this [at wallet creation](/wallets/guides/create-wallet) by passing `signers`, or afterward by [adding a signer](/wallets/guides/signers/add-signers).
* **API Key**: Ensure you have an API key with the scopes: `wallets:transactions.create`.

## What is sending a custom transaction?

Sending a custom transaction lets you interact with any smart contract on the blockchain beyond simple transfers. Common use cases include minting free tokens, claiming rewards, or registering for allowlists—all without needing to manage private keys yourself.

## Sending a Transaction

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet, SolanaWallet } from '@crossmint/client-sdk-react-ui';

    const { wallet } = useWallet();

    const solanaWallet = SolanaWallet.from(wallet);

    const { hash, explorerLink } = await solanaWallet.sendTransaction({
        transaction: versionedTransaction,
        additionalSigners: additionalSigners,
    });
    ```

    See the [React SDK reference](/sdk-reference/wallets/react/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { CrossmintWallets, createCrossmint, SolanaWallet } from "@crossmint/wallets-sdk";

    const SERVER_API_KEY = process.env.SERVER_API_KEY!;
    const CROSSMINT_SIGNER_SECRET = process.env.CROSSMINT_SIGNER_SECRET!;
    // Replace with your wallet address
    const WALLET_ADDRESS = "YOUR_WALLET_ADDRESS";

    const crossmint = createCrossmint({
        apiKey: SERVER_API_KEY,
    });

    const crossmintWallets = CrossmintWallets.from(crossmint);

    const wallet = await crossmintWallets.getWallet(
        WALLET_ADDRESS,
        { chain: "solana" }
    );

    await wallet.useSigner({ type: "server", secret: CROSSMINT_SIGNER_SECRET });

    const solanaWallet = SolanaWallet.from(wallet);

    try {
        const { hash, explorerLink } = await solanaWallet.sendTransaction({
            transaction: versionedTransaction, // your VersionedTransaction instance
        });
        console.log("Transaction sent:", hash, explorerLink);
    } catch (error) {
        console.error("Failed to send transaction:", error);
        throw error;
    }
    ```

    See the [SDK reference](/sdk-reference/wallets/typescript/classes/SolanaWallet#sendtransaction) for all parameters and return types.
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { useWallet, SolanaWallet } from '@crossmint/client-sdk-react-native-ui';

    const { wallet } = useWallet();

    const solanaWallet = SolanaWallet.from(wallet);

    const { hash, explorerLink } = await solanaWallet.sendTransaction({
        transaction: versionedTransaction,
        additionalSigners: additionalSigners,
    });
    ```

    See the [React Native SDK reference](/sdk-reference/wallets/react-native/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="Flutter">
    ```dart theme={null}
    import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

    final controller = CrossmintWalletContext.of(context).requireWalletController;
    final solanaWallet = controller.createSolanaWallet();

    // Pass the base64-encoded serialized VersionedTransaction.
    final tx = await solanaWallet.sendTransaction(
      CrossmintSolanaTransactionRequest(
        serializedTransaction: serializedTransactionBase64,
      ),
    );
    print('Transaction: ${tx.id}');
    ```

    See the [Flutter SDK reference](/sdk-reference/wallets/flutter/controllers#wallet-methods) for more details.
  </Tab>

  <Tab title="REST">
    Transactions must be approved by one of the wallet's [signers](/wallets/concepts/signers).
    The SDK handles this automatically, but with the REST API you must [approve the transaction](/api-reference/wallets/approve-transaction) to complete it.

    <Steps>
      <Step title="Create the transaction">
        Call the [create transaction](/api-reference/wallets/create-transaction) endpoint.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets/<wallet-locator>/transactions \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: YOUR_API_KEY' \
              --data '{
                  "params": {
                      "transaction": "AQAAAAAAAAAAAAA...",
                      "signer": "server:YOUR_SERVER_SIGNER_ADDRESS"
                  }
              }'
          ```

          ```js Node.js theme={null}
          // Replace with your wallet locator
          const WALLET_LOCATOR = "YOUR_WALLET_LOCATOR";
          const url = `https://staging.crossmint.com/api/2025-06-09/wallets/${WALLET_LOCATOR}/transactions`;

          const SERVER_API_KEY = process.env.SERVER_API_KEY;
          // Replace with your server signer address
          const SIGNER_ADDRESS = "YOUR_SERVER_SIGNER_ADDRESS";

          const payload = {
              params: {
                  transaction: "AQAAAAAAAAAAAAA...",
                  signer: `server:${SIGNER_ADDRESS}`
              }
          };

          const options = {
              method: 'POST',
              headers: {
                  'X-API-KEY': SERVER_API_KEY,
                  'Content-Type': 'application/json'
              },
              body: JSON.stringify(payload)
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```python Python theme={null}
          import os
          import requests

          SERVER_API_KEY = os.environ["SERVER_API_KEY"]
          # Replace with your wallet locator
          WALLET_LOCATOR = "YOUR_WALLET_LOCATOR"
          # Replace with your server signer address
          SIGNER_ADDRESS = "YOUR_SERVER_SIGNER_ADDRESS"

          url = f"https://staging.crossmint.com/api/2025-06-09/wallets/{WALLET_LOCATOR}/transactions"

          payload = {
              "params": {
                  "transaction": "AQAAAAAAAAAAAAA...",
                  "signer": f"server:{SIGNER_ADDRESS}"
              }
          }
          headers = {
              "X-API-KEY": SERVER_API_KEY,
              "Content-Type": "application/json"
          }

          response = requests.post(url, json=payload, headers=headers)

          print(response.json())
          ```
        </CodeGroup>

        See the [API reference](/api-reference/wallets/create-transaction) for more details.
      </Step>

      <Step title="Choose your signer type">
        The next steps depend on which signer type you specified in the previous step.

        <Tabs>
          <Tab title="Server Signer">
            [Server](/wallets/guides/signers/server-signer) signers derive a private key from your signer secret using HKDF-SHA256 and sign transactions locally.

            When using the **SDK**, signing and approval are handled automatically — no additional steps are needed.

            When using the **REST API** directly, you must:

            1. Derive the signing key from your signer secret (scoped to your project, environment, and chain type). See the <a href="https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/server/helpers/derive-server-signer.ts">derive-server-signer helper</a> for a reference implementation.
            2. Sign the approval message returned from the transaction creation step.
            3. Submit the signature via the [approve transaction](/api-reference/wallets/approve-transaction) endpoint.

            <Warning>
              Crossmint recommends using the <a href="https://www.npmjs.com/package/@crossmint/wallets-sdk">Wallets SDK</a> for server signer flows. The SDK handles key derivation and signing automatically.
            </Warning>

            See the [Server Signer guide](/wallets/guides/signers/server-signer) for full configuration and setup details.
          </Tab>

          <Tab title="Device Signer">
            [Device](/wallets/guides/signers/device-signer) signers generate a P256 keypair inside the device's secure hardware (Secure Enclave, Android Keystore, or browser Web Crypto API). Because the private key never leaves the device, device signers are **client-side only** and cannot be used directly with the REST API.

            <Warning>
              Crossmint recommends using the React, React Native, or Swift SDK for device signer flows. The SDK handles device key generation, storage, and signing automatically.
            </Warning>

            See the [Device Signer guide](/wallets/guides/signers/device-signer) for setup instructions.
          </Tab>

          <Tab title="External Wallet">
            For [External Wallet](/wallets/guides/signers/add-signers) signers, you must manually sign the approval message and submit it via the API. The response from Step 1 includes a pending approval with a `message` field that must be signed exactly as returned.

            From the previous step's response, extract:

            * `id` - The transaction ID (used in the next step)
            * `approvals.pending[0].message` - The hex message to sign

            Sign the message using your external wallet. The message is a raw hex string and must be signed exactly as returned. Here's an example using an EVM wallet with [Viem](https://viem.sh/):

            ```typescript theme={null}
            import { privateKeyToAccount } from "viem/accounts";

            // The message from tx.approvals.pending[0].message
            const messageToSign = "<messageFromResponse>";

            // Sign the message exactly as returned (raw hex)
            const account = privateKeyToAccount(`0x${"<privateKey>"}`);
            const signature = await account.signMessage({
                message: { raw: messageToSign },
            });
            ```
          </Tab>

          <Tab title="Email and Phone">
            [Email and phone](/wallets/guides/recovery/configure-recovery) signers require client-side OTP verification and key derivation, which the Crossmint SDK handles automatically. While REST API signing is technically possible, you still need client-side SDK integration for the signing step.

            <Warning>
              Crossmint recommends using the React, React Native, Swift, or Node.js SDK examples instead. The SDK handles the full signing flow for email and phone signers.
            </Warning>
          </Tab>

          <Tab title="Passkey">
            [Passkey](/wallets/guides/signers/add-signers) signers use WebAuthn for biometric or password manager authentication, which requires browser interaction. While REST API signing is technically possible, Crossmint does not recommend it because you would still need client-side SDK integration for the WebAuthn signing step.

            <Warning>
              Crossmint recommends using the React, React Native, Swift, or Node.js SDK examples instead. The SDK handles the full passkey signing flow automatically.
            </Warning>
          </Tab>
        </Tabs>
      </Step>

      <Step title="Submit the approval">
        <Note>
          Skip this step if using the **SDK with a server signer** — the SDK handles signing and approval automatically.
        </Note>

        Call the [approve transaction](/api-reference/wallets/approve-transaction) endpoint with the signature from Step 2 and the transaction ID from Step 1. Set `approvals[].signer` to the locator of the signer or recovery method that produced the signature.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions/<txId>/approvals \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: <x-api-key>' \
              --data '{
                  "approvals": [{
                      "signer": "external-wallet:<externalWalletAddress>",
                      "signature": "<signature>"
                  }]
              }'
          ```

          ```js Node.js theme={null}
          const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions/<txId>/approvals';

          const payload = {
              approvals: [{
                  signer: "external-wallet:<externalWalletAddress>",
                  signature: "<signature>"
              }]
          };

          const options = {
              method: 'POST',
              headers: {
                  'X-API-KEY': '<x-api-key>',
                  'Content-Type': 'application/json'
              },
              body: JSON.stringify(payload)
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions/<txId>/approvals"

          payload = {
              "approvals": [{
                  "signer": "external-wallet:<externalWalletAddress>",
                  "signature": "<signature>"
              }]
          }
          headers = {
              "X-API-KEY": "<x-api-key>",
              "Content-Type": "application/json"
          }

          response = requests.post(url, json=payload, headers=headers)

          print(response.json())
          ```
        </CodeGroup>

        See the [API reference](/api-reference/wallets/approve-transaction) for more details.
      </Step>
    </Steps>
  </Tab>
</Tabs>


# Custom Stellar Transactions
Source: https://docs.crossmint.com/wallets/guides/send-transaction-stellar

Send arbitrary Soroban contract calls from a Crossmint wallet

## Prerequisites

* Ensure you have a wallet created.
* **Signer**: The signing wallet must be registered as a signer on the wallet. You can do this [at wallet creation](/wallets/guides/create-wallet) by passing `signers`, or afterward by [adding a signer](/wallets/guides/signers/add-signers).
* **API Key**: Ensure you have an API key with the scopes: `wallets:transactions.create`.

## What is sending a custom transaction?

Sending a custom transaction lets you interact with any smart contract on the blockchain beyond simple transfers. Common use cases include minting free tokens, claiming rewards, or registering for allowlists—all without needing to manage private keys yourself.

## Sending a contract call transaction

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet, StellarWallet } from '@crossmint/client-sdk-react-ui';

    const { wallet } = useWallet();

    const stellarWallet = StellarWallet.from(wallet);

    const { hash, explorerLink } = await stellarWallet.sendTransaction({
        contractId: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
        method: "transfer",
        args: {
            to: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
            from: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
            amount: "1000000000000000000"
        }
    });
    ```

    See the [React SDK reference](/sdk-reference/wallets/react/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { CrossmintWallets, createCrossmint, StellarWallet } from "@crossmint/wallets-sdk";

    const SERVER_API_KEY = process.env.SERVER_API_KEY!;
    const CROSSMINT_SIGNER_SECRET = process.env.CROSSMINT_SIGNER_SECRET!;
    // Replace with your wallet address
    const WALLET_ADDRESS = "YOUR_WALLET_ADDRESS";

    const crossmint = createCrossmint({
        apiKey: SERVER_API_KEY,
    });

    const crossmintWallets = CrossmintWallets.from(crossmint);

    const wallet = await crossmintWallets.getWallet(
        WALLET_ADDRESS,
        { chain: "stellar" }
    );

    await wallet.useSigner({ type: "server", secret: CROSSMINT_SIGNER_SECRET });

    const stellarWallet = StellarWallet.from(wallet);

    try {
        const { hash, explorerLink } = await stellarWallet.sendTransaction({
            contractId: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
            method: "transfer",
            args: {
                to: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
                from: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
                amount: "1000000000000000000"
            }
        });
        console.log("Transaction sent:", hash, explorerLink);
    } catch (error) {
        console.error("Failed to send transaction:", error);
        throw error;
    }
    ```

    See the [SDK reference](/sdk-reference/wallets/typescript/classes/StellarWallet#sendtransaction) for all parameters and return types.
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { useWallet, StellarWallet } from '@crossmint/client-sdk-react-native-ui';

    const { wallet } = useWallet();

    const stellarWallet = StellarWallet.from(wallet);

    const { hash, explorerLink } = await stellarWallet.sendTransaction({
        contractId: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
        method: "transfer",
        args: {
            to: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
            from: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
            amount: "1000000000000000000"
        }
    });
    ```

    See the [React Native SDK reference](/sdk-reference/wallets/react-native/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="Swift">
    <Note>
      The Swift SDK sends raw Stellar transactions as a base64-encoded XDR string.
      Build and serialize the `Transaction` object using the <a href="https://github.com/Soneso/stellar-ios-mac-sdk">stellar-ios-mac-sdk</a>,
      then pass the resulting XDR string to `sendTransaction`.
    </Note>

    ```swift theme={null}
    import CrossmintClient
    import Wallet
    import stellarsdk

    CrossmintSDK.configure(apiKey: "<YOUR_API_KEY>")
    let sdk = CrossmintSDK.shared

    guard let wallet = try await sdk.crossmintWallets.getWallet(
        chain: StellarChain.stellar
    ) else {
        return
    }

    let stellarWallet = try StellarWallet.from(wallet: wallet)

    // Build a Stellar transaction using the stellar-ios-mac-sdk and serialize it to XDR.
    // Replace this with your own transaction construction logic.
    let stellarSDK = StellarSDK(withHorizonUrl: "https://horizon-testnet.stellar.org")
    let sourceAccount = try await stellarSDK.accounts.getAccountDetails(accountId: wallet.address)
    let destinationAccountId = "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J"
    let paymentOperation = try PaymentOperation(
        sourceAccountId: nil,
        destinationAccountId: destinationAccountId,
        asset: Asset(type: AssetType.ASSET_TYPE_NATIVE)!,
        amount: 10.0
    )
    let transaction = try Transaction(
        sourceAccount: sourceAccount,
        operations: [paymentOperation],
        memo: Memo.none
    )

    // Serialize to base64 XDR
    let transactionXDR = try transaction.encodedEnvelope()

    let result = try await stellarWallet.sendTransaction(transaction: transactionXDR)
    print("Transaction hash: \(result.hash)")
    ```

    ### Parameters

    <ParamField type="String">
      A base64-encoded XDR envelope of the serialized Stellar transaction.
    </ParamField>

    ### Returns

    <ParamField type="string">
      The on-chain transaction hash.
    </ParamField>
  </Tab>

  <Tab title="Flutter">
    ```dart theme={null}
    import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

    final controller = CrossmintWalletContext.of(context).requireWalletController;
    final stellarWallet = controller.createStellarWallet();

    final tx = await stellarWallet.sendTransaction(
      const CrossmintStellarContractCallRequest(
        contractId: 'GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J',
        method: 'transfer',
        args: <String, Object?>{
          'to': 'GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J',
          'from': 'GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J',
          'amount': '1000000000000000000',
        },
      ),
    );
    print('Transaction: ${tx.id}');
    ```

    See the [Flutter SDK reference](/sdk-reference/wallets/flutter/controllers#wallet-methods) for more details.
  </Tab>

  <Tab title="REST">
    Transactions must be approved by one of the wallet's [signers](/wallets/concepts/signers).
    The SDK handles this automatically, but with the REST API you must [approve the transaction](/api-reference/wallets/approve-transaction) to complete it.

    <Steps>
      <Step title="Create the transaction">
        Call the [create transaction](/api-reference/wallets/create-transaction) endpoint.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets/<wallet-locator>/transactions \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: YOUR_API_KEY' \
              --data '{
                  "params": {
                      "transaction": {
                          "type": "contract-call",
                          "contractId": "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
                          "method": "transfer",
                          "args": {
                              "to": "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
                              "from": "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
                              "amount": "1000000000000000000"
                          }
                      },
                      "signer": "server:YOUR_SERVER_SIGNER_ADDRESS"
                  }
              }'
          ```

          ```js Node.js theme={null}
          // Replace with your wallet locator
          const WALLET_LOCATOR = "YOUR_WALLET_LOCATOR";
          const url = `https://staging.crossmint.com/api/2025-06-09/wallets/${WALLET_LOCATOR}/transactions`;

          const SERVER_API_KEY = process.env.SERVER_API_KEY;
          // Replace with your server signer address
          const SIGNER_ADDRESS = "YOUR_SERVER_SIGNER_ADDRESS";

          const payload = {
              params: {
                  transaction: {
                      type: "contract-call",
                      contractId: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
                      method: "transfer",
                      args: {
                          to: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
                          from: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
                          amount: "1000000000000000000"
                      }
                  },
                  signer: `server:${SIGNER_ADDRESS}`
              }
          };

          const options = {
              method: 'POST',
              headers: {
                  'X-API-KEY': SERVER_API_KEY,
                  'Content-Type': 'application/json'
              },
              body: JSON.stringify(payload)
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```python Python theme={null}
          import os
          import requests

          SERVER_API_KEY = os.environ["SERVER_API_KEY"]
          # Replace with your wallet locator
          WALLET_LOCATOR = "YOUR_WALLET_LOCATOR"
          # Replace with your server signer address
          SIGNER_ADDRESS = "YOUR_SERVER_SIGNER_ADDRESS"

          url = f"https://staging.crossmint.com/api/2025-06-09/wallets/{WALLET_LOCATOR}/transactions"

          payload = {
              "params": {
                  "transaction": {
                      "type": "contract-call",
                      "contractId": "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
                      "method": "transfer",
                      "args": {
                          "to": "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
                          "from": "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
                          "amount": "1000000000000000000"
                      }
                  },
                  "signer": f"server:{SIGNER_ADDRESS}"
              }
          }
          headers = {
              "X-API-KEY": SERVER_API_KEY,
              "Content-Type": "application/json"
          }

          response = requests.post(url, json=payload, headers=headers)

          print(response.json())
          ```
        </CodeGroup>

        See the [API reference](/api-reference/wallets/create-transaction) for more details.
      </Step>

      <Step title="Choose your signer type">
        The next steps depend on which signer type you specified in the previous step.

        <Tabs>
          <Tab title="Server Signer">
            [Server](/wallets/guides/signers/server-signer) signers derive a private key from your signer secret using HKDF-SHA256 and sign transactions locally.

            When using the **SDK**, signing and approval are handled automatically — no additional steps are needed.

            When using the **REST API** directly, you must:

            1. Derive the signing key from your signer secret (scoped to your project, environment, and chain type). See the <a href="https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/server/helpers/derive-server-signer.ts">derive-server-signer helper</a> for a reference implementation.
            2. Sign the approval message returned from the transaction creation step.
            3. Submit the signature via the [approve transaction](/api-reference/wallets/approve-transaction) endpoint.

            <Warning>
              Crossmint recommends using the <a href="https://www.npmjs.com/package/@crossmint/wallets-sdk">Wallets SDK</a> for server signer flows. The SDK handles key derivation and signing automatically.
            </Warning>

            See the [Server Signer guide](/wallets/guides/signers/server-signer) for full configuration and setup details.
          </Tab>

          <Tab title="Device Signer">
            [Device](/wallets/guides/signers/device-signer) signers generate a P256 keypair inside the device's secure hardware (Secure Enclave, Android Keystore, or browser Web Crypto API). Because the private key never leaves the device, device signers are **client-side only** and cannot be used directly with the REST API.

            <Warning>
              Crossmint recommends using the React, React Native, or Swift SDK for device signer flows. The SDK handles device key generation, storage, and signing automatically.
            </Warning>

            See the [Device Signer guide](/wallets/guides/signers/device-signer) for setup instructions.
          </Tab>

          <Tab title="External Wallet">
            For [External Wallet](/wallets/guides/signers/add-signers) signers, you must manually sign the approval message and submit it via the API. The response from Step 1 includes a pending approval with a `message` field that must be signed exactly as returned.

            From the previous step's response, extract:

            * `id` - The transaction ID (used in the next step)
            * `approvals.pending[0].message` - The hex message to sign

            Sign the message using your external wallet. The message is a raw hex string and must be signed exactly as returned. Here's an example using an EVM wallet with [Viem](https://viem.sh/):

            ```typescript theme={null}
            import { privateKeyToAccount } from "viem/accounts";

            // The message from tx.approvals.pending[0].message
            const messageToSign = "<messageFromResponse>";

            // Sign the message exactly as returned (raw hex)
            const account = privateKeyToAccount(`0x${"<privateKey>"}`);
            const signature = await account.signMessage({
                message: { raw: messageToSign },
            });
            ```
          </Tab>

          <Tab title="Email and Phone">
            [Email and phone](/wallets/guides/recovery/configure-recovery) signers require client-side OTP verification and key derivation, which the Crossmint SDK handles automatically. While REST API signing is technically possible, you still need client-side SDK integration for the signing step.

            <Warning>
              Crossmint recommends using the React, React Native, Swift, or Node.js SDK examples instead. The SDK handles the full signing flow for email and phone signers.
            </Warning>
          </Tab>

          <Tab title="Passkey">
            [Passkey](/wallets/guides/signers/add-signers) signers use WebAuthn for biometric or password manager authentication, which requires browser interaction. While REST API signing is technically possible, Crossmint does not recommend it because you would still need client-side SDK integration for the WebAuthn signing step.

            <Warning>
              Crossmint recommends using the React, React Native, Swift, or Node.js SDK examples instead. The SDK handles the full passkey signing flow automatically.
            </Warning>
          </Tab>
        </Tabs>
      </Step>

      <Step title="Submit the approval">
        <Note>
          Skip this step if using the **SDK with a server signer** — the SDK handles signing and approval automatically.
        </Note>

        Call the [approve transaction](/api-reference/wallets/approve-transaction) endpoint with the signature from Step 2 and the transaction ID from Step 1. Set `approvals[].signer` to the locator of the signer or recovery method that produced the signature.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions/<txId>/approvals \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: <x-api-key>' \
              --data '{
                  "approvals": [{
                      "signer": "external-wallet:<externalWalletAddress>",
                      "signature": "<signature>"
                  }]
              }'
          ```

          ```js Node.js theme={null}
          const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions/<txId>/approvals';

          const payload = {
              approvals: [{
                  signer: "external-wallet:<externalWalletAddress>",
                  signature: "<signature>"
              }]
          };

          const options = {
              method: 'POST',
              headers: {
                  'X-API-KEY': '<x-api-key>',
                  'Content-Type': 'application/json'
              },
              body: JSON.stringify(payload)
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions/<txId>/approvals"

          payload = {
              "approvals": [{
                  "signer": "external-wallet:<externalWalletAddress>",
                  "signature": "<signature>"
              }]
          }
          headers = {
              "X-API-KEY": "<x-api-key>",
              "Content-Type": "application/json"
          }

          response = requests.post(url, json=payload, headers=headers)

          print(response.json())
          ```
        </CodeGroup>

        See the [API reference](/api-reference/wallets/approve-transaction) for more details.
      </Step>
    </Steps>
  </Tab>
</Tabs>


# Sign Messages
Source: https://docs.crossmint.com/wallets/guides/sign-message

Sign messages and typed data from a Crossmint wallet

<Tabs>
  <Tab title="EVM">
    ## Prerequisites

    * Ensure you have a wallet created.
    * **API Key**: Ensure you have an API key with the scopes: `wallets:signatures.create`.

    <Warning>
      If you are signing with an [operational signer](/wallets/guides/signers/add-signers), the wallet must have executed at least one transaction before signatures will work. This is because the wallet needs to be deployed onchain first.
    </Warning>

    ## Signing a Message

    <Tabs>
      <Tab title="React">
        ```typescript theme={null}
        import { useWallet, EVMWallet } from '@crossmint/client-sdk-react-ui';

        const { wallet } = useWallet();

        const evmWallet = EVMWallet.from(wallet);

        const signedMessage = await evmWallet.signMessage({ message: "Hello, world!" });
        ```

        See the [React SDK reference](/sdk-reference/wallets/react/hooks#wallet-methods) for more details.
      </Tab>

      <Tab title="Node.js">
        ```typescript theme={null}
        import { CrossmintWallets, createCrossmint, EVMWallet } from "@crossmint/wallets-sdk";

        const crossmint = createCrossmint({
            apiKey: "<your-server-api-key>",
        });

        const crossmintWallets = CrossmintWallets.from(crossmint);

        const wallet = await crossmintWallets.getWallet(
            "email:user@example.com:evm",
            { chain: "base-sepolia" }
        );

        await wallet.useSigner({ type: "email", email: "user@example.com" });

        const evmWallet = EVMWallet.from(wallet);

        const signedMessage = await evmWallet.signMessage({ message: "Hello, world!" });
        ```

        ### Parameters

        <ParamField type="string">
          The message to sign.
        </ParamField>

        ### Returns

        <ParamField type="string">
          The signature of the message.
        </ParamField>
      </Tab>

      <Tab title="React Native">
        ```typescript theme={null}
        import { useWallet, EVMWallet } from '@crossmint/client-sdk-react-native-ui';

        const { wallet } = useWallet();

        const evmWallet = EVMWallet.from(wallet);

        const signedMessage = await evmWallet.signMessage({ message: "Hello, world!" });
        ```

        See the [React Native SDK reference](/sdk-reference/wallets/react-native/hooks#wallet-methods) for more details.
      </Tab>

      <Tab title="Kotlin">
        ```kotlin theme={null}
        import com.crossmint.kotlin.CrossmintSDK
        import com.crossmint.kotlin.types.EVMChain
        import com.crossmint.kotlin.types.getOrThrow

        CrossmintSDK.configure(apiKey = "YOUR_CROSSMINT_API_KEY")
        val sdk = CrossmintSDK.shared
        val wallet = sdk.wallets.getWallet(chain = EVMChain.BaseSepolia).getOrThrow()

        val signature = wallet.signMessage("Hello, world!").getOrThrow()
        println("Signature: $signature")
        ```
      </Tab>

      <Tab title="Swift">
        ```swift theme={null}
        import CrossmintClient
        import Wallet

        CrossmintSDK.configure(apiKey: "<YOUR_API_KEY>")
        let sdk = CrossmintSDK.shared

        guard let wallet = try await sdk.crossmintWallets.getWallet(
            chain: .baseSepolia
        ) else {
            return
        }

        let evmWallet = try EVMWallet.from(wallet: wallet)

        let signature = try await evmWallet.signMessage("Hello, world!")
        ```

        ### Parameters

        <ParamField type="string">
          The message to sign.
        </ParamField>

        ### Returns

        <ParamField type="string">
          The signature of the message.
        </ParamField>
      </Tab>

      <Tab title="Flutter">
        ```dart theme={null}
        import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

        final controller = CrossmintWalletContext.of(context).requireWalletController;
        final evmWallet = controller.createEvmWallet();

        final signature = await evmWallet.signMessage('Hello, world!');
        ```

        See the [Flutter SDK reference](/sdk-reference/wallets/flutter/controllers#wallet-methods) for more details.
      </Tab>

      <Tab title="REST">
        Signatures must be approved by one of the wallet's [signers](/wallets/concepts/signers).
        The SDK handles this automatically, but with the REST API you must [approve the signature](/api-reference/wallets/approve-signature) to complete it.

        <Steps>
          <Step title="Create the signature">
            Call the [create signature](/api-reference/wallets/create-signature) endpoint.

            <CodeGroup>
              ```bash cURL theme={null}
              curl --request POST \
                  --url https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/signatures \
                  --header 'Content-Type: application/json' \
                  --header 'X-API-KEY: <x-api-key>' \
                  --data '{
                      "type": "message",
                      "params": {
                          "message": "Hello, world!",
                          "signer": "email:user@example.com",
                          "chain": "base-sepolia"
                      }
                  }'
              ```

              ```js Node.js theme={null}
              const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/signatures';

              const payload = {
                  type: "message",
                  params: {
                      message: "Hello, world!",
                      signer: "email:user@example.com",
                      chain: "base-sepolia"
                  }
              };

              const options = {
                  method: 'POST',
                  headers: {
                      'X-API-KEY': '<x-api-key>',
                      'Content-Type': 'application/json'
                  },
                  body: JSON.stringify(payload)
              };

              try {
                  const response = await fetch(url, options);
                  const data = await response.json();
                  console.log(data);
              } catch (error) {
                  console.error(error);
              }
              ```

              ```python Python theme={null}
              import requests

              url = "https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/signatures"

              payload = {
                  "type": "message",
                  "params": {
                      "message": "Hello, world!",
                      "signer": "email:user@example.com",
                      "chain": "base-sepolia"
                  }
              }
              headers = {
                  "X-API-KEY": "<x-api-key>",
                  "Content-Type": "application/json"
              }

              response = requests.post(url, json=payload, headers=headers)

              print(response.json())
              ```
            </CodeGroup>

            See the [API reference](/api-reference/wallets/create-signature) for more details.
          </Step>

          <Step title="Sign the approval returned in the response">
            <Note>
              If you are using an `api-key` recovery method, you can skip the following steps.
            </Note>

            Sign the message returned in `signature.approvals` with the signer selected when creating the signature. When you submit the approval, set `approvals[].signer` to that signer's locator.
          </Step>

          <Step title="Approve the signature">
            Call the [approve signature](/api-reference/wallets/approve-signature) endpoint using the signature from the previous step and the signature id returned in the call from Step 1.

            <CodeGroup>
              ```bash cURL theme={null}
              curl --request POST \
                  --url https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/signatures/91e90094-9fe0-43a7-bab6-e5725767a3ad/approvals \
                  --header 'Content-Type: application/json' \
                  --header 'X-API-KEY: <x-api-key>' \
                  --data '{
                      "approvals": [{
                          "signer": "email:user@example.com",
                          "signature": "0x1234567890abcdef..."
                      }]
                  }'
              ```

              ```js Node.js theme={null}
              const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/signatures/91e90094-9fe0-43a7-bab6-e5725767a3ad/approvals';

              const payload = {
                  approvals: [{
                      signer: "email:user@example.com",
                      signature: "0x1234567890abcdef..."
                  }]
              };

              const options = {
                  method: 'POST',
                  headers: {
                      'X-API-KEY': '<x-api-key>',
                      'Content-Type': 'application/json'
                  },
                  body: JSON.stringify(payload)
              };

              try {
                  const response = await fetch(url, options);
                  const data = await response.json();
                  console.log(data);
              } catch (error) {
                  console.error(error);
              }
              ```

              ```python Python theme={null}
              import requests

              url = "https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/signatures/91e90094-9fe0-43a7-bab6-e5725767a3ad/approvals"

              payload = {
                  "approvals": [{
                      "signer": "email:user@example.com",
                      "signature": "0x1234567890abcdef..."
                  }]
              }
              headers = {
                  "X-API-KEY": "<x-api-key>",
                  "Content-Type": "application/json"
              }

              response = requests.post(url, json=payload, headers=headers)

              print(response.json())
              ```
            </CodeGroup>

            See the [API reference](/api-reference/wallets/approve-signature) for more details.
          </Step>
        </Steps>
      </Tab>
    </Tabs>

    ## Signing Typed Data

    <Tabs>
      <Tab title="React">
        ```typescript theme={null}
        import { useWallet, EVMWallet } from '@crossmint/client-sdk-react-ui';

        const { wallet } = useWallet();

        const evmWallet = EVMWallet.from(wallet);
        const typedData = {
            "types": {
                "EIP712Domain": [{
                    "name": "name",
                    "type": "string"
                }],
            },
            "primaryType": "Mail",
            "domain": {
                "name": "example.com",
                "version": "1"
            },
            "message": {
                "from": {
                    "name": "John Doe"
                },
                "to": {
                    "name": "Jane Doe"
                },
                "contents": "Hello, world!"
            }
        };
        const signedMessage = await evmWallet.signTypedData(typedData);
        ```

        See the [React SDK reference](/sdk-reference/wallets/react/hooks#wallet-methods) for more details.
      </Tab>

      <Tab title="Node.js">
        ```typescript theme={null}
        import { CrossmintWallets, createCrossmint, EVMWallet } from "@crossmint/wallets-sdk";

        const crossmint = createCrossmint({
            apiKey: "<your-server-api-key>",
        });

        const crossmintWallets = CrossmintWallets.from(crossmint);

        const wallet = await crossmintWallets.getWallet(
            "email:user@example.com:evm",
            { chain: "base-sepolia" }
        );

        await wallet.useSigner({ type: "email", email: "user@example.com" });

        const evmWallet = EVMWallet.from(wallet);

        const typedData = {
            "types": {
                "EIP712Domain": [{
                    "name": "name",
                    "type": "string"
                }],
            },
            "primaryType": "Mail",
            "domain": {
                "name": "example.com",
                "version": "1"
            },
            "message": {
                "from": {
                    "name": "John Doe"
                },
                "to": {
                    "name": "Jane Doe"
                },
                "contents": "Hello, world!"
            }
        };
        const signedMessage = await evmWallet.signTypedData(typedData);
        ```
      </Tab>

      <Tab title="React Native">
        ```typescript theme={null}
        import { useWallet, EVMWallet } from '@crossmint/client-sdk-react-native-ui';

        const { wallet } = useWallet();

        const evmWallet = EVMWallet.from(wallet);

        const typedData = {
            "types": {
                "EIP712Domain": [{
                    "name": "name",
                    "type": "string"
                }],
            },
            "primaryType": "Mail",
            "domain": {
                "name": "example.com",
                "version": "1"
            },
            "message": {
                "from": {
                    "name": "John Doe"
                },
                "to": {
                    "name": "Jane Doe"
                },
                "contents": "Hello, world!"
            }
        };
        const signedMessage = await evmWallet.signTypedData(typedData);
        ```

        See the [React Native SDK reference](/sdk-reference/wallets/react-native/hooks#wallet-methods) for more details.
      </Tab>

      <Tab title="Kotlin">
        ```kotlin theme={null}
        import com.crossmint.kotlin.CrossmintSDK
        import com.crossmint.kotlin.types.EVMChain
        import com.crossmint.kotlin.types.getOrThrow

        CrossmintSDK.configure(apiKey = "YOUR_CROSSMINT_API_KEY")
        val sdk = CrossmintSDK.shared
        val wallet = sdk.wallets.getWallet(chain = EVMChain.BaseSepolia).getOrThrow()

        val typedDataJson = """
            {
                "types": {
                    "EIP712Domain": [{ "name": "name", "type": "string" }],
                    "Person": [
                        { "name": "name", "type": "string" }
                    ],
                    "Mail": [
                        { "name": "from", "type": "Person" },
                        { "name": "to", "type": "Person" },
                        { "name": "contents", "type": "string" }
                    ]
                },
                "primaryType": "Mail",
                "domain": { "name": "example.com", "version": "1" },
                "message": {
                    "from": { "name": "John Doe" },
                    "to": { "name": "Jane Doe" },
                    "contents": "Hello, world!"
                }
            }
        """.trimIndent()

        val signature = wallet.signTypedData(typedDataJson).getOrThrow()
        println("Signature: $signature")
        ```
      </Tab>

      <Tab title="Swift">
        ```swift theme={null}
        import CrossmintClient
        import Wallet

        CrossmintSDK.configure(apiKey: "<YOUR_API_KEY>")
        let sdk = CrossmintSDK.shared

        guard let wallet = try await sdk.crossmintWallets.getWallet(
            chain: .baseSepolia
        ) else {
            return
        }

        let evmWallet = try EVMWallet.from(wallet: wallet)

        let typedData = EIP712.Builder()
            .withDomain(name: "example.com")
            .defineEIP712Domain(includeName: true, includeVersion: false, includeChainId: false, includeVerifyingContract: false)
            .defineType("Person") { fields in
                fields.string("name")
            }
            .defineType("Mail") { fields in
                fields
                    .structType("from", typeName: "Person")
                    .structType("to", typeName: "Person")
                    .string("contents")
            }
            .withPrimaryType("Mail")
            .withMessage([
                "from": ["name": "John Doe"],
                "to": ["name": "Jane Doe"],
                "contents": "Hello, world!"
            ])
            .build()
        guard let typedData else { return }
        let signature = try await evmWallet.signTypedData(typedData)
        ```

        ### Parameters

        <ParamField type="EIP712.TypedData">
          The typed data to sign, constructed using `EIP712.Builder`.
        </ParamField>

        ### Returns

        <ParamField type="string">
          The signature of the message.
        </ParamField>
      </Tab>

      <Tab title="Flutter">
        ```dart theme={null}
        import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

        final controller = CrossmintWalletContext.of(context).requireWalletController;
        final evmWallet = controller.createEvmWallet();

        final typedData = CrossmintTypedData(
          raw: const <String, Object?>{
            'types': <String, Object?>{
              'EIP712Domain': <Map<String, Object?>>[
                <String, Object?>{'name': 'name', 'type': 'string'},
              ],
            },
            'primaryType': 'Mail',
            'domain': <String, Object?>{
              'name': 'example.com',
              'version': '1',
              'chainId': 84532,
              'verifyingContract': '0x...',
            },
            'message': <String, Object?>{
              'from': <String, Object?>{'name': 'John Doe'},
              'to': <String, Object?>{'name': 'Jane Doe'},
              'contents': 'Hello, world!',
            },
          },
        );
        final signature = await evmWallet.signTypedData(typedData);
        ```

        See the [Flutter SDK reference](/sdk-reference/wallets/flutter/controllers#wallet-methods) for more details.
      </Tab>

      <Tab title="REST">
        Signatures must be approved by one of the wallet's [signers](/wallets/concepts/signers).
        The SDK handles this automatically, but with the REST API you must [approve the signature](/api-reference/wallets/approve-signature) to complete it.

        <Steps>
          <Step title="Create the signature">
            Call the [create signature](/api-reference/wallets/create-signature) endpoint.

            <CodeGroup>
              ```bash cURL theme={null}
              curl --request POST \
                  --url https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/signatures \
                  --header 'Content-Type: application/json' \
                  --header 'X-API-KEY: <x-api-key>' \
                  --data '{
                      "type": "typed-data",
                      "params": {
                          "typedData": {
                              "types": {
                                  "EIP712Domain": [{
                                      "name": "name",
                                      "type": "string"
                                  }],
                              },
                              "primaryType": "Mail",
                              "domain": {
                                  "name": "example.com",
                                  "version": "1"
                              },
                              "message": {
                                  "from": {
                                      "name": "John Doe"
                                  },
                                  "to": {
                                      "name": "Jane Doe"
                                  },
                                  "contents": "Hello, world!"
                              }
                          },
                          "signer": "email:user@example.com",
                          "chain": "base-sepolia"
                      }
                  }'
              ```

              ```js Node.js theme={null}
              const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/signatures';

              const payload = {
                  type: "typed-data",
                  params: {
                      typedData: {
                          types: {
                              EIP712Domain: [{
                                  name: "name",
                                  type: "string"
                              }]
                          },
                          primaryType: "Mail",
                          domain: {
                              name: "example.com",
                              version: "1"
                          },
                          message: {
                              from: {
                                  name: "John Doe"
                              },
                              to: {
                                  name: "Jane Doe"
                              },
                              contents: "Hello, world!"
                          }
                      },
                      signer: "email:user@example.com",
                      chain: "base-sepolia"
                  }
              };

              const options = {
                  method: 'POST',
                  headers: {
                      'X-API-KEY': '<x-api-key>',
                      'Content-Type': 'application/json'
                  },
                  body: JSON.stringify(payload)
              };

              try {
                  const response = await fetch(url, options);
                  const data = await response.json();
                  console.log(data);
              } catch (error) {
                  console.error(error);
              }
              ```

              ```python Python theme={null}
              import requests

              url = "https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/signatures"

              payload = {
                  "type": "typed-data",
                  "params": {
                      "typedData": {
                          "types": {
                              "EIP712Domain": [{
                                  "name": "name",
                                  "type": "string"
                              }],
                          },
                          "primaryType": "Mail",
                          "domain": {
                              "name": "example.com",
                              "version": "1"
                          },
                          "message": {
                              "from": {
                                  "name": "John Doe"
                              },
                              "to": {
                                  "name": "Jane Doe"
                              },
                              "contents": "Hello, world!"
                          }
                      },
                      "signer": "email:user@example.com",
                      "chain": "base-sepolia"
                  }
              }
              headers = {
                  "X-API-KEY": "<x-api-key>",
                  "Content-Type": "application/json"
              }

              response = requests.post(url, json=payload, headers=headers)

              print(response.json())
              ```
            </CodeGroup>

            See the [API reference](/api-reference/wallets/create-signature) for more details.
          </Step>

          <Step title="Sign the approval returned in the response">
            <Note>
              If you are using an `api-key` recovery method, you can skip the following steps.
            </Note>

            Sign the message returned in `signature.approvals` with the signer selected when creating the signature. When you submit the approval, set `approvals[].signer` to that signer's locator.
          </Step>

          <Step title="Approve the signature">
            Call the [approve signature](/api-reference/wallets/approve-signature) endpoint using the signature from the previous step and the signature id returned in the call from Step 1.

            <CodeGroup>
              ```bash cURL theme={null}
              curl --request POST \
                  --url https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/signatures/91e90094-9fe0-43a7-bab6-e5725767a3ad/approvals \
                  --header 'Content-Type: application/json' \
                  --header 'X-API-KEY: <x-api-key>' \
                  --data '{
                      "approvals": [{
                          "signer": "email:user@example.com",
                          "signature": "0x1234567890abcdef..."
                      }]
                  }'
              ```

              ```js Node.js theme={null}
              const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/signatures/91e90094-9fe0-43a7-bab6-e5725767a3ad/approvals';

              const payload = {
                  approvals: [{
                      signer: "email:user@example.com",
                      signature: "0x1234567890abcdef..."
                  }]
              };

              const options = {
                  method: 'POST',
                  headers: {
                      'X-API-KEY': '<x-api-key>',
                      'Content-Type': 'application/json'
                  },
                  body: JSON.stringify(payload)
              };

              try {
                  const response = await fetch(url, options);
                  const data = await response.json();
                  console.log(data);
              } catch (error) {
                  console.error(error);
              }
              ```

              ```python Python theme={null}
              import requests

              url = "https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/signatures/91e90094-9fe0-43a7-bab6-e5725767a3ad/approvals"

              payload = {
                  "approvals": [{
                      "signer": "email:user@example.com",
                      "signature": "0x1234567890abcdef..."
                  }]
              }
              headers = {
                  "X-API-KEY": "<x-api-key>",
                  "Content-Type": "application/json"
              }

              response = requests.post(url, json=payload, headers=headers)

              print(response.json())
              ```
            </CodeGroup>

            See the [API reference](/api-reference/wallets/approve-signature) for more details.
          </Step>
        </Steps>
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Solana">
    <Note>
      Signing messages is not yet supported for Solana wallets. To send a transaction instead, see the [Custom Solana Transactions](/wallets/guides/send-transaction-solana) guide.
    </Note>
  </Tab>

  <Tab title="Stellar">
    <Note>
      Signing messages is not yet supported for Stellar wallets. To send a transaction instead, see the [Custom Stellar Transactions](/wallets/guides/send-transaction-stellar) guide.
    </Note>
  </Tab>
</Tabs>


# Add Signers to a Wallet
Source: https://docs.crossmint.com/wallets/guides/signers/add-signers

Add signers to an existing wallet — passkeys, external wallets, device signers, email, and phone.

Use `addSigner()` to register additional operational signers on an existing wallet. One of the wallet's recovery methods must approve the operation — the SDK handles this automatically. A wallet with several recovery methods needs one selected with `useRecoveryMethod()` first; see [Manage Recovery Methods](/wallets/guides/recovery/manage-recovery-methods#select-the-authorizing-recovery-method).

## Prerequisites

* An existing wallet with a recovery method configured
* **API key** with `wallets:signatures.create` and `wallets:transactions.create` scopes

## How It Works

When you call `addSigner()`, the SDK:

1. Submits the new signer registration request
2. Temporarily activates the recovery method to approve the operation
3. After approval, restores the previously active signer

For client-side wallets with an email or phone recovery method, your user enters a one-time code to approve the new signer. When a server signer is the recovery method, approval happens automatically.

### Installation Timing

A signer must be installed onchain before it can sign. You can control when this happens. Set the `deployImmediately` option on `addSigner()`:

* Set `deployImmediately: true` to install the signer immediately. The recovery method approves an onchain registration transaction. The signer is ready to sign after that transaction confirms.
* Set `deployImmediately: false` to install the signer later. Registration records a signature request. The signer is installed on its first transaction.

```typescript theme={null}
const signer = await wallet.addSigner(
    { type: "external-wallet", address: "0x1234...abcd" },
    { deployImmediately: false }
);
```

When you use `prepareOnly: true`, the return value shows which approval endpoint to use. Approve a `transactionId` with the [approve transaction](/api-reference/wallets/approve-transaction) endpoint. Approve a `signatureId` with the [approve signature](/api-reference/wallets/approve-signature) endpoint.

This option is currently available on EVM through the TypeScript SDK, which installs the signer immediately by default. Solana and Stellar always install signers with an onchain transaction.

If you want to add restrictions to the signer (such as spending limits, recipient whitelists, or an expiry), see [Restrict a Signer with Scopes](/wallets/guides/signers/scopes).

## Add a Passkey Signer

Passkey signers use the WebAuthn/FIDO2 standard for biometric authentication. The user registers a passkey via a browser or platform authenticator prompt.

<Note>
  Passkey signers are supported on EVM, Solana, and Stellar. In React Native, configure the `passkeys` prop first; see [Passkey Signer](/wallets/guides/signers/passkey).
</Note>

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet } from "@crossmint/client-sdk-react-ui";

    const { wallet } = useWallet();

    const signer = await wallet.addSigner({ type: "passkey" });

    console.log("Passkey added:", signer.locator);
    ```

    After adding, activate the passkey for signing:

    ```typescript theme={null}
    wallet.useSigner({ type: "passkey" });

    const { hash } = await wallet.send(
        "0xRecipientAddress",
        "usdc",
        "10"
    );
    ```
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import {
        createCrossmint,
        CrossmintWallets,
    } from "@crossmint/wallets-sdk";

    const crossmint = createCrossmint({
        apiKey: "YOUR_SERVER_API_KEY",
    });
    const crossmintWallets = CrossmintWallets.from(crossmint);

    const wallet = await crossmintWallets.getWallet(
        "<wallet-address>",
        { chain: "base-sepolia" }
    );

    await wallet.useSigner({
        type: "server",
        secret: process.env.CROSSMINT_SIGNER_SECRET,
    });

    const signer = await wallet.addSigner({ type: "passkey" });

    console.log("Passkey added:", signer.locator);
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    import CrossmintClient

    @MainActor
    func addPasskeySigner() async throws {
        guard let wallet = try await CrossmintSDK.shared.crossmintWallets.getWallet(
            chain: EVMChain.baseSepolia
        ) else { return }

        let passkey = SignerConfig.passkey(name: "user@example.com", host: "app.example.com")
        try await wallet.addSigner(passkey)
        try await wallet.useSigner(passkey)
    }
    ```

    The SDK shows the system prompt to create the passkey. This example needs a configured SDK, a signed-in user and an existing wallet; see the [Swift quickstart](/wallets/quickstarts/swift). Set up the associated domain first; see [Passkey Signer](/wallets/guides/signers/passkey).
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    import android.app.Activity
    import androidx.credentials.CredentialManager
    import com.crossmint.kotlin.CrossmintSDK
    import com.crossmint.kotlin.passkeys.createPasskeyCredential
    import com.crossmint.kotlin.passkeys.useSigner
    import com.crossmint.kotlin.signers.DelegatedSigner
    import com.crossmint.kotlin.types.EVMChain
    import com.crossmint.kotlin.types.getOrThrow

    suspend fun addPasskeySigner(activity: Activity) {
        val wallet = CrossmintSDK.shared.wallets.getWallet(chain = EVMChain.BaseSepolia).getOrThrow()
        val credentialManager = CredentialManager.create(activity)
        val credential = createPasskeyCredential(
            name = "user@example.com",
            activityProvider = { activity },
            credentialManager = credentialManager,
            rpId = "app.example.com",
            rpName = "Example",
        ) ?: return
        val passkey = DelegatedSigner.Passkey(
            id = credential.id,
            name = credential.name,
            publicKeyX = credential.publicKeyX,
            publicKeyY = credential.publicKeyY,
        )

        wallet.addSigner(passkey).getOrThrow()
        wallet.useSigner(passkey, credentialManager, { activity }, rpId = "app.example.com").getOrThrow()
    }
    ```

    This example needs a configured SDK, a signed-in user and an existing wallet; see the [Kotlin quickstart](/wallets/quickstarts/kotlin). Passkey signers also need the `sdk-passkeys` module and an `assetlinks.json` file on the `rpId` domain; see [Passkey Signer](/wallets/guides/signers/passkey).
  </Tab>

  <Tab title="Flutter">
    ```dart theme={null}
    import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

    final controller = CrossmintWalletContext.of(context).requireWalletController;
    final wallet = controller.createEvmWallet();

    // The SDK has no built-in passkey implementation — bridge to the passkey
    // plugin of your choice (for example `passkeys` or a native platform
    // channel). The SDK invokes your callback whenever a signature is needed.
    final passkeyConfig = CrossmintPasskeySignerConfig(
      name: 'My device passkey',
      onCreatePasskey: (name) async {
        // Register a new passkey credential with your plugin and return it
        // as a `CrossmintPasskeyCredential`. Called once when the signer is
        // registered.
        return await YourPasskeyPlugin.create(name);
      },
      onSignWithPasskey: (message) async {
        // Sign `message` with the passkey and return the result as a
        // `CrossmintPasskeySignResult`. Called on every signing operation.
        return await YourPasskeyPlugin.sign(message);
      },
    );
    final result = await wallet.addSigner(passkeyConfig);
    print('Passkey added: ${result.signer.locator}');
    ```

    Passkey signers require `onCreatePasskey` and `onSignWithPasskey` callbacks
    that bridge to your native passkey plugin. See the
    [Flutter SDK reference](/sdk-reference/wallets/flutter/controllers#wallet-methods)
    for the `CrossmintPasskeySignerConfig` API.
  </Tab>
</Tabs>

## Add an External Wallet Signer

An external wallet signer connects an existing blockchain wallet or keypair — such as MetaMask, Phantom, or a raw keypair — as a signer. When adding an external wallet via `addSigner()`, only the `address` is needed (no `onSign` callback required for registration).

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet } from "@crossmint/client-sdk-react-ui";

    const { wallet } = useWallet();

    const signer = await wallet.addSigner({
        type: "external-wallet",
        address: "0x1234...abcd",
    });

    console.log("External wallet added:", signer.locator);
    ```

    To use the external wallet for signing, activate it with the full config including `onSign`:

    ```typescript theme={null}
    wallet.useSigner({
        type: "external-wallet",
        address: "0x1234...abcd",
        onSign: async (payload) => {
            // Sign the hex payload with your external wallet
            return await externalWallet.signMessage(payload);
        },
    });
    ```
  </Tab>

  <Tab title="Flutter">
    ```dart theme={null}
    import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

    final controller = CrossmintWalletContext.of(context).requireWalletController;
    final wallet = controller.createEvmWallet();

    final result = await wallet.addSigner(
      const CrossmintExternalWalletSignerConfig(address: '0x1234...abcd'),
    );
    print('External wallet added: ${result.signer.locator}');
    ```

    To use the external wallet for signing, wrap it with a sign callback via
    `controller.createEvmWalletWithExternalWalletSigner(...)`.
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import {
        createCrossmint,
        CrossmintWallets,
    } from "@crossmint/wallets-sdk";

    const crossmint = createCrossmint({
        apiKey: "YOUR_SERVER_API_KEY",
    });
    const crossmintWallets = CrossmintWallets.from(crossmint);

    const wallet = await crossmintWallets.getWallet(
        "<wallet-address>",
        { chain: "base-sepolia" }
    );

    await wallet.useSigner({
        type: "server",
        secret: process.env.CROSSMINT_SIGNER_SECRET,
    });

    const signer = await wallet.addSigner({
        type: "external-wallet",
        address: "0x1234...abcd",
    });

    console.log("External wallet added:", signer.locator);
    ```
  </Tab>

  <Tab title="REST">
    <Steps>
      <Step title="Register the signer">
        Call the register signer endpoint with the external wallet address. By default, the EVM endpoint returns a deferred signature. To get an onchain transaction immediately, set `deployImmediately: true` in the request body.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/signers \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: <x-api-key>' \
              --data '{
                  "chain": "base-sepolia",
                  "signer": "external-wallet:0x1234...abcd"
              }'
          ```

          ```js Node.js theme={null}
          const url =
              "https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/signers";

          const payload = {
              chain: "base-sepolia",
              signer: "external-wallet:0x1234...abcd",
          };

          const response = await fetch(url, {
              method: "POST",
              headers: {
                  "X-API-KEY": "<x-api-key>",
                  "Content-Type": "application/json",
              },
              body: JSON.stringify(payload),
          });

          const data = await response.json();
          console.log(data);
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/signers"

          payload = {
              "chain": "base-sepolia",
              "signer": "external-wallet:0x1234...abcd"
          }
          headers = {
              "X-API-KEY": "<x-api-key>",
              "Content-Type": "application/json"
          }

          response = requests.post(
              url, json=payload, headers=headers
          )
          print(response.json())
          ```
        </CodeGroup>

        See the [API reference](/api-reference/wallets/register-delegated-key) for more details.
      </Step>

      <Step title="Approve the registration">
        Sign the approval message returned in the response using your recovery method, then submit the approval. The EVM endpoint defaults to the deferred signature flow, so use the [approve signature](/api-reference/wallets/approve-signature) endpoint. If you passed `deployImmediately: true` in the request, the response contains a transaction and you must use the [approve transaction](/api-reference/wallets/approve-transaction) endpoint. For Solana and Stellar, the response is always a transaction and uses the [approve transaction](/api-reference/wallets/approve-transaction) endpoint.
      </Step>
    </Steps>
  </Tab>
</Tabs>

### External Wallet `onSign` by Chain

When using an external wallet signer for transactions (via `useSigner`), the `onSign` callback receives chain-specific payloads:

| Chain | `onSign` Signature | Payload | Expected Return |
| - | - | - | - |
| EVM | `(payload: string) => Promise<string>` | Hex-encoded message | Hex-encoded signature |
| Solana | `(tx: VersionedTransaction) => Promise<VersionedTransaction>` | Unsigned transaction | Signed transaction |
| Stellar | `(payload: string) => Promise<string>` | String payload | Signed string |

## Add a Device Signer on a New Device

When a user accesses their wallet from a new device, the SDK automatically handles device signer creation through the [recovery flow](/wallets/guides/signers/device-signer#new-device-recovery). You do not need to call `addSigner()` manually for this — it happens as part of the recovery process.

If you want to trigger recovery before the first transaction:

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet } from "@crossmint/client-sdk-react-ui";

    const { wallet } = useWallet();

    if (wallet.needsRecovery()) {
        await wallet.recover();
    }
    ```
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { useWallet } from "@crossmint/client-sdk-react-native-ui";

    const { wallet } = useWallet();

    if (wallet.needsRecovery()) {
        await wallet.recover();
    }
    ```
  </Tab>

  <Tab title="Flutter">
    ```dart theme={null}
    import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

    final controller = CrossmintWalletContext.of(context).requireWalletController;
    final wallet = controller.createEvmWallet();

    if (wallet.needsRecovery) {
      await wallet.recover();
    }
    ```
  </Tab>
</Tabs>

## List Signers

To list all signers registered on a wallet, see [List Wallet Signers](/wallets/guides/signers/list-signers).

## Signer Type Reference

For the full capability matrix, see [Signer Types](/wallets/concepts/signer-types).

These signers are used for day-to-day transactions and can be listed with [`wallet.signers()`](/wallets/guides/signers/list-signers).

| Signer Type | Can Add via `addSigner()` | Chains | Notes |
| - | - | - | - |
| Passkey | Yes | EVM, Solana, Stellar | Biometric WebAuthn prompt |
| External wallet | Yes | EVM, Solana, Stellar | Requires `address`; `onSign` needed for transactions |
| Device | Automatic | EVM, Solana, Stellar | Created during recovery flow on new devices |
| Server | Yes | EVM, Solana, Stellar | Requires `secret` |
| Email | Yes | All | OTP-based |
| Phone | Yes | All | OTP-based |

## Next Steps

<CardGroup>
  <Card title="Device Signer" icon="microchip" href="/wallets/guides/signers/device-signer">
    Understand the default client-side signer
  </Card>

  <Card title="Configure Recovery" icon="shield-halved" href="/wallets/guides/recovery/configure-recovery">
    Set up recovery methods for your wallets
  </Card>

  <Card title="Transfer Tokens" icon="arrow-right-arrow-left" href="/wallets/guides/transfer-tokens">
    Send tokens from your wallet
  </Card>
</CardGroup>


# Cloud KMS Signers
Source: https://docs.crossmint.com/wallets/guides/signers/cloud-kms

Use a cloud key management service as a secure signer for your Crossmint wallet.

A Cloud KMS signer uses a signing key generated and stored inside a cloud key management service — AWS KMS, Azure Key Vault, or GCP Cloud HSM. The key is non-extractable by design: no employee at your company (or at the cloud provider) can ever retrieve the raw key material.

Cloud KMS signers support advanced enterprise security controls natively, including IP allowlisting, cloud IAM-based access policies, rate limiting, circuit breakers, and detailed audit logs and alerting.

For a conceptual overview, see [Cloud KMS](/wallets/concepts/signer-types#cloud-kms-signer) in the Signer Types reference. To learn how to register additional operational signers on an existing wallet, see [Registering a signer](/wallets/guides/signers/add-signers).

***

<Tabs>
  <Tab title="Google Cloud KMS">
    ## How It Works

    1. You create a signing key inside Google Cloud KMS — the private key never leaves Google's hardware.
    2. A Cloud Run function sits in front of KMS and signs transaction digests on demand.
    3. The Crossmint SDK calls your Cloud Run function whenever the wallet needs to sign something.
    4. The signature is converted from Google's format to Ethereum's format, and the Crossmint SDK uses it to complete the transaction.

    That is it — your key stays in the HSM, and Crossmint never sees it.

    ## What You Will Build

    * An asymmetric signing key in Google Cloud KMS (secp256k1)
    * A Cloud Run function that signs digests via KMS
    * A Crossmint server wallet using your KMS key as its signer

    ### Prerequisites

    * A <a href="https://console.cloud.google.com/">Google Cloud</a> project with billing enabled
    * A [Crossmint server API key](/introduction/platform/api-keys)
    * Node.js 18+

    ***

    ## Set Up Google Cloud KMS

    <Steps>
      <Step title="Enable the Cloud KMS API">
        Navigate to <a href="https://console.cloud.google.com/marketplace/product/google/cloudkms.googleapis.com">Cloud Key Management</a> in the Google Cloud Marketplace and click **Enable**.
      </Step>

      <Step title="Create a Key Ring">
        Go to **Security > Key Management** in the Google Cloud Console and click **Create Key Ring**.

        <img alt="Create a key ring" />

        * **Key ring name:** `crossmint-keys` (or your preferred name)
        * **Location:** Select a region, e.g. `us-west1`
      </Step>

      <Step title="Create an Asymmetric Signing Key">
        Inside your key ring, click **Create Key** with the following settings:

        <img alt="Create a key" />

        | Setting | Value |
        | - | - |
        | **Key name** | `my-crossmint-wallet-key` |
        | **Protection level** | HSM (Hardware Security Module) |
        | **Key material** | HSM-generated key |
        | **Purpose** | Asymmetric Sign |
        | **Algorithm** | Elliptic Curve secp256k1 - SHA256 Digest |

        <Warning>
          You **must** use the `secp256k1` curve for EVM-compatible wallets. Other curves (e.g. P-256) will not produce valid Ethereum signatures.
        </Warning>
      </Step>

      <Step title="Download the Public Key">
        Once the key is created, click on the key version, select **Get Public Key**, and download it in PEM format.

        <img alt="Download the public key" />

        Save the contents — you will need this PEM string in later steps. It looks like:

        ```text theme={null}
        -----BEGIN PUBLIC KEY-----
        MFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAE...
        -----END PUBLIC KEY-----
        ```
      </Step>
    </Steps>

    ***

    ## Set Up IAM Permissions

    <Steps>
      <Step title="Create a Service Account">
        Navigate to **IAM & Admin > Service Accounts** and create a new service account (e.g. `kms-signer-sa`).
      </Step>

      <Step title="Grant KMS Permissions">
        Assign the following role to the service account:

        * **Role:** `Cloud KMS CryptoKey Signer/Verifier` (`roles/cloudkms.signerVerifier`)

        <Note>
          This follows the principle of least privilege — the service account can only sign and verify, not manage or destroy keys.
        </Note>
      </Step>
    </Steps>

    ***

    ## Deploy a Cloud Run Signing Function

    This function receives a digest, signs it with your KMS key, and returns the DER-encoded signature.

    <Steps>
      <Step title="Create a Cloud Run Function">
        Go to <a href="https://console.cloud.google.com/run/create">Cloud Run Functions</a> and create a new function:

        * **Name:** `kms-signer-function`
        * **Region:** Same region as your key ring (e.g. `us-west1`)
        * **Runtime:** Node.js 18+
        * **Authentication:** Configure based on your security requirements

        <Warning>
          For production, restrict access to your Cloud Run function using IAM authentication or VPC Service Controls. Allowing unauthenticated access is only suitable for development.
        </Warning>
      </Step>

      <Step title="Set Environment Variables">
        In the Cloud Run function settings, go to the **Containers** tab, expand **Edit Container**, then select the **Variables & Secrets** tab. Add the following environment variables. To get these values, use **Copy resource name** from the same key version actions menu where you downloaded the public key — it gives you a path like `projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions/VERSION`.

        | Variable | Example Value |
        | - | - |
        | `PROJECT_ID` | `crossmint-test-462521` |
        | `LOCATION` | `us-west1` |
        | `KEY_RING` | `crossmint-keys` |
        | `KEY_NAME` | `my-crossmint-wallet-key` |
        | `VERSION` | `1` |

        <img alt="Add environment variables to container" />
      </Step>

      <Step title="Add the Function Code">
        Set the **Function entry point** to `signDigest`, then paste the following code:

        ```javascript index.js theme={null}
        const { KeyManagementServiceClient } = require("@google-cloud/kms");
        const client = new KeyManagementServiceClient();

        exports.signDigest = async (req, res) => {
            try {
                const { digest } = req.body;

                const keyName = client.cryptoKeyVersionPath(
                    process.env.PROJECT_ID,
                    process.env.LOCATION,
                    process.env.KEY_RING,
                    process.env.KEY_NAME,
                    process.env.VERSION || "1"
                );

                const [signResponse] = await client.asymmetricSign({
                    name: keyName,
                    digest: { sha256: Buffer.from(digest, "hex") },
                });

                res.status(200).send({
                    derSignature: Buffer.from(signResponse.signature).toString("hex"),
                });
            } catch (error) {
                res.status(500).send({ error: error.message });
            }
        };
        ```

        Add `@google-cloud/kms` to your function's `package.json` dependencies:

        <img alt="Add the google kms dependency" />
      </Step>

      <Step title="Deploy and Test">
        Deploy the function and note the **URL** — you will need it in the next step.

        Test with a sample request:

        ```bash theme={null}
        curl -X POST https://YOUR_FUNCTION_URL \
          -H "Content-Type: application/json" \
          -d '{"digest": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"}'
        ```

        You should receive a JSON response containing a `derSignature` field.
      </Step>
    </Steps>

    ***

    ## Create and Use the Crossmint Wallet

    Now wire everything together — convert your KMS public key to an Ethereum address, create a Crossmint wallet, and sign transactions through your Cloud Run function.

    ### Install Dependencies

    <CodeGroup>
      ```bash npm theme={null}
      npm i @crossmint/wallets-sdk viem @peculiar/asn1-schema @peculiar/asn1-x509 buffer
      ```

      ```bash yarn theme={null}
      yarn add @crossmint/wallets-sdk viem @peculiar/asn1-schema @peculiar/asn1-x509 buffer
      ```

      ```bash pnpm theme={null}
      pnpm add @crossmint/wallets-sdk viem @peculiar/asn1-schema @peculiar/asn1-x509 buffer
      ```

      ```bash bun theme={null}
      bun add @crossmint/wallets-sdk viem @peculiar/asn1-schema @peculiar/asn1-x509 buffer
      ```
    </CodeGroup>

    ### Convert the KMS Public Key to an Ethereum Address

    Google Cloud KMS returns public keys in PEM/DER format. This helper extracts the raw public key bytes and converts them to an Ethereum address using `viem`.

    ```typescript kms-utils.ts theme={null}
    import { publicKeyToAddress } from "viem/accounts";
    import { AsnParser } from "@peculiar/asn1-schema";
    import { SubjectPublicKeyInfo } from "@peculiar/asn1-x509";
    import { Buffer } from "buffer";

    export const publicKeyPem = `-----BEGIN PUBLIC KEY-----
    YOUR_PUBLIC_KEY_HERE
    -----END PUBLIC KEY-----`;

    export function kmsPemToEthAddress(pem: string): `0x${string}` {
      const b64 = pem.replace(
        /-----BEGIN PUBLIC KEY-----|-----END PUBLIC KEY-----|\s+/g,
        ""
      );
      const der = Uint8Array.from(Buffer.from(b64, "base64"));
      const spki = AsnParser.parse(der, SubjectPublicKeyInfo);
      const publicKeyHex = `0x${Buffer.from(
        new Uint8Array(spki.subjectPublicKey)
      ).toString("hex")}` as `0x${string}`;
      return publicKeyToAddress(publicKeyHex);
    }
    ```

    ### Build the KMS Signing Function

    Cloud KMS returns DER-encoded signatures. Ethereum requires `r`, `s`, `v` format with <a href="https://eips.ethereum.org/EIPS/eip-2">EIP-2 low-s normalization</a>. This function handles the full conversion:

    ```typescript kms-signer.ts theme={null}
    import { hashMessage, recoverPublicKey } from "viem";
    import { publicKeyToAddress } from "viem/accounts";
    import { Buffer } from "buffer";
    import { kmsPemToEthAddress, publicKeyPem } from "./kms-utils";

    const KMS_SIGNER_URL = "https://YOUR_CLOUD_FUNCTION_URL";

    const SECP256K1_N =
        0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141n;
    const SECP256K1_HALF_N = SECP256K1_N / 2n;

    function derToRS(derHex: string): { r: bigint; s: bigint } {
        const bytes = Buffer.from(derHex, "hex");
        let offset = 2; // skip 0x30 + length byte

        offset++; // skip 0x02 tag for r
        const rLen = bytes[offset++];
        const r = BigInt("0x" + bytes.slice(offset, offset + rLen).toString("hex"));
        offset += rLen;

        offset++; // skip 0x02 tag for s
        const sLen = bytes[offset++];
        const s = BigInt("0x" + bytes.slice(offset, offset + sLen).toString("hex"));

        return { r, s };
    }

    function bigintToHex(value: bigint): `0x${string}` {
        return `0x${value.toString(16).padStart(64, "0")}`;
    }

    export async function signWithKms(message: `0x${string}`): Promise<`0x${string}`> {
        const digest = hashMessage({ raw: message });

        const response = await fetch(KMS_SIGNER_URL, {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({ digest: digest.slice(2) }),
        });

        if (!response.ok) {
            throw new Error(`KMS signing failed: ${response.statusText}`);
        }

        const { derSignature } = await response.json();
        let { r, s } = derToRS(derSignature);

        // EIP-2 low-s normalization
        if (s > SECP256K1_HALF_N) {
            s = SECP256K1_N - s;
        }

        const rHex = bigintToHex(r);
        const sHex = bigintToHex(s);
        const expectedAddress = kmsPemToEthAddress(publicKeyPem);

        // Recover v by trying both 27 and 28
        for (const v of [27n, 28n]) {
            const sig = `${rHex}${sHex.slice(2)}${
                v === 27n ? "1b" : "1c"
            }` as `0x${string}`;
            const recovered = publicKeyToAddress(
                await recoverPublicKey({ hash: digest, signature: sig })
            );
            if (recovered.toLowerCase() === expectedAddress.toLowerCase()) {
                return sig;
            }
        }

        throw new Error("Could not recover valid signature");
    }
    ```

    ### Create the Wallet

    Use the KMS-derived Ethereum address as the wallet's recovery method. The recovery method is used for wallet recovery and adding new signers — ideal for a server-held KMS key.

    ```typescript create-wallet.ts theme={null}
    import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";
    import { kmsPemToEthAddress, publicKeyPem } from "./kms-utils";
    import { signWithKms } from "./kms-signer";

    const crossmint = createCrossmint({
        apiKey: "YOUR_CROSSMINT_SERVER_API_KEY",
    });
    export const crossmintWallets = CrossmintWallets.from(crossmint);

    const wallet = await crossmintWallets.createWallet({
        chain: "base-sepolia",
        recoveryMethods: [
            {
                type: "external-wallet",
                address: kmsPemToEthAddress(publicKeyPem),
                onSign: async (message) => {
                    return signWithKms(message as `0x${string}`);
                },
            },
        ],
        alias: "my-crossmint-wallet",
    });
    ```

    ### Use the Wallet

    Once created, retrieve the wallet and use it to sign transactions. Here are a couple of examples:

    ```typescript use-wallet.ts theme={null}
    import { EVMWallet } from "@crossmint/wallets-sdk";
    import { kmsPemToEthAddress, publicKeyPem } from "./kms-utils";
    import { signWithKms } from "./kms-signer";
    import { crossmintWallets } from "./create-wallet";

    const wallet = await crossmintWallets.getWallet(
        "evm:alias:my-crossmint-wallet",
        { chain: "base-sepolia" }
    );

    await wallet.useSigner({
        type: "external-wallet",
        address: kmsPemToEthAddress(publicKeyPem),
        onSign: async (message) => {
            return signWithKms(message as `0x${string}`);
        },
    });

    // Example: Send tokens
    await wallet.send("0xRecipientAddress", "usdxm", "1");

    // Example: Send a raw EVM transaction
    const evmWallet = EVMWallet.from(wallet);
    await evmWallet.sendTransaction({
        to: "0xRecipientAddress",
        value: BigInt(0),
        data: "0x",
    });
    ```

    ***

    ## Security Best Practices

    <Note>
      **Key rotation caveat:** While Cloud KMS supports automatic key rotation,
      rotating an asymmetric signing key generates a new key pair — which means a
      new Ethereum address. For wallets, manage key versions carefully and plan
      migrations accordingly.
    </Note>

    * **Restrict Cloud Run access:** Use IAM authentication or VPC Service Controls to ensure only authorized services can call your signing function.
    * **Enable audit logs:** Turn on Cloud KMS "Data Access" audit logs to track every signing operation.
    * **Principle of least privilege:** Only grant the `signerVerifier` role — never grant `admin` or `encrypterDecrypter` roles to your signing service account.
    * **Environment variables:** Never hardcode your Crossmint API key or GCP credentials. Use environment variables or a secrets manager.
  </Tab>

  <Tab title="AWS KMS">
    ## How It Works

    1. You create an asymmetric signing key inside AWS KMS — the private key never leaves AWS hardware security modules (HSMs).
    2. An AWS Lambda function sits in front of KMS and signs transaction digests on demand.
    3. The Crossmint SDK calls your Lambda function whenever the wallet needs to sign something.
    4. The signature is converted from AWS's DER format to Ethereum's `r, s, v` format, and the Crossmint SDK uses it to complete the transaction.

    That is it — your key stays in the HSM, and Crossmint never sees it.

    ## What You Will Build

    * An asymmetric signing key in AWS KMS (secp256k1)
    * An IAM role scoped to KMS signing operations
    * A Lambda function that signs digests via KMS
    * A Crossmint server wallet using your KMS key as its signer

    ### Prerequisites

    * An <a href="https://aws.amazon.com/console/">AWS account</a> with appropriate permissions to create KMS keys, IAM roles, Lambda functions, and API Gateway resources
    * A [Crossmint server API key](/introduction/platform/api-keys)
    * Node.js 18+

    <Accordion title="Required AWS IAM Permissions">
      To complete this setup, your AWS user or role will need the following permissions:

      | Permission | Purpose |
      | - | - |
      | `kms:CreateKey` | Create the KMS asymmetric key for signing |
      | `iam:CreateRole` | Create the IAM role for Lambda execution |
      | `iam:PutRolePolicy` | Attach inline policies to the IAM role |
      | `iam:PutGroupPolicy` | Configure group-level policies if needed |
      | `ec2:DescribeVpcEndpoints` | Configure VPC endpoints for private API access |
      | `apigateway:UpdateRestApiPolicy` | Update API Gateway resource policies |
    </Accordion>

    ***

    ## Set Up AWS KMS

    <Note>
      This guide is written for **EVM-compatible blockchains**. The steps for Solana or Stellar are similar, but key
      settings change. Contact your Crossmint support representative for assistance.
    </Note>

    <Steps>
      <Step title="Access AWS KMS">
        Log in to your AWS account and search for "KMS" in the AWS Console. Navigate to the **Key Management Service**.
      </Step>

      <Step title="Create a Customer Managed Key">
        Go to **Customer managed keys** and click **Create key**.
      </Step>

      <Step title="Configure Key Settings">
        Configure your key with the following settings:

        | Setting | Value |
        | - | - |
        | Key type | Asymmetric |
        | Key usage | Sign and verify |
        | Key spec | ECC\_SECG\_P256K1 |

        <Info>
          The `ECC_SECG_P256K1` specification is the secp256k1 elliptic curve, which is the same curve used by Ethereum and other EVM-compatible blockchains for cryptographic operations.
        </Info>
      </Step>

      <Step title="Name Your Key">
        Give your key a descriptive alias that identifies its purpose, for example: `my-crossmint-wallet-key`.
      </Step>

      <Step title="Set Permissions">
        Specify the key administrators and users who should have access to manage and use this key.
      </Step>

      <Step title="Copy the Public Key">
        After creating the key, navigate to the key's detail page and go to the **Public key** tab. Click **Download**
        to download the public key in PEM format, or copy the public key content directly.

        Save the contents — you will need this PEM string in later steps. It looks like:

        ```text theme={null}
        -----BEGIN PUBLIC KEY-----
        MFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAE...
        -----END PUBLIC KEY-----
        ```

        <Warning>
          Save this public key securely. You will need it in the next step to derive the Ethereum address for your wallet signer.
        </Warning>
      </Step>
    </Steps>

    ***

    ## Set Up IAM Permissions

    Next, create an IAM role that allows your Lambda function to call KMS for signing operations.

    <Info>
      In this guide, an **AWS Lambda function** handles signing requests. However, this architecture can be adapted
      to run on other compute types such as **EC2 instances** or **ECS containers** depending on your infrastructure
      requirements.
    </Info>

    <Steps>
      <Step title="Create a New Role">
        Search for "IAM" in the AWS Console, navigate to **Roles**, and click **Create role**.
      </Step>

      <Step title="Configure Role Type">
        Keep **AWS service** selected and choose **Lambda** under "Service or use case".
      </Step>

      <Step title="Skip Permission Policies">
        Skip the permission policies step for now (you will add an inline policy next).
      </Step>

      <Step title="Name the Role">
        Give your role a descriptive name, for example: `kms-signer-role`.
      </Step>

      <Step title="Add Inline Policy">
        From within the new role page, select **Add Permissions** and then **Create inline policy**.
      </Step>

      <Step title="Configure the Policy">
        Set the **Policy editor** to **JSON** and add the following policy:

        ```json theme={null}
        {
            "Version": "2012-10-17",
            "Statement": [
                {
                    "Effect": "Allow",
                    "Action": ["kms:Sign", "kms:GetPublicKey"],
                    "Resource": "arn:aws:kms:REGION:ACCOUNT_ID:key/KEY_ID"
                }
            ]
        }
        ```

        Replace the placeholders with your actual values:

        | Placeholder | Where to Find It |
        | - | - |
        | `REGION` | Your AWS region (e.g., `us-east-1`, `eu-north-1`) |
        | `ACCOUNT_ID` | Click your profile icon in the top-right corner of AWS Console |
        | `KEY_ID` | Found on your KMS key's dashboard page |

        <Note>
          This follows the principle of least privilege — the role can only sign and get the public key, not manage or destroy keys.
        </Note>
      </Step>

      <Step title="Save the Policy">
        Name the policy (e.g., `kms.policy`) and click "Create policy".
      </Step>
    </Steps>

    ***

    ## Deploy a Lambda Signing Function

    Now create a Lambda function that will handle signing requests using your KMS key.

    <Steps>
      <Step title="Create the Function">
        Search for "Lambda" in the AWS Console and click **Create function**. Give your function a name, for example: `kms-signer-function`.
      </Step>

      <Step title="Configure Execution Role">
        Under **Change default execution role**, select **Use an existing role**. From the **Existing role** dropdown, select the role you created during IAM Role Setup (e.g., `kms-signer-role`).
      </Step>

      <Step title="Set Environment Variables">
        Create a new environment variable `KMS_KEY_ID` and set it to your KMS key ID. You can find the key ID at the top of the KMS key's dashboard page.

        <img alt="KMS Key ID" />
      </Step>

      <Step title="Add the Function Code">
        Enter the following code in the Lambda function editor:

        <Accordion title="View Lambda Function Code">
          ```javascript theme={null}
          import { KMSClient, SignCommand } from '@aws-sdk/client-kms'

          const kms = new KMSClient({})

          const KEY_ID = process.env.KMS_KEY_ID
          if (!KEY_ID) throw new Error('Missing env var KMS_KEY_ID')

          // secp256k1 curve parameters
          const SECP256K1_P = BigInt('0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEFFFFFC2F')
          const SECP256K1_N = BigInt('0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141')
          const SECP256K1_HALF_N = SECP256K1_N / 2n
          const SECP256K1_Gx = BigInt('0x79BE667EF9DCBBAC55A06295CE870B07029BFCDB2DCE28D959F2815B16F81798')
          const SECP256K1_Gy = BigInt('0x483ADA7726A3C4655DA4FBFC0E1108A8FD17B448A68554199C47D08FFB10D4B8')

          export const handler = async (event) => {
            const body = typeof event.body === 'string' ? JSON.parse(event.body) : (event.body ?? event)

            const digestInput = body.userOpHash ?? body.useropHash ?? body.hash ?? body.digest
            if (!digestInput) {
              return resp(400, {
                error: 'Missing userOpHash (0x..32 bytes) or digest (0x..32 bytes or base64 32 bytes)'
              })
            }

            const signerAddress = body.signerAddress
            if (!signerAddress || !signerAddress.startsWith('0x') || signerAddress.length !== 42) {
              return resp(400, {
                error: 'Missing or invalid signerAddress (must be 0x-prefixed 20-byte hex address)'
              })
            }

            const digestBytes = parse32ByteDigest(digestInput)
            if (!digestBytes) return resp(400, { error: 'Digest must be 32 bytes (hex 0x.. or base64)' })

            // Apply EIP-191 personal sign prefix before signing
            // This computes: keccak256("\x19Ethereum Signed Message:\n32" + digestBytes)
            const ethSignedHash = hashMessage(digestBytes)

            const out = await kms.send(
              new SignCommand({
                KeyId: KEY_ID,
                Message: ethSignedHash,
                MessageType: 'DIGEST',
                SigningAlgorithm: 'ECDSA_SHA_256'
              })
            )

            if (!out.Signature) return resp(500, { error: 'KMS did not return a signature' })

            let { r, s } = derToRS(Buffer.from(out.Signature))

            // Enforce low-s (EIP-2)
            let sBig = BigInt(s)
            let sFlipped = false
            if (sBig > SECP256K1_HALF_N) {
              sBig = SECP256K1_N - sBig
              s = toPaddedHex(sBig, 32)
              sFlipped = true
            }

            // Determine the correct recovery parameter by trying both and comparing addresses
            const rBig = BigInt(r)
            const hashBig = BigInt('0x' + Buffer.from(ethSignedHash).toString('hex'))

            let correctV = null
            const recoveredAddresses = []
            for (const recoveryParam of [0, 1]) {
              try {
                const recoveredPubKey = ecrecover(hashBig, rBig, sBig, recoveryParam)
                if (!recoveredPubKey) {
                  recoveredAddresses.push({ v: recoveryParam + 27, error: 'recovery returned null' })
                  continue
                }
                
                const recoveredAddress = pubKeyToAddress(recoveredPubKey)
                recoveredAddresses.push({ v: recoveryParam + 27, address: recoveredAddress })
                
                if (recoveredAddress.toLowerCase() === signerAddress.toLowerCase()) {
                  correctV = recoveryParam + 27
                  break
                }
              } catch (err) {
                recoveredAddresses.push({ v: recoveryParam + 27, error: err.message })
              }
            }

            if (correctV === null) {
              return resp(500, { 
                error: 'Failed to determine correct signature recovery parameter. Verify signerAddress matches the KMS key.',
                debug: {
                  expectedAddress: signerAddress,
                  recoveredAddresses,
                  r,
                  s
                }
              })
            }

            const signature = hexConcat([r, s, toPaddedHex(BigInt(correctV), 1)])

            return {
              statusCode: 200,
              headers: { 'content-type': 'application/json' },
              body: JSON.stringify({ signature })
            }
          }

          function resp(statusCode, body) {
            return { statusCode, headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) }
          }

          // EIP-191 personal sign: keccak256("\x19Ethereum Signed Message:\n" + len + message)
          function hashMessage(messageBytes) {
            const prefix = Buffer.from(`\x19Ethereum Signed Message:\n${messageBytes.length}`, 'utf8')
            const prefixedMessage = Buffer.concat([prefix, messageBytes])
            return Buffer.from(keccak256(prefixedMessage))
          }

          function parse32ByteDigest(input) {
            if (typeof input !== 'string') return null
            if (input.startsWith('0x')) {
              try {
                const bytes = Buffer.from(input.slice(2), 'hex')
                return bytes.length === 32 ? bytes : null
              } catch {
                return null
              }
            }
            try {
              const bytes = Buffer.from(input, 'base64')
              return bytes.length === 32 ? bytes : null
            } catch {
              return null
            }
          }

          function derToRS(der) {
            let i = 0
            if (der[i++] !== 0x30) throw new Error('Invalid DER: expected SEQUENCE')
            const seq = readDerLen(der, i)
            i = seq.next
            if (der[i++] !== 0x02) throw new Error('Invalid DER: expected INTEGER (r)')
            const rLen = readDerLen(der, i)
            i = rLen.next
            const rBytes = der.slice(i, i + rLen.len)
            i += rLen.len
            if (der[i++] !== 0x02) throw new Error('Invalid DER: expected INTEGER (s)')
            const sLen = readDerLen(der, i)
            i = sLen.next
            const sBytes = der.slice(i, i + sLen.len)
            return { r: bytesToPaddedHex(stripLeadingZero(rBytes), 32), s: bytesToPaddedHex(stripLeadingZero(sBytes), 32) }
          }

          function readDerLen(buf, offset) {
            const first = buf[offset]
            if (first < 0x80) return { len: first, next: offset + 1 }
            const n = first & 0x7f
            let len = 0
            for (let j = 0; j < n; j++) len = (len << 8) | buf[offset + 1 + j]
            return { len, next: offset + 1 + n }
          }

          function stripLeadingZero(b) {
            return (b.length > 1 && b[0] === 0x00) ? b.slice(1) : b
          }

          function bytesToPaddedHex(b, size) {
            return '0x' + Buffer.from(b).toString('hex').padStart(size * 2, '0')
          }

          function toPaddedHex(n, size) {
            let hex = n.toString(16)
            if (hex.length > size * 2) hex = hex.slice(-size * 2)
            return '0x' + hex.padStart(size * 2, '0')
          }

          function hexConcat(parts) {
            return '0x' + parts.map((p) => (p.startsWith('0x') ? p.slice(2) : p)).join('')
          }

          // ============================================================================
          // Pure JavaScript secp256k1 ecrecover implementation
          // ============================================================================

          // Modular arithmetic helpers
          function mod(a, m) {
            const result = a % m
            return result >= 0n ? result : result + m
          }

          function modInverse(a, m) {
            a = mod(a, m) // Ensure a is positive before computing inverse
            if (a === 0n) throw new Error('No modular inverse for 0')
            let [old_r, r] = [a, m]
            let [old_s, s] = [1n, 0n]
            while (r !== 0n) {
              const q = old_r / r
              ;[old_r, r] = [r, old_r - q * r]
              ;[old_s, s] = [s, old_s - q * s]
            }
            return mod(old_s, m)
          }

          function modPow(base, exp, m) {
            let result = 1n
            base = mod(base, m)
            while (exp > 0n) {
              if (exp % 2n === 1n) result = mod(result * base, m)
              exp = exp / 2n
              base = mod(base * base, m)
            }
            return result
          }

          // Elliptic curve point operations (affine coordinates)
          function pointAdd(p1, p2) {
            if (p1 === null) return p2
            if (p2 === null) return p1
            
            const [x1, y1] = p1
            const [x2, y2] = p2
            
            if (x1 === x2) {
              if (y1 !== y2) return null // point at infinity
              // Point doubling
              const s = mod(3n * x1 * x1 * modInverse(2n * y1, SECP256K1_P), SECP256K1_P)
              const x3 = mod(s * s - 2n * x1, SECP256K1_P)
              const y3 = mod(s * (x1 - x3) - y1, SECP256K1_P)
              return [x3, y3]
            }
            
            const s = mod((y2 - y1) * modInverse(x2 - x1, SECP256K1_P), SECP256K1_P)
            const x3 = mod(s * s - x1 - x2, SECP256K1_P)
            const y3 = mod(s * (x1 - x3) - y1, SECP256K1_P)
            return [x3, y3]
          }

          function pointMul(k, point) {
            let result = null
            let addend = point
            while (k > 0n) {
              if (k & 1n) result = pointAdd(result, addend)
              addend = pointAdd(addend, addend)
              k >>= 1n
            }
            return result
          }

          // Recover y-coordinate from x-coordinate on secp256k1
          function recoverY(x, isOdd) {
            // y² = x³ + 7 (mod p)
            const ySquared = mod(modPow(x, 3n, SECP256K1_P) + 7n, SECP256K1_P)
            // y = ySquared^((p+1)/4) mod p (works because p ≡ 3 mod 4)
            const y = modPow(ySquared, (SECP256K1_P + 1n) / 4n, SECP256K1_P)
            // Verify
            if (mod(y * y, SECP256K1_P) !== ySquared) return null
            // Return the y with correct parity
            const yIsOdd = (y & 1n) === 1n
            return yIsOdd === isOdd ? y : mod(-y, SECP256K1_P)
          }

          // ecrecover: recover public key from signature
          function ecrecover(msgHash, r, s, recoveryParam) {
            // Recover the point R from r and recoveryParam
            const isOdd = (recoveryParam & 1) === 1
            const x = r
            const y = recoverY(x, isOdd)
            if (y === null) return null
            
            const R = [x, y]
            const G = [SECP256K1_Gx, SECP256K1_Gy]
            
            // Public key P = r^(-1) * (s*R - e*G)
            const rInv = modInverse(r, SECP256K1_N)
            const u1 = mod(-msgHash * rInv, SECP256K1_N)
            const u2 = mod(s * rInv, SECP256K1_N)
            
            const point1 = pointMul(u1, G)
            const point2 = pointMul(u2, R)
            const pubKeyPoint = pointAdd(point1, point2)
            
            if (pubKeyPoint === null) return null
            
            // Return uncompressed public key (65 bytes: 0x04 || x || y)
            const xHex = pubKeyPoint[0].toString(16).padStart(64, '0')
            const yHex = pubKeyPoint[1].toString(16).padStart(64, '0')
            return Buffer.from('04' + xHex + yHex, 'hex')
          }

          function pubKeyToAddress(pubKey) {
            // Skip the 0x04 prefix and hash the 64 bytes
            const hash = keccak256(pubKey.slice(1))
            return '0x' + Buffer.from(hash.slice(12)).toString('hex')
          }

          // ============================================================================
          // Pure JavaScript Keccak-256 implementation (no external dependencies)
          // ============================================================================
          const KECCAK_ROUNDS = 24
          const ROTC = [1,3,6,10,15,21,28,36,45,55,2,14,27,41,56,8,25,43,62,18,39,61,20,44]
          const PILN = [10,7,11,17,18,3,5,16,8,21,24,4,15,23,19,13,12,2,20,14,22,9,6,1]
          const RNDC = [
            0x0000000000000001n, 0x0000000000008082n, 0x800000000000808an, 0x8000000080008000n,
            0x000000000000808bn, 0x0000000080000001n, 0x8000000080008081n, 0x8000000000008009n,
            0x000000000000008an, 0x0000000000000088n, 0x0000000080008009n, 0x000000008000000an,
            0x000000008000808bn, 0x800000000000008bn, 0x8000000000008089n, 0x8000000000008003n,
            0x8000000000008002n, 0x8000000000000080n, 0x000000000000800an, 0x800000008000000an,
            0x8000000080008081n, 0x8000000000008080n, 0x0000000080000001n, 0x8000000080008008n
          ]

          function rotl64(x, n) {
            n = BigInt(n)
            return ((x << n) | (x >> (64n - n))) & 0xffffffffffffffffn
          }

          function keccakF(state) {
            for (let round = 0; round < KECCAK_ROUNDS; round++) {
              // Theta
              const C = new Array(5)
              for (let x = 0; x < 5; x++) {
                C[x] = state[x] ^ state[x + 5] ^ state[x + 10] ^ state[x + 15] ^ state[x + 20]
              }
              const D = new Array(5)
              for (let x = 0; x < 5; x++) {
                D[x] = C[(x + 4) % 5] ^ rotl64(C[(x + 1) % 5], 1)
              }
              for (let x = 0; x < 5; x++) {
                for (let y = 0; y < 5; y++) {
                  state[x + y * 5] ^= D[x]
                }
              }

              // Rho and Pi
              let t = state[1]
              for (let i = 0; i < 24; i++) {
                const j = PILN[i]
                const temp = state[j]
                state[j] = rotl64(t, ROTC[i])
                t = temp
              }

              // Chi
              for (let y = 0; y < 5; y++) {
                const row = [state[y * 5], state[y * 5 + 1], state[y * 5 + 2], state[y * 5 + 3], state[y * 5 + 4]]
                for (let x = 0; x < 5; x++) {
                  state[y * 5 + x] = row[x] ^ ((~row[(x + 1) % 5]) & row[(x + 2) % 5])
                }
              }

              // Iota
              state[0] ^= RNDC[round]
            }
          }

          function keccak256(input) {
            const inputBytes = Buffer.isBuffer(input) ? input : Buffer.from(input)
            const rate = 136 // (1600 - 256 * 2) / 8 for keccak-256
            const state = new Array(25).fill(0n)

            // Pad the input: append 0x01, then zeros, then 0x80
            const padLen = rate - (inputBytes.length % rate)
            const padded = Buffer.alloc(inputBytes.length + padLen)
            inputBytes.copy(padded)
            padded[inputBytes.length] = 0x01
            padded[padded.length - 1] |= 0x80

            // Absorb
            for (let offset = 0; offset < padded.length; offset += rate) {
              for (let i = 0; i < rate / 8; i++) {
                const lane = padded.readBigUInt64LE(offset + i * 8)
                state[i] ^= lane
              }
              keccakF(state)
            }

            // Squeeze (just 32 bytes for keccak-256)
            const output = Buffer.alloc(32)
            for (let i = 0; i < 4; i++) {
              output.writeBigUInt64LE(state[i], i * 8)
            }
            return output
          }
          ```
        </Accordion>
      </Step>

      <Step title="Deploy the Function">
        Click **Deploy** to save and deploy your Lambda function
      </Step>

      <Step title="Expose Function as HTTP Endpoint">
        Make the function accessible to your application via an HTTP endpoint.

        The simplest approach is to enable a **Lambda Function URL** — a built-in HTTPS endpoint with no extra infrastructure:

        <Steps>
          <Step title="Open your Lambda function">
            In the AWS Console, navigate to your Lambda function and go to the **Configuration** tab.
          </Step>

          <Step title="Create Function URL">
            Select **Function URL** in the left panel, then click **Create function URL**.
          </Step>

          <Step title="Set Auth Type">
            Choose **NONE** for auth type (simplest for development). For production, use **AWS\_IAM** and sign requests with SigV4.
          </Step>

          <Step title="Copy the URL">
            Copy the **Function URL** — you will use this as `KMS_SIGNER_URL` in your application code.
          </Step>
        </Steps>

        <Warning>
          A Function URL with auth type `NONE` is publicly accessible. For production, use `AWS_IAM` auth
          or put the Lambda behind an API Gateway with IAM authorization. See the advanced setup below.
        </Warning>

        <AccordionGroup>
          <Accordion title="Advanced: Create an API Gateway with IAM Auth">
            For production, you can expose the function via API Gateway with IAM authorization.
            This requires AWS SigV4-signed requests (e.g., via `awscurl`).

            <Steps>
              <Step title="Create the API">
                Search for "API Gateway" in the AWS Console and click **Create API**. Select **Build** for **REST API**.
              </Step>

              <Step title="Configure API Settings">
                Name your API (e.g., `KMS Sign API`) and select a security policy that meets your requirements.
              </Step>

              <Step title="Create a Method">
                After creating the API, select **Create method** with the following settings:

                | Setting | Value |
                | - | - |
                | Method type | POST |
                | Lambda function | Select the Lambda function you created |
                | Authorization (In Method Request Settings) | AWS IAM |
              </Step>

              <Step title="Create a Stage">
                Go to **Stages** in the left panel and click **Create Stage**. Name the stage (e.g., `prod`).
              </Step>

              <Step title="Deploy the API">
                Go back to **API** > **Resource** and select **Deploy API**. Select the stage you created and click **Deploy**.
              </Step>

              <Step title="Add Resource Policy">
                Navigate to **Resource policy** in the left panel and add the following policy to allow invocations from your AWS account:

                ```json theme={null}
                {
                    "Version": "2012-10-17",
                    "Statement": [
                        {
                            "Sid": "AllowAnyoneInThisAccount",
                            "Effect": "Allow",
                            "Principal": "*",
                            "Action": "execute-api:Invoke",
                            "Resource": "arn:aws:execute-api:REGION:ACCOUNT_ID:API_ID/*/POST/",
                            "Condition": {
                                "StringEquals": {
                                    "aws:PrincipalAccount": "ACCOUNT_ID"
                                }
                            }
                        }
                    ]
                }
                ```

                Replace the placeholders with your actual values:

                | Placeholder | Where to Find It |
                | - | - |
                | `REGION` | Your AWS region (e.g., `us-east-1`, `eu-north-1`) |
                | `ACCOUNT_ID` | Click your profile icon in the top-right corner of AWS Console |
                | `API_ID` | Found in the API Gateway console URL or in the API's ARN |

                After adding the policy, click **Save** and then re-deploy the API to the stage for the changes to take effect.
              </Step>

              <Step title="Save the Invoke URL">
                Copy the **Invoke URL** for your API. You will need this URL to test the endpoint. You can always find this URL under the **Stages** view.
              </Step>

              <Step title="Grant User Group Access to API Gateway">
                Add a policy to your user group to allow members to invoke the API Gateway endpoint.

                1. Search for **IAM** in the AWS Console and navigate to **User groups** in the left panel.
                2. Select the user group you want to grant access to (or create a new one).
                3. Go to the **Permissions** tab.
                4. Click **Add permissions** and select **Create inline policy**.
                5. Select the **JSON** tab in the policy editor.
                6. Paste the following policy:

                ```json theme={null}
                {
                    "Version": "2012-10-17",
                    "Statement": [
                        {
                            "Effect": "Allow",
                            "Action": "execute-api:Invoke",
                            "Resource": "arn:aws:execute-api:REGION:ACCOUNT_ID:API_ID/STAGE/POST/"
                        }
                    ]
                }
                ```

                Replace the placeholders with your actual values:

                | Placeholder | Where to Find It |
                | - | - |
                | `REGION` | Your AWS region (e.g., `us-east-1`, `eu-north-1`) |
                | `ACCOUNT_ID` | Click your profile icon in the top-right corner of AWS Console |
                | `API_ID` | Found in the API Gateway console URL or in the API's ARN |
                | `STAGE` | The stage name you created (e.g., `prod`) |

                7. Click **Next**, give the policy a name (e.g., `api-gateway-invoke-policy`), and click **Create policy**.
              </Step>
            </Steps>
          </Accordion>

          <Accordion title="Test Using AWS CLI">
            You can invoke the function using the AWS CLI to ensure everything is working correctly.

            <Steps>
              <Step title="Open Security Credentials">
                Click on your username in the top right corner of the AWS Console, then select **Security credentials** from the dropdown menu.
              </Step>

              <Step title="Create Access Key">
                Scroll down to the **Access keys** section and click **Create access key**.
              </Step>

              <Step title="Select Use Case">
                Select the use case (e.g., "Command Line Interface (CLI)") and click **Create access key**.
              </Step>

              <Step title="Copy Access Keys">
                **Important**: Copy both the **Access key ID** and **Secret access key** immediately. The secret access key will only be shown once and cannot be retrieved later.
              </Step>

              <Step title="Run AWS Configure">
                Run `aws configure` to set up your AWS credentials:

                ```bash theme={null}
                aws configure
                ```
              </Step>

              <Step title="Enter Access Key ID">
                When prompted, enter your **AWS Access Key ID**: Paste the access key ID you copied in the previous step.
              </Step>

              <Step title="Enter Secret Access Key">
                Enter your **AWS Secret Access Key**: Paste the secret access key you copied.
              </Step>

              <Step title="Enter Default Region">
                Enter your **Default region name**: Enter your AWS region (e.g., `us-east-1`, `eu-north-1`).
              </Step>

              <Step title="Set Output Format">
                For **Default output format**: Press Enter to use the default (JSON) or specify `json`, `yaml`, `text`, or `table`.

                Your credentials will be stored in `~/.aws/credentials` and your configuration in `~/.aws/config`.
              </Step>

              <Step title="Install awscurl">
                Install `awscurl` to make signed requests to your API:

                ```bash theme={null}
                pip install awscurl
                ```
              </Step>

              <Step title="Generate Signature">
                Run the following command to sign a message using your endpoint:

                ```bash theme={null}
                awscurl --service execute-api --region YOUR_REGION \
                    -X POST "https://YOUR_API_ID.execute-api.YOUR_REGION.amazonaws.com/prod/" \
                    -d '{"digest":"BASE64_ENCODED_MESSAGE_HASH", "signerAddress":"0xYOUR_KMS_SIGNER_ADDRESS"}'
                ```

                Replace the placeholders with your actual values:

                | Placeholder | Description |
                | - | - |
                | `YOUR_REGION` | Your AWS region (e.g., `us-east-1`, `eu-north-1`) |
                | `YOUR_API_ID` | Found in the API Gateway console URL or ARN (e.g., if ARN is `arn:aws:execute-api:eu-north-1:257027486036:bho48fe8dl/*/POST/`, then `API_ID` is `bho48fe8dl`) |
                | `BASE64_ENCODED_MESSAGE_HASH` | The base64-encoded message hash returned from wallet APIs |
                | `0xYOUR_KMS_SIGNER_ADDRESS` | The Ethereum address derived from your KMS public key (from step 3) |
              </Step>
            </Steps>
          </Accordion>
        </AccordionGroup>
      </Step>
    </Steps>

    ***

    ## Create and Use the Crossmint Wallet

    Now wire everything together — convert your KMS public key to an Ethereum address, create a Crossmint wallet, and sign transactions through your Lambda function.

    ### Install Dependencies

    <CodeGroup>
      ```bash npm theme={null}
      npm i @crossmint/wallets-sdk viem @peculiar/asn1-schema @peculiar/asn1-x509 buffer
      ```

      ```bash yarn theme={null}
      yarn add @crossmint/wallets-sdk viem @peculiar/asn1-schema @peculiar/asn1-x509 buffer
      ```

      ```bash pnpm theme={null}
      pnpm add @crossmint/wallets-sdk viem @peculiar/asn1-schema @peculiar/asn1-x509 buffer
      ```

      ```bash bun theme={null}
      bun add @crossmint/wallets-sdk viem @peculiar/asn1-schema @peculiar/asn1-x509 buffer
      ```
    </CodeGroup>

    ### Convert the KMS Public Key to an Ethereum Address

    AWS KMS provides the public key in PEM format. You need to convert it to an Ethereum address. The code below
    handles this conversion by parsing the PEM-encoded public key and deriving the corresponding Ethereum address.

    <Info>
      Replace the `publicKeyPem` placeholder with the public key you copied from AWS KMS in the previous step.
    </Info>

    ```typescript kms-utils.ts theme={null}
    import { publicKeyToAddress } from "viem/accounts";
    import { AsnParser } from "@peculiar/asn1-schema";
    import { SubjectPublicKeyInfo } from "@peculiar/asn1-x509";
    import { Buffer } from "buffer";

    // Paste the public key from your AWS KMS key here
    export const publicKeyPem = `-----BEGIN PUBLIC KEY-----
    YOUR_KMS_PUBLIC_KEY_HERE
    -----END PUBLIC KEY-----
    `;

    function pemToDer(pem: string): Uint8Array {
        const b64 = pem
            .replace(/-----BEGIN PUBLIC KEY-----/g, "")
            .replace(/-----END PUBLIC KEY-----/g, "")
            .replace(/\s+/g, "");
        return Uint8Array.from(Buffer.from(b64, "base64"));
    }

    export function kmsPemToEthAddress(pem: string): `0x${string}` {
        const der = pemToDer(pem);

        // Parse SPKI and extract the BIT STRING (the actual EC point bytes)
        const spki = AsnParser.parse(der, SubjectPublicKeyInfo);
        const uncompressed = new Uint8Array(spki.subjectPublicKey); // 65 bytes: 04 || X || Y

        if (uncompressed.length !== 65 || uncompressed[0] !== 0x04) {
            throw new Error("Expected uncompressed secp256k1 public key (65 bytes starting with 0x04).");
        }

        const publicKeyHex = `0x${Buffer.from(uncompressed).toString("hex")}` as `0x${string}`;
        return publicKeyToAddress(publicKeyHex);
    }
    ```

    <Note>
      The `@peculiar/asn1-schema` and `@peculiar/asn1-x509` packages were already installed in the "Install Dependencies" step above.
    </Note>

    ### Build the KMS Signing Function

    The Lambda function from the previous step handles DER-to-Ethereum signature conversion and <a href="https://eips.ethereum.org/EIPS/eip-2">EIP-2 low-s normalization</a>. This client-side function calls your Lambda and returns the resulting signature:

    <Info>
      This example uses a plain `fetch` call, which works with Lambda Function URLs (auth type `NONE`). If you set up API Gateway with IAM auth instead, you will need to sign requests with AWS SigV4 — use `awscurl` for testing (see the "Test Using AWS CLI" section above).
    </Info>

    ```typescript kms-signer.ts theme={null}
    import { kmsPemToEthAddress, publicKeyPem } from "./kms-utils";

    const KMS_SIGNER_URL = "https://YOUR_LAMBDA_FUNCTION_URL";

    export async function signWithKms(message: `0x${string}`): Promise<`0x${string}`> {
        const expectedAddress = kmsPemToEthAddress(publicKeyPem);

        const response = await fetch(KMS_SIGNER_URL, {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({
                hash: message,
                signerAddress: expectedAddress,
            }),
        });

        if (!response.ok) {
            throw new Error(`KMS signing failed: ${response.statusText}`);
        }

        const { signature } = await response.json();
        return signature as `0x${string}`;
    }
    ```

    ### Create the Wallet

    Use the KMS-derived Ethereum address as the wallet's recovery method. The recovery method is used for wallet recovery and adding new signers — ideal for a server-held KMS key.

    ```typescript create-wallet.ts theme={null}
    import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";
    import { kmsPemToEthAddress, publicKeyPem } from "./kms-utils";
    import { signWithKms } from "./kms-signer";

    const crossmint = createCrossmint({
        apiKey: "YOUR_CROSSMINT_SERVER_API_KEY",
    });
    export const crossmintWallets = CrossmintWallets.from(crossmint);

    const wallet = await crossmintWallets.createWallet({
        chain: "base-sepolia",
        recoveryMethods: [
            {
                type: "external-wallet",
                address: kmsPemToEthAddress(publicKeyPem),
                onSign: async (message) => {
                    return signWithKms(message as `0x${string}`);
                },
            },
        ],
        alias: "my-crossmint-wallet",
    });
    ```

    ### Use the Wallet

    Once created, retrieve the wallet and use it to sign transactions. Here are a couple of examples:

    ```typescript use-wallet.ts theme={null}
    import { EVMWallet } from "@crossmint/wallets-sdk";
    import { kmsPemToEthAddress, publicKeyPem } from "./kms-utils";
    import { signWithKms } from "./kms-signer";
    import { crossmintWallets } from "./create-wallet";

    const wallet = await crossmintWallets.getWallet(
        "evm:alias:my-crossmint-wallet",
        { chain: "base-sepolia" }
    );

    await wallet.useSigner({
        type: "external-wallet",
        address: kmsPemToEthAddress(publicKeyPem),
        onSign: async (message) => {
            return signWithKms(message as `0x${string}`);
        },
    });

    // Example: Send tokens
    await wallet.send("0xRecipientAddress", "usdxm", "1");

    // Example: Send a raw EVM transaction
    const evmWallet = EVMWallet.from(wallet);
    await evmWallet.sendTransaction({
        to: "0xRecipientAddress",
        value: BigInt(0),
        data: "0x",
    });
    ```

    ***

    ## Security Best Practices

    <Note>
      **Key rotation caveat:** While AWS KMS supports automatic key rotation,
      rotating an asymmetric signing key generates a new key pair — which means a
      new Ethereum address. For wallets, manage key versions carefully and plan
      migrations accordingly.
    </Note>

    * **Restrict Lambda access:** Use IAM authentication or VPC endpoints to ensure only authorized services can call your signing function.
    * **Enable audit logs:** Turn on AWS CloudTrail to log all KMS and Lambda operations.
    * **Principle of least privilege:** Only grant `kms:Sign` and `kms:GetPublicKey` — never grant broader KMS permissions to your signing role.
    * **Environment variables:** Never hardcode your Crossmint API key or AWS credentials. Use environment variables or AWS Secrets Manager.
  </Tab>
</Tabs>


# Device Signer
Source: https://docs.crossmint.com/wallets/guides/signers/device-signer

How device signers work — hardware-backed P256 keypairs for frictionless transaction signing.

The device signer is the **default signer** for client-side wallets. It generates a P256 keypair inside the device's secure hardware — the iOS Secure Enclave, Android Keystore, or the browser's Web Crypto API — so the private key never leaves the device. Transactions are signed silently, with no OTP or user confirmation required.

## How It Works

When a client-side wallet is created, the SDK automatically generates a device signer unless you explicitly configure a different signer. The flow:

1. The SDK initializes secure storage on the device (Secure Enclave, Keystore, or a hidden iframe in the browser)
2. A P256 keypair is generated — the private key is **non-extractable** and never leaves the hardware boundary
3. The public key is sent to the Crossmint backend, which registers the device signer on the wallet
4. Subsequent transactions are signed locally on the device — no OTP, no network round-trips for signing

### Browser Architecture

In browser environments, the device signer key lives inside a hidden iframe hosted at `crossmint-signer.io` — a separate origin from your application. Key generation and signing happen inside the iframe via `postMessage`. Keys are stored as non-extractable `CryptoKey` objects in the iframe's IndexedDB, isolated from the parent page by the browser's same-origin policy.

### Mobile Architecture

On iOS, keys are stored in the Secure Enclave. On Android, keys are stored in the Android Keystore. Both provide hardware-level isolation for the private key material.

## Setup

No explicit configuration is needed. When you create a wallet on the client side, a device signer is added automatically.

<Tabs>
  <Tab title="React">
    Using `createOnLogin` on the provider (recommended for most apps):

    ```tsx theme={null}
    import {
        CrossmintProvider,
        CrossmintAuthProvider,
        CrossmintWalletProvider,
    } from "@crossmint/client-sdk-react-ui";

    function App({ children }) {
        return (
            <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
                <CrossmintAuthProvider loginMethods={["email", "google"]}>
                    <CrossmintWalletProvider
                        createOnLogin={{
                            chain: "base-sepolia",
                            recoveryMethods: [{ type: "email" }],
                            // Device signer is added automatically
                        }}
                    >
                        {children}
                    </CrossmintWalletProvider>
                </CrossmintAuthProvider>
            </CrossmintProvider>
        );
    }
    ```

    Or using `createWallet` directly:

    ```typescript theme={null}
    import { useWallet } from "@crossmint/client-sdk-react-ui";

    const { createWallet } = useWallet();

    const wallet = await createWallet({
        chain: "base-sepolia",
        recoveryMethods: [{ type: "email", email: "user@example.com" }],
        // signers defaults to [{ type: "device" }]
    });
    ```
  </Tab>

  <Tab title="React Native">
    ```tsx theme={null}
    import {
        CrossmintProvider,
        CrossmintAuthProvider,
        CrossmintWalletProvider,
    } from "@crossmint/client-sdk-react-native-ui";

    function App({ children }) {
        return (
            <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
                <CrossmintAuthProvider loginMethods={["email", "google"]}>
                    <CrossmintWalletProvider
                        createOnLogin={{
                            chain: "base-sepolia",
                            recoveryMethods: [{ type: "email" }],
                        }}
                    >
                        {children}
                    </CrossmintWalletProvider>
                </CrossmintAuthProvider>
            </CrossmintProvider>
        );
    }
    ```
  </Tab>

  <Tab title="Flutter">
    ```dart theme={null}
    import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

    CrossmintWalletProvider(
      config: CrossmintWalletProviderConfig(
        clientConfig: const CrossmintClientConfig(
          apiKey: 'YOUR_CLIENT_API_KEY',
          appScheme: 'myapp',
        ),
        walletControllerConfig: const CrossmintWalletControllerConfig(
          createOnLogin: CrossmintCreateOnLoginConfig(
            chain: 'base-sepolia',
            recovery: CrossmintEmailSignerConfig(),
            // Device signer is added automatically.
          ),
        ),
        otpPromptBuilder: crossmintDefaultOtpPromptBuilder,
      ),
      child: const HomeScreen(),
    )
    ```

    On iOS the private key lives in Secure Enclave; on Android it uses
    Android Keystore. Both are provided by the `crossmint_device_signer` plugin.
  </Tab>
</Tabs>

## Signing Transactions

With a device signer, `useSigner()` is **not needed** — the device signer is auto-selected as the default. Transactions are signed without any user-facing prompts:

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet } from "@crossmint/client-sdk-react-ui";

    const { wallet } = useWallet();

    const { hash, explorerLink } = await wallet.send(
        "0xRecipientAddress",
        "usdc",
        "10"
    );
    ```
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { useWallet } from "@crossmint/client-sdk-react-native-ui";

    const { wallet } = useWallet();

    const { hash, explorerLink } = await wallet.send(
        "0xRecipientAddress",
        "usdc",
        "10"
    );
    ```
  </Tab>

  <Tab title="Flutter">
    ```dart theme={null}
    import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

    final controller = CrossmintWalletContext.of(context).requireWalletController;
    final wallet = controller.createEvmWallet();

    final tx = await wallet.sendToken('0xRecipientAddress', 'base-sepolia:usdc', '10');
    print('Transaction: ${tx.id}');
    ```

    The SDK auto-recovers the device signer on first signing if the wallet
    reports `needsRecovery == true`, so no explicit setup is required.
  </Tab>
</Tabs>

## New Device Recovery

Device signers are **per-device** — they do not sync across devices. When a user accesses their wallet from a new device:

1. The user authenticates via your app (JWT) and the SDK retrieves the wallet
2. No local device signer exists on the new device, so `wallet.needsRecovery()` returns `true`
3. On the first transaction, the SDK automatically triggers recovery: the user verifies via their recovery method (e.g., email OTP) to authorize a new device signer for this device
4. After recovery, all subsequent transactions on the new device are frictionless again

The previous device's signer remains valid — each device maintains its own independent signer.

### Pre-emptive Recovery

Recovery runs automatically before the first signing operation on a new device. If you want to trigger it earlier (e.g., on app startup to avoid an OTP prompt mid-transaction), call `recover()` explicitly:

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet } from "@crossmint/client-sdk-react-ui";

    const { wallet } = useWallet();

    try {
        if (wallet.needsRecovery()) {
            await wallet.recover();
        }
    } catch (error) {
        console.error("Recovery failed:", error);
    }
    ```
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { useWallet } from "@crossmint/client-sdk-react-native-ui";

    const { wallet } = useWallet();

    try {
        if (wallet.needsRecovery()) {
            await wallet.recover();
        }
    } catch (error) {
        console.error("Recovery failed:", error);
    }
    ```
  </Tab>

  <Tab title="Flutter">
    ```dart theme={null}
    import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

    final controller = CrossmintWalletContext.of(context).requireWalletController;
    final wallet = controller.createEvmWallet();

    try {
      if (wallet.needsRecovery) {
        await wallet.recover();
      }
    } catch (error) {
      debugPrint('Recovery failed: $error');
    }
    ```

    `needsRecovery` is a getter (no parens) on the Flutter runtime wallet.
  </Tab>
</Tabs>

## Chain Support

| Chain | Device Signer Support |
| - | - |
| EVM (Base, Ethereum, Polygon, etc.) | Supported |
| Stellar | Supported |
| Solana | Supported |

## Next Steps

<CardGroup>
  <Card title="Configure Recovery" icon="shield-halved" href="/wallets/guides/recovery/configure-recovery">
    Set up email or phone recovery for new device flows
  </Card>

  <Card title="Add Signers" icon="key" href="/wallets/guides/signers/add-signers">
    Add passkeys or external wallets as additional signers
  </Card>

  <Card title="Transfer Tokens" icon="arrow-right-arrow-left" href="/wallets/guides/transfer-tokens">
    Send tokens from your wallet
  </Card>
</CardGroup>


# Server-Side Wallet with Device Signer
Source: https://docs.crossmint.com/wallets/guides/signers/device-signer-server-wallet

Build a seamless wallet experience where your server manages wallet creation and recovery while users sign transactions instantly on their device — no OTP required.

Most applications create wallets server-side for security and control. However, to enable frictionless client-side signing with a [device signer](/wallets/guides/signers/device-signer), it must be registered at wallet creation time — otherwise, adding it later requires an OTP verification step.

This guide walks through the recommended pattern: generate the device signer on the client, send it to your server, create the wallet with both the device signer and an email recovery method, then return the wallet to the client.

## Prerequisites

* A **server API key** with `wallets.create` and `wallets.read` scopes
* A **client API key** for the React or React Native SDK
* `@crossmint/client-sdk-react-ui` installed on the client (React), or `@crossmint/client-sdk-react-native-ui` (React Native)

## Architecture

```mermaid theme={null}
sequenceDiagram
    participant C as Client
    participant S as Server

    C->>C: Generate device signer<br>`createDeviceSigner()`
    C->>S: user identity + device signer
    S->>S: POST /wallets<br>(recovery + device signer)
    Note over S: recovery = email or phone
    S-->>C: wallet creation confirmed
    C->>C: `createOnLogin` prop or `getWallet()`<br>Wallet available on login<br>(matches recovery method)
    Note over C: No OTP required
```

## Provider Setup

Wrap your app with the Crossmint providers. During the initial wallet creation flow, omit `createOnLogin` — the wallet will be created server-side in [Step 2](#step-2-create-the-wallet-server).

<Tabs>
  <Tab title="React">
    ```tsx theme={null}
    import {
        CrossmintProvider,
        CrossmintAuthProvider,
        CrossmintWalletProvider,
    } from "@crossmint/client-sdk-react-ui";

    function App({ children }) {
        return (
            <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
                <CrossmintAuthProvider loginMethods={["email", "google"]}>
                    <CrossmintWalletProvider>
                        {children}
                    </CrossmintWalletProvider>
                </CrossmintAuthProvider>
            </CrossmintProvider>
        );
    }
    ```
  </Tab>

  <Tab title="React Native">
    ```tsx theme={null}
    import { useEffect } from "react";
    import {
        CrossmintProvider,
        CrossmintWalletProvider,
        useCrossmint,
    } from "@crossmint/client-sdk-react-native-ui";

    // Replace with your auth provider
    // See: https://docs.crossmint.com/wallets/guides/bring-your-own-auth
    import { YourAuthProvider, useYourAuth } from "@your-auth-provider";

    function App({ children }) {
        return (
            <YourAuthProvider>
                <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
                    <CrossmintWalletProvider>
                        <JwtSync />
                        {children}
                    </CrossmintWalletProvider>
                </CrossmintProvider>
            </YourAuthProvider>
        );
    }

    function JwtSync() {
        const { jwt } = useYourAuth();
        const { setJwt } = useCrossmint();

        useEffect(() => {
            setJwt(jwt);
        }, [jwt]);

        return null;
    }
    ```
  </Tab>
</Tabs>

## Step 1: Create the Device Signer (Client)

Use `createDeviceSigner()` from the `useWallet` hook to generate a hardware-backed P256 keypair on the user's device. This happens **before** any wallet exists.

The returned descriptor contains the public key coordinates and a locator — it looks like this:

```json theme={null}
{
    "type": "device",
    "publicKey": { "x": "0x...", "y": "0x..." },
    "locator": "device:<base64-public-key>",
    "name": "Chrome on Mac"
}
```

<Tabs>
  <Tab title="React">
    ```tsx theme={null}
    import { useWallet } from "@crossmint/client-sdk-react-ui";
    import { useState } from "react";

    function CreateWalletFlow() {
        const { createDeviceSigner } = useWallet();
        const [walletAddress, setWalletAddress] = useState<string | null>(null);

        const handleCreateWallet = async () => {
            const deviceSigner = await createDeviceSigner();

            // Send the device signer to your server to create the wallet
            const response = await fetch("/api/wallet", {
                method: "POST",
                headers: { "Content-Type": "application/json" },
                body: JSON.stringify({
                    email: "user@example.com",
                    deviceSigner,
                }),
            });
            const { address } = await response.json();
            setWalletAddress(address);
        };

        return (
            <div>
                {walletAddress ? (
                    <p>Wallet: {walletAddress}</p>
                ) : (
                    <button onClick={handleCreateWallet}>Create Wallet</button>
                )}
            </div>
        );
    }
    ```

    <Note>
      The `createDeviceSigner()` function generates and stores the private key in the browser's secure storage (hidden iframe at `crossmint-signer.io`). The private key **never leaves the device** — only the public key descriptor is sent to the server.
    </Note>
  </Tab>

  <Tab title="React Native">
    ```tsx theme={null}
    import { useWallet } from "@crossmint/client-sdk-react-native-ui";
    import { useState } from "react";
    import { View, Text, TouchableOpacity } from "react-native";

    function CreateWalletFlow() {
        const { createDeviceSigner } = useWallet();
        const [walletAddress, setWalletAddress] = useState<string | null>(null);

        const handleCreateWallet = async () => {
            const deviceSigner = await createDeviceSigner();

            // Send the device signer to your server to create the wallet
            const response = await fetch("https://YOUR_SERVER/api/wallet", {
                method: "POST",
                headers: { "Content-Type": "application/json" },
                body: JSON.stringify({
                    email: "user@example.com",
                    deviceSigner,
                }),
            });
            const { address } = await response.json();
            setWalletAddress(address);
        };

        return (
            <View>
                {walletAddress ? (
                    <Text>Wallet: {walletAddress}</Text>
                ) : (
                    <TouchableOpacity onPress={handleCreateWallet}>
                        <Text>Create Wallet</Text>
                    </TouchableOpacity>
                )}
            </View>
        );
    }
    ```

    <Note>
      The `createDeviceSigner()` function generates and stores the private key in the device's native secure storage (iOS Secure Enclave / Android Keystore). The private key **never leaves the device** — only the public key descriptor is sent to the server.
    </Note>
  </Tab>
</Tabs>

## Step 2: Create the Wallet (Server)

On your server, use the device signer descriptor received from the client to create a wallet with email recovery and the device signer pre-registered.

<CodeGroup>
  ```typescript Node.js theme={null}
  import { createCrossmint, CrossmintWallets } from "@crossmint/wallets-sdk";

  const crossmint = createCrossmint({
      apiKey: "YOUR_SERVER_API_KEY",
  });

  const crossmintWallets = CrossmintWallets.from(crossmint);

  // deviceSigner is the object received from the client
  const wallet = await crossmintWallets.createWallet({
      chain: "base-sepolia",
      owner: "email:user@example.com",
      recoveryMethods: [
          {
              type: "email",
              email: "user@example.com",
          },
      ],
      signers: [deviceSigner],
  });

  console.log("Wallet created:", wallet.address);
  // Return wallet.address to the client
  ```

  ```bash cURL theme={null}
  # Note: The REST API uses different field names than the SDK:
  #   - "config.recoveryMethods" instead of "recoveryMethods"
  #   - "config.delegatedSigners" instead of "signers"
  # Public key coordinates must be decimal strings (not hex).
  curl --request POST \
      --url 'https://staging.crossmint.com/api/2025-06-09/wallets' \
      --header 'X-API-KEY: YOUR_SERVER_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
          "chainType": "evm",
          "type": "smart",
          "owner": "email:user@example.com",
          "config": {
              "recoveryMethods": [
                  {
                      "type": "email",
                      "email": "user@example.com"
                  }
              ],
              "delegatedSigners": [
                  {
                      "signer": {
                          "type": "device",
                          "publicKey": {
                              "x": "DECIMAL_STRING_X_COORDINATE",
                              "y": "DECIMAL_STRING_Y_COORDINATE"
                          },
                          "name": "Chrome on Mac"
                      }
                  }
              ]
          }
      }'
  ```

  ```python Python theme={null}
  # Note: The REST API uses different field names than the SDK:
  #   - "config.recoveryMethods" instead of "recoveryMethods"
  #   - "config.delegatedSigners" instead of "signers"
  # Public key coordinates must be decimal strings (not hex).
  import requests

  url = "https://staging.crossmint.com/api/2025-06-09/wallets"

  payload = {
      "chainType": "evm",
      "type": "smart",
      "owner": "email:user@example.com",
      "config": {
          "recoveryMethods": [
              {
                  "type": "email",
                  "email": "user@example.com"
              }
          ],
          "delegatedSigners": [
              {
                  "signer": {
                      "type": "device",
                      "publicKey": {
                          "x": "DECIMAL_STRING_X_COORDINATE",
                          "y": "DECIMAL_STRING_Y_COORDINATE"
                      },
                      "name": "Chrome on Mac"
                  }
              }
          ]
      }
  }
  headers = {
      "X-API-KEY": "YOUR_SERVER_API_KEY",
      "Content-Type": "application/json"
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.json())
  ```
</CodeGroup>

## Step 3: Use the Wallet (Client)

Once the wallet is created server-side, the client needs to retrieve it. Choose the approach that fits your app:

<Tabs>
  <Tab title="Get Wallet on Login">
    Enable `createOnLogin` on `CrossmintWalletProvider` so the wallet is automatically retrieved whenever the user logs in — no explicit `getWallet()` call needed. This is the recommended approach for most apps.

    <Tabs>
      <Tab title="React">
        ```tsx theme={null}
        import {
            CrossmintProvider,
            CrossmintAuthProvider,
            CrossmintWalletProvider,
        } from "@crossmint/client-sdk-react-ui";

        function App({ children }) {
            return (
                <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
                    <CrossmintAuthProvider loginMethods={["email", "google"]}>
                        <CrossmintWalletProvider
                            createOnLogin={{
                                chain: "base-sepolia",
                                recoveryMethods: [{ type: "email" }],
                            }}
                        >
                            {children}
                        </CrossmintWalletProvider>
                    </CrossmintAuthProvider>
                </CrossmintProvider>
            );
        }
        ```

        With `createOnLogin` enabled, any component using `useWallet()` will automatically have access to the wallet after the user logs in:

        ```tsx theme={null}
        import { useWallet } from "@crossmint/client-sdk-react-ui";

        function WalletActions() {
            const { wallet, status } = useWallet();

            if (status === "in-progress") return <p>Loading...</p>;
            if (!wallet) return <p>No wallet</p>;

            const handleSend = async () => {
                const { hash, explorerLink } = await wallet.send(
                    "0xYOUR_RECIPIENT_ADDRESS",
                    "usdc",
                    "10"
                );
                console.log("Transaction:", explorerLink);
            };

            return (
                <div>
                    <p>Wallet: {wallet.address}</p>
                    <button onClick={handleSend}>Send USDC</button>
                </div>
            );
        }
        ```
      </Tab>

      <Tab title="React Native">
        ```tsx theme={null}
        import { useEffect } from "react";
        import {
            CrossmintProvider,
            CrossmintWalletProvider,
            useCrossmint,
        } from "@crossmint/client-sdk-react-native-ui";

        // Replace with your auth provider
        import { YourAuthProvider, useYourAuth } from "@your-auth-provider";

        function App({ children }) {
            return (
                <YourAuthProvider>
                    <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
                        <CrossmintWalletProvider
                            createOnLogin={{
                                chain: "base-sepolia",
                                recoveryMethods: [{ type: "email" }],
                            }}
                        >
                            <JwtSync />
                            {children}
                        </CrossmintWalletProvider>
                    </CrossmintProvider>
                </YourAuthProvider>
            );
        }

        function JwtSync() {
            const { jwt } = useYourAuth();
            const { setJwt } = useCrossmint();

            useEffect(() => {
                setJwt(jwt);
            }, [jwt]);

            return null;
        }
        ```

        With `createOnLogin` enabled, any component using `useWallet()` will automatically have access to the wallet after the user logs in:

        ```tsx theme={null}
        import { useWallet } from "@crossmint/client-sdk-react-native-ui";
        import { View, Text, TouchableOpacity } from "react-native";

        function WalletActions() {
            const { wallet, status } = useWallet();

            if (status === "in-progress") return <Text>Loading...</Text>;
            if (!wallet) return <Text>No wallet</Text>;

            const handleSend = async () => {
                const { hash, explorerLink } = await wallet.send(
                    "0xYOUR_RECIPIENT_ADDRESS",
                    "usdc",
                    "10"
                );
                console.log("Transaction:", explorerLink);
            };

            return (
                <View>
                    <Text>Wallet: {wallet.address}</Text>
                    <TouchableOpacity onPress={handleSend}>
                        <Text>Send USDC</Text>
                    </TouchableOpacity>
                </View>
            );
        }
        ```
      </Tab>
    </Tabs>

    <Note>
      `createOnLogin` will retrieve an existing wallet if one is found for the logged-in user, or create a new one if none exists. Since the wallet was already created server-side, it will be retrieved automatically.
    </Note>
  </Tab>

  <Tab title="Get Wallet on Demand">
    Keep the [provider setup](#provider-setup) as-is (without `createOnLogin`) and call `getWallet()` explicitly whenever you need the wallet. Use this approach when you want full control over when the wallet is fetched.

    <Tabs>
      <Tab title="React">
        ```tsx theme={null}
        import { useWallet } from "@crossmint/client-sdk-react-ui";
        import { useEffect } from "react";

        function WalletActions() {
            const { wallet, status, getWallet } = useWallet();

            useEffect(() => {
                async function fetchWallet() {
                    await getWallet({ chain: "base-sepolia" });
                }
                fetchWallet();
            }, []);

            if (status === "in-progress") return <p>Loading...</p>;
            if (!wallet) return <p>No wallet</p>;

            return (
                <div>
                    <p>Wallet: {wallet.address}</p>
                </div>
            );
        }
        ```
      </Tab>

      <Tab title="React Native">
        ```tsx theme={null}
        import { useWallet } from "@crossmint/client-sdk-react-native-ui";
        import { useEffect } from "react";
        import { View, Text } from "react-native";

        function WalletActions() {
            const { wallet, status, getWallet } = useWallet();

            useEffect(() => {
                async function fetchWallet() {
                    await getWallet({ chain: "base-sepolia" });
                }
                fetchWallet();
            }, []);

            if (status === "in-progress") return <Text>Loading...</Text>;
            if (!wallet) return <Text>No wallet</Text>;

            return (
                <View>
                    <Text>Wallet: {wallet.address}</Text>
                </View>
            );
        }
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## New Device Recovery

When the user accesses their wallet from a new device, there is no local device signer. The SDK handles this automatically:

1. `wallet.needsRecovery()` returns `true`
2. On the first transaction (or explicit `recover()` call), the recovery method (email OTP) authorizes a new device signer
3. After recovery, all subsequent transactions are frictionless again

See [Device Signer — New Device Recovery](/wallets/guides/signers/device-signer#new-device-recovery) for details.

## Next Steps

<CardGroup>
  <Card title="Device Signer" icon="microchip" href="/wallets/guides/signers/device-signer">
    Understand how hardware-backed device signers work
  </Card>

  <Card title="Configure Recovery" icon="shield-halved" href="/wallets/guides/recovery/configure-recovery">
    Explore other recovery method options
  </Card>

  <Card title="Transfer Tokens" icon="arrow-right-arrow-left" href="/wallets/guides/transfer-tokens">
    Send tokens from your wallet
  </Card>
</CardGroup>


# External Wallet Signer
Source: https://docs.crossmint.com/wallets/guides/signers/external-wallet

Configure an external wallet or keypair as a signer at wallet creation.

Use an external wallet signer to connect an existing blockchain wallet or raw keypair — such as MetaMask, Phantom, or a backend keypair — as an operational signer on a Crossmint smart wallet. This is the right choice when your users already have a wallet they want to use to control a Crossmint smart wallet.

Supported on **EVM, Solana, and Stellar**.

## Configuration

Configure the wallet with an external wallet as the operational signer at creation time. The `address` is the public address of the external wallet.

<Tabs>
  <Tab title="React">
    Using `createOnLogin` on the provider:

    ```tsx theme={null}
    import {
        CrossmintProvider,
        CrossmintAuthProvider,
        CrossmintWalletProvider,
    } from "@crossmint/client-sdk-react-ui";

    function App({ children }) {
        return (
            <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
                <CrossmintAuthProvider loginMethods={["email"]}>
                    <CrossmintWalletProvider
                        createOnLogin={{
                            chain: "base-sepolia",
                            recoveryMethods: [{ type: "email" }],
                            signers: [{
                                type: "external-wallet",
                                address: "0x1234...abcd",
                            }],
                        }}
                    >
                        {children}
                    </CrossmintWalletProvider>
                </CrossmintAuthProvider>
            </CrossmintProvider>
        );
    }
    ```

    Or create the wallet explicitly:

    ```typescript theme={null}
    import { useWallet } from "@crossmint/client-sdk-react-ui";

    const { createWallet } = useWallet();

    const wallet = await createWallet({
        chain: "base-sepolia",
        recoveryMethods: [{ type: "email", email: "user@example.com" }],
        signers: [{
            type: "external-wallet",
            address: "0x1234...abcd",
        }],
    });
    ```
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";

    const crossmint = createCrossmint({
        apiKey: "YOUR_SERVER_API_KEY",
    });
    const crossmintWallets = CrossmintWallets.from(crossmint);

    const wallet = await crossmintWallets.createWallet({
        chain: "base-sepolia",
        recoveryMethods: [{ type: "email", email: "user@example.com" }],
        signers: [{
            type: "external-wallet",
            address: "0x1234...abcd",
        }],
    });
    ```
  </Tab>
</Tabs>

## Signing Transactions

External wallet signing requires an `onSign` callback. Before sending transactions, activate the signer with the full config:

```typescript theme={null}
wallet.useSigner({
    type: "external-wallet",
    address: "0x1234...abcd",
    onSign: async (payload) => {
        // EVM: payload is a hex-encoded message; return a hex-encoded signature
        // Solana: payload is a VersionedTransaction; return the signed transaction
        // Stellar: payload is a string; return a signed string
        return await externalWallet.signMessage(payload);
    },
});

const { hash } = await wallet.send(
    "0xRecipientAddress",
    "usdc",
    "10"
);
```

See [Add Signers — External Wallet `onSign` by Chain](/wallets/guides/signers/add-signers#external-wallet-onsign-by-chain) for chain-specific `onSign` signatures and return values.

## Adding an External Wallet to an Existing Wallet

If the wallet already exists with a different signer, you can register an external wallet via `wallet.addSigner({ type: "external-wallet", address })`. See [Add Signers](/wallets/guides/signers/add-signers#add-an-external-wallet-signer) for the full flow.

## Next Steps

<CardGroup>
  <Card title="Add Signers" icon="key" href="/wallets/guides/signers/add-signers">
    Register additional signers on an existing wallet
  </Card>

  <Card title="Configure Recovery" icon="shield-halved" href="/wallets/guides/recovery/configure-recovery">
    Set up email or phone recovery
  </Card>

  <Card title="Device Signer" icon="microchip" href="/wallets/guides/signers/device-signer">
    The default client-side signer
  </Card>
</CardGroup>


# List Wallet Signers
Source: https://docs.crossmint.com/wallets/guides/signers/list-signers

Retrieve all operational signers registered on a wallet, check registration status, and access the recovery methods

## Overview

The List Wallet Signers API allows you to retrieve all operational signers registered on a wallet. Each signer includes its type, locator, and current status. Recovery methods are accessed separately via `wallet.recoveryMethods`. This is useful for displaying signer management UIs, checking which signers are active, or verifying that a new signer was registered successfully.

## Prerequisites

* You have a wallet created
* **API Key**: You have an API key with the scope: `wallets.read`. In staging, all scopes are included

## Listing Signers

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet } from "@crossmint/client-sdk-react-ui";

    const { wallet } = useWallet();

    const signers = await wallet.signers();

    for (const signer of signers) {
        console.log(signer.type, signer.locator, signer.status);
    }
    ```
  </Tab>

  <Tab title="Flutter">
    ```dart theme={null}
    import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

    final controller = CrossmintWalletContext.of(context).requireWalletController;
    final wallet = controller.createEvmWallet();

    final signers = await wallet.signers();
    for (final signer in signers) {
      print('${signer.type} ${signer.locator} ${signer.status}');
    }

    // Check a specific signer
    final isRegistered = await wallet.signerIsRegistered('device:abc123');

    // The recovery method is available on the runtime wallet:
    final recovery = wallet.recovery;
    ```
  </Tab>

  <Tab title="Node.js">
    ### With a Wallet Address

    ```typescript theme={null}
    import {
        createCrossmint,
        CrossmintWallets,
    } from "@crossmint/wallets-sdk";

    const crossmint = createCrossmint({
        apiKey: "<your-server-api-key>",
    });
    const wallets = CrossmintWallets.from(crossmint);

    const wallet = await wallets.getWallet(
        "YOUR_WALLET_ADDRESS",
        { chain: "base-sepolia" }
    );

    const signers = await wallet.signers();

    for (const signer of signers) {
        console.log(signer.type, signer.locator, signer.status);
    }
    ```

    ### With a User Locator

    ```typescript theme={null}
    const wallet = await wallets.getWallet(
        "email:user@example.com",
        { chain: "base-sepolia" }
    );

    const signers = await wallet.signers();
    console.log(signers);
    ```
  </Tab>

  <Tab title="REST">
    Fetch the wallet details — signers are included in the response under the `config` field.

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request GET \
          --url 'https://staging.crossmint.com/api/2025-06-09/wallets/<WALLET_ADDRESS>' \
          --header 'X-API-KEY: <your-server-api-key>'
      ```

      ```javascript Node.js theme={null}
      const url =
          "https://staging.crossmint.com/api/2025-06-09/wallets/<WALLET_ADDRESS>";

      const response = await fetch(url, {
          method: "GET",
          headers: {
              "X-API-KEY": "<your-server-api-key>",
          },
      });

      const data = await response.json();

      // Recovery methods
      console.log("Recovery methods:", data.config?.recoveryMethods);

      // Operational signers
      console.log("Signers:", data.config?.delegatedSigners);
      ```

      ```python Python theme={null}
      import requests

      url = "https://staging.crossmint.com/api/2025-06-09/wallets/<WALLET_ADDRESS>"
      headers = {"X-API-KEY": "<your-server-api-key>"}

      response = requests.get(url, headers=headers)
      data = response.json()

      # Recovery methods
      print("Recovery methods:", data.get("config", {}).get("recoveryMethods"))

      # Operational signers
      print("Signers:", data.get("config", {}).get("delegatedSigners"))
      ```
    </CodeGroup>

    You can also retrieve a specific signer by its locator:

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request GET \
          --url 'https://staging.crossmint.com/api/2025-06-09/wallets/<WALLET_ADDRESS>/signers/<SIGNER_LOCATOR>' \
          --header 'X-API-KEY: <your-server-api-key>'
      ```

      ```javascript Node.js theme={null}
      const url =
          "https://staging.crossmint.com/api/2025-06-09/wallets/<WALLET_ADDRESS>/signers/<SIGNER_LOCATOR>";

      const response = await fetch(url, {
          method: "GET",
          headers: {
              "X-API-KEY": "<your-server-api-key>",
          },
      });

      const signer = await response.json();
      console.log(signer);
      ```

      ```python Python theme={null}
      import requests

      url = "https://staging.crossmint.com/api/2025-06-09/wallets/<WALLET_ADDRESS>/signers/<SIGNER_LOCATOR>"
      headers = {"X-API-KEY": "<your-server-api-key>"}

      response = requests.get(url, headers=headers)
      print(response.json())
      ```
    </CodeGroup>

    See the [Get Signer API reference](/api-reference/wallets/get-signer) for full parameter details and to test requests in the playground.
  </Tab>
</Tabs>

## Checking If a Signer Is Registered

Use `signerIsRegistered()` to check whether a specific signer is already registered on the wallet, without retrieving the full list:

```typescript theme={null}
const isRegistered = await wallet.signerIsRegistered("device:abc123");
console.log("Registered:", isRegistered); // true or false
```

## Accessing the Recovery Methods

Recovery methods are separate from the operational signers returned by `wallet.signers()`. `wallet.recoveryMethods` returns every recovery method configured on the wallet:

```typescript theme={null}
for (const method of wallet.recoveryMethods) {
    console.log("Recovery method:", method.type);
}
```

Operations such as adding or removing a signer are authorized by one of these recovery methods. A wallet with a single recovery method uses it automatically; a wallet with several needs you to pick one with `useRecoveryMethod()` before calling `addSigner()` or `removeSigner()`:

```typescript theme={null}
await wallet.useRecoveryMethod({ type: "phone", phone: "+1234567890" });
```

See [Manage Recovery Methods](/wallets/guides/recovery/manage-recovery-methods) for the full selection rules and for adding or removing recovery methods on an existing wallet.

## Signer Response Shape

Each operational signer returned by `wallet.signers()` includes:

| Field | Type | Description |
| - | - | - |
| `type` | `string` | The signer type — `"device"`, `"passkey"`, `"external-wallet"`, `"server"`, `"email"`, or `"phone"` |
| `locator` | `string` | Unique identifier for the signer (e.g., `"device:abc123"`, `"passkey:xyz789"`) |
| `status` | `SignerStatus` | Current status — `"success"`, `"pending"`, `"awaiting-approval"`, or `"failed"` |

## Important Notes

<AccordionGroup>
  <Accordion title="EVM Chain Filtering">
    For EVM wallets, `wallet.signers()` only returns signers that have an approval (pending or completed) for the wallet's specific chain. Signers registered on other chains are not included.
  </Accordion>

  <Accordion title="SDK vs REST API Field Names">
    The SDK uses `recoveryMethods` and `signers` terminology. When using the REST API directly, the corresponding fields are `recoveryMethods` (recovery methods) and `delegatedSigners` (operational signers).
  </Accordion>

  <Accordion title="Read-Only Wallet from getWallet (Server-Side)">
    When you retrieve a wallet server-side with `getWallet`, the wallet is in a read-only state — `wallet.signer` will be `undefined`. You must call `useSigner()` before performing any signing operations. However, `wallet.signers()` works without an active signer since it is a read operation.
  </Accordion>

  <Accordion title="Signer Status Values">
    * **`success`** — Signer is fully registered and active
    * **`pending`** — Registration is in progress
    * **`awaiting-approval`** — Signer needs approval from a recovery method
    * **`failed`** — Registration failed

    For EVM signers, `pending` and `awaiting-approval` indicate a pending operation. The operation is a transaction when `deployImmediately` is `true` (the TypeScript SDK default) and a signature when `deployImmediately` is `false` (the REST API default). The signer becomes `success` once the transaction confirms or the signature is approved. See [Installation Timing](/wallets/guides/signers/add-signers#installation-timing).
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Add Signers" icon="user-plus" href="/wallets/guides/signers/add-signers">
    Register additional signers on your wallet
  </Card>

  <Card title="Configure Recovery" icon="shield-halved" href="/wallets/guides/recovery/configure-recovery">
    Set up recovery methods for your wallets
  </Card>

  <Card title="Transfer Tokens" icon="arrow-right-arrow-left" href="/wallets/guides/transfer-tokens">
    Send tokens from your wallet
  </Card>
</CardGroup>


# Passkey Signer
Source: https://docs.crossmint.com/wallets/guides/signers/passkey

Configure a passkey signer at wallet creation using WebAuthn biometric authentication.

Use a passkey signer to let users sign transactions with biometric authentication — Face ID, Touch ID, fingerprint, or Windows Hello. Passkeys are built on the <a href="https://www.w3.org/TR/webauthn-3/">WebAuthn</a> standard and are synchronized across devices via providers like Apple Keychain, Google Password Manager, and 1Password.

## Supported Chains

| Chain | Operational signer | Recovery method |
| - | - | - |
| EVM | ✅ | ✅ |
| Stellar | ✅ | ✅ |
| Solana | ✅ | ❌ |

## Configuration

Configure the wallet to use a passkey as the operational signer at creation time. The SDK handles WebAuthn registration during the first wallet creation.

<Tabs>
  <Tab title="React">
    Using `createOnLogin` on the provider:

    ```tsx theme={null}
    import {
        CrossmintProvider,
        CrossmintAuthProvider,
        CrossmintWalletProvider,
    } from "@crossmint/client-sdk-react-ui";

    function App({ children }) {
        return (
            <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
                <CrossmintAuthProvider loginMethods={["email", "google"]}>
                    <CrossmintWalletProvider
                        createOnLogin={{
                            chain: "base-sepolia",
                            recoveryMethods: [{ type: "email" }],
                            signers: [{ type: "passkey" }],
                        }}
                    >
                        {children}
                    </CrossmintWalletProvider>
                </CrossmintAuthProvider>
            </CrossmintProvider>
        );
    }
    ```

    Or create the wallet explicitly:

    ```typescript theme={null}
    import { useWallet } from "@crossmint/client-sdk-react-ui";

    const { createWallet } = useWallet();

    const wallet = await createWallet({
        chain: "base-sepolia",
        recoveryMethods: [{ type: "email", email: "user@example.com" }],
        signers: [{ type: "passkey" }],
    });
    ```

    The same configuration works on Stellar and Solana: set `chain` to `"stellar"` or `"solana"`. On Stellar a passkey can also be a recovery method (`recoveryMethods: [{ type: "passkey" }]`); on Solana it can only be an operational signer.

    Each transaction triggers a biometric authentication prompt.
  </Tab>

  <Tab title="React Native">
    React Native uses the platform passkey APIs (iOS AuthenticationServices, Android Credential Manager) through the <a href="https://github.com/f-23/react-native-passkey">`react-native-passkey`</a> package.

    <Steps>
      <Step title="Install the native module">
        Install `react-native-passkey` and rebuild the app. Passkeys need a development build; Expo Go cannot run native modules.

        ```bash theme={null}
        npx expo install react-native-passkey
        ```
      </Step>

      <Step title="Associate the app with the relying party domain">
        Associate the app with the domain you use as the relying party ID (`rpId`):

        * **iOS:** add the associated domain `webcredentials:app.example.com` to the app, and serve an `apple-app-site-association` file from the domain that lists the app.
        * **Android:** serve `/.well-known/assetlinks.json` from the domain with the `delegate_permission/common.get_login_creds` relation for the app's package name and signing certificate.
      </Step>

      <Step title="Configure passkeys on the wallet provider">
        Pass `passkeys` to `CrossmintWalletProvider`. Pass `Passkey` from `react-native-passkey` so your bundler links the native module:

        ```tsx theme={null}
        import { Passkey } from "react-native-passkey";
        import {
            CrossmintProvider,
            CrossmintAuthProvider,
            CrossmintWalletProvider,
        } from "@crossmint/client-sdk-react-native-ui";

        function App({ children }) {
            return (
                <CrossmintProvider apiKey="YOUR_CLIENT_API_KEY">
                    <CrossmintAuthProvider loginMethods={["email", "google"]}>
                        <CrossmintWalletProvider
                            passkeys={{ rpId: "app.example.com", rpName: "Example", passkey: Passkey }}
                            createOnLogin={{
                                chain: "base-sepolia",
                                recoveryMethods: [{ type: "email" }],
                                signers: [{ type: "passkey" }],
                            }}
                        >
                            {children}
                        </CrossmintWalletProvider>
                    </CrossmintAuthProvider>
                </CrossmintProvider>
            );
        }
        ```
      </Step>
    </Steps>

    <Warning>
      Keep `rpId` fixed once users have created passkeys. A passkey only works for the domain it was created for.
    </Warning>

    Without the `passkeys` prop, the React Native SDK rejects passkey signers. Every passkey operation requires user verification (biometrics or a device PIN).
  </Tab>

  <Tab title="Swift">
    The Swift SDK uses the iOS passkey APIs (AuthenticationServices) and shows the system prompts for you. The steps below need a signed-in user; see the [Swift quickstart](/wallets/quickstarts/swift) to configure the SDK and sign the user in.

    <Steps>
      <Step title="Associate the app with the relying party domain">
        Add the associated domain `webcredentials:app.example.com` to the app, and serve an `apple-app-site-association` file from the domain that lists the app. The SDK uses this domain (`host`) as the relying party ID.
      </Step>

      <Step title="Create the wallet with a passkey signer">
        Pass a passkey in `signers`. The SDK asks the user to create the passkey, then creates the wallet:

        ```swift theme={null}
        import CrossmintClient

        CrossmintSDK.configure(apiKey: "YOUR_CLIENT_API_KEY")
        let sdk = CrossmintSDK.shared

        let passkey = SignerConfig.passkey(name: "user@example.com", host: "app.example.com")

        let wallet = try await sdk.crossmintWallets.createWallet(
            chain: EVMChain.baseSepolia,
            recoveryMethods: [EVMSigners.email("user@example.com")],
            signers: [passkey]
        )
        try await wallet.useSigner(passkey)
        ```

        `name` is the account name that the passkey prompt shows.
      </Step>

      <Step title="Sign with the passkey on later launches">
        Set `passkeyHost` when you get the wallet. The SDK then signs with the passkey:

        ```swift theme={null}
        // Uses the SDK configured in the create step
        import CrossmintClient

        let wallet = try await CrossmintSDK.shared.crossmintWallets.getWallet(
            chain: EVMChain.baseSepolia,
            options: WalletOptions(passkeyHost: "app.example.com")
        )
        ```
      </Step>
    </Steps>

    The same configuration works on Stellar and Solana: use `StellarChain.stellar` or `SolanaChain.solana`. On Stellar a passkey can also be a recovery method (`StellarSigners.passkey(name:host:)`); on Solana it can only be a signer.
  </Tab>

  <Tab title="Kotlin">
    The Kotlin SDK uses Android Credential Manager through the `sdk-passkeys` module. The steps below need a configured SDK and a signed-in user; see the [Kotlin quickstart](/wallets/quickstarts/kotlin).

    <Steps>
      <Step title="Add the passkeys module">
        The `crossmint-sdk` artifact does not include passkey support. Add `sdk-passkeys` with the same version:

        ```kotlin build.gradle.kts theme={null}
        dependencies {
            implementation(libs.crossmint.sdk)
            implementation(libs.crossmint.sdk.passkeys)
        }
        ```

        ```toml libs.versions.toml theme={null}
        [libraries]
        crossmint-sdk-passkeys = { module = "com.crossmint:sdk-passkeys", version.ref = "crossmint-sdk" }
        ```
      </Step>

      <Step title="Associate the app with the relying party domain">
        Serve `/.well-known/assetlinks.json` from the domain you use as the relying party ID (`rpId`), with the `delegate_permission/common.get_login_creds` relation for the app's package name and signing certificate.
      </Step>

      <Step title="Create the wallet with a passkey signer">
        Create the passkey with `createPasskeyCredential`, and pass it in `signers`. `AndroidPasskeyProvider` shows the passkey prompt each time the wallet signs:

        ```kotlin theme={null}
        import android.app.Activity
        import androidx.credentials.CredentialManager
        import com.crossmint.kotlin.CrossmintSDK
        import com.crossmint.kotlin.passkeys.AndroidPasskeyProvider
        import com.crossmint.kotlin.passkeys.createPasskeyCredential
        import com.crossmint.kotlin.signers.DelegatedSigner
        import com.crossmint.kotlin.signers.SignerType
        import com.crossmint.kotlin.types.EVMChain
        import com.crossmint.kotlin.types.getOrThrow

        suspend fun createPasskeyWallet(activity: Activity) {
            val credential = createPasskeyCredential(
                name = "user@example.com",
                activityProvider = { activity },
                credentialManager = CredentialManager.create(activity),
                rpId = "app.example.com",
                rpName = "Example",
            ) ?: return

            val wallet = CrossmintSDK.shared.wallets.createWallet(
                chain = EVMChain.BaseSepolia,
                recoveryMethods = listOf(SignerType.Email("user@example.com")),
                signers = listOf(
                    DelegatedSigner.Passkey(
                        id = credential.id,
                        name = credential.name,
                        publicKeyX = credential.publicKeyX,
                        publicKeyY = credential.publicKeyY,
                    ),
                ),
                passkeyProvider = AndroidPasskeyProvider(rpId = "app.example.com"),
            ).getOrThrow()
        }
        ```

        `createPasskeyCredential` returns `null` when the user cancels or the passkey cannot be created.
      </Step>

      <Step title="Sign with the passkey on later launches">
        Pass an `AndroidPasskeyProvider` when you get the wallet. The SDK then signs with the passkey:

        ```kotlin theme={null}
        // Uses the SDK configured at app start, as in the create step
        import com.crossmint.kotlin.CrossmintSDK
        import com.crossmint.kotlin.passkeys.AndroidPasskeyProvider
        import com.crossmint.kotlin.types.EVMChain
        import com.crossmint.kotlin.types.getOrThrow

        val wallet = CrossmintSDK.shared.wallets.getWallet(
            chain = EVMChain.BaseSepolia,
            passkeyProvider = AndroidPasskeyProvider(rpId = "app.example.com"),
        ).getOrThrow()
        ```
      </Step>
    </Steps>

    The same configuration works on Stellar and Solana: use `StellarChain.Stellar` or `SolanaChain.Solana`. On Stellar a passkey can also be a recovery method (`SignerType.Passkey`); on Solana it can only be a signer.
  </Tab>
</Tabs>

## Adding a Passkey to an Existing Wallet

If the wallet already exists with a different signer, you can add a passkey with `addSigner`. See [Add Signers](/wallets/guides/signers/add-signers#add-a-passkey-signer) for the full flow.

## Next Steps

<CardGroup>
  <Card title="Add Signers" icon="key" href="/wallets/guides/signers/add-signers">
    Register additional signers on an existing wallet
  </Card>

  <Card title="Configure Recovery" icon="shield-halved" href="/wallets/guides/recovery/configure-recovery">
    Set up email or phone recovery
  </Card>

  <Card title="Device Signer" icon="microchip" href="/wallets/guides/signers/device-signer">
    The default client-side signer
  </Card>
</CardGroup>


# Use a Quorum Signer
Source: https://docs.crossmint.com/wallets/guides/signers/quorum-signer

Create an m-of-n quorum signer and approve transactions with several members

A quorum signer approves a wallet action only when `threshold` of its members sign. This guide uses the REST API to create a wallet with a 2-of-3 recovery quorum, add a 2-of-3 operational quorum, sign a transaction with it, and rotate quorum members. For the concept, see [Quorum Signers](/wallets/concepts/quorum-signers).

The examples use an EVM wallet on `base-sepolia` with two quorums: a recovery quorum of email and phone members, and an operational quorum of three external wallets that signs the transaction. The same requests work on Solana and Stellar, with the Solana difference shown in [Sign a Transaction with a Quorum](#sign-a-transaction-with-a-quorum).

## Prerequisites

<Snippet />

* **API key**: A server API key with the `wallets.create`, `wallets:transactions.create`, and `wallets:transactions.sign` scopes. In staging, all scopes are included by default.
* **Members**: The signers that will form the quorum, from 2 to 10. Each member must be able to sign its own approval message. See [Rules and Limits](/wallets/concepts/quorum-signers#rules-and-limits) for the member types on each chain.

## Create a Wallet with a Quorum Recovery Method

Add an entry with `type: "quorum"` to `recoveryMethods`. Set `threshold` to the number of members that must sign, and list the members in `members`. Here, any 2 of the 3 members can recover the wallet and change its signers.

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
      --url https://staging.crossmint.com/api/2025-06-09/wallets \
      --header 'Content-Type: application/json' \
      --header 'X-API-KEY: YOUR_SERVER_API_KEY' \
      --data '{
          "chainType": "evm",
          "config": {
              "recoveryMethods": [
                  {
                      "type": "quorum",
                      "threshold": 2,
                      "members": [
                          { "type": "email", "email": "alice@example.com" },
                          { "type": "email", "email": "bob@example.com" },
                          { "type": "phone", "phone": "+12025550143" }
                      ]
                  }
              ]
          }
      }'
  ```

  ```js Node.js theme={null}
  const url = "https://staging.crossmint.com/api/2025-06-09/wallets";

  const payload = {
      chainType: "evm",
      config: {
          recoveryMethods: [
              {
                  type: "quorum",
                  threshold: 2,
                  members: [
                      { type: "email", email: "alice@example.com" },
                      { type: "email", email: "bob@example.com" },
                      { type: "phone", phone: "+12025550143" },
                  ],
              },
          ],
      },
  };

  const response = await fetch(url, {
      method: "POST",
      headers: {
          "X-API-KEY": "YOUR_SERVER_API_KEY",
          "Content-Type": "application/json",
      },
      body: JSON.stringify(payload),
  });

  const data = await response.json();
  console.log(data.config.recoveryMethods);
  ```

  ```python Python theme={null}
  import requests

  url = "https://staging.crossmint.com/api/2025-06-09/wallets"

  payload = {
      "chainType": "evm",
      "config": {
          "recoveryMethods": [
              {
                  "type": "quorum",
                  "threshold": 2,
                  "members": [
                      {"type": "email", "email": "alice@example.com"},
                      {"type": "email", "email": "bob@example.com"},
                      {"type": "phone", "phone": "+12025550143"}
                  ]
              }
          ]
      }
  }
  headers = {
      "X-API-KEY": "YOUR_SERVER_API_KEY",
      "Content-Type": "application/json"
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.json()["config"]["recoveryMethods"])
  ```
</CodeGroup>

The response lists the quorum under `config.recoveryMethods` with the `locator` that Crossmint assigned to it. Each member also has its own locator:

```json theme={null}
[
    {
        "type": "quorum",
        "locator": "quorum:3f6b2c1e-8a4d-4f7b-9c2e-5d1a7b8e9f04",
        "threshold": 2,
        "members": [
            { "type": "email", "email": "alice@example.com", "locator": "email:alice@example.com" },
            { "type": "email", "email": "bob@example.com", "locator": "email:bob@example.com" },
            { "type": "phone", "phone": "+12025550143", "locator": "phone:+12025550143" }
        ]
    }
]
```

A quorum can also sit next to other recovery methods in the same list. Each other method then acts alone, and the quorum is a second path that needs `threshold` members.

## Add a Quorum as an Operational Signer

To require several approvals for day-to-day transactions, register the quorum as an operational signer with the [register delegated key](/api-reference/wallets/register-delegated-key) endpoint. The `signer` field takes the same quorum object:

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
      --url https://staging.crossmint.com/api/2025-06-09/wallets/<wallet-address>/signers \
      --header 'Content-Type: application/json' \
      --header 'X-API-KEY: YOUR_SERVER_API_KEY' \
      --data '{
          "chain": "base-sepolia",
          "signer": {
              "type": "quorum",
              "threshold": 2,
              "members": [
                  { "type": "external-wallet", "address": "0x8617E340B3D01FA5F11F306F4090FD50E238070D" },
                  { "type": "external-wallet", "address": "0xde709f2102306220921060314715629080e2fb77" },
                  { "type": "external-wallet", "address": "0x27b1fdb04752bbc536007a920d24acb045561c26" }
              ]
          }
      }'
  ```

  ```js Node.js theme={null}
  const url = "https://staging.crossmint.com/api/2025-06-09/wallets/<wallet-address>/signers";

  const payload = {
      chain: "base-sepolia",
      signer: {
          type: "quorum",
          threshold: 2,
          members: [
              { type: "external-wallet", address: "0x8617E340B3D01FA5F11F306F4090FD50E238070D" },
              { type: "external-wallet", address: "0xde709f2102306220921060314715629080e2fb77" },
              { type: "external-wallet", address: "0x27b1fdb04752bbc536007a920d24acb045561c26" },
          ],
      },
  };

  const response = await fetch(url, {
      method: "POST",
      headers: {
          "X-API-KEY": "YOUR_SERVER_API_KEY",
          "Content-Type": "application/json",
      },
      body: JSON.stringify(payload),
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  url = "https://staging.crossmint.com/api/2025-06-09/wallets/<wallet-address>/signers"

  payload = {
      "chain": "base-sepolia",
      "signer": {
          "type": "quorum",
          "threshold": 2,
          "members": [
              {"type": "external-wallet", "address": "0x8617E340B3D01FA5F11F306F4090FD50E238070D"},
              {"type": "external-wallet", "address": "0xde709f2102306220921060314715629080e2fb77"},
              {"type": "external-wallet", "address": "0x27b1fdb04752bbc536007a920d24acb045561c26"}
          ]
      }
  }
  headers = {
      "X-API-KEY": "YOUR_SERVER_API_KEY",
      "Content-Type": "application/json"
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.json())
  ```
</CodeGroup>

A recovery method of the wallet approves the registration, as for any other signer — see [Add Signers](/wallets/guides/signers/add-signers). If that recovery method is a quorum, `threshold` of its members approve, as in the next section. The quorum can act only after its registration succeeds. Its `locator`, for example `quorum:9d41a7c2-5e3b-4c8f-a1d6-2b7e0f3c8a51`, is listed with the wallet's signers.

## Sign a Transaction with a Quorum

These steps use the operational quorum from the previous section. Its members are external wallets, which sign approvals with their own keys.

<Steps>
  <Step title="Create the transaction">
    Call the [create transaction](/api-reference/wallets/create-transaction) endpoint and set `params.signer` to the quorum's locator. A member's locator does not act for the quorum: members approve, they never create the transaction.

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request POST \
          --url https://staging.crossmint.com/api/2025-06-09/wallets/<wallet-address>/transactions \
          --header 'Content-Type: application/json' \
          --header 'X-API-KEY: YOUR_SERVER_API_KEY' \
          --data '{
              "params": {
                  "calls": [{
                      "to": "0x52908400098527886E0F7030069857D2E4169EE7",
                      "value": "0x2386f26fc10000",
                      "data": "0x"
                  }],
                  "chain": "base-sepolia",
                  "signer": "quorum:9d41a7c2-5e3b-4c8f-a1d6-2b7e0f3c8a51"
              }
          }'
      ```

      ```js Node.js theme={null}
      const url = "https://staging.crossmint.com/api/2025-06-09/wallets/<wallet-address>/transactions";

      const payload = {
          params: {
              calls: [
                  {
                      to: "0x52908400098527886E0F7030069857D2E4169EE7",
                      value: "0x2386f26fc10000",
                      data: "0x",
                  },
              ],
              chain: "base-sepolia",
              signer: "quorum:9d41a7c2-5e3b-4c8f-a1d6-2b7e0f3c8a51",
          },
      };

      const response = await fetch(url, {
          method: "POST",
          headers: {
              "X-API-KEY": "YOUR_SERVER_API_KEY",
              "Content-Type": "application/json",
          },
          body: JSON.stringify(payload),
      });

      const transaction = await response.json();
      console.log(transaction.id, transaction.approvals.pending);
      ```

      ```python Python theme={null}
      import requests

      url = "https://staging.crossmint.com/api/2025-06-09/wallets/<wallet-address>/transactions"

      payload = {
          "params": {
              "calls": [{
                  "to": "0x52908400098527886E0F7030069857D2E4169EE7",
                  "value": "0x2386f26fc10000",
                  "data": "0x"
              }],
              "chain": "base-sepolia",
              "signer": "quorum:9d41a7c2-5e3b-4c8f-a1d6-2b7e0f3c8a51"
          }
      }
      headers = {
          "X-API-KEY": "YOUR_SERVER_API_KEY",
          "Content-Type": "application/json"
      }

      response = requests.post(url, json=payload, headers=headers)
      transaction = response.json()
      print(transaction["id"], transaction["approvals"]["pending"])
      ```
    </CodeGroup>

    On Solana, also set `approvingMembers` to exactly `threshold` member locators. Only those members can approve:

    ```json theme={null}
    {
        "params": {
            "transaction": "<base58-serialized-transaction>",
            "signer": "quorum:9d41a7c2-5e3b-4c8f-a1d6-2b7e0f3c8a51",
            "approvingMembers": [
                "external-wallet:GbA2NZfpAnRVM2G2BG29qooqsYbdV5c2WVFymJ8MMir7",
                "external-wallet:7EcDhSYGxXyscszYEp35KHN8vvw3svAuLKTzXwCFLtV"
            ]
        }
    }
    ```

    On EVM and Stellar, signature requests work the same way: set `signer` to the quorum's locator.
  </Step>

  <Step title="Sign each member's message">
    The response has one pending approval entry for the quorum. Its `quorumApprovals` object lists each member that can approve, with the `message` that member must sign. On EVM and Stellar, all members are listed. On Solana, only the members in `approvingMembers` are listed.

    ```json theme={null}
    "approvals": {
        "pending": [
            {
                "signer": { "type": "quorum", "locator": "quorum:9d41a7c2-5e3b-4c8f-a1d6-2b7e0f3c8a51" },
                "quorumApprovals": {
                    "threshold": 2,
                    "remaining": 2,
                    "pending": [
                        { "member": { "type": "external-wallet", "locator": "external-wallet:0x8617E340B3D01FA5F11F306F4090FD50E238070D" }, "message": "0x7b2a..." },
                        { "member": { "type": "external-wallet", "locator": "external-wallet:0xde709f2102306220921060314715629080e2fb77" }, "message": "0x7b2a..." },
                        { "member": { "type": "external-wallet", "locator": "external-wallet:0x27b1fdb04752bbc536007a920d24acb045561c26" }, "message": "0x7b2a..." }
                    ],
                    "submitted": []
                }
            }
        ],
        "submitted": []
    }
    ```

    Each member signs its own `message` with its own key. Members sign independently and in any order. The messages can be different for each member type, so always sign the `message` from that member's entry.
  </Step>

  <Step title="Submit the member approvals">
    Call the [approve transaction](/api-reference/wallets/approve-transaction) endpoint. Set `approvals[].signer` to the member's own locator, never to the quorum's locator. You can submit the members together, as below, or in separate requests as each member signs.

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request POST \
          --url https://staging.crossmint.com/api/2025-06-09/wallets/<wallet-address>/transactions/<transaction-id>/approvals \
          --header 'Content-Type: application/json' \
          --header 'X-API-KEY: YOUR_SERVER_API_KEY' \
          --data '{
              "approvals": [
                  {
                      "signer": "external-wallet:0x8617E340B3D01FA5F11F306F4090FD50E238070D",
                      "signature": "<first-member-signature>"
                  },
                  {
                      "signer": "external-wallet:0x27b1fdb04752bbc536007a920d24acb045561c26",
                      "signature": "<second-member-signature>"
                  }
              ]
          }'
      ```

      ```js Node.js theme={null}
      const url =
          "https://staging.crossmint.com/api/2025-06-09/wallets/<wallet-address>/transactions/<transaction-id>/approvals";

      const payload = {
          approvals: [
              {
                  signer: "external-wallet:0x8617E340B3D01FA5F11F306F4090FD50E238070D",
                  signature: "<first-member-signature>",
              },
              {
                  signer: "external-wallet:0x27b1fdb04752bbc536007a920d24acb045561c26",
                  signature: "<second-member-signature>",
              },
          ],
      };

      const response = await fetch(url, {
          method: "POST",
          headers: {
              "X-API-KEY": "YOUR_SERVER_API_KEY",
              "Content-Type": "application/json",
          },
          body: JSON.stringify(payload),
      });

      const transaction = await response.json();
      console.log(transaction.status);
      ```

      ```python Python theme={null}
      import requests

      url = "https://staging.crossmint.com/api/2025-06-09/wallets/<wallet-address>/transactions/<transaction-id>/approvals"

      payload = {
          "approvals": [
              {
                  "signer": "external-wallet:0x8617E340B3D01FA5F11F306F4090FD50E238070D",
                  "signature": "<first-member-signature>"
              },
              {
                  "signer": "external-wallet:0x27b1fdb04752bbc536007a920d24acb045561c26",
                  "signature": "<second-member-signature>"
              }
          ]
      }
      headers = {
          "X-API-KEY": "YOUR_SERVER_API_KEY",
          "Content-Type": "application/json"
      }

      response = requests.post(url, json=payload, headers=headers)
      print(response.json()["status"])
      ```
    </CodeGroup>

    After each approval, `quorumApprovals.remaining` goes down by 1. If a member submits the same approval again, the request succeeds and changes nothing.
  </Step>

  <Step title="Check the result">
    When `remaining` reaches 0, the quorum entry moves to `approvals.submitted` and Crossmint broadcasts the transaction. Poll the [get transaction](/api-reference/wallets/get-transaction) endpoint until `status` is `success` or `failed`.
  </Step>
</Steps>

## Rotate a Quorum

You cannot change the members or the threshold of a quorum. To rotate them, add a new quorum and then remove the old one. The new quorum gets a new locator, and it can keep some of the old quorum's members.

### Recovery Quorum

1. Add the new quorum with the [add recovery method](/api-reference/wallets/add-recovery-method) endpoint.
2. Remove the old quorum by its locator with the [remove recovery method](/api-reference/wallets/remove-recovery-method) endpoint.

Add the new quorum first: a wallet must always keep at least one recovery method. See [Manage Recovery Methods](/wallets/guides/recovery/manage-recovery-methods) for the full request shapes.

### Operational Quorum

1. Register the new quorum with the [register delegated key](/api-reference/wallets/register-delegated-key) endpoint.
2. Remove the old quorum by its locator with the [remove signer](/api-reference/wallets/remove-delegated-key) endpoint. See [Remove a Signer](/wallets/guides/signers/remove-signer).

<Warning>
  When the old quorum is removed, its transactions that are waiting for approval fail. Submit or cancel them before you rotate, or create them again with the new quorum.
</Warning>

## Next Steps

<CardGroup>
  <Card title="Quorum Signers" icon="users" href="/wallets/concepts/quorum-signers">
    Understand how m-of-n approval works on each chain
  </Card>

  <Card title="Manage Recovery Methods" icon="key" href="/wallets/guides/recovery/manage-recovery-methods">
    Add or remove recovery methods on an existing wallet
  </Card>

  <Card title="Approve Transaction" icon="code" href="/api-reference/wallets/approve-transaction">
    Submit member approvals in the API playground
  </Card>
</CardGroup>


# Remove a Signer from a Wallet
Source: https://docs.crossmint.com/wallets/guides/signers/remove-signer

Remove a signer from an existing Crossmint wallet.

Use `removeSigner()` to remove an operational signer from an existing wallet. This revokes the signer's ability to perform day-to-day operations on behalf of the wallet. One of the wallet's recovery methods must approve the operation — the SDK handles this automatically. A wallet with several recovery methods needs one selected with `useRecoveryMethod()` first; see [Manage Recovery Methods](/wallets/guides/recovery/manage-recovery-methods#select-the-authorizing-recovery-method).

Signer removal is supported on **EVM**, **Solana**, and **Stellar**. For more context on signer roles and removal, see [Operational Signers](/wallets/concepts/signers#removing-a-signer).

## Prerequisites

* An existing wallet with at least one signer registered
* **API key** with `wallets:signatures.create` and `wallets:transactions.create` scopes

## Remove a Signer

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet } from "@crossmint/client-sdk-react-ui";

    const { wallet } = useWallet();

    const result = await wallet.removeSigner({
        type: "external-wallet",
        address: "0x1234...abcd",
    });

    console.log("Signer removed:", result);
    ```
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import {
        createCrossmint,
        CrossmintWallets,
    } from "@crossmint/wallets-sdk";

    const crossmint = createCrossmint({
        apiKey: "YOUR_SERVER_API_KEY",
    });
    const crossmintWallets = CrossmintWallets.from(crossmint);

    const wallet = await crossmintWallets.getWallet(
        "<wallet-address>",
        {
            chain: "base-sepolia",
            signer: {
                type: "server",
                secret: process.env.CROSSMINT_SIGNER_SECRET,
            },
        }
    );

    const result = await wallet.removeSigner({
        type: "external-wallet",
        address: "0x1234...abcd",
    });

    console.log("Signer removed:", result);
    ```
  </Tab>

  <Tab title="Flutter">
    ```dart theme={null}
    import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

    final controller = CrossmintWalletContext.of(context).requireWalletController;
    // Returns a runtime handle to the wallet already loaded by the controller —
    // no server-side create happens here.
    final wallet = controller.createEvmWallet();

    await wallet.removeSigner('external-wallet:0x1234...abcd');
    ```

    `removeSigner` takes the signer locator string directly. The SDK approves
    the removal via the wallet's selected recovery method.
  </Tab>

  <Tab title="REST">
    When using the REST API, removing signers must be approved by one of the wallet's recovery methods. You must [approve the transaction](/api-reference/wallets/approve-transaction) to complete the removal.

    <Steps>
      <Step title="Remove the signer">
        Call the [remove signer](/api-reference/wallets/remove-delegated-key) endpoint. Replace the wallet locator and signer locator with your own values.

        <Tip>
          The signer locator (e.g. `external-wallet:0x…` or `server:0x…`) is returned in the response when you [add a signer](/wallets/guides/signers/add-signers). You can also retrieve it by [listing the wallet's signers](/wallets/guides/signers/list-signers).
        </Tip>

        **EVM** — include the `chain` query parameter:

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request DELETE \
              --url 'https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/signers/external-wallet:0x1234567890123456789012345678901234567890?chain=base-sepolia&approver=email:user@example.com' \
              --header 'X-API-KEY: <x-api-key>'
          ```

          ```js Node.js theme={null}
          const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/signers/external-wallet:0x1234567890123456789012345678901234567890?chain=base-sepolia&approver=email:user@example.com';

          const options = {
              method: 'DELETE',
              headers: {
                  'X-API-KEY': '<x-api-key>'
              }
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/signers/external-wallet:0x1234567890123456789012345678901234567890?chain=base-sepolia&approver=email:user@example.com"

          headers = {"X-API-KEY": "<x-api-key>"}

          response = requests.delete(url, headers=headers)

          print(response.json())
          ```
        </CodeGroup>

        **Solana** — omit the `chain` query parameter; the wallet locator must include `solana` as the chain type:

        <CodeGroup>
          ```js Node.js theme={null}
          const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:solana/signers/server:SERVER_SIGNER_ADDRESS?approver=email:user@example.com';

          const options = {
              method: 'DELETE',
              headers: {
                  'X-API-KEY': '<x-api-key>'
              }
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```bash cURL theme={null}
          curl --request DELETE \
              --url 'https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:solana/signers/server:SERVER_SIGNER_ADDRESS?approver=email:user@example.com' \
              --header 'X-API-KEY: <x-api-key>'
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:solana/signers/server:SERVER_SIGNER_ADDRESS?approver=email:user@example.com"

          headers = {"X-API-KEY": "<x-api-key>"}

          response = requests.delete(url, headers=headers)

          print(response.json())
          ```
        </CodeGroup>

        Set the `approver` query parameter to the locator of the recovery method that authorizes the removal.

        See the [API reference](/api-reference/wallets/remove-delegated-key) for more details.
      </Step>

      <Step title="Sign the approval returned in the response">
        Sign the approval message field returned in the response inside `transaction.approvals` using the recovery method.
      </Step>

      <Step title="Approve the transaction to complete the removal">
        Call the [approve transaction](/api-reference/wallets/approve-transaction) endpoint using the signature from the previous step and the transaction ID returned from the remove-signer call. Replace the wallet locator in the URL with the one you used in Step 1 (for example, use `:solana` instead of `:evm` for Solana wallets).

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/transactions/b984491a-5785-43c0-8811-45d46fe6e520/approvals \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: <x-api-key>' \
              --data '{
                  "approvals": [{
                      "signer": "email:user@example.com",
                      "signature": "0x1234567890abcdef..."
                  }]
              }'
          ```

          ```js Node.js theme={null}
          const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/transactions/b984491a-5785-43c0-8811-45d46fe6e520/approvals';

          const payload = {
              approvals: [{
                  signer: "email:user@example.com",
                  signature: "0x1234567890abcdef..."
              }]
          };

          const options = {
              method: 'POST',
              headers: {
                  'X-API-KEY': '<x-api-key>',
                  'Content-Type': 'application/json'
              },
              body: JSON.stringify(payload)
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/transactions/b984491a-5785-43c0-8811-45d46fe6e520/approvals"

          payload = {
              "approvals": [{
                  "signer": "email:user@example.com",
                  "signature": "0x1234567890abcdef..."
              }]
          }
          headers = {
              "X-API-KEY": "<x-api-key>",
              "Content-Type": "application/json"
          }

          response = requests.post(url, json=payload, headers=headers)

          print(response.json())
          ```
        </CodeGroup>

        See the [API reference](/api-reference/wallets/approve-transaction) for more details.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Next Steps

<CardGroup>
  <Card title="List Signers" icon="list" href="/wallets/guides/signers/list-signers">
    View all signers registered on your wallet
  </Card>

  <Card title="Configure Recovery" icon="shield-halved" href="/wallets/guides/recovery/configure-recovery">
    Set up recovery methods for your wallets
  </Card>

  <Card title="Transfer Tokens" icon="arrow-right-arrow-left" href="/wallets/guides/transfer-tokens">
    Send tokens from your wallet
  </Card>
</CardGroup>


# Restrict a Signer with Scopes
Source: https://docs.crossmint.com/wallets/guides/signers/scopes

Set spending limits, recipient whitelists, and an expiry to signers.

A signer added to a wallet after creation handles day-to-day operations on behalf of the recovery method. By default, an added signer has full control. **Scopes** narrow that control by restricting which tokens the signer can transfer, in what amounts, and to which recipients. The signer-level `expiresAt` field denies the signer after a given timestamp.

For an overview of signer types and roles, see [Signers](/wallets/concepts/signers). To register a signer without scopes, see [Add Signers to a Wallet](/wallets/guides/signers/add-signers).

## Prerequisites

* **Wallet**: [Create a wallet](/wallets/guides/create-wallet) on EVM, Solana, or Stellar
* **Recovery method**: The recovery method must be available to approve the registration transaction
* **API key** with the `wallets.create` scope. In staging, all scopes are included by default.

## What Scopes Restrict

A scope applies to a single token on a single chain and can combine two optional restrictions:

* **Spending limit**: a maximum amount the signer can transfer, optionally resetting on a fixed interval
* **Recipient whitelist**: a list of addresses or wallet locators the signer is allowed to transfer to

The only supported scope type is `transfer`. A signer with no scopes has unrestricted token spending; a signer with one or more scopes can only transfer the tokens listed in its scopes, and only within the configured restrictions.

In addition to scopes, the signer accepts a top-level `expiresAt` (ISO 8601) after which every transaction from the signer is rejected. `expiresAt` is **not** a scope field. It sits alongside the `scopes` array in the request body.

<Info>
  Scopes are checked **before** the transaction is broadcast onchain. A transfer that exceeds the spending limit, targets a non-whitelisted recipient, or is signed after `expiresAt` is rejected at validation time.
</Info>

## Add a Signer with Scopes

Two ways to attach scopes to a signer:

* **`@crossmint/wallets-sdk`**: pass a `scopes` array to `addSigner()`. The SDK handles approval through the wallet's recovery method automatically. `expiresAt` and wallet-creation-time scope registration require the REST API
* **REST API**: direct control over the full registration request, including `expiresAt` and registering scopes at wallet creation time

### Using the SDK

Use [`addSigner()`](/sdk-reference/wallets/typescript/classes/Wallet#addsigner) and pass `scopes` in the options object. The wallet's chain is inferred from the wallet itself; only the `tokenLocator` needs to match.

```typescript Node.js theme={null}
import { createCrossmint, CrossmintWallets } from "@crossmint/wallets-sdk";

const crossmint = createCrossmint({ apiKey: "YOUR_SERVER_API_KEY" });
const wallets = CrossmintWallets.from(crossmint);

const wallet = await wallets.getWallet("YOUR_WALLET_ADDRESS", { chain: "base-sepolia" });

await wallet.useSigner({
    type: "server",
    secret: process.env.CROSSMINT_SIGNER_SECRET,
});

const signer = await wallet.addSigner(
    { type: "external-wallet", address: "0x1234567890123456789012345678901234567890" },
    {
        scopes: [
            {
                type: "transfer",
                tokenLocator: "base-sepolia:usdc",
                spendingLimit: { amount: "10", interval: 86400 },
                recipients: ["0xABCDEF0123456789ABCDEF0123456789ABCDEF01"],
            },
        ],
    },
);

console.log("Scoped signer added:", signer.locator);
```

For Solana, use `chain: "solana"` when fetching the wallet and a `solana:<symbol-or-mint>` token locator (for example, `solana:usdc`). For Stellar, use `chain: "stellar"` and a `stellar:<symbol-or-contract-id>` locator. To set `expiresAt` or to attach scopes at wallet creation, use the REST API below.

### Using the REST API

Use REST when you need `expiresAt` or when registering scopes at wallet creation.

<Tabs>
  <Tab title="EVM">
    Call the [register delegated key](/api-reference/wallets/register-delegated-key) endpoint with a `scopes` array. Each scope's `tokenLocator` must target the same EVM chain as the wallet.

    <Steps>
      <Step title="Register the scoped signer">
        <CodeGroup>
          ```js Node.js theme={null}
          const url = "https://staging.crossmint.com/api/2025-06-09/wallets/YOUR_WALLET_ADDRESS/signers";

          const payload = {
              signer: "external-wallet:0x1234567890123456789012345678901234567890",
              chain: "base-sepolia",
              expiresAt: "2027-08-31T16:34:33.854Z",
              scopes: [
                  {
                      type: "transfer",
                      tokenLocator: "base-sepolia:usdc",
                      spendingLimit: { amount: "10", interval: 86400 },
                      recipients: ["0xABCDEF0123456789ABCDEF0123456789ABCDEF01"],
                  },
              ],
          };

          const response = await fetch(url, {
              method: "POST",
              headers: {
                  "X-API-KEY": "YOUR_API_KEY",
                  "Content-Type": "application/json",
              },
              body: JSON.stringify(payload),
          });

          const data = await response.json();
          console.log(data);
          ```

          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets/YOUR_WALLET_ADDRESS/signers \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: YOUR_API_KEY' \
              --data '{
                  "signer": "external-wallet:0x1234567890123456789012345678901234567890",
                  "chain": "base-sepolia",
                  "expiresAt": "2027-08-31T16:34:33.854Z",
                  "scopes": [
                      {
                          "type": "transfer",
                          "tokenLocator": "base-sepolia:usdc",
                          "spendingLimit": { "amount": "10", "interval": 86400 },
                          "recipients": ["0xABCDEF0123456789ABCDEF0123456789ABCDEF01"]
                      }
                  ]
              }'
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets/YOUR_WALLET_ADDRESS/signers"

          payload = {
              "signer": "external-wallet:0x1234567890123456789012345678901234567890",
              "chain": "base-sepolia",
              "expiresAt": "2027-08-31T16:34:33.854Z",
              "scopes": [
                  {
                      "type": "transfer",
                      "tokenLocator": "base-sepolia:usdc",
                      "spendingLimit": {"amount": "10", "interval": 86400},
                      "recipients": ["0xABCDEF0123456789ABCDEF0123456789ABCDEF01"],
                  }
              ],
          }
          headers = {
              "X-API-KEY": "YOUR_API_KEY",
              "Content-Type": "application/json",
          }

          response = requests.post(url, json=payload, headers=headers)
          print(response.json())
          ```
        </CodeGroup>

        The EVM endpoint defaults to `deployImmediately: false`, so the response includes a `chains` entry for the target chain with a pending signature `id` and an `approvals` field describing what must be signed by the recovery method. If you set `deployImmediately: true` in the payload, the response includes a `transaction` object with an `id` and an `approvals` field instead.
      </Step>

      <Step title="Sign the approval message with the recovery method">
        If the response is a signature, sign the message field returned under the signature's `approvals` using the wallet's recovery method. If the response is a transaction, sign the message field returned under `transaction.approvals`.
      </Step>

      <Step title="Submit the approval">
        Call the [approve signature](/api-reference/wallets/approve-signature) endpoint with the signature from the previous step and the signature ID returned in step 1. If the response is a transaction, call the [approve transaction](/api-reference/wallets/approve-transaction) endpoint with the signature and the transaction ID. The signer becomes active once the signature or transaction is approved.
      </Step>
    </Steps>

    Amounts in `spendingLimit.amount` are decimal strings expressed in the token's display units (for example, `"10"` USDC means 10 USDC, not 10 base units). Crossmint reads the token's `decimals()` onchain to convert to the wei amount the policy contract expects.
  </Tab>

  <Tab title="Solana">
    Call the [register delegated key](/api-reference/wallets/register-delegated-key) endpoint with a `scopes` array. The wallet's chain is inferred from the wallet locator, so do not pass `chain`.

    <Steps>
      <Step title="Register the scoped signer">
        <CodeGroup>
          ```js Node.js theme={null}
          const url = "https://staging.crossmint.com/api/2025-06-09/wallets/YOUR_WALLET_ADDRESS/signers";

          const payload = {
              signer: {
                  type: "external-wallet",
                  address: "GbA2NZfpAnRVM2G2BG29qooqsYbdV5c2WVFymJ8MMir7",
              },
              expiresAt: "2027-08-31T16:34:33.854Z",
              scopes: [
                  {
                      type: "transfer",
                      tokenLocator: "solana:sol",
                      spendingLimit: { amount: "1", interval: 86400 },
                  },
              ],
          };

          const response = await fetch(url, {
              method: "POST",
              headers: {
                  "X-API-KEY": "YOUR_API_KEY",
                  "Content-Type": "application/json",
              },
              body: JSON.stringify(payload),
          });

          const data = await response.json();
          console.log(data);
          ```

          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets/YOUR_WALLET_ADDRESS/signers \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: YOUR_API_KEY' \
              --data '{
                  "signer": {
                      "type": "external-wallet",
                      "address": "GbA2NZfpAnRVM2G2BG29qooqsYbdV5c2WVFymJ8MMir7"
                  },
                  "expiresAt": "2027-08-31T16:34:33.854Z",
                  "scopes": [
                      {
                          "type": "transfer",
                          "tokenLocator": "solana:sol",
                          "spendingLimit": { "amount": "1", "interval": 86400 }
                      }
                  ]
              }'
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets/YOUR_WALLET_ADDRESS/signers"

          payload = {
              "signer": {
                  "type": "external-wallet",
                  "address": "GbA2NZfpAnRVM2G2BG29qooqsYbdV5c2WVFymJ8MMir7",
              },
              "expiresAt": "2027-08-31T16:34:33.854Z",
              "scopes": [
                  {
                      "type": "transfer",
                      "tokenLocator": "solana:sol",
                      "spendingLimit": {"amount": "1", "interval": 86400},
                  }
              ],
          }
          headers = {
              "X-API-KEY": "YOUR_API_KEY",
              "Content-Type": "application/json",
          }

          response = requests.post(url, json=payload, headers=headers)
          print(response.json())
          ```
        </CodeGroup>
      </Step>

      <Step title="Sign the approval transaction with the recovery method">
        The response includes a `transaction` object. Sign the transaction returned under `transaction.approvals` with the wallet's recovery method.
      </Step>

      <Step title="Submit the approval">
        Call the [approve transaction](/api-reference/wallets/approve-transaction) endpoint with the signature and the transaction ID. The signer becomes active once the transaction is confirmed onchain.
      </Step>
    </Steps>

    On Solana, spending-limit reset intervals are measured in seconds but enforced at the slot level (Solana produces a slot roughly every 400 milliseconds). The reset can drift by a few minutes per day relative to wall-clock time.
  </Tab>

  <Tab title="Stellar">
    Call the [register delegated key](/api-reference/wallets/register-delegated-key) endpoint with a `scopes` array. The wallet's chain is inferred from the wallet locator, so do not pass `chain`.

    <Steps>
      <Step title="Register the scoped signer">
        <CodeGroup>
          ```js Node.js theme={null}
          const url = "https://staging.crossmint.com/api/2025-06-09/wallets/YOUR_WALLET_ADDRESS/signers";

          const payload = {
              signer: {
                  type: "external-wallet",
                  address: "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
              },
              expiresAt: "2027-08-31T16:34:33.854Z",
              scopes: [
                  {
                      type: "transfer",
                      tokenLocator: "stellar:usdc",
                      spendingLimit: { amount: "100", interval: 86400 },
                      recipients: ["GDUCX62IF76FFIYRNI25LJDS2V43QEZDY4YNF2DJWVIASN5LKX76Q4TW"],
                  },
              ],
          };

          const response = await fetch(url, {
              method: "POST",
              headers: {
                  "X-API-KEY": "YOUR_API_KEY",
                  "Content-Type": "application/json",
              },
              body: JSON.stringify(payload),
          });

          const data = await response.json();
          console.log(data);
          ```

          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets/YOUR_WALLET_ADDRESS/signers \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: YOUR_API_KEY' \
              --data '{
                  "signer": {
                      "type": "external-wallet",
                      "address": "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ"
                  },
                  "expiresAt": "2027-08-31T16:34:33.854Z",
                  "scopes": [
                      {
                          "type": "transfer",
                          "tokenLocator": "stellar:usdc",
                          "spendingLimit": { "amount": "100", "interval": 86400 },
                          "recipients": ["GDUCX62IF76FFIYRNI25LJDS2V43QEZDY4YNF2DJWVIASN5LKX76Q4TW"]
                      }
                  ]
              }'
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets/YOUR_WALLET_ADDRESS/signers"

          payload = {
              "signer": {
                  "type": "external-wallet",
                  "address": "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",
              },
              "expiresAt": "2027-08-31T16:34:33.854Z",
              "scopes": [
                  {
                      "type": "transfer",
                      "tokenLocator": "stellar:usdc",
                      "spendingLimit": {"amount": "100", "interval": 86400},
                      "recipients": ["GDUCX62IF76FFIYRNI25LJDS2V43QEZDY4YNF2DJWVIASN5LKX76Q4TW"],
                  }
              ],
          }
          headers = {
              "X-API-KEY": "YOUR_API_KEY",
              "Content-Type": "application/json",
          }

          response = requests.post(url, json=payload, headers=headers)
          print(response.json())
          ```
        </CodeGroup>
      </Step>

      <Step title="Sign the approval transaction with the recovery method">
        Sign the transaction returned under `transaction.approvals` with the wallet's recovery method.
      </Step>

      <Step title="Submit the approval">
        Call the [approve transaction](/api-reference/wallets/approve-transaction) endpoint with the signature and the transaction ID. The signer becomes active once the transaction is confirmed onchain.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Add Scopes at Wallet Creation

Scopes and `expiresAt` can also be set on each signer entry when [creating a wallet](/api-reference/wallets/create-wallet). The signer is registered alongside the wallet. No separate approval call is required because the recovery method authorizes the wallet creation.

<Note>
  The REST API uses `recoveryMethods` and `delegatedSigners` as field names. These map to `recoveryMethods` and `signers` in the SDK. See the [V1 migration guide](/wallets/guides/migrate-to-v1) for details.
</Note>

<Tabs>
  <Tab title="EVM">
    ```json theme={null}
    {
        "chainType": "evm",
        "type": "smart",
        "config": {
            "recoveryMethods": [
                {
                    "type": "external-wallet",
                    "address": "0x1234567890123456789012345678901234567890"
                }
            ],
            "delegatedSigners": [
                {
                    "signer": "external-wallet:0x9999999999999999999999999999999999999999",
                    "expiresAt": "2027-08-31T16:34:33.854Z",
                    "scopes": [
                        {
                            "type": "transfer",
                            "tokenLocator": "base-sepolia:usdc",
                            "spendingLimit": { "amount": "10", "interval": 86400 }
                        }
                    ]
                }
            ]
        }
    }
    ```
  </Tab>

  <Tab title="Solana">
    ```json theme={null}
    {
        "chainType": "solana",
        "type": "smart",
        "config": {
            "recoveryMethods": [
                {
                    "type": "external-wallet",
                    "address": "BWBcCcCcCcCcCcCcCcCcCcCcCcCcCcCcCcCcCcCcCcCc"
                }
            ],
            "delegatedSigners": [
                {
                    "signer": {
                        "type": "external-wallet",
                        "address": "GbA2NZfpAnRVM2G2BG29qooqsYbdV5c2WVFymJ8MMir7"
                    },
                    "expiresAt": "2027-08-31T16:34:33.854Z",
                    "scopes": [
                        {
                            "type": "transfer",
                            "tokenLocator": "solana:sol",
                            "spendingLimit": { "amount": "1", "interval": 86400 }
                        }
                    ]
                }
            ]
        }
    }
    ```
  </Tab>

  <Tab title="Stellar">
    ```json theme={null}
    {
        "chainType": "stellar",
        "type": "smart",
        "config": {
            "recoveryMethods": [
                {
                    "type": "external-wallet",
                    "address": "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ"
                }
            ],
            "delegatedSigners": [
                {
                    "signer": {
                        "type": "external-wallet",
                        "address": "GDUCX62IF76FFIYRNI25LJDS2V43QEZDY4YNF2DJWVIASN5LKX76Q4TW"
                    },
                    "expiresAt": "2027-08-31T16:34:33.854Z",
                    "scopes": [
                        {
                            "type": "transfer",
                            "tokenLocator": "stellar:usdc",
                            "spendingLimit": { "amount": "100", "interval": 86400 }
                        }
                    ]
                }
            ]
        }
    }
    ```
  </Tab>
</Tabs>

## Common Patterns

### One-Time Spending Allowance

Omit `interval` to set an absolute, non-resetting cap. Once the signer has spent up to `amount`, every subsequent transfer is rejected until the signer is removed and re-registered.

```json theme={null}
{
    "type": "transfer",
    "tokenLocator": "base-sepolia:usdc",
    "spendingLimit": { "amount": "10" }
}
```

### Recurring Daily Allowance

Set `interval` to the number of seconds in the period (for example, `86400` for 24 hours). The counter resets the first time the signer transfers after the interval elapses, measured from the moment the scope was registered onchain.

```json theme={null}
{
    "type": "transfer",
    "tokenLocator": "base-sepolia:usdc",
    "spendingLimit": { "amount": "10", "interval": 86400 }
}
```

### Recipient Whitelist

Pass a non-empty `recipients` array to restrict transfers to specific addresses. Wallet locators (for example, `"email:user@example.com:evm"`) are supported in addition to raw addresses. An empty or omitted `recipients` array allows any recipient.

```json theme={null}
{
    "type": "transfer",
    "tokenLocator": "base-sepolia:usdc",
    "recipients": [
        "0xABCDEF0123456789ABCDEF0123456789ABCDEF01",
        "email:partner@example.com:evm"
    ]
}
```

### Restrict the Token Without Capping the Amount

A `transfer` scope with no `spendingLimit` and no `recipients` restricts the signer to that one token but otherwise allows unlimited transfers of it. This is useful when the spending limit is enforced off-chain by your application.

```json theme={null}
{
    "type": "transfer",
    "tokenLocator": "base-sepolia:usdc"
}
```

### Expire the Signer

Set `expiresAt` at the signer level (not inside a scope). After the timestamp, every transaction signed by this signer is rejected.

```json theme={null}
{
    "signer": "external-wallet:0x9999999999999999999999999999999999999999",
    "chain": "base-sepolia",
    "expiresAt": "2027-08-31T16:34:33.854Z"
}
```

## See Also

* [Add Signers to a Wallet](/wallets/guides/signers/add-signers): register a signer without scopes
* [Remove a Signer](/wallets/guides/signers/remove-signer): revoke a signer
* [Register delegated key API reference](/api-reference/wallets/register-delegated-key): full request and response schema
* [V1 Migration Guide](/wallets/guides/migrate-to-v1): SDK and REST API terminology mapping
* [Create wallet API reference](/api-reference/wallets/create-wallet): set scopes at wallet creation under `config.delegatedSigners`


# Server Signer
Source: https://docs.crossmint.com/wallets/guides/signers/server-signer

Authorize wallet operations directly from your server, using an API key and secret.

Authorize transactions directly from a server environment using a Crossmint API key, and a secret provided by you. Signing happens entirely in-process with no external network call, making this the lowest-latency option available.

Because this key lives as a secret in your infrastructure, enforcing regular rotations is recommended — for example, quarterly — to limit exposure in the event of a compromised environment, a departed employee, or an infrastructure incident.

For a conceptual overview, see [Server signer](/wallets/concepts/signer-types#server-signer) in the Signer Types reference. To learn how to register additional operational signers on an existing wallet, see [Registering a signer](/wallets/guides/signers/add-signers).

## Configuration

<Steps>
  <Step title="Generate a Signer Secret">
    You must generate a signer secret to ensure that no one — including Crossmint — can access or control your wallet. This secret:

    1. Must be either 64 hex characters (case-insensitive) or use the prefixed format `xmsk1_<64-hex-chars>`.
    2. Remains on your server and is never transmitted to Crossmint. The SDK derives a private/public keypair from it locally and uses public-key infrastructure (PKI) for authorization — only the public key is ever shared.

    <Warning>
      Generate and store this secret securely. This secret can grant full signing authority over the wallet.
    </Warning>

    Generate a secret using the [tool below](#signer-secret-generator) or [programmatically](#generate-your-own-key-programmatically), and store it as the `CROSSMINT_SIGNER_SECRET` environment variable on your server:

    ```bash theme={null}
    CROSSMINT_SIGNER_SECRET="xmsk1_<your-64-hex-character-secret>"
    # OR
    CROSSMINT_SIGNER_SECRET="<your-64-hex-character-secret>"

    # EXAMPLE
    CROSSMINT_SIGNER_SECRET="b62b473b3ba7d3d72bf7c3a397f1eb61c305a4193ce670dd056686c13d95bbaa"
    ```

    The Crossmint SDK automatically derives signing keys from this secret, scoped to your **project ID**, **environment**, and **chain type** (EVM, Solana, or Stellar). A single secret produces the same derived address across all EVM chains within a project — you do not get a different key per EVM network.
  </Step>

  <Step title="Create a Wallet with a Server Signer">
    Pass `type: "server"` as the signer type when creating a wallet. The SDK handles key derivation and address resolution automatically.

    <Tabs>
      <Tab title="Node.js">
        ```typescript theme={null}
        import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";

        const crossmint = createCrossmint({
            apiKey: "<your-server-api-key>",
        });
        const crossmintWallets = CrossmintWallets.from(crossmint);

        const wallet = await crossmintWallets.createWallet({
            chain: "base-sepolia",
            recoveryMethods: [
                {
                    type: "server",
                    secret: process.env.CROSSMINT_SIGNER_SECRET,
                },
            ],
            alias: "my-server-wallet"
        });
        ```

        <Tip>
          The `alias` parameter lets you retrieve the wallet later without storing the wallet address:

          ```typescript theme={null}
          const wallet = await crossmintWallets.getWallet(
              "evm:alias:my-server-wallet",
              { chain: "base-sepolia" }
          );
          await wallet.useSigner({
              type: "server",
              secret: process.env.CROSSMINT_SIGNER_SECRET,
          });
          ```
        </Tip>
      </Tab>

      <Tab title="REST">
        Server wallets require using the Crossmint SDK because the SDK handles key derivation and transaction signing locally. If you need to work with the REST API directly, use an [external wallet signer](/wallets/guides/signers/external-wallet) instead — it provides equivalent functionality and lets you manage your own keys while calling the API without the SDK.
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Signer Secret Generator

Use this tool to generate a master signer secret for your server-side or agent wallet environment. The secret is generated entirely in your browser — nothing is transmitted to any server.

<SignerSecretGenerator />

### Generate Your Own Key Programmatically

You can also generate a signer secret programmatically:

<CodeGroup>
  ```typescript Node.js / TypeScript theme={null}
  import { randomBytes } from "crypto";

  function generateSignerSecret(): string {
    const bytes = randomBytes(32);
    const hex = bytes.toString("hex");
    return `xmsk1_${hex}`;
  }

  const secret = generateSignerSecret();
  console.log(`CROSSMINT_SIGNER_SECRET="${secret}"`);
  ```

  ```python Python theme={null}
  import secrets

  def generate_signer_secret() -> str:
      hex_bytes = secrets.token_hex(32)
      return f"xmsk1_{hex_bytes}"

  secret = generate_signer_secret()
  print(f'CROSSMINT_SIGNER_SECRET="{secret}"')
  ```

  ```bash Shell (openssl) theme={null}
  echo "CROSSMINT_SIGNER_SECRET=\"xmsk1_$(openssl rand -hex 32)\""
  ```
</CodeGroup>

## Under the Hood

A server signer is, at its core, a secret that gets deterministically mapped into a private key compatible with the underlying blockchain network. You provide a master secret, and the Crossmint SDK derives signing keys from it grouped by chain type — so a single secret works across all supported chains within a project.

### How Key Derivation Works

A 32-byte (256-bit) random value serves as your master secret. The SDK derives private keys from this master secret using **HKDF-SHA256**, scoped to your project ID, environment, and chain type:

```text theme={null}
key = HKDF-SHA256(
  ikm:  <master secret>,
  salt: "crossmint",
  info: "<projectId>:<environment>:<chainType>-<algorithm>"
)
```

Where `chainType` is one of `evm`, `solana`, or `stellar`, and `algorithm` is `secp256k1` (EVM) or `ed25519` (Solana/Stellar).

The `projectId` and `environment` are extracted automatically from your server API key by the SDK. Because derivation uses chain type rather than the specific network name, the same master secret produces the **same** signing key and address across all EVM chains (e.g., Base, Ethereum, Polygon) within a given project and environment. Solana and Stellar each derive their own distinct key.

<Note>
  Wallets created before the chain-type normalization may have been derived using the specific chain name (e.g., `base-sepolia`) instead of `evm`. The SDK automatically applies a legacy fallback for these wallets so existing addresses continue to resolve correctly.
</Note>

You can derive the public address using Crossmint's wallets SDK — see the <a href="https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/server/helpers/derive-server-signer.ts">derive-server-signer helper</a> for reference.

### How Are Server Signer Locators Derived

When referencing a server signer in API calls (for example, when submitting approvals or registering it as an operational signer), use the locator format `server:<address>`:

```text theme={null}
server:0x1234567890123456789012345678901234567890
```

The `<address>` is the public address derived from your signer secret for the target chain. The SDK computes this automatically when you use `type: "server"` — you only need the locator format when working with the REST API directly.


# Transfer Tokens
Source: https://docs.crossmint.com/wallets/guides/transfer-tokens

Transfer tokens between wallets using Crossmint's APIs

## Prerequisites

* **Wallet**: [Create a wallet](/wallets/guides/create-wallet) to transfer from.
* **Signer**: The signing wallet must be registered as a signer on the wallet. You can do this [at wallet creation](/wallets/guides/create-wallet) by passing `signers`, or afterward by [adding a signer](/wallets/guides/signers/add-signers).
* **Test Tokens**: Fund your wallet with [USDXM testnet tokens](/wallets/guides/fund-staging-wallet) before transferring.
* **API Key**: Get an API key with the `wallets:transactions.create` scope. In staging, all scopes are included by default.

## What is a token transfer?

A token transfer moves a token from one wallet address to another onchain. This creates an onchain transaction that costs gas, which Crossmint handles for you. Once the blockchain confirms the transaction, the transfer is final and cannot be reversed.

## Sending tokens

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet } from '@crossmint/client-sdk-react-ui';

    const RECIPIENT_ADDRESS = "RECIPIENT_WALLET_ADDRESS";
    const { wallet } = useWallet();

    const { hash, explorerLink } = await wallet.send(RECIPIENT_ADDRESS, "usdxm", "3.14");
    ```

    See the [React SDK reference](/sdk-reference/wallets/react/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import {
        CrossmintWallets,
        createCrossmint,
    } from "@crossmint/wallets-sdk";

    const RECIPIENT_ADDRESS = "RECIPIENT_WALLET_ADDRESS";

    const crossmint = createCrossmint({
        apiKey: "YOUR_SERVER_API_KEY",
    });

    const wallets = CrossmintWallets.from(crossmint);

    const wallet = await wallets.getWallet(
        "WALLET_ADDRESS_OR_ALIAS",
        { chain: "base-sepolia" }
    );

    await wallet.useSigner({
        type: "server",
        secret: process.env.SIGNER_SECRET!,
    });

    const { hash, explorerLink } = await wallet.send(
        RECIPIENT_ADDRESS,
        "usdxm",
        "3.14"
    );

    console.log("Transaction hash:", hash);
    console.log("Explorer:", explorerLink);
    ```

    See the [SDK reference](/sdk-reference/wallets/typescript/classes/Wallet#send) for all parameters and return types.
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { useWallet } from '@crossmint/client-sdk-react-native-ui';

    const RECIPIENT_ADDRESS = "RECIPIENT_WALLET_ADDRESS";
    const { wallet } = useWallet();

    const { hash, explorerLink } = await wallet.send(RECIPIENT_ADDRESS, "usdxm", "3.14");
    ```

    See the [React Native SDK reference](/sdk-reference/wallets/react-native/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    import com.crossmint.kotlin.CrossmintSDK
    import com.crossmint.kotlin.types.EVMChain
    import com.crossmint.kotlin.types.getOrThrow

    CrossmintSDK.configure(apiKey = "YOUR_CROSSMINT_API_KEY")
    val sdk = CrossmintSDK.shared
    val wallet = sdk.wallets.getWallet(chain = EVMChain.BaseSepolia).getOrThrow()

    val transaction = wallet.send(
        recipient = "RECIPIENT_WALLET_ADDRESS",
        tokenLocator = "base-sepolia:usdxm",
        amount = 3.14
    ).getOrThrow()
    println("Transaction ID: ${transaction.id}")
    ```
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    import CrossmintClient
    import Wallet

    let recipientAddress = "RECIPIENT_WALLET_ADDRESS"
    CrossmintSDK.configure(apiKey: "<YOUR_API_KEY>")
    let sdk = CrossmintSDK.shared

    guard let wallet = try await sdk.crossmintWallets.getWallet(
        chain: .baseSepolia
    ) else {
        return
    }

    let result = try await wallet.send(recipientAddress, "base-sepolia:usdxm", 3.14)
    ```
  </Tab>

  <Tab title="Flutter">
    ```dart theme={null}
    import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

    const recipientAddress = 'RECIPIENT_WALLET_ADDRESS';
    final controller = CrossmintWalletContext.of(context).requireWalletController;
    final wallet = controller.createEvmWallet();

    final tx = await wallet.sendToken(recipientAddress, 'base-sepolia:usdxm', '3.14');
    print('Transaction: ${tx.id}');
    ```

    See the [Flutter SDK reference](/sdk-reference/wallets/flutter/controllers#wallet-methods) for more details.
  </Tab>

  <Tab title="REST">
    Transfers must be approved by one of the wallet's [signers](/wallets/concepts/signers).
    The SDK handles this automatically, but with the REST API you may need to craft, sign, and submit the approval manually.

    <Steps>
      <Step title="Create the transaction">
        Call the [transfer token](/api-reference/wallets/transfer-token) endpoint.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/tokens/base-sepolia:usdxm/transfers \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: YOUR_SERVER_API_KEY' \
              --data '{
                  "recipient": "RECIPIENT_WALLET_ADDRESS",
                  "amount": "3.14",
                  "signer": "external-wallet:YOUR_EXTERNAL_WALLET_ADDRESS"
              }'
          ```

          ```js Node.js theme={null}
          const WALLET_ADDRESS = "YOUR_WALLET_ADDRESS";
          const RECIPIENT_ADDRESS = "RECIPIENT_WALLET_ADDRESS";
          const EXTERNAL_WALLET_ADDRESS = "YOUR_EXTERNAL_WALLET_ADDRESS";

          const url = `https://staging.crossmint.com/api/2025-06-09/wallets/${WALLET_ADDRESS}/tokens/base-sepolia:usdxm/transfers`;

          const payload = {
              recipient: RECIPIENT_ADDRESS,
              amount: "3.14",
              signer: `external-wallet:${EXTERNAL_WALLET_ADDRESS}`
          };

          const options = {
              method: 'POST',
              headers: {
                  'X-API-KEY': 'YOUR_SERVER_API_KEY',
                  'Content-Type': 'application/json'
              },
              body: JSON.stringify(payload)
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```python Python theme={null}
          import requests

          WALLET_ADDRESS = "YOUR_WALLET_ADDRESS"
          RECIPIENT_ADDRESS = "RECIPIENT_WALLET_ADDRESS"
          EXTERNAL_WALLET_ADDRESS = "YOUR_EXTERNAL_WALLET_ADDRESS"

          url = f"https://staging.crossmint.com/api/2025-06-09/wallets/{WALLET_ADDRESS}/tokens/base-sepolia:usdxm/transfers"

          payload = {
              "recipient": RECIPIENT_ADDRESS,
              "amount": "3.14",
              "signer": f"external-wallet:{EXTERNAL_WALLET_ADDRESS}"
          }
          headers = {
              "X-API-KEY": "YOUR_SERVER_API_KEY",
              "Content-Type": "application/json"
          }

          response = requests.post(url, json=payload, headers=headers)

          print(response.json())
          ```
        </CodeGroup>

        See the [API reference](/api-reference/wallets/transfer-token) for more details.
      </Step>

      <Step title="Choose your signer type">
        The next steps depend on which signer type you specified in the previous step.

        <Tabs>
          <Tab title="Server Signer">
            [Server](/wallets/guides/signers/server-signer) signers derive a private key from your signer secret using HKDF-SHA256 and sign transactions locally.

            When using the **SDK**, signing and approval are handled automatically — no additional steps are needed.

            When using the **REST API** directly, you must:

            1. Derive the signing key from your signer secret (scoped to your project, environment, and chain type). See the <a href="https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/server/helpers/derive-server-signer.ts">derive-server-signer helper</a> for a reference implementation.
            2. Sign the approval message returned from the transaction creation step.
            3. Submit the signature via the [approve transaction](/api-reference/wallets/approve-transaction) endpoint.

            <Warning>
              Crossmint recommends using the <a href="https://www.npmjs.com/package/@crossmint/wallets-sdk">Wallets SDK</a> for server signer flows. The SDK handles key derivation and signing automatically.
            </Warning>

            See the [Server Signer guide](/wallets/guides/signers/server-signer) for full configuration and setup details.
          </Tab>

          <Tab title="Device Signer">
            [Device](/wallets/guides/signers/device-signer) signers generate a P256 keypair inside the device's secure hardware (Secure Enclave, Android Keystore, or browser Web Crypto API). Because the private key never leaves the device, device signers are **client-side only** and cannot be used directly with the REST API.

            <Warning>
              Crossmint recommends using the React, React Native, or Swift SDK for device signer flows. The SDK handles device key generation, storage, and signing automatically.
            </Warning>

            See the [Device Signer guide](/wallets/guides/signers/device-signer) for setup instructions.
          </Tab>

          <Tab title="External Wallet">
            For [External Wallet](/wallets/guides/signers/add-signers) signers, you must manually sign the approval message and submit it via the API. The response from Step 1 includes a pending approval with a `message` field that must be signed exactly as returned.

            From the previous step's response, extract:

            * `id` - The transaction ID (used in the next step)
            * `approvals.pending[0].message` - The hex message to sign

            Sign the message using your external wallet. The message is a raw hex string and must be signed exactly as returned. Here's an example using an EVM wallet with [Viem](https://viem.sh/):

            ```typescript theme={null}
            import { privateKeyToAccount } from "viem/accounts";

            // The message from tx.approvals.pending[0].message
            const messageToSign = "<messageFromResponse>";

            // Sign the message exactly as returned (raw hex)
            const account = privateKeyToAccount(`0x${"<privateKey>"}`);
            const signature = await account.signMessage({
                message: { raw: messageToSign },
            });
            ```
          </Tab>

          <Tab title="Email and Phone">
            [Email and phone](/wallets/guides/recovery/configure-recovery) signers require client-side OTP verification and key derivation, which the Crossmint SDK handles automatically. While REST API signing is technically possible, you still need client-side SDK integration for the signing step.

            <Warning>
              Crossmint recommends using the React, React Native, Swift, or Node.js SDK examples instead. The SDK handles the full signing flow for email and phone signers.
            </Warning>
          </Tab>

          <Tab title="Passkey">
            [Passkey](/wallets/guides/signers/add-signers) signers use WebAuthn for biometric or password manager authentication, which requires browser interaction. While REST API signing is technically possible, Crossmint does not recommend it because you would still need client-side SDK integration for the WebAuthn signing step.

            <Warning>
              Crossmint recommends using the React, React Native, Swift, or Node.js SDK examples instead. The SDK handles the full passkey signing flow automatically.
            </Warning>
          </Tab>
        </Tabs>
      </Step>

      <Step title="Submit the approval">
        <Note>
          Skip this step if using the **SDK with a server signer** — the SDK handles signing and approval automatically.
        </Note>

        Call the [approve transaction](/api-reference/wallets/approve-transaction) endpoint with the signature from Step 2 and the transaction ID from Step 1. Set `approvals[].signer` to the locator of the signer or recovery method that produced the signature.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions/<txId>/approvals \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: <x-api-key>' \
              --data '{
                  "approvals": [{
                      "signer": "external-wallet:<externalWalletAddress>",
                      "signature": "<signature>"
                  }]
              }'
          ```

          ```js Node.js theme={null}
          const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions/<txId>/approvals';

          const payload = {
              approvals: [{
                  signer: "external-wallet:<externalWalletAddress>",
                  signature: "<signature>"
              }]
          };

          const options = {
              method: 'POST',
              headers: {
                  'X-API-KEY': '<x-api-key>',
                  'Content-Type': 'application/json'
              },
              body: JSON.stringify(payload)
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions/<txId>/approvals"

          payload = {
              "approvals": [{
                  "signer": "external-wallet:<externalWalletAddress>",
                  "signature": "<signature>"
              }]
          }
          headers = {
              "X-API-KEY": "<x-api-key>",
              "Content-Type": "application/json"
          }

          response = requests.post(url, json=payload, headers=headers)

          print(response.json())
          ```
        </CodeGroup>

        See the [API reference](/api-reference/wallets/approve-transaction) for more details.
      </Step>

      <Step title="(Optional) Check transaction status">
        You can poll the transaction status to confirm it completed successfully.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request GET \
              --url https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions/<txId> \
              --header 'X-API-KEY: YOUR_SERVER_API_KEY'
          ```

          ```js Node.js theme={null}
          const WALLET_ADDRESS = "YOUR_WALLET_ADDRESS";
          const TRANSACTION_ID = "YOUR_TRANSACTION_ID";

          const url = `https://staging.crossmint.com/api/2025-06-09/wallets/${WALLET_ADDRESS}/transactions/${TRANSACTION_ID}`;

          const options = {
              method: 'GET',
              headers: {
                  'X-API-KEY': 'YOUR_SERVER_API_KEY'
              }
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```python Python theme={null}
          import requests

          WALLET_ADDRESS = "YOUR_WALLET_ADDRESS"
          TRANSACTION_ID = "YOUR_TRANSACTION_ID"

          url = f"https://staging.crossmint.com/api/2025-06-09/wallets/{WALLET_ADDRESS}/transactions/{TRANSACTION_ID}"

          headers = {
              "X-API-KEY": "YOUR_SERVER_API_KEY"
          }

          response = requests.get(url, headers=headers)

          print(response.json())
          ```
        </CodeGroup>
      </Step>
    </Steps>

    ### Complete example

    Here's a complete, copy-pastable example for the `external-wallet` signer flow using <Tooltip>Viem</Tooltip>:

    ```typescript theme={null}
    import { privateKeyToAccount } from "viem/accounts";

    // ============================
    // Config (replace placeholders)
    // ============================
    const API_BASE_URL = "https://staging.crossmint.com";
    const API_VERSION = "2025-06-09";

    const API_KEY = "YOUR_SERVER_API_KEY";
    const WALLET_ADDRESS = "YOUR_WALLET_ADDRESS";
    const CHAIN = "base-sepolia";
    const TOKEN = "usdxm";

    // The externally-owned address that will sign the approval message:
    const EXTERNAL_WALLET_ADDRESS = "YOUR_EXTERNAL_WALLET_ADDRESS";

    const RECIPIENT_ADDRESS = "RECIPIENT_WALLET_ADDRESS";

    const AMOUNT = "0.69";

    const headers = {
        "X-API-KEY": API_KEY,
        "Content-Type": "application/json",
    };

    // ============================
    // STEP 1: Create the transaction
    // ============================
    const createTransferUrl =
        `${API_BASE_URL}/api/${API_VERSION}` +
        `/wallets/${WALLET_ADDRESS}/tokens/${CHAIN}:${TOKEN}/transfers`;

    const createTransferPayload = {
        recipient: RECIPIENT_ADDRESS,
        amount: AMOUNT,
        signer: `external-wallet:${EXTERNAL_WALLET_ADDRESS}`,
    };

    const createTransferRes = await fetch(createTransferUrl, {
        method: "POST",
        headers,
        body: JSON.stringify(createTransferPayload),
    });

    if (!createTransferRes.ok) {
        throw new Error(
            `Failed to create transfer: ${createTransferRes.status} ${await createTransferRes.text()}`
        );
    }

    const tx = await createTransferRes.json();
    const txId = tx.id;
    const messageToSign = tx?.approvals?.pending?.[0]?.message;

    if (!messageToSign) {
        throw new Error(
            "No approval message found. Ensure signer is external-wallet and that an approval is pending."
        );
    }

    console.log("txId:", txId);
    console.log("messageToSign:", messageToSign);

    // ============================
    // STEP 2: Sign the approval message (Viem)
    // ============================
    // IMPORTANT: sign the message EXACTLY as returned (a raw hex string).
    const account = privateKeyToAccount(`0x${"YOUR_PRIVATE_KEY"}`);

    const signature = await account.signMessage({
        message: { raw: messageToSign },
    });

    console.log("signature:", signature);

    // ============================
    // STEP 3: Submit the signature
    // ============================
    const submitApprovalUrl =
        `${API_BASE_URL}/api/${API_VERSION}` +
        `/wallets/${WALLET_ADDRESS}/transactions/${txId}/approvals`;

    const submitApprovalPayload = {
        approvals: [
            {
                signer: `external-wallet:${EXTERNAL_WALLET_ADDRESS}`,
                signature,
            },
        ],
    };

    const submitApprovalRes = await fetch(submitApprovalUrl, {
        method: "POST",
        headers,
        body: JSON.stringify(submitApprovalPayload),
    });

    if (!submitApprovalRes.ok) {
        throw new Error(
            `Failed to submit approval: ${submitApprovalRes.status} ${await submitApprovalRes.text()}`
        );
    }

    const approvalResult = await submitApprovalRes.json();
    console.log("approvalResult:", approvalResult);

    // ============================
    // STEP 4 (optional): Check transaction status
    // ============================
    const getTxUrl =
        `${API_BASE_URL}/api/${API_VERSION}` +
        `/wallets/${WALLET_ADDRESS}/transactions/${txId}`;

    const getTxRes = await fetch(getTxUrl, { method: "GET", headers });

    if (!getTxRes.ok) {
        throw new Error(
            `Failed to fetch transaction: ${getTxRes.status} ${await getTxRes.text()}`
        );
    }

    const txStatus = await getTxRes.json();
    console.log("txStatus:", txStatus);
    ```
  </Tab>
</Tabs>

See the [API reference](/api-reference/wallets/transfer-token) for all supported locator formats.

## Verify your transfer

Once the transfer completes, you can verify it in two ways:

1. **View the onchain transaction** using the `explorerLink` returned by the `send` method:

```typescript theme={null}
console.log("View transaction:", explorerLink);
// Example: https://sepolia.basescan.org/tx/0xe5844116732d6cd21127bfc100ba29aee02b82cc4ab51e134d44e719ca8d0b48
```

2. **Check the recipient's balance** programmatically using the [check balances API](/wallets/guides/check-balances).

## Retry Transfers Safely

Add an `x-idempotency-key` header when you create a transfer from your server. If you retry the request with the same key, Crossmint returns the original transaction instead of creating a second one. The key identifies your request. It is not the transaction ID.

<Steps>
  <Step title="Create a key">
    Create a new UUID for each transfer and store it with the transfer in your system. Send it with the request.

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request POST \
          --url https://staging.crossmint.com/api/2025-06-09/wallets/WALLET_ADDRESS/tokens/base-sepolia:usdxm/transfers \
          --header 'Content-Type: application/json' \
          --header 'X-API-KEY: YOUR_SERVER_API_KEY' \
          --header 'x-idempotency-key: payout-1042' \
          --data '{
              "recipient": "RECIPIENT_ADDRESS",
              "amount": "10"
          }'
      ```

      ```js Node.js theme={null}
      const response = await fetch(
          "https://staging.crossmint.com/api/2025-06-09/wallets/WALLET_ADDRESS/tokens/base-sepolia:usdxm/transfers",
          {
              method: "POST",
              headers: {
                  "Content-Type": "application/json",
                  "X-API-KEY": "YOUR_SERVER_API_KEY",
                  "x-idempotency-key": "payout-1042",
              },
              body: JSON.stringify({
                  recipient: "RECIPIENT_ADDRESS",
                  amount: "10",
              }),
          }
      );

      const transaction = await response.json();
      console.log(transaction.id);
      ```

      ```python Python theme={null}
      import requests

      response = requests.post(
          "https://staging.crossmint.com/api/2025-06-09/wallets/WALLET_ADDRESS/tokens/base-sepolia:usdxm/transfers",
          headers={
              "Content-Type": "application/json",
              "X-API-KEY": "YOUR_SERVER_API_KEY",
              "x-idempotency-key": "payout-1042",
          },
          json={"recipient": "RECIPIENT_ADDRESS", "amount": "10"},
      )

      transaction = response.json()
      print(transaction["id"])
      ```
    </CodeGroup>
  </Step>

  <Step title="Retry with the same key">
    If the request times out or returns a `5xx` error, send the same request with the same key. A new key creates a new transfer.
  </Step>

  <Step title="Save the transaction ID">
    Save the `id` from the response. Use [Get Transaction](/api-reference/wallets/get-transaction) to check the status of the transfer.
  </Step>
</Steps>

### Retry Limitations

* **A retry does not restart a transaction.** You get the transaction in its current status. A `failed` transaction stays failed, and an `awaiting-approval` transaction still needs approval. To try again, use a new key.
* **The request body is not compared.** If you reuse a key with a different amount or recipient, Crossmint returns the original transaction.
* **Keys apply to the whole project and do not expire.** A key covers all wallets in the project, on both the Transfer Token and [Create Transaction](/api-reference/wallets/create-transaction) endpoints.
* **Responses do not include the key.** You cannot look up a transaction by key, so save the transaction `id`.

<Note>
  On Stellar, a transaction expires if it is not approved before the ledger in `onChain.expiration`, about 8 minutes after it is created. An expired transaction keeps the `awaiting-approval` status. If you submit an approval for it, Crossmint returns a `422` error and sets the status to `failed`.
</Note>

## Next steps

<CardGroup>
  <Card title="Monitor transfers with webhooks" icon="bell" href="/wallets/guides/webhooks">
    Track transactions and receive completion notifications
  </Card>

  <Card title="How to check wallet balances" icon="wallet" href="/wallets/guides/check-balances">
    Query token balances across your wallets
  </Card>

  <Card title="Test the Transfer Tokens API" icon="code" href="/api-reference/wallets/transfer-token">
    Try out the API in the interactive playground
  </Card>
</CardGroup>


# Set Up a Treasury Wallet
Source: https://docs.crossmint.com/wallets/guides/treasury-wallets

Create and fund a company-owned wallet for stablecoin operations

This guide walks you through creating a Treasury Wallet — a company-owned wallet for managing stablecoins — and performing basic operations like funding and checking balances.

For background on what Treasury Wallets are and when to use them, see the [Treasury Wallets concept page](/wallets/concepts/treasury).

## Prerequisites

<CardGroup>
  <Snippet />
</CardGroup>

<Snippet />

## Create a Treasury Wallet

<Steps>
  <Step title="Install the SDK">
    Run the following command to install the SDK:

    <Snippet />
  </Step>

  <Step title="Create a treasury wallet">
    See all supported chains [here](/introduction/supported-chains).

    <CodeGroup>
      ```typescript Node.js theme={null}
      import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";

      const crossmint = createCrossmint({
          apiKey: "<your-server-api-key>",
      });

      const crossmintWallets = CrossmintWallets.from(crossmint);

      const wallet = await crossmintWallets.createWallet({
          chain: "base-sepolia",
          recoveryMethods: [{ type: "server", secret: "<your-recovery-secret>" }],
          owner: "COMPANY",
          alias: "treasury",
      });

      console.log(wallet.address);
      ```

      ```bash cURL theme={null}
      curl --request POST \
          --url 'https://staging.crossmint.com/api/2025-06-09/wallets' \
          --header 'X-API-KEY: <your-server-api-key>' \
          --header 'Content-Type: application/json' \
          --data '{
              "chainType": "evm",
              "type": "smart",
              "config": {
                  "recoveryMethods": [
                      {
                          "type": "server",
                          "address": "YOUR_DERIVED_SERVER_SIGNER_ADDRESS"
                      }
                  ]
              },
              "owner": "COMPANY",
              "alias": "treasury"
          }'
      ```

      ```python Python theme={null}
      import requests

      url = "https://staging.crossmint.com/api/2025-06-09/wallets"

      payload = {
          "chainType": "evm",
          "type": "smart",
          "config": {
              "recoveryMethods": [
                  {
                      "type": "server",
                      "address": "YOUR_DERIVED_SERVER_SIGNER_ADDRESS"
                  }
              ]
          },
          "owner": "COMPANY",
          "alias": "treasury"
      }
      headers = {
          "X-API-KEY": "<your-server-api-key>",
          "Content-Type": "application/json"
      }

      response = requests.post(url, json=payload, headers=headers)

      print(response.json())
      ```
    </CodeGroup>

    <Note>
      The `address` is the blockchain address derived from your server
      signer's secret key. You must derive this yourself before calling
      the API -- the REST API never sees your secret. See the
      [server signer guide](/wallets/guides/signers/server-signer)
      for how to generate and derive this address.
    </Note>

    **Key Points:**

    * The `owner` field must be set to `"COMPANY"` for treasury wallets to ensure the wallet appears under Company in the console
    * Each entry in `recoveryMethods` must be a non-custodial type (`external-wallet`, `passkey`, or `server`)
    * The `alias` field is set to `"treasury"` to identify this as your treasury wallet
    * A `server` signer is suitable for low-risk use-cases. For higher-risk use-cases, use an `external-wallet` signer via [Cloud KMS](/wallets/guides/signers/cloud-kms)
  </Step>

  <Step title="Fund and check treasury wallet balance">
    Fund the wallet using the SDK, then check the balance:

    <CodeGroup>
      ```typescript Node.js theme={null}
      import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";

      const crossmint = createCrossmint({
          apiKey: "<your-server-api-key>",
      });

      const crossmintWallets = CrossmintWallets.from(crossmint);

      const treasuryWallet = await crossmintWallets.getWallet("<your-wallet-address>", {
          chain: "base-sepolia",
      });
      // Fund the wallet (staging only)
      await treasuryWallet.stagingFund(10);

      // Check balance
      const balances = await treasuryWallet.balances(["usdxm"]);
      const usdxmToken = balances.tokens.find(t => t.symbol === "usdxm");
      console.log(usdxmToken?.amount);
      ```

      ```bash cURL theme={null}
      # Fund the wallet (staging only)
      curl --request POST \
          --url 'https://staging.crossmint.com/api/v1-alpha2/wallets/<your-wallet-address>/balances' \
          --header 'X-API-KEY: <your-server-api-key>' \
          --header 'Content-Type: application/json' \
          --data '{
              "amount": 10,
              "token": "usdxm",
              "chain": "base-sepolia"
          }'

      # Check balance
      curl --request GET \
          --url 'https://staging.crossmint.com/api/2025-06-09/wallets/<your-wallet-address>/balances' \
          --header 'X-API-KEY: <your-server-api-key>'
      ```

      ```python Python theme={null}
      import requests

      api_key = "<your-server-api-key>"
      wallet_address = "<your-wallet-address>"
      headers = {
          "X-API-KEY": api_key,
          "Content-Type": "application/json"
      }

      # Fund the wallet (staging only)
      fund_url = f"https://staging.crossmint.com/api/v1-alpha2/wallets/{wallet_address}/balances"
      fund_payload = {
          "amount": 10,
          "token": "usdxm",
          "chain": "base-sepolia"
      }
      requests.post(fund_url, json=fund_payload, headers=headers)

      # Check balance
      balance_url = f"https://staging.crossmint.com/api/2025-06-09/wallets/{wallet_address}/balances"
      response = requests.get(balance_url, headers={"X-API-KEY": api_key})

      print(response.json())
      ```
    </CodeGroup>
  </Step>

  <Step title="Run the code">
    Execute your `index.ts` file using one of the following methods:

    **Using ts-node:**

    ```bash theme={null}
    npx ts-node index.ts
    ```

    **Or compile and run with Node.js:**

    ```bash theme={null}
    npx tsc index.ts && node index.js
    ```

    You should see the wallet address printed to the console after successful execution.
  </Step>

  <Step title="Verify in the console">
    After creating your treasury wallet, you can verify it was created correctly in the <a href="https://staging.crossmint.com/console">Crossmint Console</a>:

    1. Navigate to **Wallets** in the left sidebar
    2. Click on the **Company** tab
    3. Your treasury wallet should appear in the list with the alias "treasury"
  </Step>
</Steps>

## Launching in Production

<Snippet />

For production, the steps are almost identical, but some changes are required:

1. Create a developer account on the <a href="https://www.crossmint.com/console">production console</a>
2. Create a production server API key on the <a href="https://www.crossmint.com/console/projects/apiKeys">API Keys</a> page with the API scopes `wallets.read`, `wallets.create`, `wallets:transactions.create`, `wallets:transactions.sign`, `wallets:balance.read`, `wallets.fund`
3. Replace your test API key with the production key
4. Discuss with your Crossmint Customer Success Engineering (CSE) team the best signer configuration for your expected usage, and recovery mechanisms

## Next Steps

<CardGroup>
  <Card title="Check Balances" icon="money-bill-transfer" href="/wallets/guides/check-balances">
    Check the balance of a wallet.
  </Card>

  <Card title="Funding the Wallet" icon="money-bill-transfer" href="/stablecoin-orchestration/guides/on-off-ramps/funding-company-wallets">
    Learn how to fund your treasury wallet.
  </Card>

  <Card title="Withdrawals" icon="building-columns" href="/stablecoin-orchestration/guides/on-off-ramps/withdrawing-from-company-wallets">
    Withdraw stablecoins to your bank account.
  </Card>

  <Card title="Payouts" icon="coins" href="/stablecoin-orchestration/regulated-transfers/overview">
    Send stablecoins to your customers and vendors.
  </Card>
</CardGroup>


# Troubleshooting
Source: https://docs.crossmint.com/wallets/guides/troubleshooting

Common errors and debugging techniques for Crossmint wallet integrations

Sometimes transactions fail. This guide outlines common failure reasons and provides tools to help you identify the underlying causes.

<Note>
  Reverted transactions are marked as "failed" and will not be executed. There is no auto-retry mechanism for failed
  transactions; you must manually resubmit them if needed.
</Note>

## Common Error Types

Transaction errors typically fall into two categories: validation failures and execution failures.

### Validation Errors

Validation errors occur when the provided transaction data is invalid. These errors commonly relate to invalid data (e.g., `signature`) during transaction approval. Common issues include:

* Malformed signatures
* Invalid signatures (e.g., from an unauthorized wallet)
* Insufficient signer permissions for transaction approval

An example of a validation error:

```json theme={null}
"error": {
  "reason": "execution_reverted",
  "message": "Execution reverted, see 'revert' for details",
  "revert": {
    "type": "wallet_authorization",
    "reason": "Invalid signature",
    "reasonData": "AA24"
  }
}
```

Troubleshooting steps:

* Verify the transaction signer is valid
* Confirm you are signing the correct `message` data
* Verify the signing private key matches the `signer` wallet

### Execution Errors

Execution errors occur when a transaction is reverted during runtime. These typically relate to the `calls` provided during transaction creation. Common causes include:

* Another transaction with the same call was executed already
* State changes between transaction creation and execution (e.g. asset price updated exceeding slippage allowance)

The Crossmint API typically provides specific revert reasons:

```json theme={null}
"error": {
  "reason": "execution_reverted",
  "message": "Execution reverted, see 'revert' for details",
  "revert": {
    "type": "contract_call",
    "reason": "ERC20: transfer amount exceeds balance"
  }
}
```

On EVM smart wallets, `revert` can also include a `debug` object that classifies the failure and points to the call that reverted. See [Revert Debug Object](#revert-debug-object).

Troubleshooting:

* Check `revert.debug.details.code` when present, and follow the matching action in [Failure Codes](#failure-codes)
* Check for similar previous transactions
* Attempt to resubmit with the same parameters

### Wallet Errors

#### WalletNotAvailableError

Thrown by `getWallet()` when no wallet exists for the given parameters. This is expected in the get-then-create pattern where you first attempt to retrieve a wallet and fall back to creating one.

```typescript theme={null}
import { useWallet } from "@crossmint/client-sdk-react-ui";
import { WalletNotAvailableError } from "@crossmint/wallets-sdk";

const { getWallet, createWallet } = useWallet();

try {
    const wallet = await getWallet({ chain: "base-sepolia" });
} catch (error) {
    if (error instanceof WalletNotAvailableError) {
        // No wallet exists yet — create one
        const wallet = await createWallet({
            chain: "base-sepolia",
            recoveryMethods: [{ type: "email", email: "user@example.com" }],
        });
    }
}
```

<Note>
  In previous SDK versions, `getOrCreateWallet()` handled this automatically. In V1, wallet retrieval and creation are separate operations. See the [migration guide](/wallets/guides/migrate-to-v1) for details.
</Note>

## Common Pitfalls

These are frequent sources of confusion when working with the V1 SDK.

### Read-only wallet from `getWallet()`

`getWallet()` returns a wallet with no active signer unless a device signer is found locally. Calling `send()`, `approve()`, or `addSigner()` on a read-only wallet throws an error.

**Fix:** Call `wallet.useSigner()` to activate a signer before performing signing operations, or rely on automatic device signer initialization on the client side.

```typescript theme={null}
const wallet = await getWallet({ chain: "base-sepolia" });

// wallet.signer may be undefined — check before signing
if (wallet.signer == null) {
    await wallet.useSigner({ type: "passkey" });
}

await wallet.send("0x...", "usdc", "1.0");
```

### `useSigner()` does not accept locator strings

In V1, `useSigner()` only accepts signer config objects. Passing a locator string (e.g., `"evm-keypair:0x..."`) results in a type error.

```typescript theme={null}
// ❌ Old — no longer works
await wallet.useSigner("evm-keypair:0xABC...");

// ✅ New — pass a config object
await wallet.useSigner({ type: "external-wallet", address: "0xABC..." });
```

### `getWallet()` parameter mismatch between client and server

`getWallet()` has different signatures on client and server. Using the wrong one throws an error.

* **Client-side:** `getWallet({ chain: "base-sepolia" })` — pass wallet args directly. Passing a `walletLocator` string as the first argument throws.
* **Server-side:** `getWallet("0xWalletAddress", { chain: "base-sepolia" })` — requires a `walletLocator` string as the first parameter. Omitting it throws: `"getWallet on server side requires a walletLocator parameter."`

### Client-side input validation errors

The V1 SDK validates inputs before making API calls, failing fast with descriptive errors:

| Error | Thrown by | Cause |
| - | - | - |
| `InvalidAddressError` | `wallet.send()` | Invalid `to` address format for the chain (EVM: `0x` + 40 hex chars, Solana: base58, Stellar: `G` + 55 alphanumeric) |
| `InvalidChainError` | `createWallet()`, `getWallet()` | Unrecognized chain name |
| `InvalidAmountError` | `wallet.send()` | Zero, negative, `Infinity`, or `NaN` amount |

### Other Errors

If you encounter transaction failures without error details or receive no error message, there may be an issue with the Crossmint infrastructure. First, check <a href="https://status.crossmint.com">the status page</a> to verify API availability and try again later. If the problem continues, contact Crossmint support.

## Signer Is Not Active After Adding

When you add a signer on EVM, the operation is either a transaction or a signature, depending on `deployImmediately`:

* TypeScript SDK (`@crossmint/wallets-sdk`, and React / React Native): `addSigner()` defaults to `deployImmediately: true`, which installs the signer onchain as soon as the registration transaction confirms.
* REST API: `POST /2025-06-09/wallets/{walletLocator}/signers` defaults to `deployImmediately: false` for EVM, so the signer is installed lazily on its first transaction after the signature is approved.
* Flutter, Kotlin, and Swift SDKs: These SDKs do not currently expose `deployImmediately`, so they use the REST API default (deferred signature flow on EVM).

If a signer is stuck in `pending` or `awaiting-approval`, check whether the response contains a `transactionId` or a `signatureId` and approve the correct object:

* `transactionId` → call [approve transaction](/api-reference/wallets/approve-transaction)
* `signatureId` → call [approve signature](/api-reference/wallets/approve-signature)

See [Installation Timing](/wallets/guides/signers/add-signers#installation-timing) for details.

## Debugging

The Crossmint API simulates all transactions before submitting them onchain. Failed simulations prevent onchain execution.

In most cases, the transaction fails during the simulation. If that is the case, the `revert.reason` and `revert.reasonData` fields describe the failure, and on EVM smart wallets `revert.debug` adds structured details. Otherwise, you can use a block explorer to inspect the transaction.

### Revert Debug Object

`revert.debug` is an optional object on the `revert` of failed EVM smart wallet transactions. It appears in transaction responses and in transaction webhook payloads. `revert.reason` and `revert.reasonData` keep their existing format, so code that reads them continues to work.

`revert.debug` is only available for EVM smart wallets and is absent when the chain returned no information about the failure, so always fall back to `revert.reason`. The classification is best effort: `details.code` is `unknown` when the cause cannot be determined, and `call` is omitted when the failing call cannot be identified.

`revert.debug` contains:

* **`message`**: a one-sentence summary of the failure
* **`retryable`**: `true` when resubmitting the same transaction can succeed, either after you fix the cause (for example funds or gas) or without changes (for example a nonce conflict, a gas sponsorship failure, or a failure with no revert data). `false` when a contract call itself reverts and the calls must change.
* **`chain`** and **`blockNumber`**: the chain and the block whose state the failure was observed against
* **`revert`**: the raw revert returned by the chain — `selector`, `name`, `signature`, and positional `args`. `selector` is absent when the revert carried no data; `name` and `signature` are absent when the error could not be decoded.
* **`call`**: the call in the batch that reverted — `index`, `to`, `value`, `function`, and `args`. Absent when the failure cannot be attributed to a call, for example during wallet validation.
* **`details`**: the classified root cause. Branch on `details.code`; the other fields depend on the code.

Each entry in `args` has a Solidity `type` and a `value`, with integers as decimal strings. `args[].name` is present only when the ABI was supplied in the transaction request.

To reproduce the failure, send an `eth_call` from the EntryPoint to the wallet with `onChain.userOperation.callData` at `blockNumber`. Hook-enabled operations prefix the calldata with the `executeUserOp` selector, which must be stripped, and wallets not yet deployed need a state override (proxy code plus the EIP-1967 implementation slot).

This example shows a USDC transfer that exceeds the wallet balance:

```json theme={null}
"error": {
  "reason": "execution_reverted",
  "message": "Execution reverted, see 'revert' for details",
  "revert": {
    "type": "contract_call",
    "reason": "ERC20InsufficientBalance(0x1234567890abcdef1234567890abcdef1234abcd,500000,1000000)",
    "reasonData": "0xe450d38c0000…",
    "debug": {
      "message": "Wallet holds 0.5 USDC but the transfer requires 1 USDC",
      "retryable": true,
      "chain": "base",
      "blockNumber": "38104211",
      "revert": {
        "selector": "0xe450d38c",
        "name": "ERC20InsufficientBalance",
        "signature": "ERC20InsufficientBalance(address,uint256,uint256)",
        "args": [
          { "type": "address", "value": "0x1234567890abcdef1234567890abcdef1234abcd" },
          { "type": "uint256", "value": "500000" },
          { "type": "uint256", "value": "1000000" }
        ]
      },
      "call": {
        "index": 1,
        "to": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
        "value": "0",
        "function": "transfer(address,uint256)",
        "args": [
          { "type": "address", "name": "to", "value": "0x9999999999999999999999999999999999999999" },
          { "type": "uint256", "name": "amount", "value": "1000000" }
        ]
      },
      "details": {
        "code": "insufficient_erc20_balance",
        "token": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
        "symbol": "USDC",
        "required": "1000000",
        "available": "500000"
      }
    }
  }
}
```

### Failure Codes

| `details.code` | Extra fields | What to do |
| - | - | - |
| `insufficient_erc20_balance` | `token`, `symbol`, `required`, `available` | Fund the wallet with at least `required` of `token`, or lower the amount, then resubmit |
| `insufficient_erc20_allowance` | `token`, `symbol`, `spender`, `required`, `available` | Approve `spender` for at least `required` of `token`, then resubmit |
| `insufficient_native_balance` | `required`, `available` | Fund the wallet with enough native token, in wei, to cover the value sent plus gas |
| `out_of_gas` | `gasLimit`, `gasUsed` | Resubmit with a higher gas limit, or reduce the work done in the transaction |
| `account_abstraction` | `entryPointCode`, `entryPointMessage` | The ERC-4337 EntryPoint rejected the transaction. See [EntryPoint Codes](#entrypoint-codes). |
| `contract_revert` | — | A contract reverted for a reason Crossmint does not classify. Inspect `revert` and `call` to see which error and call failed. |
| `unknown` | — | The chain returned no revert data. Check `call`, replay at `blockNumber`, or inspect the transaction in a block explorer. |

`required` and `available` are decimal strings in the token's smallest unit.

Crossmint returns an `insufficient_*` or `out_of_gas` code only when it can confirm the cause. Otherwise the same revert is reported as `contract_revert`, with the decoded error in `revert`, so handle every code in the table.

### EntryPoint Codes

When `details.code` is `account_abstraction`, `entryPointCode` holds the EntryPoint code and `entryPointMessage` holds the EntryPoint's own message.

| `entryPointCode` | `entryPointMessage` | What to do |
| - | - | - |
| `AA13` | `initCode failed or OOG` | The wallet deployment failed. Contact Crossmint support with the transaction ID. |
| `AA21` | `didn't pay prefund` | The wallet cannot pay for gas. Fund it with native token, or enable gas sponsorship for the project. |
| `AA22` | `expired or not due` | The signer is outside its validity window: expired, or not yet valid. Check the signer's `expiresAt`. |
| `AA23` | `reverted` | The wallet rejected the transaction during validation. Verify the signer is registered and active on the wallet. |
| `AA24` | `signature error` | The signature is invalid. Confirm you signed the correct `message` with the transaction's signer. |
| `AA25` | `invalid account nonce` | Another transaction used the same nonce. Resubmit the transaction. |
| `AA30`–`AA36`, `PostOpReverted` | `Gas sponsorship failed` | Gas sponsorship failed and no further detail is returned. Contact Crossmint support with the transaction ID. |

### Block Explorer

If the transaction was included onchain, you can check its status using a block explorer.


# LI.FI
Source: https://docs.crossmint.com/wallets/guides/wallet-extensions/bridge-lifi

Bridge tokens between chains using Crossmint wallets and LI.FI

This guide explains how to bridge tokens across chains using the <a href="https://docs.li.fi/li.fi-api/li.fi-api">LI.FI</a> API with Crossmint wallets. LI.FI aggregates bridges and DEXs to find optimal cross-chain routes.

## Prerequisites

To use LI.FI bridging with Crossmint wallets, you need:

* A Crossmint [wallet](/wallets/guides/create-wallet) on any supported EVM chain
* A **production** **API Key** with the scope: `wallets:transactions.create` (create in the <a href="https://www.crossmint.com/console">Production Console</a>)

This guide uses Base → Polygon as an example. To follow along, you will also need:

* USDC on Base mainnet in the wallet
* ETH on Base for gas fees (not required if [gas sponsorship](/wallets/guides/gas-sponsorship) is enabled — but see [Gas Sponsorship and Bridge Fees](#gas-sponsorship-and-bridge-fees) for an important caveat about bridge protocol fees)

You can adapt the code to bridge between any chains and tokens that LI.FI supports. See [Customizing the Bridge](#customizing-the-bridge) below.

## Bridge Tokens

High level steps to bridging tokens with LI.FI and Crossmint:

1. Request a bridge quote from the LI.FI API
2. Approve the LI.FI router to spend the source token
3. Execute the bridge transaction using the quote calldata
4. Poll the LI.FI status endpoint until the bridge completes

<Warning>
  Cross-chain bridges operate on mainnet only. The wallet must hold sufficient tokens on the source chain and may need native tokens for bridge protocol fees — see [Gas Sponsorship and Bridge Fees](#gas-sponsorship-and-bridge-fees).
</Warning>

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet, EVMWallet } from "@crossmint/client-sdk-react-ui";
    import { encodeFunctionData, erc20Abi, parseUnits } from "viem";

    const LIFI_API = "https://li.quest/v1";
    const FROM_CHAIN = "8453"; // Base
    const TO_CHAIN = "137"; // Polygon
    const FROM_TOKEN = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"; // USDC on Base
    const TO_TOKEN = "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359"; // USDC on Polygon
    const USDC_DECIMALS = 6;

    export function BridgeComponent() {
        const { wallet } = useWallet();

        async function bridge(amount: string) {
            if(!wallet) return;
            const evmWallet = EVMWallet.from(wallet);

            // 1. Get a bridge quote from the LI.FI API
            const quoteRes = await fetch(
                `${LIFI_API}/quote?` +
                    new URLSearchParams({
                        fromChain: FROM_CHAIN,
                        toChain: TO_CHAIN,
                        fromToken: FROM_TOKEN,
                        toToken: TO_TOKEN,
                        fromAmount: parseUnits(amount, USDC_DECIMALS).toString(),
                        fromAddress: wallet.address,
                        integrator: "crossmint",
                    })
            );
            if (!quoteRes.ok) {
                throw new Error(`Quote request failed: ${quoteRes.status}`);
            }
            const quote = await quoteRes.json();

            // 2. Approve the LI.FI router to spend USDC
            if (quote.estimate.approvalAddress) {
                await evmWallet.sendTransaction({
                    to: FROM_TOKEN,
                    data: encodeFunctionData({
                        abi: erc20Abi,
                        functionName: "approve",
                        args: [
                            quote.estimate.approvalAddress,
                            parseUnits(amount, USDC_DECIMALS),
                        ],
                    }),
                });
            }

            // 3. Execute the bridge transaction
            const tx = await evmWallet.sendTransaction({
                to: quote.transactionRequest.to,
                data: quote.transactionRequest.data,
                value: quote.transactionRequest.value
                    ? BigInt(quote.transactionRequest.value)
                    : 0n,
            });

            // 4. Poll the LI.FI status endpoint until completion
            let status = "PENDING";
            while (status === "PENDING" || status === "NOT_FOUND") {
                await new Promise((r) => setTimeout(r, 5000));
                const statusRes = await fetch(
                    `${LIFI_API}/status?` +
                        new URLSearchParams({
                            txHash: tx.hash,
                            fromChain: FROM_CHAIN,
                            toChain: TO_CHAIN,
                        })
                );
                if (!statusRes.ok) {
                    throw new Error(`Status request failed: ${statusRes.status}`);
                }
                const s = await statusRes.json();
                status = s.status;
            }
        }

        return (
            <button onClick={() => bridge("5")}>Bridge Tokens</button>
        );
    }
    ```

    See the [React SDK reference](/sdk-reference/wallets/react/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { CrossmintWallets, createCrossmint, EVMWallet } from "@crossmint/wallets-sdk";
    import { encodeFunctionData, erc20Abi, parseUnits } from "viem";

    const crossmint = createCrossmint({
        apiKey: "YOUR_SERVER_API_KEY",
    });
    const crossmintWallets = CrossmintWallets.from(crossmint);

    const wallet = await crossmintWallets.getWallet(
        "email:user@example.com",
        { chain: "base" }
    );
    if(!wallet) throw new Error("Wallet not found");
    await wallet.useSigner({ type: "email", email: "user@example.com" });
    const evmWallet = EVMWallet.from(wallet);

    const LIFI_API = "https://li.quest/v1";
    const FROM_CHAIN = "8453"; // Base
    const TO_CHAIN = "137"; // Polygon
    const FROM_TOKEN = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"; // USDC on Base
    const TO_TOKEN = "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359"; // USDC on Polygon
    const USDC_DECIMALS = 6;
    const amount = "5";

    // 1. Get a bridge quote from the LI.FI API
    const quoteRes = await fetch(
        `${LIFI_API}/quote?` +
            new URLSearchParams({
                fromChain: FROM_CHAIN,
                toChain: TO_CHAIN,
                fromToken: FROM_TOKEN,
                toToken: TO_TOKEN,
                fromAmount: parseUnits(amount, USDC_DECIMALS).toString(),
                fromAddress: wallet.address,
                integrator: "crossmint",
            })
    );
    if (!quoteRes.ok) {
        throw new Error(`Quote request failed: ${quoteRes.status}`);
    }
    const quote = await quoteRes.json();

    // 2. Approve the LI.FI router to spend USDC
    if (quote.estimate.approvalAddress) {
        await evmWallet.sendTransaction({
            to: FROM_TOKEN,
            data: encodeFunctionData({
                abi: erc20Abi,
                functionName: "approve",
                args: [
                    quote.estimate.approvalAddress,
                    parseUnits(amount, USDC_DECIMALS),
                ],
            }),
        });
    }

    // 3. Execute the bridge transaction
    const tx = await evmWallet.sendTransaction({
        to: quote.transactionRequest.to,
        data: quote.transactionRequest.data,
        value: quote.transactionRequest.value
            ? BigInt(quote.transactionRequest.value)
            : 0n,
    });

    // 4. Poll the LI.FI status endpoint until completion
    let status = "PENDING";
    while (status === "PENDING" || status === "NOT_FOUND") {
        await new Promise((r) => setTimeout(r, 5000));
        const statusRes = await fetch(
            `${LIFI_API}/status?` +
                new URLSearchParams({
                    txHash: tx.hash,
                    fromChain: FROM_CHAIN,
                    toChain: TO_CHAIN,
                })
        );
        if (!statusRes.ok) {
            throw new Error(`Status request failed: ${statusRes.status}`);
        }
        const s = await statusRes.json();
        status = s.status;
    }

    console.log("Bridge complete!");
    ```
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { useWallet, EVMWallet } from "@crossmint/client-sdk-react-native-ui";
    import { View, Button } from "react-native";
    import { encodeFunctionData, erc20Abi, parseUnits } from "viem";

    const LIFI_API = "https://li.quest/v1";
    const FROM_CHAIN = "8453"; // Base
    const TO_CHAIN = "137"; // Polygon
    const FROM_TOKEN = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"; // USDC on Base
    const TO_TOKEN = "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359"; // USDC on Polygon
    const USDC_DECIMALS = 6;

    export function BridgeComponent() {
        const { wallet } = useWallet();

        async function bridge(amount: string) {
            if(!wallet) return;
            const evmWallet = EVMWallet.from(wallet);

            // 1. Get a bridge quote from the LI.FI API
            const quoteRes = await fetch(
                `${LIFI_API}/quote?` +
                    new URLSearchParams({
                        fromChain: FROM_CHAIN,
                        toChain: TO_CHAIN,
                        fromToken: FROM_TOKEN,
                        toToken: TO_TOKEN,
                        fromAmount: parseUnits(amount, USDC_DECIMALS).toString(),
                        fromAddress: wallet.address,
                        integrator: "crossmint",
                    })
            );
            if (!quoteRes.ok) {
                throw new Error(`Quote request failed: ${quoteRes.status}`);
            }
            const quote = await quoteRes.json();

            // 2. Approve the LI.FI router to spend USDC
            if (quote.estimate.approvalAddress) {
                await evmWallet.sendTransaction({
                    to: FROM_TOKEN,
                    data: encodeFunctionData({
                        abi: erc20Abi,
                        functionName: "approve",
                        args: [
                            quote.estimate.approvalAddress,
                            parseUnits(amount, USDC_DECIMALS),
                        ],
                    }),
                });
            }

            // 3. Execute the bridge transaction
            const tx = await evmWallet.sendTransaction({
                to: quote.transactionRequest.to,
                data: quote.transactionRequest.data,
                value: quote.transactionRequest.value
                    ? BigInt(quote.transactionRequest.value)
                    : 0n,
            });

            // 4. Poll the LI.FI status endpoint until completion
            let status = "PENDING";
            while (status === "PENDING" || status === "NOT_FOUND") {
                await new Promise((r) => setTimeout(r, 5000));
                const statusRes = await fetch(
                    `${LIFI_API}/status?` +
                        new URLSearchParams({
                            txHash: tx.hash,
                            fromChain: FROM_CHAIN,
                            toChain: TO_CHAIN,
                        })
                );
                if (!statusRes.ok) {
                    throw new Error(`Status request failed: ${statusRes.status}`);
                }
                const s = await statusRes.json();
                status = s.status;
            }
        }

        return (
            <View>
                <Button title="Bridge Tokens" onPress={() => bridge("5")} />
            </View>
        );
    }
    ```

    See the [React Native SDK reference](/sdk-reference/wallets/react-native/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    import CrossmintClient
    import Wallet
    import Foundation

    CrossmintSDK.configure(apiKey: "<YOUR_API_KEY>")
    let sdk = CrossmintSDK.shared

    let wallet: Wallet
    if let existing = try await sdk.crossmintWallets.getWallet(chain: EVMChain.base) {
        wallet = existing
    } else {
        wallet = try await sdk.crossmintWallets.createWallet(
            chain: EVMChain.base,
            recoveryMethods: [EVMSigners.email("user@example.com")]
        )
    }

    let evmWallet = try EVMWallet.from(wallet: wallet)

    let fromChain = "8453"
    let toChain = "137"
    let fromToken = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
    let toToken = "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359"
    let amount = "5000000" // 5 USDC (6 decimals)

    // 1. Get a bridge quote from the LI.FI API
    var quoteURL = URLComponents(string: "https://li.quest/v1/quote")!
    quoteURL.queryItems = [
        URLQueryItem(name: "fromChain", value: fromChain),
        URLQueryItem(name: "toChain", value: toChain),
        URLQueryItem(name: "fromToken", value: fromToken),
        URLQueryItem(name: "toToken", value: toToken),
        URLQueryItem(name: "fromAmount", value: amount),
        URLQueryItem(name: "fromAddress", value: wallet.address),
        URLQueryItem(name: "integrator", value: "crossmint"),
    ]

    let (quoteData, quoteResponse) = try await URLSession.shared.data(from: quoteURL.url!)
    guard let httpResponse = quoteResponse as? HTTPURLResponse,
          httpResponse.statusCode == 200 else {
        throw URLError(.badServerResponse)
    }
    let quote = try JSONSerialization.jsonObject(with: quoteData) as! [String: Any]
    let estimate = quote["estimate"] as! [String: Any]
    let txRequest = quote["transactionRequest"] as! [String: Any]

    // 2. Approve the LI.FI router to spend USDC
    //    Encodes ERC-20 approve(address,uint256) — selector 0x095ea7b3
    //    Note: UInt64 supports up to ~18.4e18. For tokens with 18 decimals
    //    and large amounts, use a big-integer hex conversion instead.
    func leftPad(_ str: String, toLength len: Int) -> String {
        String(repeating: "0", count: max(0, len - str.count)) + str
    }

    if let approvalAddress = estimate["approvalAddress"] as? String {
        let addr = leftPad(String(approvalAddress.dropFirst(2)), toLength: 64)
        let amt = leftPad(String(UInt64(amount)!, radix: 16), toLength: 64)
        let approveData = "0x095ea7b3" + addr + amt
        let _ = try await evmWallet.sendTransaction(
            to: fromToken,
            value: "0",
            data: approveData
        )
    }

    // 3. Execute the bridge transaction
    let result = try await evmWallet.sendTransaction(
        to: txRequest["to"] as! String,
        value: (txRequest["value"] as? String) ?? "0",
        data: txRequest["data"] as! String
    )

    // 4. Poll the LI.FI status endpoint until completion
    var bridgeStatus = "PENDING"
    while bridgeStatus == "PENDING" || bridgeStatus == "NOT_FOUND" {
        try await Task.sleep(nanoseconds: 5_000_000_000)

        var statusURL = URLComponents(string: "https://li.quest/v1/status")!
        statusURL.queryItems = [
            URLQueryItem(name: "txHash", value: result.hash),
            URLQueryItem(name: "fromChain", value: fromChain),
            URLQueryItem(name: "toChain", value: toChain),
        ]
        let (statusData, _) = try await URLSession.shared.data(from: statusURL.url!)
        let statusJSON = try JSONSerialization.jsonObject(with: statusData) as! [String: Any]
        bridgeStatus = statusJSON["status"] as! String
    }
    ```

    See the [Swift SDK reference](/sdk-reference/wallets/swift/classes/evmwallet) for more details.
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    import com.crossmint.kotlin.compose.LocalCrossmintSDK
    import com.crossmint.kotlin.types.EVMChain
    import com.crossmint.kotlin.signers.SignerType
    import com.crossmint.kotlin.types.Result
    import com.crossmint.kotlin.types.WalletError
    import com.crossmint.kotlin.types.getOrThrow
    import kotlinx.coroutines.Dispatchers
    import kotlinx.coroutines.delay
    import kotlinx.coroutines.withContext
    import kotlinx.serialization.json.Json
    import kotlinx.serialization.json.buildJsonObject
    import kotlinx.serialization.json.contentOrNull
    import kotlinx.serialization.json.jsonObject
    import kotlinx.serialization.json.jsonPrimitive
    import kotlinx.serialization.json.put
    import kotlinx.serialization.json.putJsonArray
    import kotlinx.serialization.json.putJsonObject
    import java.net.HttpURLConnection
    import java.net.URL

    val API_KEY = "YOUR_API_KEY"
    val SIGNER_EMAIL = "user@example.com"
    val LIFI_API = "https://li.quest/v1"
    val CROSSMINT_API = "https://www.crossmint.com/api/2025-06-09"
    val FROM_CHAIN = "8453"  // Base
    val TO_CHAIN = "137"     // Polygon
    val FROM_TOKEN = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"  // USDC on Base
    val TO_TOKEN = "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359"    // USDC on Polygon
    val AMOUNT = "5000000"   // 5 USDC (6 decimals)

    // Access the SDK — must be called inside a CrossmintSDKProvider composable
    val sdk = LocalCrossmintSDK.current
    val wallet = when (val result = sdk.wallets.getWallet(chain = EVMChain.Base)) {
        is Result.Success -> result.value
        is Result.Failure -> if (result.error is WalletError.WalletNotFound) {
            sdk.wallets.createWallet(chain = EVMChain.Base, recoveryMethods = listOf(SignerType.Email(SIGNER_EMAIL))).getOrThrow()
        } else {
            throw Exception(result.error.toString())
        }
    }

    val json = Json { ignoreUnknownKeys = true }

    // 1. Get a bridge quote from the LI.FI API
    val quoteText = withContext(Dispatchers.IO) {
        val conn = URL(
            "$LIFI_API/quote?fromChain=$FROM_CHAIN&toChain=$TO_CHAIN" +
                "&fromToken=$FROM_TOKEN&toToken=$TO_TOKEN" +
                "&fromAmount=$AMOUNT&fromAddress=${wallet.address}&integrator=crossmint"
        ).openConnection() as HttpURLConnection
        check(conn.responseCode == 200) { "Quote request failed: ${conn.responseCode}" }
        conn.inputStream.bufferedReader().readText()
    }
    val quote = json.parseToJsonElement(quoteText).jsonObject
    val estimate = quote["estimate"]!!.jsonObject
    val txRequest = quote["transactionRequest"]!!.jsonObject

    // The Kotlin SDK's send() only supports simple token transfers, not raw calldata.
    // The REST API is used here to create approval and bridge transactions directly.
    suspend fun sendEvmTransaction(to: String, data: String, value: String = "0"): String {
        val body = buildJsonObject {
            putJsonObject("params") {
                put("chain", "base")
                put("signer", "email:$SIGNER_EMAIL")
                putJsonArray("calls") {
                    add(buildJsonObject {
                        put("to", to)
                        put("value", value)
                        put("data", data)
                    })
                }
            }
        }.toString()
        val responseText = withContext(Dispatchers.IO) {
            val conn = URL("$CROSSMINT_API/wallets/${wallet.address}/transactions")
                .openConnection() as HttpURLConnection
            conn.requestMethod = "POST"
            conn.setRequestProperty("X-API-KEY", API_KEY)
            conn.setRequestProperty("Content-Type", "application/json")
            conn.doOutput = true
            conn.outputStream.write(body.toByteArray())
            val code = conn.responseCode
            if (code !in 200..299) {
                val err = conn.errorStream?.bufferedReader()?.readText()
                error("Transaction request failed ($code): $err")
            }
            conn.inputStream.bufferedReader().readText()
        }
        val transactionId = json.parseToJsonElement(responseText)
            .jsonObject["id"]!!.jsonPrimitive.content
        val tx = wallet.approve(transactionId).getOrThrow()
        return tx.onChain.txId ?: tx.onChain.userOperationHash
            ?: error("Transaction completed but no hash was returned")
    }

    // 2. Approve the LI.FI router to spend USDC
    //    Encodes ERC-20 approve(address,uint256) — selector 0x095ea7b3
    //    Note: Long supports up to ~9.2e18. For tokens with 18 decimals
    //    and large amounts, use a BigInteger hex conversion instead.
    val approvalAddress = estimate["approvalAddress"]?.jsonPrimitive?.contentOrNull
    if (approvalAddress != null) {
        val addr = approvalAddress.removePrefix("0x").padStart(64, '0')
        val amt = AMOUNT.toLong().toString(16).padStart(64, '0')
        sendEvmTransaction(to = FROM_TOKEN, data = "0x095ea7b3$addr$amt")
    }

    // 3. Execute the bridge transaction
    val txHash = sendEvmTransaction(
        to = txRequest["to"]!!.jsonPrimitive.content,
        data = txRequest["data"]!!.jsonPrimitive.content,
        value = txRequest["value"]?.jsonPrimitive?.contentOrNull ?: "0",
    )

    // 4. Poll the LI.FI status endpoint until completion
    var bridgeStatus = "PENDING"
    while (bridgeStatus == "PENDING" || bridgeStatus == "NOT_FOUND") {
        delay(5_000)
        val statusText = withContext(Dispatchers.IO) {
            val conn = URL("$LIFI_API/status?txHash=$txHash&fromChain=$FROM_CHAIN&toChain=$TO_CHAIN")
                .openConnection() as HttpURLConnection
            check(conn.responseCode == 200) { "Status request failed: ${conn.responseCode}" }
            conn.inputStream.bufferedReader().readText()
        }
        bridgeStatus = json.parseToJsonElement(statusText).jsonObject["status"]!!.jsonPrimitive.content
    }
    ```

    See the [Kotlin SDK reference](/sdk-reference/wallets/kotlin/classes/wallet) for more details.
  </Tab>

  <Tab title="REST">
    Transactions must be approved by one of the wallet's [signers](/wallets/concepts/signers).
    The SDK handles this automatically, but with the REST API you must [approve the transaction](/api-reference/wallets/approve-transaction) to complete it.

    <Steps>
      <Step title="Get a bridge quote from the LI.FI API">
        Call the <a href="https://docs.li.fi/li.fi-api/li.fi-api">LI.FI API</a> `/quote` endpoint with the source and destination chain, token addresses, and amount.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request GET \
              --url 'https://li.quest/v1/quote?fromChain=8453&toChain=137&fromToken=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913&toToken=0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359&fromAmount=5000000&fromAddress=YOUR_WALLET_ADDRESS&integrator=crossmint' \
              --header 'Content-Type: application/json'
          ```

          ```js Node.js theme={null}
          const params = new URLSearchParams({
              fromChain: "8453",
              toChain: "137",
              fromToken:
                  "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
              toToken:
                  "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
              fromAmount: "5000000",
              fromAddress: "YOUR_WALLET_ADDRESS",
              integrator: "crossmint",
          });

          const response = await fetch(
              `https://li.quest/v1/quote?${params}`
          );
          const quote = await response.json();
          ```

          ```python Python theme={null}
          import requests

          response = requests.get(
              "https://li.quest/v1/quote",
              params={
                  "fromChain": "8453",
                  "toChain": "137",
                  "fromToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                  "toToken": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
                  "fromAmount": "5000000",
                  "fromAddress": "YOUR_WALLET_ADDRESS",
                  "integrator": "crossmint",
              }
          )
          quote = response.json()
          ```
        </CodeGroup>

        The response includes `estimate.approvalAddress` and `transactionRequest` with the bridge calldata.
      </Step>

      <Step title="Send the approve and bridge transactions">
        Use the quote response to send two transactions via the Crossmint REST API:

        1. **Approve** — call the USDC contract with ERC-20 `approve` calldata targeting `estimate.approvalAddress`
        2. **Bridge** — send `transactionRequest.to`, `transactionRequest.data`, and `transactionRequest.value`

        Follow the steps in the [Send a transaction](/wallets/guides/send-transaction-evm#rest) guide to submit each transaction via the Crossmint REST API.
      </Step>

      <Step title="Poll for bridge status">
        Call the LI.FI `/status` endpoint every five seconds until the bridge completes.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request GET \
              --url 'https://li.quest/v1/status?txHash=YOUR_TRANSACTION_HASH&fromChain=8453&toChain=137' \
              --header 'Content-Type: application/json'
          ```

          ```js Node.js theme={null}
          const statusParams = new URLSearchParams({
              txHash: "YOUR_TRANSACTION_HASH",
              fromChain: "8453",
              toChain: "137",
          });

          const statusRes = await fetch(
              `https://li.quest/v1/status?${statusParams}`
          );
          const status = await statusRes.json();
          // status.status is "DONE", "FAILED",
          // "PENDING", or "NOT_FOUND"
          ```

          ```python Python theme={null}
          import requests

          response = requests.get(
              "https://li.quest/v1/status",
              params={
                  "txHash": "YOUR_TRANSACTION_HASH",
                  "fromChain": "8453",
                  "toChain": "137",
              }
          )
          status = response.json()
          # status["status"] is "DONE", "FAILED",
          # "PENDING", or "NOT_FOUND"
          ```
        </CodeGroup>

        The bridge is complete when `status` is `DONE`. If `FAILED`, check the transaction on the block explorer for details.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Gas Sponsorship and Bridge Fees

<Warning>
  **Gas sponsorship covers execution gas only — not native-token bridge fees.** Some bridge protocols (e.g., LayerZero, Stargate) charge a protocol fee in the source chain's native token, passed as `transactionRequest.value` in the quote response. This fee must be paid from the wallet's own balance — the paymaster does not cover it. Routes through Relay or CCTP typically set `transactionRequest.value = 0` and work with wallets that hold no native tokens.
</Warning>

If your wallets use gas sponsorship and hold no native tokens, add `allowBridges=across,cctp,hop,relay` to the LI.FI quote request to restrict to bridges that do not require native-token fees. Alternatively, validate `BigInt(quote.transactionRequest.value) === 0n` before executing.

## Customizing the Bridge

You can bridge any token pair that LI.FI supports by changing the chain and token constants. You can also perform cross-chain swaps — changing both the asset and the chain in a single operation:

```typescript theme={null}
const FROM_CHAIN = "1"; // Ethereum
const TO_CHAIN = "42161"; // Arbitrum
const FROM_TOKEN =
    "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"; // USDC on Ethereum
const TO_TOKEN =
    "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"; // USDC on Arbitrum
```

See the full list of supported chains and tokens in the <a href="https://docs.li.fi/introduction/chains#chain-overview">LI.FI Documentation</a>.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Transaction fails with insufficient balance">
    Verify the wallet holds enough USDC on Base. If gas sponsorship is not enabled, the wallet also needs ETH for gas fees.
    Use the [Check Balances](/wallets/guides/check-balances) guide to confirm token balances before bridging.
  </Accordion>

  <Accordion title="Transaction reverts with gas sponsorship enabled">
    If the wallet holds 0 ETH and the bridge transaction reverts, the LI.FI route likely requires a native-token bridge fee (`transactionRequest.value > 0`). Gas sponsorship covers execution gas only, not bridge protocol fees. See [Gas Sponsorship and Bridge Fees](#gas-sponsorship-and-bridge-fees) for recommended solutions.
  </Accordion>

  <Accordion title="ERC-20 approval transaction is rejected">
    Ensure the approval amount is greater than or equal to the bridge amount.
    If a previous approval exists for a smaller amount, send a new approval transaction with the correct value.
    Verify the API key has the `wallets:transactions.create` scope.
  </Accordion>

  <Accordion title="Bridge status stays PENDING for a long time">
    Cross-chain bridges can take several minutes depending on the route and chain congestion.
    The LI.FI `/status` endpoint returns `PENDING` until both the source and destination chain transactions confirm.
    If the status does not change after 10 minutes, check the source transaction on a block explorer to verify it was included.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Check Balances" icon="wallet" href="/wallets/guides/check-balances">
    Verify updated token balances after bridging on any chain
  </Card>

  <Card title="Send a Transaction" icon="arrow-right" href="/wallets/guides/transfer-tokens">
    Transfer tokens from any chain
  </Card>
</CardGroup>


# Rain Card Issuance
Source: https://docs.crossmint.com/wallets/guides/wallet-extensions/credit-cards

Build a complete Visa credit card application for your users using Rain cards and Crossmint wallets.

<Note>
  This integration requires access to both Rain's card issuance API and
  Crossmint's wallet services.
</Note>

## Introduction

This guide shows you how to integrate Rain's card issuance platform with Crossmint wallets to build a complete crypto-to-credit card application. You'll learn how to create an app where users can sign up, issue a Visa card, and fund them directly from their wallets.

<Note>
  Check out our [live demo](https://rain-wallets-demo.vercel.app/) to see the
  integration in action before building your own.
</Note>

**What you'll build:**

* Virtual Visa card issuance
* Crypto-to-card funding with RUSD tokens
* Real-time balance and transaction monitoring

**Tech Stack:**

* Next.js >=15 (with App Router)
* React Server Actions for API integration
* [Crossmint React SDK](https://www.npmjs.com/package/@crossmint/client-sdk-react-ui) for wallet and authentication
* Rain API for card issuance ([contact the rain team for access](https://www.rain.xyz/contact-us))

## Prerequisites

<Steps>
  <Step icon="circle-dot" title="Rain API Key">
    [Get your Rain Staging API key](https://use-dev.raincards.xyz) with card
    issuance permissions
  </Step>

  <Step icon="circle-dot" title="Crossmint API Key">
    [Get your Crossmint Staging API
    key](https://docs.crossmint.com/introduction/platform/api-keys/client-side)
    with wallet and transaction scopes
  </Step>

  <Step icon="circle-dot" title="Next.js Project">
    Set up a Next.js project with App Router enabled for server actions: `npx
            create-next-app@latest my-rain-crossmint-app`
  </Step>

  <Step icon="circle-dot" title="Install Dependencies">
    ```bash theme={null}
    # Using npm
    npm install @crossmint/client-sdk-react-ui viem

    # Using pnpm
    pnpm add @crossmint/client-sdk-react-ui viem

    # Using yarn
    yarn add @crossmint/client-sdk-react-ui viem
    ```
  </Step>
</Steps>

## Integration Steps

<Steps>
  <Step title="Set up Crossmint Authentication and Wallet Providers">
    Set up the complete Crossmint provider stack with authentication and wallet functionality. This enables users to sign in and automatically creates wallets for them. This example uses [Crossmint Auth](/authentication/introduction) for simplicity, but for production you should [bring your own auth provider](/wallets/guides/bring-your-own-auth).

    ```tsx app/providers.tsx theme={null}
    "use client";

    import {
      CrossmintProvider,
      CrossmintAuthProvider,
      CrossmintWalletProvider,
    } from "@crossmint/client-sdk-react-ui";

    export function Providers({ children }: { children: React.ReactNode }) {
      return (
        <CrossmintProvider apiKey={process.env.NEXT_PUBLIC_CROSSMINT_API_KEY!}>
          <CrossmintAuthProvider>
            <CrossmintWalletProvider
              createOnLogin={{
                chain: "base-sepolia", // Using Base Sepolia for this demo
                signer: {
                  type: "email",
                },
              }}
            >
              {children}
            </CrossmintWalletProvider>
          </CrossmintAuthProvider>
        </CrossmintProvider>
      );
    }
    ```

    ```tsx app/layout.tsx theme={null}
    import { Providers } from "./providers";

    export default function RootLayout({ children }: { children: React.ReactNode }) {
      return (
        <html lang="en">
          <body>
            <Providers>{children}</Providers>
          </body>
        </html>
      );
    }
    ```
  </Step>

  <Step title="Add Environment Configuration">
    Set up your environment variables for both Rain and Crossmint APIs.

    ```bash .env theme={null}
    # Crossmint Configuration
    NEXT_PUBLIC_CROSSMINT_API_KEY=your_crossmint_api_key
    NEXT_PUBLIC_CHAIN=base-sepolia

    # Rain Configuration
    # Server-side secret for Rain API calls in actions/rain.ts
    RAIN_API_KEY=your_rain_api_key
    ```
  </Step>

  <Step title="Build the Rain Integration Layer">
    Create Next.js server action functions to handle Rain API calls securely on the server side. This keeps your Rain API key secure and provides a clean interface for your React components.

    ```typescript actions/rain.ts theme={null}
    "use server";

    const RAIN_API_URL = "https://api-dev.raincards.xyz/v1";

    /**
    * Creates a new Rain user application with KYC data
    * This is the first step - submits user information to Rain for account creation
    * Using "approved" as lastName will skip KYC verification in sandbox mode
    */
    export async function createRainUserApplication(params: {
      firstName: string;
      lastName: string;
      email: string;
      walletAddress: string;
      // ... other required fields
    }) {
      const response = await fetch(`${RAIN_API_URL}/issuing/applications/user`, {
        method: "POST",
        headers: {
          "Api-Key": process.env.RAIN_API_KEY!, // This variable should be defined in your .env file
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          ...params,
          // Demo data for quick testing
          birthDate: "1990-01-01",
          nationalId: "123456789",
          countryOfIssue: "US",
          address: {
            line1: "123 Test Street",
            city: "San Francisco",
            region: "CA",
            postalCode: "94105",
            countryCode: "US",
          },
          ipAddress: "127.0.0.1",
          phoneCountryCode: "1",
          phoneNumber: "5551234567",
          annualSalary: "75000",
          accountPurpose: "personal",
          expectedMonthlyVolume: "2000",
          isTermsOfServiceAccepted: true,
        }),
      });

      if (!response.ok) {
        const error = await response.json();
        throw new Error(`Rain application failed: ${error.message}`);
      }

      const result = await response.json();
      return { userId: result.id, status: result.applicationStatus };
    }

    /**
    * Creates a smart contract for the approved Rain user
    * Rain manages the smart contract deployment and operations for collateral handling
    * This contract will hold the user's crypto collateral (RUSD tokens)
    */
    export async function createRainUserContract(userId: string, chainId: number) {
      await fetch(`${RAIN_API_URL}/issuing/users/${userId}/contracts`, {
        method: "POST",
        headers: {
          "Api-Key": process.env.RAIN_API_KEY!,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ chainId }),
      });
    }

    /**
    * Issues a virtual Visa credit card for the Rain user
    * The card will be linked to their smart contract for collateral-backed spending
    * Card starts active and ready to be funded with crypto collateral
    */
    export async function issueRainCard(userId: string, displayName: string) {
      const response = await fetch(
        `${RAIN_API_URL}/issuing/users/${userId}/cards`,
        {
          method: "POST",
          headers: {
            "Api-Key": process.env.RAIN_API_KEY!,
            "Content-Type": "application/json",
          },
          body: JSON.stringify({
            type: "virtual",
            limit: { frequency: "allTime", amount: 1000 },
            displayName,
            status: "active",
          }),
        }
      );

      return await response.json();
    }

    /**
    * Gets user's existing Rain cards
    * Returns array of cards with basic info like status and last four digits
    */
    export async function getRainUserCards(userId: string) {
      const response = await fetch(
        `${RAIN_API_URL}/issuing/cards?userId=${userId}&limit=20`,
        {
          headers: { "Api-Key": process.env.RAIN_API_KEY! },
        }
      );
      return await response.json();
    }

    /**
    * Gets Rain user smart contracts with retry logic
    * Returns Base Sepolia contract with RUSD token info
    */
    export async function getRainUserContracts(userId: string) {
      const BASE_SEPOLIA_CHAIN_ID = 84532;
      const RUSD_CONTRACT_BASE_SEPOLIA =
        "0x10b5Be494C2962A7B318aFB63f0Ee30b959D000b";

      // Simple retry logic - try up to 3 times
      for (let attempt = 0; attempt < 3; attempt++) {
        try {
          const response = await fetch(
            `${RAIN_API_URL}/issuing/users/${userId}/contracts`,
            {
              headers: { "Api-Key": process.env.RAIN_API_KEY! },
            }
          );

          const contracts = await response.json();
          const baseContract = contracts.find(
            (c: { chainId: number }) => c.chainId === BASE_SEPOLIA_CHAIN_ID
          );

          if (baseContract) {
            const rusdToken = baseContract.tokens.find(
              (t: { address: string }) => t.address === RUSD_CONTRACT_BASE_SEPOLIA
            );
            return {
              contractId: baseContract.id,
              depositAddress: baseContract.depositAddress,
              tokens: baseContract.tokens,
              rusdBalance: rusdToken?.balance || "0.0",
            };
          }

          // Wait 2 seconds before retry if no contract found
          if (attempt < 2)
            await new Promise((resolve) => setTimeout(resolve, 2000));
        } catch (error) {
          if (attempt === 2) throw error;
          await new Promise((resolve) => setTimeout(resolve, 2000));
        }
      }
      throw new Error("No Base Sepolia contract found after retries");
    }

    /**
    * Gets user's credit balances and spending power
    * Returns simplified balance info in dollars (converted from cents)
    */
    export async function getRainUserCreditBalances(userId: string) {
      const response = await fetch(
        `${RAIN_API_URL}/issuing/users/${userId}/balances`,
        {
          headers: { "Api-Key": process.env.RAIN_API_KEY! },
        }
      );

      const data = await response.json();
      return {
        creditLimit: data.creditLimit / 100,
        spendingPower: data.spendingPower / 100,
        balanceDue: data.balanceDue / 100,
      };
    }

    /**
    * Gets Rain user status by checking application status
    * Returns basic user info and approval status
    */
    export async function getRainUserStatus(userId: string) {
      const response = await fetch(
        `${RAIN_API_URL}/issuing/applications/user/${userId}`,
        {
          headers: { "Api-Key": process.env.RAIN_API_KEY! },
        }
      );

      const result = await response.json();
      return {
        userId: result.id,
        applicationStatus: result.applicationStatus,
        email: result.email,
        isActive: result.isActive,
      };
    }

    /**
    * Finds Rain user by wallet address
    * Returns array of users (should be 0 or 1 for unique wallets)
    */
    export async function getRainUserByWalletAddress(walletAddress: string) {
      const response = await fetch(`${RAIN_API_URL}/issuing/users?limit=100`, {
        headers: { "Api-Key": process.env.RAIN_API_KEY! },
      });

      const users = await response.json();
      return users.filter(
        (user: { walletAddress: string }) => user.walletAddress === walletAddress
      );
    }
    ```
  </Step>

  <Step title="Create the Main Integration Component">
    Build a React component that handles both authentication and the Rain integration flow in one place.

    ```tsx components/rain-integration.tsx theme={null}
    "use client";

    import { useState, useEffect } from "react";
    import {
      useCrossmintAuth,
      useWallet,
      EVMWallet,
    } from "@crossmint/client-sdk-react-ui";
    import { encodeFunctionData } from "viem";
    import {
      createRainUserApplication,
      createRainUserContract,
      issueRainCard,
      getRainUserByWalletAddress,
      getRainUserContracts,
      getRainUserCards,
      getRainUserCreditBalances,
      getRainUserStatus,
    } from "../actions/rain";

    const RUSD_CONTRACT_BASE_SEPOLIA =
      "0x10b5Be494C2962A7B318aFB63f0Ee30b959D000b";

    export function RainIntegration() {
      const { wallet } = useWallet();
      const { user, login, logout } = useCrossmintAuth();
      const [step, setStep] = useState<"signup" | "contract" | "card" | "funded">(
        "signup"
      );
      const [rainUserId, setRainUserId] = useState("");
      const [contractAddress, setContractAddress] = useState("");
      const [contractData, setContractData] = useState<{
        contractId: string;
        depositAddress: string;
        tokens: Array<{ address: string; balance: string }>;
        rusdBalance: string;
      } | null>(null);
      const [cardData, setCardData] = useState<{
        id: string;
        type: string;
        status: string;
        last4: string;
        expirationMonth: string;
        expirationYear: string;
        limit: {
          amount: number;
          frequency: string;
        };
      } | null>(null);
      const [loading, setLoading] = useState(false);
      const [initialLoading, setInitialLoading] = useState(true);
      const [creditBalances, setCreditBalances] = useState<{
        creditLimit: number;
        spendingPower: number;
        balanceDue: number;
      } | null>(null);
      const [isRefreshingBalances, setIsRefreshingBalances] = useState(false);

      // Comprehensive state determination on wallet connection
      useEffect(() => {
        const determineCurrentState = async () => {
          if (!wallet?.address || !user?.email) {
            setInitialLoading(false);
            return;
          }
          setInitialLoading(true);
          try {
            // Step 1: Check if user exists
            const existingUsers =
              await getRainUserByWalletAddress(wallet.address);
            if (existingUsers.length === 0) {
              // No user exists - start from signup
              setStep("signup");
              return;
            }
            // User exists - get their details
            const rainUser = existingUsers[0];
            setRainUserId(rainUser.id);
            // Step 2: Check user status
            const userStatus = await getRainUserStatus(rainUser.id);
            if (userStatus.applicationStatus !== "approved") {
              setStep("signup");
              return;
            }
            // Step 3: Check for contracts
            try {
              const contractInfo = await getRainUserContracts(rainUser.id);
              setContractAddress(contractInfo.depositAddress);
              setContractData(contractInfo);

              // Step 4: Check for cards
              try {
                const cards = await getRainUserCards(rainUser.id);
                if (cards.length > 0) {
                  // User has cards - check if funded
                  const card = cards[0];
                  setCardData({
                    id: card.id,
                    type: card.type,
                    status: card.status,
                    last4: card.last4,
                    expirationMonth: card.expirationMonth,
                    expirationYear: card.expirationYear,
                    limit: card.limit,
                  });
                  // Get credit balances to determine if funded
                  const balances =
                    await getRainUserCreditBalances(rainUser.id);
                  setCreditBalances(balances);
                  // If there's spending power, consider it funded
                  if (balances.spendingPower > 0) {
                    setStep("funded");
                  } else {
                    setStep("card");
                  }
                } else {
                  // Contract exists but no card
                  setStep("contract");
                }
              } catch {
                // Error getting cards - assume no cards exist
                setStep("contract");
              }
            } catch {
              // No contract exists - need to create one
              setStep("contract");
            }
          } catch (error) {
            console.error("Error determining state:", error);
            setStep("signup"); // Default to signup on error
          } finally {
            setInitialLoading(false);
          }
        };
        determineCurrentState();
      }, [wallet?.address, user?.email]);

      const handleSignup = async () => {
        if (!wallet || !user?.email) return;
        setLoading(true);
        try {
          const result = await createRainUserApplication({
            firstName: user.email,
            lastName: "approved", // Skip KYC for demo
            email: user.email,
            walletAddress: wallet.address,
          });
          setRainUserId(result.userId);
          // Move to contract step - don't auto-create contract here
          // Let the user manually trigger contract creation
          setStep("contract");
        } catch (error) {
          console.error("Signup failed:", error);
          alert("Signup failed: " + error);
        } finally {
          setLoading(false);
        }
      };

      const handleCreateContract = async () => {
        if (!rainUserId) return;
        setLoading(true);
        try {
          // Create the contract
          await createRainUserContract(rainUserId, 84532);
          // Wait a bit for contract to be created
          await new Promise((resolve) => setTimeout(resolve, 3000));
          // Try to get contract info with retry logic
          let contractInfo;
          let attempts = 0;
          const maxAttempts = 5;
          while (attempts < maxAttempts) {
            try {
              contractInfo = await getRainUserContracts(rainUserId);
              if (contractInfo?.depositAddress) {
                break;
              }
            } catch {
              console.log(`Attempt ${attempts + 1} failed, retrying...`);
            }
            attempts++;
            if (attempts < maxAttempts) {
              await new Promise((resolve) => setTimeout(resolve, 2000));
            }
          }
          if (contractInfo?.depositAddress) {
            setContractAddress(contractInfo.depositAddress);
            setContractData(contractInfo);
            alert("✅ Smart contract created successfully!");
          } else {
            throw new Error(
              "Contract was created but details are not yet available. Please refresh the page."
            );
          }
        } catch (error) {
          console.error("Contract creation failed:", error);
          alert(
            "Contract creation may have succeeded but details are not yet available. Please refresh the page to check."
          );
        } finally {
          setLoading(false);
        }
      };

      const handleIssueCard = async () => {
        if (!rainUserId) return;

        setLoading(true);
        try {
          const card = await issueRainCard(
            rainUserId,
            user?.email || "Demo User"
          );
          setCardData({
            id: card.id,
            type: card.type,
            status: card.status,
            last4: card.last4,
            expirationMonth: card.expirationMonth,
            expirationYear: card.expirationYear,
            limit: card.limit,
          });
          // Fetch initial credit balances after card issuance
          await handleRefreshCreditBalances();
          setStep("card");
        } catch (error) {
          console.error("Card issuance failed:", error);
          alert("Card issuance failed: " + error);
        } finally {
          setLoading(false);
        }
      };

      const handleRefreshCreditBalances = async () => {
        if (!rainUserId) return;
        setIsRefreshingBalances(true);
        try {
          const balances = await getRainUserCreditBalances(rainUserId);
          setCreditBalances(balances);
        } catch (error) {
          console.error("Failed to refresh credit balances:", error);
        } finally {
          setIsRefreshingBalances(false);
        }
      };

      const handleFundCard = async () => {
        if (!wallet || !contractAddress) return;
        setLoading(true);
        try {
          const evmWallet = EVMWallet.from(wallet);
          // Mint RUSD tokens
          const mintData = encodeFunctionData({
            abi: [
              {
                name: "mint",
                type: "function",
                inputs: [{ name: "_amountDollars_Max100", type: "uint256" }],
                outputs: [],
              },
            ],
            functionName: "mint",
            args: [BigInt(10)], // Mint $10 RUSD
          });
          await evmWallet.sendTransaction({
            to: RUSD_CONTRACT_BASE_SEPOLIA,
            data: mintData,
            value: BigInt(0),
            chain: "base-sepolia", // Using Base Sepolia - see Rain docs for other supported chains
          });
          // Send RUSD to contract
          await wallet.send(contractAddress, RUSD_CONTRACT_BASE_SEPOLIA, "10");
          // Refresh credit balances after funding
          await handleRefreshCreditBalances();
          setStep("funded");
        } catch (error) {
          console.error("Funding failed:", error);
        } finally {
          setLoading(false);
        }
      };

      // Show login screen if user is not authenticated
      if (!user) {
        return (
          <div className="max-w-md mx-auto p-6 bg-white rounded-lg shadow text-center">
            <h2 className="text-2xl font-bold mb-4">Rain Card Demo</h2>
            <p className="text-gray-600 mb-6">
              Sign in to create your account and get started with crypto-backed
              credit cards
            </p>
            <button
              onClick={login}
              className="bg-blue-600 text-white py-2 px-6 rounded-lg hover:bg-blue-700 transition-colors"
            >
              Login to Get Started
            </button>
          </div>
        );
      }

      // Show loading screen while determining current state
      if (initialLoading) {
        return (
          <div className="max-w-md mx-auto p-6 bg-white rounded-lg shadow text-center">
            <h2 className="text-2xl font-bold mb-4">Rain Card Demo</h2>
            <div className="flex items-center justify-center py-8">
              <div className="w-8 h-8 border-4 border-blue-600 border-t-transparent rounded-full animate-spin" />
              <p className="text-gray-600 ml-3">
                Checking your Rain account status...
              </p>
            </div>
          </div>
        );
      }

      return (
        <div className="max-w-md mx-auto p-6 bg-white rounded-lg shadow">
          {/* Header with user info and logout */}
          <div className="flex justify-between items-center mb-6">
            <h2 className="text-xl font-bold">Rain Card Demo</h2>
            <div className="flex items-center gap-3">
              {wallet && (
                <span className="text-xs text-gray-500">
                  {wallet.address.slice(0, 6)}...{wallet.address.slice(-4)}
                </span>
              )}
              <button
                onClick={logout}
                className="text-sm text-gray-600 hover:text-gray-800 transition-colors"
              >
                Logout
              </button>
            </div>
          </div>
          {/* Card Data Display - Show whenever card data exists */}
          {cardData?.last4 && (
            <div className="mb-6">
              {/* Credit Card Visual */}
              <div className="relative w-full max-w-sm mx-auto aspect-[1.586/1] bg-gray-900 rounded-lg shadow-2xl overflow-hidden">
                {/* Card Background Pattern */}
                <div className="absolute inset-0 opacity-10">
                  <div className="absolute top-4 right-4 w-12 h-12 border-2 border-white rounded-full"></div>
                  <div className="absolute top-4 right-20 w-8 h-8 border-2 border-white rounded-full"></div>
                </div>
                {/* Card Content */}
                <div className="relative h-full p-6 flex flex-col justify-between text-white">
                  {/* Top Section */}
                  <div className="flex justify-between items-start">
                    <div>
                      <div className="text-xs opacity-70 mb-1">VIRTUAL CARD</div>
                      <div className="text-sm font-semibold">Rain Card</div>
                    </div>
                    <div
                      className={`px-2 py-1 rounded text-xs font-medium ${
                        cardData.status === "active"
                          ? "bg-green-500 text-white"
                          : "bg-yellow-500 text-black"
                      }`}
                    >
                      {cardData.status.toUpperCase()}
                    </div>
                  </div>
                  {/* Card Number */}
                  <div className="my-4">
                    <div className="font-mono text-lg tracking-wider">
                      •••• •••• •••• {cardData.last4}
                    </div>
                  </div>
                  {/* Bottom Section */}
                  <div className="flex justify-between items-end">
                    <div>
                      {cardData.expirationMonth && cardData.expirationYear && (
                        <div>
                          <div className="text-xs opacity-70">VALID THRU</div>
                          <div className="font-mono text-sm">
                            {cardData.expirationMonth}/
                            {cardData.expirationYear.slice(-2)}
                          </div>
                        </div>
                      )}
                    </div>
                    <div className="text-right">
                      <div className="text-xs opacity-70">SPENDING POWER</div>
                      <div className="text-sm font-semibold">
                        ${creditBalances?.spendingPower?.toFixed(0) || "0"}
                      </div>
                    </div>
                  </div>
                </div>
              </div>
              {/* Credit Balance Refresh - Only show when card exists */}
              {creditBalances && (
                <div className="text-center mt-2">
                  <button
                    onClick={handleRefreshCreditBalances}
                    disabled={isRefreshingBalances}
                    className="text-xs px-3 py-1 bg-gray-100 text-gray-700 rounded hover:bg-gray-200 disabled:opacity-50"
                  >
                    {isRefreshingBalances ? "Refreshing..." : "Refresh Balance"}
                  </button>
                </div>
              )}
            </div>
          )}
          {step === "signup" && (
            <div>
              <p className="mb-4">
                Create your Rain account and get approved instantly
              </p>
              <button
                onClick={handleSignup}
                disabled={loading || !wallet}
                className="w-full bg-blue-600 text-white py-2 px-4 rounded disabled:opacity-50"
              >
                {loading ? "Creating Account..." : "Sign Up for Rain Card"}
              </button>
            </div>
          )}
          {step === "contract" && (
            <div>
              {!contractData ? (
                <div>
                  <p className="mb-4">
                    ✅ Account approved! Ready to create your smart contract.
                  </p>
                  <button
                    onClick={handleCreateContract}
                    disabled={loading}
                    className="w-full bg-blue-600 text-white py-2 px-4 rounded disabled:opacity-50 mb-4"
                  >
                    {loading
                      ? "Creating Smart Contract..."
                      : "Create Smart Contract"}
                  </button>
                </div>
              ) : (
                <div>
                  <p className="mb-4">
                    🏗️ Smart contract created! Ready to issue your card.
                  </p>
                  <button
                    onClick={handleIssueCard}
                    disabled={loading}
                    className="w-full bg-green-600 text-white py-2 px-4 rounded disabled:opacity-50"
                  >
                    {loading ? "Issuing Card..." : "Issue Virtual Card"}
                  </button>
                </div>
              )}
            </div>
          )}
          {step === "card" && (
            <div>
              <p className="mb-4">🎉 Card issued! Fund it to start spending.</p>

              <button
                onClick={handleFundCard}
                disabled={loading}
                className="w-full bg-purple-600 text-white py-2 px-4 rounded disabled:opacity-50"
              >
                {loading ? "Funding..." : "Fund Card ($10 RUSD)"}
              </button>
            </div>
          )}
          {step === "funded" && (
            <div className="text-center">
              <p className="text-green-600 font-bold mb-2">🎉 Card Ready!</p>
              <p className="text-sm text-gray-600">
                Your card is funded and ready to use for purchases. Balance may take
                a moment to update.
              </p>
            </div>
          )}
        </div>
      );
    }
    ```
  </Step>

  <Step title="Wire Everything Together">
    Update your main page component to use the `RainIntegration` component directly.

    ```tsx app/page.tsx theme={null}
    import { RainIntegration } from "./components/rain-integration";

    export default function HomePage() {
      return (
        <div className="min-h-screen bg-gray-50 py-8">
          <RainIntegration />
        </div>
      );
    }
    ```
  </Step>
</Steps>

## Next Steps

<CardGroup>
  <Card title="Learn Token Transfers" icon="credit-card" href="https://docs.crossmint.com/wallets/guides/transfer-tokens">
    Send tokens between wallets and external addresses
  </Card>

  <Card title="Bring Your Own Auth" icon="key" href="https://docs.crossmint.com/wallets/guides/bring-your-own-auth#bring-your-own-auth">
    Use your own authentication system with Crossmint
  </Card>

  <Card title="Staging vs Production" icon="shield-check" href="https://docs.crossmint.com/introduction/platform/staging-vs-production">
    Learn about staging and production environments
  </Card>
</CardGroup>

## Need Help?

<Card title="Contact Sales" icon="comment" href="https://www.crossmint.com/contact/sales">
  Contact our team if you're interested in planning your integration.
</Card>

## Resources

* [Rain API Documentation](https://api-dev.raincards.xyz/v1)
* [Crossmint Wallet SDK](https://docs.crossmint.com/wallets)
* [Demo Repository](https://github.com/Crossmint/rain-wallets-demo)
* [Base Sepolia Explorer](https://sepolia.basescan.org/)


# Morpho
Source: https://docs.crossmint.com/wallets/guides/wallet-extensions/morpho

Supply USDC to Morpho Vaults and enable yield for your users

This guide explains how to supply tokens to <a href="https://docs.morpho.org">Morpho</a> Vaults and earn yield using Crossmint wallets. Morpho is a decentralized lending protocol deployed across multiple EVM chains, offering ERC-4626 compliant vaults that optimize yield across lending markets.

## Prerequisites

To use Morpho Vaults with Crossmint wallets, you need:

* A Crossmint [wallet](/wallets/guides/create-wallet) on Base
* A **production** **API Key** with the scope: `wallets:transactions.create` (create in the <a href="https://www.crossmint.com/console">Production Console</a>)

This guide uses USDC on Base mainnet as an example. To follow along, you will also need:

* USDC on Base mainnet in the wallet
* ETH on Base for gas fees (not required if [gas sponsorship](/wallets/guides/gas-sponsorship) is enabled)

You can adapt the code to supply other tokens or use vaults on other chains where Morpho is deployed (Ethereum, Arbitrum, Polygon, and others).

## Discover Vaults

Morpho exposes a public <a href="https://api.morpho.org/graphql">GraphQL API</a> for discovering available vaults, their APYs, and total deposits. No API key is required.

```typescript theme={null}
const MORPHO_API = "https://api.morpho.org/graphql";

const query = `{
  vaultV2s(
    first: 10,
    where: { chainId_in: [8453], assetAddress_in: ["0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"] },
    orderBy: TotalAssetsUsd,
    orderDirection: Desc
  ) {
    items {
      address
      name
      avgNetApy
      totalAssetsUsd
    }
  }
}`;

const response = await fetch(MORPHO_API, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ query }),
});
const data = await response.json();
const vaults = data.data.vaultV2s.items;
```

## Supply Tokens

High-level steps to supply tokens to a Morpho Vault:

1. Query the Morpho API to select a vault
2. Approve the vault contract to spend your tokens (ERC-20 `approve`)
3. Deposit tokens into the vault (ERC-4626 `deposit`)

<Warning>
  Morpho Vaults operate on mainnet only. The wallet must hold sufficient tokens on the target chain and ETH for gas fees.
</Warning>

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet, EVMWallet } from "@crossmint/client-sdk-react-ui";
    import { encodeFunctionData, erc20Abi, parseUnits } from "viem";

    const USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
    const USDC_DECIMALS = 6;
    const VAULT_ADDRESS = "0xbeef0e0834849aCC03f0089F01f4F1Eeb06873C9"; // Steakhouse USDC on Base

    const vaultAbi = [
        {
            name: "deposit",
            type: "function",
            inputs: [
                { name: "assets", type: "uint256" },
                { name: "receiver", type: "address" },
            ],
            outputs: [{ name: "shares", type: "uint256" }],
            stateMutability: "nonpayable",
        },
    ] as const;

    export function SupplyComponent() {
        const { wallet } = useWallet();

        async function supply(amount: string) {
            if (!wallet) return;
            const evmWallet = EVMWallet.from(wallet);
            const depositAmount = parseUnits(amount, USDC_DECIMALS);

            // 1. Approve the vault to spend USDC
            await evmWallet.sendTransaction({
                to: USDC_ADDRESS,
                data: encodeFunctionData({
                    abi: erc20Abi,
                    functionName: "approve",
                    args: [VAULT_ADDRESS, depositAmount],
                }),
            });

            // 2. Deposit USDC into the Morpho vault
            const tx = await evmWallet.sendTransaction({
                to: VAULT_ADDRESS,
                data: encodeFunctionData({
                    abi: vaultAbi,
                    functionName: "deposit",
                    args: [depositAmount, wallet.address as `0x${string}`],
                }),
            });

            console.log("Supply complete!", tx.hash);
        }

        return (
            <button onClick={() => supply("10")}>Supply 10 USDC</button>
        );
    }
    ```

    See the [React SDK reference](/sdk-reference/wallets/react/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { CrossmintWallets, createCrossmint, EVMWallet } from "@crossmint/wallets-sdk";
    import { encodeFunctionData, erc20Abi, parseUnits } from "viem";

    const crossmint = createCrossmint({
        apiKey: "YOUR_SERVER_API_KEY",
    });
    const crossmintWallets = CrossmintWallets.from(crossmint);

    const wallet = await crossmintWallets.getWallet(
        "email:user@example.com",
        { chain: "base" }
    );
    if (!wallet) throw new Error("Wallet not found");
    await wallet.useSigner({ type: "email", email: "user@example.com" });
    const evmWallet = EVMWallet.from(wallet);

    const USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
    const USDC_DECIMALS = 6;
    const VAULT_ADDRESS = "0xbeef0e0834849aCC03f0089F01f4F1Eeb06873C9"; // Steakhouse USDC on Base
    const amount = "10";

    const vaultAbi = [
        {
            name: "deposit",
            type: "function",
            inputs: [
                { name: "assets", type: "uint256" },
                { name: "receiver", type: "address" },
            ],
            outputs: [{ name: "shares", type: "uint256" }],
            stateMutability: "nonpayable",
        },
    ] as const;

    const depositAmount = parseUnits(amount, USDC_DECIMALS);

    // 1. Approve the vault to spend USDC
    await evmWallet.sendTransaction({
        to: USDC_ADDRESS,
        data: encodeFunctionData({
            abi: erc20Abi,
            functionName: "approve",
            args: [VAULT_ADDRESS, depositAmount],
        }),
    });

    // 2. Deposit USDC into the Morpho vault
    const tx = await evmWallet.sendTransaction({
        to: VAULT_ADDRESS,
        data: encodeFunctionData({
            abi: vaultAbi,
            functionName: "deposit",
            args: [depositAmount, wallet.address as `0x${string}`],
        }),
    });

    console.log("Supply complete!", tx.hash);
    ```
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { useWallet, EVMWallet } from "@crossmint/client-sdk-react-native-ui";
    import { View, Button } from "react-native";
    import { encodeFunctionData, erc20Abi, parseUnits } from "viem";

    const USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
    const USDC_DECIMALS = 6;
    const VAULT_ADDRESS = "0xbeef0e0834849aCC03f0089F01f4F1Eeb06873C9"; // Steakhouse USDC on Base

    const vaultAbi = [
        {
            name: "deposit",
            type: "function",
            inputs: [
                { name: "assets", type: "uint256" },
                { name: "receiver", type: "address" },
            ],
            outputs: [{ name: "shares", type: "uint256" }],
            stateMutability: "nonpayable",
        },
    ] as const;

    export function SupplyComponent() {
        const { wallet } = useWallet();

        async function supply(amount: string) {
            if (!wallet) return;
            const evmWallet = EVMWallet.from(wallet);
            const depositAmount = parseUnits(amount, USDC_DECIMALS);

            // 1. Approve the vault to spend USDC
            await evmWallet.sendTransaction({
                to: USDC_ADDRESS,
                data: encodeFunctionData({
                    abi: erc20Abi,
                    functionName: "approve",
                    args: [VAULT_ADDRESS, depositAmount],
                }),
            });

            // 2. Deposit USDC into the Morpho vault
            const tx = await evmWallet.sendTransaction({
                to: VAULT_ADDRESS,
                data: encodeFunctionData({
                    abi: vaultAbi,
                    functionName: "deposit",
                    args: [depositAmount, wallet.address as `0x${string}`],
                }),
            });

            console.log("Supply complete!", tx.hash);
        }

        return (
            <View>
                <Button title="Supply 10 USDC" onPress={() => supply("10")} />
            </View>
        );
    }
    ```

    See the [React Native SDK reference](/sdk-reference/wallets/react-native/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    import CrossmintClient
    import Wallet
    import Foundation

    CrossmintSDK.configure(apiKey: "<YOUR_API_KEY>")
    let sdk = CrossmintSDK.shared

    let wallet: Wallet
    if let existing = try await sdk.crossmintWallets.getWallet(chain: EVMChain.base) {
        wallet = existing
    } else {
        wallet = try await sdk.crossmintWallets.createWallet(
            chain: EVMChain.base,
            recoveryMethods: [EVMSigners.email("user@example.com")]
        )
    }

    let evmWallet = try EVMWallet.from(wallet: wallet)

    let usdcAddress = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
    let vaultAddress = "0xbeef0e0834849aCC03f0089F01f4F1Eeb06873C9"
    let amount = "10000000" // 10 USDC (6 decimals)

    // 1. Approve the vault to spend USDC
    //    Encodes ERC-20 approve(address,uint256) — selector 0x095ea7b3
    func leftPad(_ str: String, toLength len: Int) -> String {
        String(repeating: "0", count: max(0, len - str.count)) + str
    }

    let addr = leftPad(String(vaultAddress.dropFirst(2)), toLength: 64)
    let amt = leftPad(String(UInt64(amount)!, radix: 16), toLength: 64)
    let approveData = "0x095ea7b3" + addr + amt
    let _ = try await evmWallet.sendTransaction(
        to: usdcAddress,
        value: "0",
        data: approveData
    )

    // 2. Deposit USDC into the Morpho vault
    //    Encodes ERC-4626 deposit(uint256,address) — selector 0x6e553f65
    let walletAddr = leftPad(String(wallet.address.dropFirst(2)), toLength: 64)
    let depositData = "0x6e553f65" + amt + walletAddr
    let result = try await evmWallet.sendTransaction(
        to: vaultAddress,
        value: "0",
        data: depositData
    )
    ```

    See the [Swift SDK reference](/sdk-reference/wallets/swift/classes/evmwallet) for more details.
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    import com.crossmint.kotlin.compose.LocalCrossmintSDK
    import com.crossmint.kotlin.types.EVMChain
    import com.crossmint.kotlin.signers.SignerType
    import com.crossmint.kotlin.types.Result
    import com.crossmint.kotlin.types.WalletError
    import com.crossmint.kotlin.types.getOrThrow
    import kotlinx.coroutines.Dispatchers
    import kotlinx.coroutines.runBlocking
    import kotlinx.coroutines.withContext
    import kotlinx.serialization.json.Json
    import kotlinx.serialization.json.buildJsonObject
    import kotlinx.serialization.json.jsonObject
    import kotlinx.serialization.json.jsonPrimitive
    import kotlinx.serialization.json.put
    import kotlinx.serialization.json.putJsonArray
    import kotlinx.serialization.json.putJsonObject
    import java.net.HttpURLConnection
    import java.net.URL

    val API_KEY = "YOUR_API_KEY"
    val SIGNER_EMAIL = "user@example.com"
    val CROSSMINT_API = "https://www.crossmint.com/api/2025-06-09"
    val USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
    val VAULT_ADDRESS = "0xbeef0e0834849aCC03f0089F01f4F1Eeb06873C9"
    val AMOUNT = "10000000" // 10 USDC (6 decimals)

    // Access the SDK — must be called inside a CrossmintSDKProvider composable
    val sdk = LocalCrossmintSDK.current
    val wallet = when (val result = sdk.wallets.getWallet(chain = EVMChain.Base)) {
        is Result.Success -> result.value
        is Result.Failure -> if (result.error is WalletError.WalletNotFound) {
            sdk.wallets.createWallet(chain = EVMChain.Base, recoveryMethods = listOf(SignerType.Email(SIGNER_EMAIL))).getOrThrow()
        } else {
            throw Exception(result.error.toString())
        }
    }

    val json = Json { ignoreUnknownKeys = true }

    suspend fun sendEvmTransaction(to: String, data: String, value: String = "0"): String {
        val body = buildJsonObject {
            putJsonObject("params") {
                put("chain", "base")
                put("signer", "email:$SIGNER_EMAIL")
                putJsonArray("calls") {
                    add(buildJsonObject {
                        put("to", to)
                        put("value", value)
                        put("data", data)
                    })
                }
            }
        }.toString()
        val responseText = withContext(Dispatchers.IO) {
            val conn = URL("$CROSSMINT_API/wallets/${wallet.address}/transactions")
                .openConnection() as HttpURLConnection
            conn.requestMethod = "POST"
            conn.setRequestProperty("X-API-KEY", API_KEY)
            conn.setRequestProperty("Content-Type", "application/json")
            conn.doOutput = true
            conn.outputStream.write(body.toByteArray())
            val code = conn.responseCode
            if (code !in 200..299) {
                val err = conn.errorStream?.bufferedReader()?.readText()
                error("Transaction request failed ($code): $err")
            }
            conn.inputStream.bufferedReader().readText()
        }
        val transactionId = json.parseToJsonElement(responseText)
            .jsonObject["id"]!!.jsonPrimitive.content
        val tx = wallet.approve(transactionId).getOrThrow()
        return tx.onChain.txId ?: tx.onChain.userOperationHash
            ?: error("Transaction completed but no hash was returned")
    }

    // 1. Approve the vault to spend USDC
    //    Encodes ERC-20 approve(address,uint256) — selector 0x095ea7b3
    val addr = VAULT_ADDRESS.removePrefix("0x").padStart(64, '0')
    val amt = AMOUNT.toLong().toString(16).padStart(64, '0')

    // 2. Deposit USDC into the Morpho vault
    //    Encodes ERC-4626 deposit(uint256,address) — selector 0x6e553f65
    val walletAddr = wallet.address.removePrefix("0x").padStart(64, '0')

    runBlocking {
        sendEvmTransaction(to = USDC_ADDRESS, data = "0x095ea7b3$addr$amt")
        val txHash = sendEvmTransaction(to = VAULT_ADDRESS, data = "0x6e553f65$amt$walletAddr")
        println("Supply complete! $txHash")
    }
    ```

    See the [Kotlin SDK reference](/sdk-reference/wallets/kotlin/classes/wallet) for more details.
  </Tab>

  <Tab title="REST">
    Transactions must be approved by one of the wallet's [signers](/wallets/concepts/signers).
    The SDK handles this automatically, but with the REST API you must [approve the transaction](/api-reference/wallets/approve-transaction) to complete it.

    <Steps>
      <Step title="Create the ERC-20 approve transaction">
        Send an ERC-20 `approve` transaction to allow the Morpho vault to pull tokens.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://www.crossmint.com/api/2025-06-09/wallets/WALLET_ADDRESS/transactions \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: YOUR_API_KEY' \
              --data '{
                  "params": {
                      "chain": "base",
                      "signer": "email:USER_EMAIL",
                      "calls": [{
                          "to": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                          "value": "0",
                          "data": "0x095ea7b3000000000000000000000000beef0e0834849acc03f0089f01f4f1eeb06873c90000000000000000000000000000000000000000000000000000000000989680"
                      }]
                  }
              }'
          ```

          ```js Node.js theme={null}
          const walletAddress = "YOUR_WALLET_ADDRESS";

          const response = await fetch(
              `https://www.crossmint.com/api/2025-06-09/wallets/${walletAddress}/transactions`,
              {
                  method: "POST",
                  headers: {
                      "Content-Type": "application/json",
                      "X-API-KEY": "YOUR_API_KEY",
                  },
                  body: JSON.stringify({
                      params: {
                          chain: "base",
                          signer: "email:user@example.com",
                          calls: [{
                              to: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                              value: "0",
                              data: "0x095ea7b3000000000000000000000000beef0e0834849acc03f0089f01f4f1eeb06873c90000000000000000000000000000000000000000000000000000000000989680",
                          }],
                      },
                  }),
              }
          );
          const { id } = await response.json();
          ```

          ```python Python theme={null}
          import requests

          wallet_address = "YOUR_WALLET_ADDRESS"

          response = requests.post(
              f"https://www.crossmint.com/api/2025-06-09/wallets/{wallet_address}/transactions",
              headers={
                  "Content-Type": "application/json",
                  "X-API-KEY": "YOUR_API_KEY",
              },
              json={
                  "params": {
                      "chain": "base",
                      "signer": "email:user@example.com",
                      "calls": [{
                          "to": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                          "value": "0",
                          "data": "0x095ea7b3000000000000000000000000beef0e0834849acc03f0089f01f4f1eeb06873c90000000000000000000000000000000000000000000000000000000000989680",
                      }],
                  },
              },
          )
          transaction_id = response.json()["id"]
          ```
        </CodeGroup>
      </Step>

      <Step title="Approve the transaction">
        Use the transaction ID from the previous step to [approve the transaction](/api-reference/wallets/approve-transaction) so it settles on-chain.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://www.crossmint.com/api/2025-06-09/wallets/WALLET_ADDRESS/transactions/TRANSACTION_ID/approve \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: YOUR_API_KEY'
          ```

          ```js Node.js theme={null}
          await fetch(
              `https://www.crossmint.com/api/2025-06-09/wallets/${walletAddress}/transactions/${id}/approve`,
              {
                  method: "POST",
                  headers: {
                      "Content-Type": "application/json",
                      "X-API-KEY": "YOUR_API_KEY",
                  },
              }
          );
          ```

          ```python Python theme={null}
          requests.post(
              f"https://www.crossmint.com/api/2025-06-09/wallets/{wallet_address}/transactions/{transaction_id}/approve",
              headers={
                  "Content-Type": "application/json",
                  "X-API-KEY": "YOUR_API_KEY",
              },
          )
          ```
        </CodeGroup>
      </Step>

      <Step title="Create the deposit transaction">
        Send an ERC-4626 `deposit` transaction to the Morpho vault. The `data` field encodes `deposit(uint256 assets, address receiver)` where:

        * `0x6e553f65` is the function selector
        * Next 32 bytes: the deposit amount (10 USDC = `0x989680`)
        * Last 32 bytes: the receiver wallet address, zero-padded to 32 bytes

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://www.crossmint.com/api/2025-06-09/wallets/WALLET_ADDRESS/transactions \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: YOUR_API_KEY' \
              --data '{
                  "params": {
                      "chain": "base",
                      "signer": "email:USER_EMAIL",
                      "calls": [{
                          "to": "0xbeef0e0834849aCC03f0089F01f4F1Eeb06873C9",
                          "value": "0",
                          "data": "0x6e553f6500000000000000000000000000000000000000000000000000000000009896800000000000000000000000001234567890abcdef1234567890abcdef12345678"
                      }]
                  }
              }'
          ```

          ```js Node.js theme={null}
          const walletAddress = "YOUR_WALLET_ADDRESS";

          const depositResponse = await fetch(
              `https://www.crossmint.com/api/2025-06-09/wallets/${walletAddress}/transactions`,
              {
                  method: "POST",
                  headers: {
                      "Content-Type": "application/json",
                      "X-API-KEY": "YOUR_API_KEY",
                  },
                  body: JSON.stringify({
                      params: {
                          chain: "base",
                          signer: "email:user@example.com",
                          calls: [{
                              to: "0xbeef0e0834849aCC03f0089F01f4F1Eeb06873C9",
                              value: "0",
                              data: `0x6e553f650000000000000000000000000000000000000000000000000000000000989680${walletAddress.slice(2).padStart(64, "0")}`,
                          }],
                      },
                  }),
              }
          );
          const { id: depositId } = await depositResponse.json();
          ```

          ```python Python theme={null}
          wallet_address = "YOUR_WALLET_ADDRESS"

          deposit_response = requests.post(
              f"https://www.crossmint.com/api/2025-06-09/wallets/{wallet_address}/transactions",
              headers={
                  "Content-Type": "application/json",
                  "X-API-KEY": "YOUR_API_KEY",
              },
              json={
                  "params": {
                      "chain": "base",
                      "signer": "email:user@example.com",
                      "calls": [{
                          "to": "0xbeef0e0834849aCC03f0089F01f4F1Eeb06873C9",
                          "value": "0",
                          "data": f"0x6e553f650000000000000000000000000000000000000000000000000000000000989680{wallet_address[2:].zfill(64)}",
                      }],
                  },
              },
          )
          deposit_id = deposit_response.json()["id"]
          ```
        </CodeGroup>
      </Step>

      <Step title="Approve the deposit transaction">
        Approve the deposit transaction using the ID returned in the previous step.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://www.crossmint.com/api/2025-06-09/wallets/WALLET_ADDRESS/transactions/TRANSACTION_ID/approve \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: YOUR_API_KEY'
          ```

          ```js Node.js theme={null}
          await fetch(
              `https://www.crossmint.com/api/2025-06-09/wallets/${walletAddress}/transactions/${depositId}/approve`,
              {
                  method: "POST",
                  headers: {
                      "Content-Type": "application/json",
                      "X-API-KEY": "YOUR_API_KEY",
                  },
              }
          );
          ```

          ```python Python theme={null}
          requests.post(
              f"https://www.crossmint.com/api/2025-06-09/wallets/{wallet_address}/transactions/{deposit_id}/approve",
              headers={
                  "Content-Type": "application/json",
                  "X-API-KEY": "YOUR_API_KEY",
              },
          )
          ```
        </CodeGroup>
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Withdraw Tokens

To withdraw tokens from a Morpho Vault, call the ERC-4626 `withdraw` function. This redeems your shares and returns the underlying tokens.

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet, EVMWallet } from "@crossmint/client-sdk-react-ui";
    import { encodeFunctionData, parseUnits } from "viem";

    const VAULT_ADDRESS = "0xbeef0e0834849aCC03f0089F01f4F1Eeb06873C9";
    const USDC_DECIMALS = 6;

    const withdrawAbi = [
        {
            name: "withdraw",
            type: "function",
            inputs: [
                { name: "assets", type: "uint256" },
                { name: "receiver", type: "address" },
                { name: "owner", type: "address" },
            ],
            outputs: [{ name: "shares", type: "uint256" }],
            stateMutability: "nonpayable",
        },
    ] as const;

    export function WithdrawComponent() {
        const { wallet } = useWallet();

        async function withdraw(amount: string) {
            if (!wallet) return;
            const evmWallet = EVMWallet.from(wallet);
            const walletAddress = wallet.address as `0x${string}`;

            const tx = await evmWallet.sendTransaction({
                to: VAULT_ADDRESS,
                data: encodeFunctionData({
                    abi: withdrawAbi,
                    functionName: "withdraw",
                    args: [parseUnits(amount, USDC_DECIMALS), walletAddress, walletAddress],
                }),
            });

            console.log("Withdrawal complete!", tx.hash);
        }

        return (
            <button onClick={() => withdraw("10")}>Withdraw 10 USDC</button>
        );
    }
    ```
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { CrossmintWallets, createCrossmint, EVMWallet } from "@crossmint/wallets-sdk";
    import { encodeFunctionData, parseUnits } from "viem";

    const crossmint = createCrossmint({
        apiKey: "YOUR_SERVER_API_KEY",
    });
    const crossmintWallets = CrossmintWallets.from(crossmint);

    const wallet = await crossmintWallets.getWallet(
        "email:user@example.com",
        { chain: "base" }
    );
    if (!wallet) throw new Error("Wallet not found");
    await wallet.useSigner({ type: "email", email: "user@example.com" });
    const evmWallet = EVMWallet.from(wallet);

    const VAULT_ADDRESS = "0xbeef0e0834849aCC03f0089F01f4F1Eeb06873C9";
    const USDC_DECIMALS = 6;
    const amount = "10";
    const walletAddress = wallet.address as `0x${string}`;

    const withdrawAbi = [
        {
            name: "withdraw",
            type: "function",
            inputs: [
                { name: "assets", type: "uint256" },
                { name: "receiver", type: "address" },
                { name: "owner", type: "address" },
            ],
            outputs: [{ name: "shares", type: "uint256" }],
            stateMutability: "nonpayable",
        },
    ] as const;

    const tx = await evmWallet.sendTransaction({
        to: VAULT_ADDRESS,
        data: encodeFunctionData({
            abi: withdrawAbi,
            functionName: "withdraw",
            args: [parseUnits(amount, USDC_DECIMALS), walletAddress, walletAddress],
        }),
    });

    console.log("Withdrawal complete!", tx.hash);
    ```
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { useWallet, EVMWallet } from "@crossmint/client-sdk-react-native-ui";
    import { View, Button } from "react-native";
    import { encodeFunctionData, parseUnits } from "viem";

    const VAULT_ADDRESS = "0xbeef0e0834849aCC03f0089F01f4F1Eeb06873C9";
    const USDC_DECIMALS = 6;

    const withdrawAbi = [
        {
            name: "withdraw",
            type: "function",
            inputs: [
                { name: "assets", type: "uint256" },
                { name: "receiver", type: "address" },
                { name: "owner", type: "address" },
            ],
            outputs: [{ name: "shares", type: "uint256" }],
            stateMutability: "nonpayable",
        },
    ] as const;

    export function WithdrawComponent() {
        const { wallet } = useWallet();

        async function withdraw(amount: string) {
            if (!wallet) return;
            const evmWallet = EVMWallet.from(wallet);
            const walletAddress = wallet.address as `0x${string}`;

            const tx = await evmWallet.sendTransaction({
                to: VAULT_ADDRESS,
                data: encodeFunctionData({
                    abi: withdrawAbi,
                    functionName: "withdraw",
                    args: [parseUnits(amount, USDC_DECIMALS), walletAddress, walletAddress],
                }),
            });

            console.log("Withdrawal complete!", tx.hash);
        }

        return (
            <View>
                <Button title="Withdraw 10 USDC" onPress={() => withdraw("10")} />
            </View>
        );
    }
    ```

    See the [React Native SDK reference](/sdk-reference/wallets/react-native/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    import CrossmintClient
    import Wallet
    import Foundation

    CrossmintSDK.configure(apiKey: "<YOUR_API_KEY>")
    let sdk = CrossmintSDK.shared

    let wallet: Wallet
    if let existing = try await sdk.crossmintWallets.getWallet(chain: EVMChain.base) {
        wallet = existing
    } else {
        wallet = try await sdk.crossmintWallets.createWallet(
            chain: EVMChain.base,
            recoveryMethods: [EVMSigners.email("user@example.com")]
        )
    }

    let evmWallet = try EVMWallet.from(wallet: wallet)

    let vaultAddress = "0xbeef0e0834849aCC03f0089F01f4F1Eeb06873C9"
    let amount = "10000000" // 10 USDC (6 decimals)

    func leftPad(_ str: String, toLength len: Int) -> String {
        String(repeating: "0", count: max(0, len - str.count)) + str
    }

    // Encodes ERC-4626 withdraw(uint256,address,address) — selector 0xb460af94
    let amt = leftPad(String(UInt64(amount)!, radix: 16), toLength: 64)
    let walletAddr = leftPad(String(wallet.address.dropFirst(2)), toLength: 64)
    let withdrawData = "0xb460af94" + amt + walletAddr + walletAddr
    let result = try await evmWallet.sendTransaction(
        to: vaultAddress,
        value: "0",
        data: withdrawData
    )
    ```

    See the [Swift SDK reference](/sdk-reference/wallets/swift/classes/evmwallet) for more details.
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    import com.crossmint.kotlin.compose.LocalCrossmintSDK
    import com.crossmint.kotlin.types.EVMChain
    import com.crossmint.kotlin.signers.SignerType
    import com.crossmint.kotlin.types.Result
    import com.crossmint.kotlin.types.WalletError
    import com.crossmint.kotlin.types.getOrThrow
    import kotlinx.coroutines.Dispatchers
    import kotlinx.coroutines.runBlocking
    import kotlinx.coroutines.withContext
    import kotlinx.serialization.json.Json
    import kotlinx.serialization.json.buildJsonObject
    import kotlinx.serialization.json.jsonObject
    import kotlinx.serialization.json.jsonPrimitive
    import kotlinx.serialization.json.put
    import kotlinx.serialization.json.putJsonArray
    import kotlinx.serialization.json.putJsonObject
    import java.net.HttpURLConnection
    import java.net.URL

    val API_KEY = "YOUR_API_KEY"
    val SIGNER_EMAIL = "user@example.com"
    val CROSSMINT_API = "https://www.crossmint.com/api/2025-06-09"
    val VAULT_ADDRESS = "0xbeef0e0834849aCC03f0089F01f4F1Eeb06873C9"
    val AMOUNT = "10000000" // 10 USDC (6 decimals)

    // Access the SDK — must be called inside a CrossmintSDKProvider composable
    val sdk = LocalCrossmintSDK.current
    val wallet = when (val result = sdk.wallets.getWallet(chain = EVMChain.Base)) {
        is Result.Success -> result.value
        is Result.Failure -> if (result.error is WalletError.WalletNotFound) {
            sdk.wallets.createWallet(chain = EVMChain.Base, recoveryMethods = listOf(SignerType.Email(SIGNER_EMAIL))).getOrThrow()
        } else {
            throw Exception(result.error.toString())
        }
    }

    val json = Json { ignoreUnknownKeys = true }

    suspend fun sendEvmTransaction(to: String, data: String, value: String = "0"): String {
        val body = buildJsonObject {
            putJsonObject("params") {
                put("chain", "base")
                put("signer", "email:$SIGNER_EMAIL")
                putJsonArray("calls") {
                    add(buildJsonObject {
                        put("to", to)
                        put("value", value)
                        put("data", data)
                    })
                }
            }
        }.toString()
        val responseText = withContext(Dispatchers.IO) {
            val conn = URL("$CROSSMINT_API/wallets/${wallet.address}/transactions")
                .openConnection() as HttpURLConnection
            conn.requestMethod = "POST"
            conn.setRequestProperty("X-API-KEY", API_KEY)
            conn.setRequestProperty("Content-Type", "application/json")
            conn.doOutput = true
            conn.outputStream.write(body.toByteArray())
            val code = conn.responseCode
            if (code !in 200..299) {
                val err = conn.errorStream?.bufferedReader()?.readText()
                error("Transaction request failed ($code): $err")
            }
            conn.inputStream.bufferedReader().readText()
        }
        val transactionId = json.parseToJsonElement(responseText)
            .jsonObject["id"]!!.jsonPrimitive.content
        val tx = wallet.approve(transactionId).getOrThrow()
        return tx.onChain.txId ?: tx.onChain.userOperationHash
            ?: error("Transaction completed but no hash was returned")
    }

    // Encodes ERC-4626 withdraw(uint256,address,address) — selector 0xb460af94
    val amt = AMOUNT.toLong().toString(16).padStart(64, '0')
    val walletAddr = wallet.address.removePrefix("0x").padStart(64, '0')

    runBlocking {
        val txHash = sendEvmTransaction(to = VAULT_ADDRESS, data = "0xb460af94$amt$walletAddr$walletAddr")
        println("Withdrawal complete! $txHash")
    }
    ```

    See the [Kotlin SDK reference](/sdk-reference/wallets/kotlin/classes/wallet) for more details.
  </Tab>

  <Tab title="REST">
    Transactions must be approved by one of the wallet's [signers](/wallets/concepts/signers).
    The SDK handles this automatically, but with the REST API you must [approve the transaction](/api-reference/wallets/approve-transaction) to complete it.

    <Steps>
      <Step title="Create the withdraw transaction">
        Send an ERC-4626 `withdraw` transaction. The `data` field encodes `withdraw(uint256 assets, address receiver, address owner)` where:

        * `0xb460af94` is the function selector
        * Next 32 bytes: the withdraw amount (10 USDC = `0x989680`)
        * Next 32 bytes: the receiver address, zero-padded to 32 bytes
        * Last 32 bytes: the owner address (same as receiver), zero-padded to 32 bytes

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://www.crossmint.com/api/2025-06-09/wallets/WALLET_ADDRESS/transactions \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: YOUR_API_KEY' \
              --data '{
                  "params": {
                      "chain": "base",
                      "signer": "email:USER_EMAIL",
                      "calls": [{
                          "to": "0xbeef0e0834849aCC03f0089F01f4F1Eeb06873C9",
                          "value": "0",
                          "data": "0xb460af9400000000000000000000000000000000000000000000000000000000009896800000000000000000000000001234567890abcdef1234567890abcdef123456780000000000000000000000001234567890abcdef1234567890abcdef12345678"
                      }]
                  }
              }'
          ```

          ```js Node.js theme={null}
          const walletAddress = "YOUR_WALLET_ADDRESS";

          const response = await fetch(
              `https://www.crossmint.com/api/2025-06-09/wallets/${walletAddress}/transactions`,
              {
                  method: "POST",
                  headers: {
                      "Content-Type": "application/json",
                      "X-API-KEY": "YOUR_API_KEY",
                  },
                  body: JSON.stringify({
                      params: {
                          chain: "base",
                          signer: "email:user@example.com",
                          calls: [{
                              to: "0xbeef0e0834849aCC03f0089F01f4F1Eeb06873C9",
                              value: "0",
                              data: `0xb460af940000000000000000000000000000000000000000000000000000000000989680${walletAddress.slice(2).padStart(64, "0")}${walletAddress.slice(2).padStart(64, "0")}`,
                          }],
                      },
                  }),
              }
          );
          const { id } = await response.json();
          ```

          ```python Python theme={null}
          import requests

          wallet_address = "YOUR_WALLET_ADDRESS"

          response = requests.post(
              f"https://www.crossmint.com/api/2025-06-09/wallets/{wallet_address}/transactions",
              headers={
                  "Content-Type": "application/json",
                  "X-API-KEY": "YOUR_API_KEY",
              },
              json={
                  "params": {
                      "chain": "base",
                      "signer": "email:user@example.com",
                      "calls": [{
                          "to": "0xbeef0e0834849aCC03f0089F01f4F1Eeb06873C9",
                          "value": "0",
                          "data": f"0xb460af940000000000000000000000000000000000000000000000000000000000989680{wallet_address[2:].zfill(64)}{wallet_address[2:].zfill(64)}",
                      }],
                  },
              },
          )
          transaction_id = response.json()["id"]
          ```
        </CodeGroup>
      </Step>

      <Step title="Approve the withdraw transaction">
        Approve the transaction using the ID returned in the previous step.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://www.crossmint.com/api/2025-06-09/wallets/WALLET_ADDRESS/transactions/TRANSACTION_ID/approve \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: YOUR_API_KEY'
          ```

          ```js Node.js theme={null}
          await fetch(
              `https://www.crossmint.com/api/2025-06-09/wallets/${walletAddress}/transactions/${id}/approve`,
              {
                  method: "POST",
                  headers: {
                      "Content-Type": "application/json",
                      "X-API-KEY": "YOUR_API_KEY",
                  },
              }
          );
          ```

          ```python Python theme={null}
          requests.post(
              f"https://www.crossmint.com/api/2025-06-09/wallets/{wallet_address}/transactions/{transaction_id}/approve",
              headers={
                  "Content-Type": "application/json",
                  "X-API-KEY": "YOUR_API_KEY",
              },
          )
          ```
        </CodeGroup>
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Customizing the Vault

The example above uses the Steakhouse Prime Instant USDC vault on Base. You can adapt this to any Morpho vault by:

1. **Changing the vault address** — Use the [Discover Vaults](#discover-vaults) query to find vaults for different tokens or chains
2. **Changing the chain** — Morpho is deployed on Ethereum, Base, Arbitrum, Polygon, and other EVM chains. Update the `chainId_in` filter and the wallet chain accordingly.
3. **Changing the token** — Update the `assetAddress_in` filter and token decimals to match the vault's underlying asset

## Troubleshooting

<AccordionGroup>
  <Accordion title="Approve transaction reverts">
    Ensure the wallet holds enough of the token to cover the deposit amount.
  </Accordion>

  <Accordion title="Deposit transaction reverts">
    Verify the approval was confirmed before calling deposit. Check that the vault has not been paused.
  </Accordion>

  <Accordion title="Vault not found in API">
    Confirm the chain ID and asset address are correct. Some vaults may be delisted.
  </Accordion>

  <Accordion title="Shares not appearing">
    Vault shares are minted to the `receiver` address. Verify the wallet address is correct.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Yield Strategies" icon="chart-line" href="/wallets/guides/wallet-extensions/overview">
    Learn how vaults generate returns and which strategies fit your users.
  </Card>

  <Card title="Gas Sponsorship" icon="gas-pump" href="/wallets/guides/gas-sponsorship">
    Remove the ETH requirement for gas fees so users only need the supply token.
  </Card>

  <Card title="Morpho SDK" icon="book" href="https://docs.morpho.org/tools/offchain/sdks/morpho-sdk/">
    Explore advanced use cases like direct market lending and borrowing.
  </Card>
</CardGroup>


# Wallet Extensions
Source: https://docs.crossmint.com/wallets/guides/wallet-extensions/overview

Overview of wallet plugin capabilities including yield generation, token swapping, and credit card issuance

Crossmint wallets support a set of built-in extensions that add financial functionality beyond basic token transfers. These extensions let you offer yield generation, token swapping, bridging, and credit card issuance directly from your wallet integration — without building custom protocol integrations.

## Yield

Wallet extensions include mechanisms to generate yield from wallet balances, primarily through stablecoins. There are two primary strategies:

### Yield from Reserves

Earn from the interest generated by a stablecoin's underlying reserves, which are typically invested in U.S. Treasury bills or equivalent cash instruments.

| Option | Description | Notes |
| - | - | - |
| USDC, USDT | Negotiate a direct revenue-sharing agreement with the stablecoin issuer. | Typically limited to large partners; smaller revenue share; allows direct staking. |
| USDG | Use a stablecoin that automatically accrues interest to holders or distributors. | Easier to get started; usually requires swapping to USDC/USDT before staking or transferring out, if the recipient prefers another stable. |
| Issue your own stablecoin | Create your proprietary stablecoin backed by your own reserves. | Around 10–20 basis points (bps) more yield and control vs a non-standard token; higher setup costs, complexity, and slower go-to-market. Similar swapping requirements vs USDG. |

### Yield from Staking

Earn yield by delegating tokens to validators or liquidity pools. Protocols such as Aave and Morpho offer staking opportunities, and Crossmint wallets are compatible with any of them. <a href="https://yield.xyz">Yield.xyz</a> provides integrations with all top DeFi protocols, making it easy to connect your Crossmint wallets to yield-generating strategies.

These mechanisms are not mutually exclusive — the same asset can simultaneously generate passive income from its reserves while being staked to earn additional yield.

## Swapping and Bridging

Wallet extensions support token swapping and cross-chain bridging through integrated protocols:

* **Swapping** — exchange one token for another on the same chain (for example, USDC to ETH on Base)
* **Bridging** — move tokens across chains (for example, USDC from Ethereum to Base)

See the [Swapping and Bridging guide](/wallets/guides/wallet-extensions/swapping-and-bridging) for integration details.

## Credit Cards

Issue virtual or physical credit cards funded by wallet balances. This extension enables fintech use cases where users can spend their digital assets through traditional payment rails.

See the [Rain Card Issuance guide](/wallets/guides/wallet-extensions/credit-cards) for Rain cards or the [Reap Card Issuance guide](/wallets/guides/wallet-extensions/reap) for Reap virtual cards.

## Get Started

<CardGroup>
  <Card title="Offer Yield" icon="chart-line-up" href="/wallets/guides/wallet-extensions/yield-xyz">
    Follow the step-by-step guide to start earning yield from your wallet balances
  </Card>

  <Card title="Swap and Bridge Tokens" icon="arrows-rotate" href="/wallets/guides/wallet-extensions/swapping-and-bridging">
    Exchange tokens and move assets across chains
  </Card>

  <Card title="Issue Credit Cards" icon="credit-card" href="/wallets/guides/wallet-extensions/credit-cards">
    Fund credit cards from wallet balances for traditional payments
  </Card>

  <Card title="Try the Demo" icon="building-columns" href="https://fintech-starter-app.demos-crossmint.com/">
    Explore a live fintech app demo showcasing yield and wallet features
  </Card>
</CardGroup>


# Reap Card Issuance
Source: https://docs.crossmint.com/wallets/guides/wallet-extensions/reap

Issue virtual cards with Reap and fund them from Crossmint wallets

This guide explains how to issue a virtual card with the <a href="https://docs.reap.global/">Reap</a> Card Issuing API and fund it from a Crossmint wallet. Reap issues cards under a Program-Funded model: your program holds collateral in a Reap master account, and each user's spending power is tracked as a Reap balance that your backend credits after the user moves stablecoins out of their Crossmint wallet.

You will build a Next.js app where a user signs in with Crossmint, gets a wallet on Base Sepolia, passes Reap KYC, receives a virtual card, funds it by sending stablecoins to your program treasury, and views the card details through Reap's secure reveal. The same funding path works for wallets controlled by AI agents, which lets an agent top up a card from its stablecoin balance.

## Prerequisites

To use Reap with Crossmint wallets, you need:

* **Crossmint wallet:** a [wallet](/wallets/guides/create-wallet) on Base Sepolia
* **Crossmint API key:** a **staging** **Client API Key** with the scopes `users.create`, `users.read`, `wallets.create`, `wallets.read`, `wallets:transactions.create`, `wallets:transactions.sign`, `wallets:balance.read`, and `wallets.fund` (create in the <a href="https://console.crossmint.com/">Crossmint Console</a>). In staging, all scopes are included by default.
* **Reap API key:** a sandbox API key for a Program-Funded project, issued by Reap (see the <a href="https://docs.reap.global/api-reference/overview">Reap API overview</a>)
* **Next.js project:** an App Router project with the Crossmint React SDK installed

<Snippet />

This guide uses Base Sepolia and the Reap sandbox as examples. To follow along, you will also need:

* **Test tokens:** USDXM in the wallet from `wallet.stagingFund()` (see [Fund a Staging Wallet](/wallets/guides/fund-staging-wallet))
* **Program treasury:** an EVM address your program controls on Base Sepolia that receives user deposits
* **Gas:** ETH on Base Sepolia for gas fees (not required if [gas sponsorship](/wallets/guides/gas-sponsorship) is enabled)

In production, Reap collateralizes the master account with stablecoins or bank transfers, users complete Reap's hosted KYC, and your backend credits balances from real deposits. Contact <a href="https://www.crossmint.com/contact/sales">Crossmint Sales</a> to get connected with the Reap team.

## What You Will Build

High-level steps:

1. Set up Crossmint authentication and wallet providers.
2. Build a server-side Reap client.
3. Create the Reap user, complete KYC, and issue a virtual card.
4. Fund the card from the Crossmint wallet.
5. Simulate a purchase and reveal the card.

<Note>
  Reap's sandbox exposes `/simulation/*` endpoints for KYC approval, collateral deposits, and card authorizations. These
  endpoints do not exist in production and are marked as sandbox only below.
</Note>

## Set Up Crossmint

<Steps>
  <Step title="Configure the providers">
    Wrap your app with the Crossmint providers so users can sign in and receive a wallet on Base Sepolia. This example uses [Crossmint Auth](/authentication/introduction); for production you can also [bring your own auth](/wallets/guides/bring-your-own-auth).

    ```tsx app/providers.tsx theme={null}
    "use client";

    import {
        CrossmintProvider,
        CrossmintAuthProvider,
        CrossmintWalletProvider,
    } from "@crossmint/client-sdk-react-ui";

    export function Providers({ children }: { children: React.ReactNode }) {
        return (
            <CrossmintProvider apiKey={process.env.NEXT_PUBLIC_CROSSMINT_API_KEY ?? ""}>
                <CrossmintAuthProvider loginMethods={["email", "google"]}>
                    <CrossmintWalletProvider
                        createOnLogin={{
                            chain: "base-sepolia",
                            recovery: { type: "email" },
                        }}
                    >
                        {children}
                    </CrossmintWalletProvider>
                </CrossmintAuthProvider>
            </CrossmintProvider>
        );
    }
    ```

    <Columns>
      <Frame type="simple">
        <img alt="Crossmint sign-in modal with Google and email options" />
      </Frame>

      <Frame type="simple">
        <img alt="Crossmint one-time code screen after submitting an email" />
      </Frame>
    </Columns>

    After login, the wallet card shows the `base-sepolia` address and the USDXM balance:

    <Frame type="simple">
      <img alt="Demo app showing the Crossmint wallet address, base-sepolia chain, and a 10 USDXM balance after the staging faucet" />
    </Frame>
  </Step>

  <Step title="Add environment variables">
    The Reap API key is only read in server actions, so it has no `NEXT_PUBLIC_` prefix.

    ```bash .env.local theme={null}
    NEXT_PUBLIC_CROSSMINT_API_KEY=YOUR_CROSSMINT_CLIENT_API_KEY
    NEXT_PUBLIC_PROGRAM_TREASURY_ADDRESS=YOUR_TREASURY_ADDRESS

    REAP_API_KEY=YOUR_REAP_API_KEY
    REAP_API_URL=https://sg.sandbox.api.reap.global
    TREASURY_TOKEN_ADDRESSES=0x14196f08a4fa0b66b7331bc40dd6bcd8a1deea9f
    ```

    `TREASURY_TOKEN_ADDRESSES` lists the stablecoin contracts your treasury accepts; the value above is USDXM on `base-sepolia`.
  </Step>
</Steps>

## Build the Reap Integration Layer

Reap authenticates with a bearer token and pins the API version through the `Reap-Version` header. Create-style requests also require an `Idempotency-Key`. Keep every Reap call in Next.js server actions so the API key never reaches the browser.

<Steps>
  <Step title="Create a Reap client">
    ```typescript actions/reap.ts theme={null}
    "use server";

    import { randomUUID } from "crypto";

    const REAP_API_URL = process.env.REAP_API_URL ?? "https://sg.sandbox.api.reap.global";
    const REAP_VERSION = "2025-02-14";

    interface ReapError {
        error?: { code?: string; message?: string };
    }

    async function reap<T>(
        path: string,
        init: { method?: "GET" | "POST"; body?: object; idempotencyKey?: string } = {}
    ): Promise<T> {
        const apiKey = process.env.REAP_API_KEY;
        if (apiKey == null) {
            throw new Error("REAP_API_KEY is not set");
        }
        const headers: Record<string, string> = {
            Authorization: `Bearer ${apiKey}`,
            "Reap-Version": REAP_VERSION,
            "Content-Type": "application/json",
        };
        if (init.idempotencyKey != null) {
            headers["Idempotency-Key"] = init.idempotencyKey;
        }
        const response = await fetch(`${REAP_API_URL}${path}`, {
            method: init.method ?? "GET",
            headers,
            body: init.body == null ? undefined : JSON.stringify(init.body),
            cache: "no-store",
        });
        if (response.status === 204) {
            return undefined as T;
        }
        const json = (await response.json()) as T & ReapError;
        if (!response.ok) {
            const code = json.error?.code ?? response.status;
            const message = json.error?.message ?? response.statusText;
            throw new Error(`Reap ${init.method ?? "GET"} ${path} failed: ${code} ${message}`);
        }
        return json;
    }
    ```
  </Step>

  <Step title="Add user, account, and card operations">
    Store the Crossmint wallet address as Reap's `externalId` so a returning user maps to the same Reap user. List endpoints return results under `items`.

    ```typescript actions/reap.ts theme={null}
    // Uses the reap client from the previous step

    export interface ReapUser {
        id: string;
        email: string;
        application: { status: "NOT_STARTED" | "PENDING" | "IN_REVIEW" | "APPROVED" | "REJECTED" } | null;
    }

    export interface ReapAccount {
        id: string;
        ownerId: string;
        status: string;
    }

    export interface ReapCard {
        id: string;
        accountId: string;
        type: "VIRTUAL" | "PHYSICAL";
        status: string;
        last4: string;
    }

    export async function findOrCreateReapUser(params: {
        walletAddress: string;
        email: string;
        firstName: string;
        lastName: string;
        phoneNumber: string;
    }): Promise<ReapUser> {
        const existing = await reap<{ items: ReapUser[] }>(
            `/users?externalId=${encodeURIComponent(params.walletAddress)}`
        );
        if (existing.items.length > 0) {
            return existing.items[0];
        }
        return reap<ReapUser>("/users", {
            method: "POST",
            idempotencyKey: randomUUID(),
            body: {
                externalId: params.walletAddress,
                email: params.email,
                firstName: params.firstName,
                lastName: params.lastName,
                phoneNumber: params.phoneNumber,
            },
        });
    }

    export async function getReapUser(userId: string): Promise<ReapUser> {
        return reap<ReapUser>(`/users/${userId}`);
    }

    // Sandbox only. In production, users complete KYC through Reap's hosted flow.
    export async function simulateKycApproval(userId: string): Promise<void> {
        await reap<void>(`/simulation/users/${userId}/application`, {
            method: "POST",
            body: { status: "APPROVED" },
        });
    }

    export async function findOrCreateReapAccount(userId: string): Promise<ReapAccount> {
        const existing = await reap<{ items: ReapAccount[] }>(`/accounts?ownerType=USER&ownerId=${userId}`);
        if (existing.items.length > 0) {
            return existing.items[0];
        }
        return reap<ReapAccount>("/accounts", {
            method: "POST",
            idempotencyKey: randomUUID(),
            body: { ownerId: userId },
        });
    }

    export async function findOrCreateVirtualCard(params: {
        userId: string;
        accountId: string;
    }): Promise<ReapCard> {
        const existing = await reap<{ items: ReapCard[] }>(`/cards?accountId=${params.accountId}`);
        const active = existing.items.find((card) => card.status === "ACTIVE");
        if (active != null) {
            return active;
        }
        return reap<ReapCard>("/cards", {
            method: "POST",
            idempotencyKey: randomUUID(),
            body: { userId: params.userId, accountId: params.accountId, type: "VIRTUAL" },
        });
    }
    ```
  </Step>

  <Step title="Add balance, funding, and reveal operations">
    A Program-Funded project mirrors each user's spending power as a Reap Virtual Asset balance. Create one fixed 1:1 USD asset for the project and post a `DEPOSIT` against the user's account after their on-chain transfer settles.

    ```typescript actions/reap.ts theme={null}
    // Uses the reap client from the previous step

    export interface ReapBalance {
        currency: string;
        availableBalance: number;
        totalAssetValue: number;
        liabilities: { cardDebt: { pending: number; cleared: number; total: number } };
    }

    export async function getReapBalance(accountId: string): Promise<ReapBalance> {
        return reap<ReapBalance>(`/accounts/${accountId}/balance`);
    }

    async function findOrCreateUsdVirtualAsset(): Promise<{ id: string }> {
        const symbol = "XUSD";
        const existing = await reap<{ items: { id: string; symbol: string }[] }>("/virtual-assets");
        const match = existing.items.find((asset) => asset.symbol === symbol);
        if (match != null) {
            return match;
        }
        return reap<{ id: string }>("/virtual-assets", {
            method: "POST",
            idempotencyKey: randomUUID(),
            body: { symbol, name: "Program USD", decimals: 6, rateSource: "FIXED", rate: "1" },
        });
    }

    // Derive idempotencyKey from the verified on-chain transfer so a retried call
    // returns the original posting instead of crediting the deposit twice.
    export async function creditReapAccount(params: { accountId: string; amount: string; idempotencyKey: string }) {
        const asset = await findOrCreateUsdVirtualAsset();
        return reap<{ id: string; type: string }>("/postings", {
            method: "POST",
            idempotencyKey: params.idempotencyKey,
            body: {
                accountId: params.accountId,
                type: "DEPOSIT",
                entries: [{ virtualAssetId: asset.id, amount: params.amount }],
            },
        });
    }

    // Sandbox only. In production, collateralize the master account through Reap.
    export async function simulateCollateralTopUp(amount: number) {
        return reap<{ id: string; status: string; amount: number }>("/simulation/fiat-deposits", {
            method: "POST",
            body: { amount, currency: "USD", senderName: "Program Treasury" },
        });
    }

    export async function createCardRevealUrl(cardId: string): Promise<{ revealUrl: string; expiresAt: string }> {
        return reap(`/cards/${cardId}/reveal`, { method: "POST", body: {} });
    }
    ```

    <Warning>
      These actions are callable from the browser and run with your program's Reap API key. Before production, every
      action must verify the signed-in Crossmint user (for example by validating the Crossmint JWT on the server) and
      only act on the Reap user, account, and card that belong to that user. Never accept an `accountId`, `cardId`, or
      `amount` from the client without that ownership check. The PoC omits this to keep the flow short.
    </Warning>
  </Step>

  <Step title="Verify the deposit on-chain">
    Before crediting Reap, confirm that the user's transaction to the program treasury succeeded and read the transferred amount from the ERC-20 `Transfer` event. Only accept transfers emitted by the stablecoin contracts you trust (USDXM in staging, USDC in production) and sent from the signed-in user's wallet; otherwise any token transfer to the treasury would count as USD funding.

    ```typescript actions/treasury.ts theme={null}
    "use server";

    const RPC_URL = process.env.BASE_SEPOLIA_RPC_URL ?? "https://sepolia.base.org";
    const TRANSFER_TOPIC = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
    const TOKEN_DECIMALS = 6;
    // Comma-separated list of ERC-20 contracts accepted as USD, for example USDXM on base-sepolia
    const ACCEPTED_TOKENS = (process.env.TREASURY_TOKEN_ADDRESSES ?? "").toLowerCase().split(",");

    interface Receipt {
        status: string;
        logs: { address: string; topics: string[]; data: string; logIndex: string }[];
    }

    function topicToAddress(topic: string): string {
        return `0x${topic.slice(26)}`.toLowerCase();
    }

    export async function confirmTreasuryDeposit(
        transactionHash: string,
        senderAddress: string
    ): Promise<{ amount: string; tokenAddress: string; depositKey: string }> {
        const treasury = process.env.NEXT_PUBLIC_PROGRAM_TREASURY_ADDRESS;
        if (treasury == null) {
            throw new Error("NEXT_PUBLIC_PROGRAM_TREASURY_ADDRESS is not set");
        }

        let receipt: Receipt | null = null;
        for (let attempt = 0; attempt < 15 && receipt == null; attempt++) {
            const response = await fetch(RPC_URL, {
                method: "POST",
                headers: { "Content-Type": "application/json" },
                body: JSON.stringify({
                    jsonrpc: "2.0",
                    id: 1,
                    method: "eth_getTransactionReceipt",
                    params: [transactionHash],
                }),
                cache: "no-store",
            });
            const json = (await response.json()) as { result: Receipt | null };
            receipt = json.result;
            if (receipt == null) {
                await new Promise((resolve) => setTimeout(resolve, 2000));
            }
        }
        if (receipt == null) {
            throw new Error(`Transaction ${transactionHash} was not found on chain`);
        }
        if (receipt.status !== "0x1") {
            throw new Error(`Transaction ${transactionHash} reverted`);
        }

        const transfer = receipt.logs.find(
            (log) =>
                log.topics[0] === TRANSFER_TOPIC &&
                ACCEPTED_TOKENS.includes(log.address.toLowerCase()) &&
                topicToAddress(log.topics[1]) === senderAddress.toLowerCase() &&
                topicToAddress(log.topics[2]) === treasury.toLowerCase()
        );
        if (transfer == null) {
            throw new Error("No accepted stablecoin transfer from the user to the program treasury in this transaction");
        }

        const raw = BigInt(transfer.data);
        const unit = BigInt(10) ** BigInt(TOKEN_DECIMALS);
        const whole = raw / unit;
        const fraction = (raw % unit).toString().padStart(TOKEN_DECIMALS, "0").replace(/0+$/, "");
        return {
            amount: fraction === "" ? whole.toString() : `${whole}.${fraction}`,
            tokenAddress: transfer.address,
            depositKey: `${transactionHash}:${transfer.logIndex}`,
        };
    }
    ```
  </Step>
</Steps>

## Issue and Fund the Card

<Steps>
  <Step title="Create the user, approve KYC, and issue a card">
    Reap's sandbox KYC simulation is asynchronous: the request returns `204` immediately and the application flips to `APPROVED` a few seconds later, so poll the user until it does.

    ```tsx components/reap-card.tsx theme={null}
    "use client";

    import { useState } from "react";
    import { useCrossmintAuth, useWallet } from "@crossmint/client-sdk-react-ui";
    import {
        findOrCreateReapAccount,
        findOrCreateReapUser,
        findOrCreateVirtualCard,
        getReapUser,
        simulateKycApproval,
        type ReapAccount,
        type ReapCard,
    } from "@/actions/reap";

    const KYC_POLL_MS = 5000;
    const KYC_POLL_ATTEMPTS = 24;

    export function ReapCard() {
        const { wallet } = useWallet();
        const { user } = useCrossmintAuth();
        const [account, setAccount] = useState<ReapAccount | null>(null);
        const [card, setCard] = useState<ReapCard | null>(null);

        const setUpCard = async () => {
            if (wallet == null || user?.email == null) {
                return;
            }
            let reapUser = await findOrCreateReapUser({
                walletAddress: wallet.address,
                email: user.email,
                firstName: "Jane",
                lastName: "Doe",
                phoneNumber: "+14155550123",
            });

            if (reapUser.application?.status !== "APPROVED") {
                await simulateKycApproval(reapUser.id);
                for (let i = 0; i < KYC_POLL_ATTEMPTS; i++) {
                    await new Promise((resolve) => setTimeout(resolve, KYC_POLL_MS));
                    reapUser = await getReapUser(reapUser.id);
                    if (reapUser.application?.status === "APPROVED") {
                        break;
                    }
                }
                if (reapUser.application?.status !== "APPROVED") {
                    throw new Error(`KYC still ${reapUser.application?.status ?? "missing"}`);
                }
            }

            const reapAccount = await findOrCreateReapAccount(reapUser.id);
            setAccount(reapAccount);
            setCard(await findOrCreateVirtualCard({ userId: reapUser.id, accountId: reapAccount.id }));
        };

        return (
            <div>
                <button onClick={setUpCard}>Issue virtual card</button>
                {card != null && <p>Card •••• {card.last4} · {card.status}</p>}
            </div>
        );
    }
    ```

    <Frame type="simple">
      <img alt="Demo app showing a Reap user with APPROVED status, an ACTIVE account, and an ACTIVE virtual card ending in 8871" />
    </Frame>

    The same objects appear in the Reap platform under **Users** and **Cards** (sandbox):

    <Columns>
      <Frame type="simple">
        <img alt="Reap platform user drawer showing the user ID, country, and an Approved application status" />
      </Frame>

      <Frame type="simple">
        <img alt="Reap platform card drawer showing an Active virtual card, card ID, cardholder, and the user account as funding source" />
      </Frame>
    </Columns>
  </Step>

  <Step title="Fund the card from the wallet">
    Send stablecoins from the Crossmint wallet to your program treasury, confirm the receipt on-chain, then mirror the amount into Reap. In staging, `wallet.stagingFund()` mints USDXM, so read and send `"usdxm"`; in production use `"usdc"`.

    ```tsx components/reap-card.tsx theme={null}
    // Uses the component state from the previous step
    import { confirmTreasuryDeposit } from "@/actions/treasury";
    import { creditReapAccount, getReapBalance } from "@/actions/reap";

    const TREASURY = process.env.NEXT_PUBLIC_PROGRAM_TREASURY_ADDRESS ?? "";
    const STABLECOIN = "usdxm";

    const fundCard = async (amount: string) => {
        if (wallet == null || account == null) {
            return;
        }
        await wallet.stagingFund(10);

        const tx = await wallet.send(TREASURY, STABLECOIN, amount);
        const deposit = await confirmTreasuryDeposit(tx.hash, wallet.address);
        await creditReapAccount({ accountId: account.id, amount: deposit.amount, idempotencyKey: deposit.depositKey });

        const balance = await getReapBalance(account.id);
        console.log(`Spending power: ${balance.availableBalance} ${balance.currency}`);
    };

    // Add to the component's returned JSX
    {account != null && <button onClick={() => fundCard("5")}>Fund card with 5 {STABLECOIN.toUpperCase()}</button>}
    ```

    <Frame type="simple">
      <img alt="Demo app showing the wallet balance reduced to 5 USDXM and Reap card spending power of 5 USD with an explorer link for the transfer" />
    </Frame>

    In the Reap platform, each mirrored deposit appears under **Activities → Virtual asset postings**, and the user account balance reflects the credited units:

    <Frame type="simple">
      <img alt="Reap platform Activities page listing Deposit postings of +5 XUSD to the user account" />
    </Frame>

    See [Transfer Tokens](/wallets/guides/transfer-tokens) and the [React SDK reference](/sdk-reference/wallets/react/hooks#wallet-methods) for `send` and `balances` parameters.
  </Step>

  <Step title="Simulate a purchase and reveal the card">
    Card authorizations draw on the program's master collateral, so top it up in the sandbox before the first purchase. Approved authorizations return `amount` as a running total (`{ authorized, reversed, current }`), while declines omit `amount` and return a scalar `originalAmount` with a `declineReason`.

    ```typescript actions/reap.ts theme={null}
    // Uses the reap client from the create step

    export interface ReapTransaction {
        id: string;
        status: string;
        amount: number;
        currency: string;
        merchant: { name: string };
        declineReason: { code: string; message: string } | null;
    }

    interface ReapTransactionResponse extends Omit<ReapTransaction, "amount" | "declineReason"> {
        amount?: { authorized: number; reversed: number; current: number };
        originalAmount: number | { current: number };
        declineReason?: { code: string; message: string } | null;
    }

    // Sandbox only
    export async function simulateCardPurchase(params: {
        cardId: string;
        amount: number;
        merchantName: string;
    }): Promise<ReapTransaction> {
        const tx = await reap<ReapTransactionResponse>("/simulation/card-transactions/authorization", {
            method: "POST",
            body: { cardId: params.cardId, amount: params.amount, merchant: { name: params.merchantName } },
        });
        const amount =
            tx.amount?.current ??
            (typeof tx.originalAmount === "number" ? tx.originalAmount : tx.originalAmount.current);
        return { ...tx, amount, declineReason: tx.declineReason ?? null };
    }
    ```

    Reap's reveal endpoint returns a single-use URL that expires after about 5 minutes. Load it directly in an `<iframe>` so the PAN and CVV are rendered by Reap and never pass through your servers.

    ```tsx components/reap-card.tsx theme={null}
    // Uses the component state from the previous step
    import { createCardRevealUrl, simulateCardPurchase, simulateCollateralTopUp } from "@/actions/reap";

    const [revealUrl, setRevealUrl] = useState<string | null>(null);

    const purchaseAndReveal = async () => {
        if (card == null) {
            return;
        }
        await simulateCollateralTopUp(100);
        const purchase = await simulateCardPurchase({ cardId: card.id, amount: 2.5, merchantName: "Coffee Shop" });
        console.log(`${purchase.status}: ${purchase.amount} ${purchase.currency}`);

        const session = await createCardRevealUrl(card.id);
        setRevealUrl(session.revealUrl);
    };

    // Add to the component's returned JSX
    {card != null && <button onClick={purchaseAndReveal}>Simulate purchase and reveal card</button>}
    {revealUrl != null && <iframe src={revealUrl} title="Card details" width={400} height={260} />}
    ```

    <Columns>
      <Frame type="simple">
        <img alt="Demo app showing master collateral, a PENDING 2.50 USD purchase, and the event log" />
      </Frame>

      <Frame type="simple">
        <img alt="Demo app showing the Reap secure reveal iframe with card details redacted" />
      </Frame>
    </Columns>

    On the program side, the authorization appears under **Activities → Card transactions** and reduces the user account's available balance against the master account collateral:

    <Columns>
      <Frame type="simple">
        <img alt="Reap platform transaction drawer showing a Pending 2.50 USD e-commerce authorization at Crossmint Coffee" />
      </Frame>

      <Frame type="simple">
        <img alt="Reap platform account drawer showing 4.50 USD available balance, 10 XUSD asset value, 5.50 USD liabilities, and the master account balance behind it" />
      </Frame>
    </Columns>
  </Step>
</Steps>

## Verify the Integration

Run `npm run dev`, sign in with an email, and click through the flow. A successful run shows:

* The wallet address on `base-sepolia` with a USDXM balance after `stagingFund`.
* A Reap user with `application.status: "APPROVED"`, an `ACTIVE` account, and an `ACTIVE` virtual card.
* The wallet balance decreasing by the funded amount and `availableBalance` on the Reap account increasing by the same amount.
* A `PENDING` authorization after the simulated purchase, with `availableBalance` reduced by the purchase amount.
* Card number, expiry, and CVV rendered inside the reveal iframe.

<Frame type="simple">
  <img alt="Demo app showing an approved Reap user, an active virtual card, wallet and Reap balances, and a pending purchase" />
</Frame>

## Troubleshooting

<AccordionGroup>
  <Accordion title="KYC status stays PENDING after the simulation call">
    The `/simulation/users/{id}/application` endpoint returns `204` when the request is accepted, not when the application is approved. Poll `GET /users/{id}` until `application.status` is `APPROVED`; the sandbox usually takes 5 to 15 seconds.
  </Accordion>

  <Accordion title="Wallet balance shows 0 after stagingFund">
    `wallet.stagingFund()` mints Crossmint's staging stablecoin USDXM, not testnet USDC. Read the balance with `wallet.balances(["usdxm"])` and send with `wallet.send(recipient, "usdxm", amount)`. Base Sepolia has several USDC-like tokens, so do not assume a single USDC address.
  </Accordion>

  <Accordion title="Card authorization is declined with INSUFFICIENT_MASTER_BALANCE">
    Authorizations are backed by the project's master collateral account, not only by the user's balance. In the sandbox, call `/simulation/fiat-deposits` to add collateral; in production, fund the master account through Reap.
  </Accordion>

  <Accordion title="Purchase amount renders as [object Object]">
    Approved authorizations return `amount` as an object with `authorized`, `reversed`, and `current`, while declines return a scalar `originalAmount`. Normalize the response in the server action as shown above before rendering it.
  </Accordion>

  <Accordion title="Reveal URL fails to load or shows an expired session">
    Reveal URLs are single-use and expire after about 5 minutes. Request a new URL each time the user opens the card details, and load it directly in an iframe or WebView rather than fetching it from your backend.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Check Wallet Balances" icon="wallet" href="/wallets/guides/check-balances">
    Show the wallet balance alongside the card's spending power
  </Card>

  <Card title="Gas Sponsorship" icon="gas-pump" href="/wallets/guides/gas-sponsorship">
    Cover gas fees so users can fund their card without holding ETH
  </Card>

  <Card title="Rain Card Issuance" icon="credit-card" href="/wallets/guides/wallet-extensions/credit-cards">
    Compare with the Rain integration for collateral-backed Visa cards
  </Card>
</CardGroup>


# Relay
Source: https://docs.crossmint.com/wallets/guides/wallet-extensions/relay

Bridge and swap tokens across chains using Crossmint wallets and Relay

This guide explains how to bridge and swap tokens across chains using the <a href="https://docs.relay.link/">Relay</a> API with Crossmint wallets. Relay is an intent-based cross-chain protocol that aggregates bridges and DEXs to execute transfers across 20+ EVM chains. Both human users and AI agents can use this integration to move assets between blockchains programmatically.

## Prerequisites

To use Relay with Crossmint wallets, you need:

* A Crossmint [wallet](/wallets/guides/create-wallet) on any supported EVM chain
* A **production API Key** with the scope: `wallets:transactions.create` (create in the <a href="https://www.crossmint.com/console">Production Console</a>)

This guide uses mainnet for all examples because testnet bridging support is limited. Start with small test amounts before moving larger sums.

To follow along using Base as the origin chain, you also need:

* ETH on Base mainnet for gas fees (not required if [gas sponsorship](/wallets/guides/gas-sponsorship) is enabled)
* For bridging: ETH on Base
* For swapping: USDC on Base

A Relay API key is optional. Without one, requests are subject to default rate limits. To obtain a key, visit the <a href="https://docs.relay.link/references/api/api-keys#how-to-request-an-api-key">Relay API Keys page</a>.

## Bridge Tokens

Bridging moves the same token from one chain to another. This example bridges native ETH from Base to Arbitrum.

<Note>
  Both the Relay API and Crossmint wallets must support the source and destination chains. Most major EVM chains are supported, but for less common chains, verify support on the <a href="https://docs.relay.link/resources/supported-chains">Relay supported chains page</a> and the <a href="/wallets/guides/create-wallet">Crossmint supported chains list</a> before proceeding.
</Note>

High level steps:

1. Request a bridge quote from the Relay `/quote/v2` endpoint
2. Execute the bridge transaction using the quote calldata
3. Poll the Relay `/intents/status/v3` endpoint until the bridge completes

<Warning>
  Cross-chain bridges primarily operate on mainnet. The wallet must hold sufficient tokens on the source chain and ETH for gas fees. Testnet support varies by route; see the <a href="https://docs.relay.link/resources/supported-chains">Relay supported chains page</a> for availability.
</Warning>

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet, EVMWallet } from "@crossmint/client-sdk-react-ui";
    import { parseEther } from "viem";

    const RELAY_API = "https://api.relay.link";
    const ORIGIN_CHAIN_ID = 8453; // Base
    const DESTINATION_CHAIN_ID = 42161; // Arbitrum
    const ETH_TOKEN_ADDRESS = "0x0000000000000000000000000000000000000000";

    export function BridgeComponent() {
        const { wallet } = useWallet();

        async function bridge(amount: string) {
            if (!wallet) return;
            const evmWallet = EVMWallet.from(wallet);

            // 1. Get a bridge quote from Relay
            const quoteRes = await fetch(`${RELAY_API}/quote/v2`, {
                method: "POST",
                headers: { "Content-Type": "application/json" },
                body: JSON.stringify({
                    user: wallet.address,
                    originChainId: ORIGIN_CHAIN_ID,
                    destinationChainId: DESTINATION_CHAIN_ID,
                    originCurrency: ETH_TOKEN_ADDRESS,
                    destinationCurrency: ETH_TOKEN_ADDRESS,
                    amount: parseEther(amount).toString(),
                    tradeType: "EXACT_INPUT",
                }),
            });
            if (!quoteRes.ok) {
                throw new Error(`Quote request failed: ${quoteRes.status}`);
            }
            const quote = await quoteRes.json();

            // 2. Execute the bridge transaction
            // For native ETH bridges, Relay returns a single deposit step
            const txData = quote.steps[0].items[0].data;
            await evmWallet.sendTransaction({
                to: txData.to,
                data: txData.data,
                value: txData.value ? BigInt(txData.value) : 0n,
            });

            // 3. Poll Relay for bridge status
            const requestId = quote.steps[0].requestId;
            let status = "pending";
            while (status === "pending") {
                await new Promise((r) => setTimeout(r, 5000));
                const statusRes = await fetch(
                    `${RELAY_API}/intents/status/v3?requestId=${requestId}`
                );
                const s = await statusRes.json();
                status = s.status;
            }
            if (status !== "success") {
                throw new Error(`Bridge failed with status: ${status}`);
            }
        }

        return (
            <button onClick={() => bridge("0.001")}>
                Bridge ETH to Arbitrum
            </button>
        );
    }
    ```

    See the [React SDK reference](/sdk-reference/wallets/react/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { useWallet, EVMWallet } from "@crossmint/client-sdk-react-native-ui";
    import { View, Button } from "react-native";
    import { parseEther } from "viem";

    const RELAY_API = "https://api.relay.link";
    const ORIGIN_CHAIN_ID = 8453; // Base
    const DESTINATION_CHAIN_ID = 42161; // Arbitrum
    const ETH_TOKEN_ADDRESS = "0x0000000000000000000000000000000000000000";

    export function BridgeComponent() {
        const { wallet } = useWallet();

        async function bridge(amount: string) {
            if (!wallet) return;
            const evmWallet = EVMWallet.from(wallet);

            // 1. Get a bridge quote from Relay
            const quoteRes = await fetch(`${RELAY_API}/quote/v2`, {
                method: "POST",
                headers: { "Content-Type": "application/json" },
                body: JSON.stringify({
                    user: wallet.address,
                    originChainId: ORIGIN_CHAIN_ID,
                    destinationChainId: DESTINATION_CHAIN_ID,
                    originCurrency: ETH_TOKEN_ADDRESS,
                    destinationCurrency: ETH_TOKEN_ADDRESS,
                    amount: parseEther(amount).toString(),
                    tradeType: "EXACT_INPUT",
                }),
            });
            if (!quoteRes.ok) {
                throw new Error(`Quote request failed: ${quoteRes.status}`);
            }
            const quote = await quoteRes.json();

            // 2. Execute the bridge transaction
            // For native ETH bridges, Relay returns a single deposit step
            const txData = quote.steps[0].items[0].data;
            await evmWallet.sendTransaction({
                to: txData.to,
                data: txData.data,
                value: txData.value ? BigInt(txData.value) : 0n,
            });

            // 3. Poll Relay for bridge status
            const requestId = quote.steps[0].requestId;
            let status = "pending";
            while (status === "pending") {
                await new Promise((r) => setTimeout(r, 5000));
                const statusRes = await fetch(
                    `${RELAY_API}/intents/status/v3?requestId=${requestId}`
                );
                const s = await statusRes.json();
                status = s.status;
            }
            if (status !== "success") {
                throw new Error(`Bridge failed with status: ${status}`);
            }
        }

        return (
            <View>
                <Button
                    title="Bridge ETH to Arbitrum"
                    onPress={() => bridge("0.001")}
                />
            </View>
        );
    }
    ```

    See the [React Native SDK reference](/sdk-reference/wallets/react-native/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { CrossmintWallets, createCrossmint, EVMWallet } from "@crossmint/wallets-sdk";
    import { parseEther } from "viem";

    const crossmint = createCrossmint({
        apiKey: "YOUR_SERVER_API_KEY",
    });
    const crossmintWallets = CrossmintWallets.from(crossmint);

    const wallet = await crossmintWallets.getWallet(
        "email:user@example.com",
        { chain: "base" }
    );
    if (!wallet) throw new Error("Wallet not found");
    await wallet.useSigner({ type: "email", email: "user@example.com" });
    const evmWallet = EVMWallet.from(wallet);

    const RELAY_API = "https://api.relay.link";
    const ORIGIN_CHAIN_ID = 8453; // Base
    const DESTINATION_CHAIN_ID = 42161; // Arbitrum
    const ETH_TOKEN_ADDRESS = "0x0000000000000000000000000000000000000000";
    const amount = "0.001";

    // 1. Get a bridge quote from Relay
    const quoteRes = await fetch(`${RELAY_API}/quote/v2`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
            user: wallet.address,
            originChainId: ORIGIN_CHAIN_ID,
            destinationChainId: DESTINATION_CHAIN_ID,
            originCurrency: ETH_TOKEN_ADDRESS,
            destinationCurrency: ETH_TOKEN_ADDRESS,
            amount: parseEther(amount).toString(),
            tradeType: "EXACT_INPUT",
        }),
    });
    if (!quoteRes.ok) {
        throw new Error(`Quote request failed: ${quoteRes.status}`);
    }
    const quote = await quoteRes.json();

    // 2. Execute the bridge transaction
    // For native ETH bridges, Relay returns a single deposit step
    const txData = quote.steps[0].items[0].data;
    await evmWallet.sendTransaction({
        to: txData.to,
        data: txData.data,
        value: txData.value ? BigInt(txData.value) : 0n,
    });

    // 3. Poll Relay for bridge status
    const requestId = quote.steps[0].requestId;
    let status = "pending";
    while (status === "pending") {
        await new Promise((r) => setTimeout(r, 5000));
        const statusRes = await fetch(
            `${RELAY_API}/intents/status/v3?requestId=${requestId}`
        );
        const s = await statusRes.json();
        status = s.status;
    }
    if (status !== "success") {
        throw new Error(`Bridge failed with status: ${status}`);
    }

    console.log("Bridge complete!");
    ```
  </Tab>

  <Tab title="REST">
    Transactions must be approved by one of the wallet's [signers](/wallets/concepts/signers).
    The SDK handles this automatically, but with the REST API you must [approve the transaction](/api-reference/wallets/approve-transaction) to complete it.

    <Steps>
      <Step title="Get a bridge quote from Relay">
        Call the <a href="https://docs.relay.link/references/api/get-quote-v2">Relay API</a> `/quote/v2` endpoint with the origin and destination chain, token addresses, and amount.

        <CodeGroup>
          ```js Node.js theme={null}
          const response = await fetch(
              "https://api.relay.link/quote/v2",
              {
                  method: "POST",
                  headers: {
                      "Content-Type": "application/json",
                  },
                  body: JSON.stringify({
                      user: "YOUR_WALLET_ADDRESS",
                      originChainId: 8453,
                      destinationChainId: 42161,
                      originCurrency:
                          "0x0000000000000000000000000000000000000000",
                      destinationCurrency:
                          "0x0000000000000000000000000000000000000000",
                      amount: "1000000000000000",
                      tradeType: "EXACT_INPUT",
                  }),
              }
          );
          const quote = await response.json();
          ```

          ```bash cURL theme={null}
          curl --request POST \
              --url 'https://api.relay.link/quote/v2' \
              --header 'Content-Type: application/json' \
              --data '{
                  "user": "YOUR_WALLET_ADDRESS",
                  "originChainId": 8453,
                  "destinationChainId": 42161,
                  "originCurrency": "0x0000000000000000000000000000000000000000",
                  "destinationCurrency": "0x0000000000000000000000000000000000000000",
                  "amount": "1000000000000000",
                  "tradeType": "EXACT_INPUT"
              }'
          ```

          ```python Python theme={null}
          import requests

          response = requests.post(
              "https://api.relay.link/quote/v2",
              json={
                  "user": "YOUR_WALLET_ADDRESS",
                  "originChainId": 8453,
                  "destinationChainId": 42161,
                  "originCurrency": "0x0000000000000000000000000000000000000000",
                  "destinationCurrency": "0x0000000000000000000000000000000000000000",
                  "amount": "1000000000000000",
                  "tradeType": "EXACT_INPUT",
              },
          )
          quote = response.json()
          ```
        </CodeGroup>

        The response includes `steps[]` with transaction calldata and a `requestId` for tracking.
      </Step>

      <Step title="Execute the bridge transaction">
        Use the transaction data from `quote.steps[0].items[0].data` to send the bridge transaction via the Crossmint REST API.

        Follow the steps in the [Send a transaction](/wallets/guides/send-transaction-evm#rest) guide to submit the transaction via the Crossmint REST API.
      </Step>

      <Step title="Poll for bridge status">
        Call the Relay `/intents/status/v3` endpoint every five seconds until the bridge completes.

        <CodeGroup>
          ```js Node.js theme={null}
          const statusRes = await fetch(
              `https://api.relay.link/intents/status/v3?requestId=YOUR_REQUEST_ID`
          );
          const status = await statusRes.json();
          // status.status is "pending", "success", or "failure"
          ```

          ```bash cURL theme={null}
          curl --request GET \
              --url 'https://api.relay.link/intents/status/v3?requestId=YOUR_REQUEST_ID'
          ```

          ```python Python theme={null}
          import requests

          response = requests.get(
              "https://api.relay.link/intents/status/v3",
              params={
                  "requestId": "YOUR_REQUEST_ID",
              },
          )
          status = response.json()
          # status["status"] is "pending", "success", or "failure"
          ```
        </CodeGroup>

        The bridge is complete when `status` is `success`. If `failure`, check the transaction on the block explorer for details.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Swap Tokens

Swapping exchanges one token for another across chains or within the same chain. This example swaps USDC on Base for USDC on Arbitrum. The same pattern works for any token pair that Relay supports.

For ERC-20 swaps, Relay may return multiple steps — an **approval** step followed by a **deposit** step. The code below iterates through all steps to handle both cases.

High level steps:

1. Request a swap quote from the Relay `/quote/v2` endpoint
2. Execute all steps from the quote (approval + deposit)
3. Poll the Relay `/intents/status/v3` endpoint until the swap completes

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet, EVMWallet } from "@crossmint/client-sdk-react-ui";
    import { parseUnits } from "viem";

    const RELAY_API = "https://api.relay.link";
    const ORIGIN_CHAIN_ID = 8453; // Base
    const DESTINATION_CHAIN_ID = 42161; // Arbitrum
    const BASE_USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
    const ARB_USDC = "0xaf88d065e77c8cC2239327C5EDb3A432268e5831";
    const USDC_DECIMALS = 6;

    export function SwapComponent() {
        const { wallet } = useWallet();

        async function swap(amount: string) {
            if (!wallet) return;
            const evmWallet = EVMWallet.from(wallet);

            // 1. Get a swap quote from Relay
            const quoteRes = await fetch(`${RELAY_API}/quote/v2`, {
                method: "POST",
                headers: { "Content-Type": "application/json" },
                body: JSON.stringify({
                    user: wallet.address,
                    originChainId: ORIGIN_CHAIN_ID,
                    destinationChainId: DESTINATION_CHAIN_ID,
                    originCurrency: BASE_USDC,
                    destinationCurrency: ARB_USDC,
                    amount: parseUnits(amount, USDC_DECIMALS).toString(),
                    tradeType: "EXACT_INPUT",
                }),
            });
            if (!quoteRes.ok) {
                throw new Error(`Quote request failed: ${quoteRes.status}`);
            }
            const quote = await quoteRes.json();

            // 2. Execute all steps (approval + deposit)
            for (const step of quote.steps) {
                for (const item of step.items) {
                    if (item.status === "incomplete") {
                        await evmWallet.sendTransaction({
                            to: item.data.to,
                            data: item.data.data,
                            value: item.data.value
                                ? BigInt(item.data.value)
                                : 0n,
                        });
                    }
                }
            }

            // 3. Poll Relay for swap status
            const depositStep = quote.steps.find((s: { id: string }) => s.id === "deposit");
            if (!depositStep) throw new Error("No deposit step found in quote response");
            const requestId = depositStep.requestId;
            let status = "pending";
            while (status === "pending") {
                await new Promise((r) => setTimeout(r, 5000));
                const statusRes = await fetch(
                    `${RELAY_API}/intents/status/v3?requestId=${requestId}`
                );
                const s = await statusRes.json();
                status = s.status;
            }
            if (status !== "success") {
                throw new Error(`Swap failed with status: ${status}`);
            }
        }

        return (
            <button onClick={() => swap("5")}>
                Swap USDC to Arbitrum
            </button>
        );
    }
    ```

    See the [React SDK reference](/sdk-reference/wallets/react/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { useWallet, EVMWallet } from "@crossmint/client-sdk-react-native-ui";
    import { View, Button } from "react-native";
    import { parseUnits } from "viem";

    const RELAY_API = "https://api.relay.link";
    const ORIGIN_CHAIN_ID = 8453; // Base
    const DESTINATION_CHAIN_ID = 42161; // Arbitrum
    const BASE_USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
    const ARB_USDC = "0xaf88d065e77c8cC2239327C5EDb3A432268e5831";
    const USDC_DECIMALS = 6;

    export function SwapComponent() {
        const { wallet } = useWallet();

        async function swap(amount: string) {
            if (!wallet) return;
            const evmWallet = EVMWallet.from(wallet);

            // 1. Get a swap quote from Relay
            const quoteRes = await fetch(`${RELAY_API}/quote/v2`, {
                method: "POST",
                headers: { "Content-Type": "application/json" },
                body: JSON.stringify({
                    user: wallet.address,
                    originChainId: ORIGIN_CHAIN_ID,
                    destinationChainId: DESTINATION_CHAIN_ID,
                    originCurrency: BASE_USDC,
                    destinationCurrency: ARB_USDC,
                    amount: parseUnits(amount, USDC_DECIMALS).toString(),
                    tradeType: "EXACT_INPUT",
                }),
            });
            if (!quoteRes.ok) {
                throw new Error(`Quote request failed: ${quoteRes.status}`);
            }
            const quote = await quoteRes.json();

            // 2. Execute all steps (approval + deposit)
            for (const step of quote.steps) {
                for (const item of step.items) {
                    if (item.status === "incomplete") {
                        await evmWallet.sendTransaction({
                            to: item.data.to,
                            data: item.data.data,
                            value: item.data.value
                                ? BigInt(item.data.value)
                                : 0n,
                        });
                    }
                }
            }

            // 3. Poll Relay for swap status
            const depositStep = quote.steps.find((s: { id: string }) => s.id === "deposit");
            if (!depositStep) throw new Error("No deposit step found in quote response");
            const requestId = depositStep.requestId;
            let status = "pending";
            while (status === "pending") {
                await new Promise((r) => setTimeout(r, 5000));
                const statusRes = await fetch(
                    `${RELAY_API}/intents/status/v3?requestId=${requestId}`
                );
                const s = await statusRes.json();
                status = s.status;
            }
            if (status !== "success") {
                throw new Error(`Swap failed with status: ${status}`);
            }
        }

        return (
            <View>
                <Button
                    title="Swap USDC to Arbitrum"
                    onPress={() => swap("5")}
                />
            </View>
        );
    }
    ```

    See the [React Native SDK reference](/sdk-reference/wallets/react-native/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { CrossmintWallets, createCrossmint, EVMWallet } from "@crossmint/wallets-sdk";
    import { parseUnits } from "viem";

    const crossmint = createCrossmint({
        apiKey: "YOUR_SERVER_API_KEY",
    });
    const crossmintWallets = CrossmintWallets.from(crossmint);

    const wallet = await crossmintWallets.getWallet(
        "email:user@example.com",
        { chain: "base" }
    );
    if (!wallet) throw new Error("Wallet not found");
    await wallet.useSigner({ type: "email", email: "user@example.com" });
    const evmWallet = EVMWallet.from(wallet);

    const RELAY_API = "https://api.relay.link";
    const ORIGIN_CHAIN_ID = 8453; // Base
    const DESTINATION_CHAIN_ID = 42161; // Arbitrum
    const BASE_USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
    const ARB_USDC = "0xaf88d065e77c8cC2239327C5EDb3A432268e5831";
    const USDC_DECIMALS = 6;
    const amount = "5";

    // 1. Get a swap quote from Relay
    const quoteRes = await fetch(`${RELAY_API}/quote/v2`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
            user: wallet.address,
            originChainId: ORIGIN_CHAIN_ID,
            destinationChainId: DESTINATION_CHAIN_ID,
            originCurrency: BASE_USDC,
            destinationCurrency: ARB_USDC,
            amount: parseUnits(amount, USDC_DECIMALS).toString(),
            tradeType: "EXACT_INPUT",
        }),
    });
    if (!quoteRes.ok) {
        throw new Error(`Quote request failed: ${quoteRes.status}`);
    }
    const quote = await quoteRes.json();

    // 2. Execute all steps (approval + deposit)
    for (const step of quote.steps) {
        for (const item of step.items) {
            if (item.status === "incomplete") {
                await evmWallet.sendTransaction({
                    to: item.data.to,
                    data: item.data.data,
                    value: item.data.value ? BigInt(item.data.value) : 0n,
                });
            }
        }
    }

    // 3. Poll Relay for swap status
    const depositStep = quote.steps.find((s: { id: string }) => s.id === "deposit");
    if (!depositStep) throw new Error("No deposit step found in quote response");
    const requestId = depositStep.requestId;
    let status = "pending";
    while (status === "pending") {
        await new Promise((r) => setTimeout(r, 5000));
        const statusRes = await fetch(
            `${RELAY_API}/intents/status/v3?requestId=${requestId}`
        );
        const s = await statusRes.json();
        status = s.status;
    }
    if (status !== "success") {
        throw new Error(`Swap failed with status: ${status}`);
    }

    console.log("Swap complete!");
    ```
  </Tab>

  <Tab title="REST">
    Transactions must be approved by one of the wallet's [signers](/wallets/concepts/signers).
    The SDK handles this automatically, but with the REST API you must [approve the transaction](/api-reference/wallets/approve-transaction) to complete it.

    <Steps>
      <Step title="Get a swap quote from Relay">
        Call the <a href="https://docs.relay.link/references/api/get-quote-v2">Relay API</a> `/quote/v2` endpoint with the origin and destination tokens and amount.

        <CodeGroup>
          ```js Node.js theme={null}
          const response = await fetch(
              "https://api.relay.link/quote/v2",
              {
                  method: "POST",
                  headers: {
                      "Content-Type": "application/json",
                  },
                  body: JSON.stringify({
                      user: "YOUR_WALLET_ADDRESS",
                      originChainId: 8453,
                      destinationChainId: 42161,
                      originCurrency:
                          "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                      destinationCurrency:
                          "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
                      amount: "5000000",
                      tradeType: "EXACT_INPUT",
                  }),
              }
          );
          const quote = await response.json();
          ```

          ```bash cURL theme={null}
          curl --request POST \
              --url 'https://api.relay.link/quote/v2' \
              --header 'Content-Type: application/json' \
              --data '{
                  "user": "YOUR_WALLET_ADDRESS",
                  "originChainId": 8453,
                  "destinationChainId": 42161,
                  "originCurrency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                  "destinationCurrency": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
                  "amount": "5000000",
                  "tradeType": "EXACT_INPUT"
              }'
          ```

          ```python Python theme={null}
          import requests

          response = requests.post(
              "https://api.relay.link/quote/v2",
              json={
                  "user": "YOUR_WALLET_ADDRESS",
                  "originChainId": 8453,
                  "destinationChainId": 42161,
                  "originCurrency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                  "destinationCurrency": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
                  "amount": "5000000",
                  "tradeType": "EXACT_INPUT",
              },
          )
          quote = response.json()
          ```
        </CodeGroup>

        The response includes `steps[]` — for ERC-20 swaps this may include an approval step followed by a deposit step.
      </Step>

      <Step title="Execute all steps from the quote">
        Iterate through each step in `quote.steps` and each item in `step.items`. For items with `status: "incomplete"`, send a transaction using the `item.data` fields (`to`, `data`, `value`).

        1. **Approval** (if present) — grants the Relay contract permission to spend the source token
        2. **Deposit** — executes the swap

        Follow the steps in the [Send a transaction](/wallets/guides/send-transaction-evm#rest) guide to submit each transaction via the Crossmint REST API.
      </Step>

      <Step title="Poll for swap status">
        Call the Relay `/intents/status/v3` endpoint every five seconds until the swap completes.

        <CodeGroup>
          ```js Node.js theme={null}
          const statusRes = await fetch(
              `https://api.relay.link/intents/status/v3?requestId=YOUR_REQUEST_ID`
          );
          const status = await statusRes.json();
          // status.status is "pending", "success", or "failure"
          ```

          ```bash cURL theme={null}
          curl --request GET \
              --url 'https://api.relay.link/intents/status/v3?requestId=YOUR_REQUEST_ID'
          ```

          ```python Python theme={null}
          import requests

          response = requests.get(
              "https://api.relay.link/intents/status/v3",
              params={
                  "requestId": "YOUR_REQUEST_ID",
              },
          )
          status = response.json()
          # status["status"] is "pending", "success", or "failure"
          ```
        </CodeGroup>

        The swap is complete when `status` is `success`. If `failure`, check the transaction on the block explorer for details.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Customizing the Route

You can bridge or swap any token pair that Relay supports by changing the chain IDs and token addresses:

```typescript theme={null}
const ORIGIN_CHAIN_ID = 1; // Ethereum
const DESTINATION_CHAIN_ID = 10; // Optimism
const ORIGIN_CURRENCY =
    "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"; // USDC on Ethereum
const DESTINATION_CURRENCY =
    "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85"; // USDC on Optimism
```

See the full list of supported chains in the <a href="https://docs.relay.link/resources/supported-chains">Relay documentation</a>.

## Testing the Integration

To test the integration end-to-end:

1. Create a Crossmint wallet on Base using the <a href="https://www.crossmint.com/console">Crossmint Console</a>
2. Fund the wallet with a small amount of ETH on Base for gas (and USDC if testing the swap)
3. Run the bridge or swap code with a small amount (for example, 0.001 ETH for bridging or 1 USDC for swapping)
4. Verify the transaction completes by checking the status polling returns `success`
5. Confirm the destination wallet balance updated on the destination chain using the [Check Balances](/wallets/guides/check-balances) guide

<Note>
  Relay also supports testnets (Base Sepolia, Sepolia, etc.), but testnet availability may vary. Check the <a href="https://docs.relay.link/resources/supported-chains">Relay supported chains page</a> for the latest testnet status.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Transaction Fails with Insufficient Balance">
    Verify the wallet holds enough tokens on the source chain and ETH for gas fees.
    Use the [Check Balances](/wallets/guides/check-balances) guide to confirm token balances before bridging or swapping.
  </Accordion>

  <Accordion title="Quote Request Returns an Error">
    Ensure the `user` address is a valid wallet address and the `amount` is in the smallest unit (wei for ETH, or the token's smallest denomination — for example, 6 decimals for USDC).
    Verify the origin and destination chain IDs and token addresses are correct.
    Check the <a href="https://docs.relay.link/resources/supported-chains">Relay supported chains</a> to confirm the route is available.
  </Accordion>

  <Accordion title="ERC-20 Swap Requires Multiple Transactions">
    For ERC-20 tokens, Relay may return an approval step before the deposit step. Make sure to iterate through all `steps` and all `items` within each step. Only execute items where `status` is `"incomplete"`.
  </Accordion>

  <Accordion title="Bridge or Swap Status Stays Pending for a Long Time">
    Cross-chain operations can take several minutes depending on the route and chain congestion.
    If the status does not change after 10 minutes, check the source transaction on a block explorer to verify it was included.
  </Accordion>

  <Accordion title="Deposits Not Detected by Relay (Smart Contract Wallets)">
    If Relay is not detecting deposits from a Crossmint smart wallet, try adding `useReceiver: true` to the quote request body. This routes the payment through a receiver contract that emits events, allowing the Relay solver to detect deposits from smart contract wallets.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Check Balances" icon="wallet" href="/wallets/guides/check-balances">
    Verify updated token balances after bridging or swapping on any chain
  </Card>

  <Card title="Bridge with LI.FI" icon="bridge" href="/wallets/guides/wallet-extensions/bridge-lifi">
    Compare with the LI.FI bridging integration for alternative routes
  </Card>
</CardGroup>


# Jupiter
Source: https://docs.crossmint.com/wallets/guides/wallet-extensions/swap-jupiter

Swap tokens using Jupiter in Solana

## Prerequisites

* Ensure you have a wallet created.
* **API Key**: Ensure you have an API key with the scopes: `wallets:transactions.create`.

## Swap Tokens

This guide explains how to swap tokens in Solana using the Jupiter advanced routing engine, which requires special configuration to work with smart wallets.
If you're using EVM chains, you can use [0x](https://0x.org/docs/api) or [1inch](https://1inch.io/page-api/) directly.

To perform a swap with the Jupiter Swap API and Crossmint wallets, follow these steps:

1. [Request a quote from the Jupiter API](https://dev.jup.ag/docs/api/swap-api/quote).
2. [Build the swap transaction for that quote using the Jupiter API](https://dev.jup.ag/docs/api/swap-api/swap).
3. Send the transaction using the Crossmint wallet.

<Note>
  For tokens with lower liquidity, the number of hops required to reach the destination token may be higher. This can
  make the transaction size larger and increase the risk of failure. To minimize this risk, always set maxAccounts=33
  when building the swap transaction. This ensures that even multi-hop swaps fit within Solana's transaction account
  limits and execute reliably.
</Note>

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet, SolanaWallet } from '@crossmint/client-sdk-react-ui';
    import { VersionedTransaction } from '@solana/web3.js';

    export function SwapTokensComponent() {
        const { wallet } = useWallet();

        async function swapTokens(tokenIn: string, tokenOut: string, amount: number) {
            if (!wallet) return;

            // Get a quote from the Jupiter API
            const queryParams = new URLSearchParams({
                inputMint: tokenIn, // e.g "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
                outputMint: tokenOut, // e.g "XsCPL9dNWBMvFtTmwcCA5v3xWPSMEBCszbQdiLLq6aN"
                amount: amount.toString(), // In lamports!
                slippageBps: "50",
                maxAccounts: "33", // This ensures that even multi-hop swaps fit within Solana's transaction account limits and execute reliably.
            });

            const response = await fetch(`https://lite-api.jup.ag/swap/v1/quote?${queryParams}`, {
                method: "GET",
                headers: {
                    "Content-Type": "application/json",
                },
            });

            const quoteResponse = await response.json();

            // Build the swap transaction
            const swapResponse = await fetch("https://lite-api.jup.ag/swap/v1/swap", {
                method: "POST",
                headers: {
                    "Content-Type": "application/json",
                },
                body: JSON.stringify({
                    userPublicKey: wallet.address,
                    quoteResponse: quoteResponse,
                }),
            });

            const swapResponseData = await swapResponse.json();

            // Send the transaction
            const solanaWallet = SolanaWallet.from(wallet);

            const versionedTransaction = VersionedTransaction.deserialize(
                Buffer.from(swapResponseData.swapTransaction, "base64")
            );

            const tx = await solanaWallet.sendTransaction({
                transaction: versionedTransaction,
            });

            console.log("Swap transaction sent successfully!");
        }

        return (
            <div>
                <button onClick={() => swapTokens("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "XsCPL9dNWBMvFtTmwcCA5v3xWPSMEBCszbQdiLLq6aN", 1)}>Swap Tokens</button>
            </div>
        );
    }
    ```

    See the [React SDK reference](/sdk-reference/wallets/react/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { CrossmintWallets, createCrossmint, SolanaWallet } from "@crossmint/wallets-sdk";
    import { VersionedTransaction } from "@solana/web3.js";

    const crossmint = createCrossmint({
        apiKey: "<your-server-api-key>",
    });

    const crossmintWallets = CrossmintWallets.from(crossmint);

    const wallet = await crossmintWallets.getWallet(
        "email:user@example.com:solana",
        { chain: "solana" }
    );

    await wallet.useSigner({ type: "email" });

    // Get a quote from the Jupiter API
    const tokenIn = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
    const tokenOut = "XsCPL9dNWBMvFtTmwcCA5v3xWPSMEBCszbQdiLLq6aN";
    const amount = 1000000000;

    const queryParams = new URLSearchParams({
        inputMint: tokenIn,
        outputMint: tokenOut,
        amount: amount.toString(), // In lamports!
        slippageBps: "50",
        maxAccounts: "33", // This ensures that even multi-hop swaps fit within Solana's transaction account limits and execute reliably.
    });

    const response = await fetch(`https://lite-api.jup.ag/swap/v1/quote?${queryParams}`, {
        method: "GET",
        headers: {
            "Content-Type": "application/json",
        },
    });

    const quoteResponse = await response.json();

    // Build the swap transaction
    const swapResponse = await fetch("https://lite-api.jup.ag/swap/v1/swap", {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
        },
        body: JSON.stringify({
            userPublicKey: wallet.address,
            quoteResponse: quoteResponse,
        }),
    });

    const swapResponseData = await swapResponse.json();

    // Send the transaction
    const solanaWallet = SolanaWallet.from(wallet);

    const versionedTransaction = VersionedTransaction.deserialize(
        Buffer.from(swapResponseData.swapTransaction, "base64")
    );

    const tx = await solanaWallet.sendTransaction({
        transaction: versionedTransaction,
    });

    console.log("Swap transaction sent successfully!");
    ```
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { useWallet, SolanaWallet } from '@crossmint/client-sdk-react-native-ui';
    import { View, Button } from 'react-native';
    import { VersionedTransaction } from '@solana/web3.js';

    export function SwapTokensComponent() {
        const { wallet } = useWallet();

        async function swapTokens(tokenIn: string, tokenOut: string, amount: number) {
            if (!wallet) return;
            // Get a quote from the Jupiter API
            const queryParams = new URLSearchParams({
                inputMint: tokenIn, // e.g "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
                outputMint: tokenOut, // e.g "XsCPL9dNWBMvFtTmwcCA5v3xWPSMEBCszbQdiLLq6aN"
                amount: amount.toString(), // In lamports!
                slippageBps: "50",
                maxAccounts: "33", // This ensures that even multi-hop swaps fit within Solana's transaction account limits and execute reliably.
            });

            const response = await fetch(`https://lite-api.jup.ag/swap/v1/quote?${queryParams}`, {
                method: "GET",
                headers: {
                    "Content-Type": "application/json",
                },
            });

            const quoteResponse = await response.json();

            // Build the swap transaction
            const swapResponse = await fetch("https://lite-api.jup.ag/swap/v1/swap", {
                method: "POST",
                headers: {
                    "Content-Type": "application/json",
                },
                body: JSON.stringify({
                    userPublicKey: wallet.address,
                    quoteResponse: quoteResponse,
                }),
            });

            const swapResponseData = await swapResponse.json();

            // Send the transaction
            const solanaWallet = SolanaWallet.from(wallet);

            const versionedTransaction = VersionedTransaction.deserialize(
                Buffer.from(swapResponseData.swapTransaction, "base64")
            );

            const tx = await solanaWallet.sendTransaction({
                transaction: versionedTransaction,
            });

            console.log("Swap transaction sent successfully!");
        }

        return (
            <View>
                <Button onPress={() => swapTokens("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "XsCPL9dNWBMvFtTmwcCA5v3xWPSMEBCszbQdiLLq6aN", 1)}>Swap Tokens</Button>
            </View>
        );
    }
    ```

    See the [React Native SDK reference](/sdk-reference/wallets/react-native/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="REST">
    Transactions must be approved by one of the wallet's [signers](/wallets/concepts/signers).
    The SDK handles this automatically, but with the REST API you must [approve the transaction](/api-reference/wallets/approve-transaction) to complete it.

    <Steps>
      <Step title="Call the get quote endpoint">
        Call the [get quote endpoint](https://dev.jup.ag/docs/api/swap-api/quote) to get a quote for the swap.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://lite-api.jup.ag/swap/v1/quote?inputMint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&outputMint=XsCPL9dNWBMvFtTmwcCA5v3xWPSMEBCszbQdiLLq6aN&amount=1000000000&slippageBps=50&maxAccounts=33 \
              --header 'Content-Type: application/json'
          ```

          ```js Node.js theme={null}
          const url = 'https://lite-api.jup.ag/swap/v1/quote?inputMint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&outputMint=XsCPL9dNWBMvFtTmwcCA5v3xWPSMEBCszbQdiLLq6aN&amount=1000000000&slippageBps=50&maxAccounts=33';
          const options = {
              method: 'GET',
              headers: {'Content-Type': 'application/json'},
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```python Python theme={null}
          import requests

          url = "https://lite-api.jup.ag/swap/v1/quote?inputMint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&outputMint=XsCPL9dNWBMvFtTmwcCA5v3xWPSMEBCszbQdiLLq6aN&amount=1000000000&slippageBps=50&maxAccounts=33"

          headers = {
              "Content-Type": "application/json"
          }

          response = requests.get(url, headers=headers)

          print(response.json())
          ```
        </CodeGroup>

        See the [Jupiter API docs](https://dev.jup.ag/docs/api/swap-api/quote) for more details.
      </Step>

      <Step title="Build the swap transaction">
        Build the swap transaction using the [swap endpoint](https://dev.jup.ag/docs/api/swap-api/swap) and pass in the quote response from the previous step.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://lite-api.jup.ag/swap/v1/swap \
              --header 'Content-Type: application/json' \
              --data '{"userPublicKey": "YOUR_WALLET_ADDRESS", "quoteResponse": YOUR_QUOTE_RESPONSE}'
          ```

          ```js Node.js theme={null}
          // quoteResponse is the JSON response from the quote endpoint in the previous step
          const url = 'https://lite-api.jup.ag/swap/v1/swap';
          const options = {
              method: 'POST',
              headers: {'Content-Type': 'application/json'},
              body: JSON.stringify({
                  userPublicKey: "YOUR_WALLET_ADDRESS",
                  quoteResponse: quoteResponse,
              })
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```python Python theme={null}
          import requests

          # quote_response is the JSON response from the quote endpoint in the previous step
          url = "https://lite-api.jup.ag/swap/v1/swap"

          headers = {
              "Content-Type": "application/json"
          }

          payload = {
              "userPublicKey": "YOUR_WALLET_ADDRESS",
              "quoteResponse": quote_response,
          }

          response = requests.post(url, json=payload, headers=headers)

          print(response.json())
          ```
        </CodeGroup>

        See the [Jupiter API docs](https://dev.jup.ag/docs/api/swap-api/swap) for more details.
      </Step>

      <Step title="Send the transaction">
        Follow the steps in the [Send a transaction](/wallets/guides/send-transaction-solana#rest) guide to submit the returned transaction in the previous step.
      </Step>
    </Steps>
  </Tab>
</Tabs>


# Ondo Global Markets
Source: https://docs.crossmint.com/wallets/guides/wallet-extensions/swap-ondo

Swap USDC for Ondo Global Markets tokenized stocks

<a href="https://ondo.finance/global-markets">Ondo Global Markets</a> offers tokenized versions of publicly-traded stocks and ETFs on Solana. These tokens (such as NVDAon for Nvidia, TSLAon for Tesla, and SPYon for S\&P 500) can be swapped on decentralized exchanges via <a href="https://jup.ag">Jupiter</a>, making them accessible to both human users and AI agents through Crossmint wallets.

This guide demonstrates how to swap USDC for Ondo GM tokens using the Jupiter swap API with Crossmint wallets on Solana.

## Prerequisites

* A Crossmint wallet on Solana with USDC balance. See the [wallets quickstart](/wallets/quickstarts/nodejs) to create one.
* **API Key**: A server-side API key (`sk_...`) with the scope `wallets:transactions.create`.
* The Solana mint address for your target Ondo token. Find all available Ondo tokens and their liquidity on the <a href="https://jup.ag/tokens/ondo">Jupiter Ondo screener</a>.

## Swap USDC for Ondo Tokens

The swap flow uses the same pattern as any Jupiter swap with Crossmint wallets:

1. Request a quote from the Jupiter API for the USDC to Ondo token pair.
2. Build the swap transaction using the Jupiter API.
3. Sign and send the transaction using the Crossmint wallet.

<Note>
  Ondo GM tokens on Jupiter may route through multiple AMM pools (such as Manifest, Meteora DLMM, or Raydium CLMM). Always set `maxAccounts=33` to ensure multi-hop swaps fit within Solana transaction account limits.
</Note>

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet, SolanaWallet } from "@crossmint/client-sdk-react-ui";
    import { VersionedTransaction } from "@solana/web3.js";

    const USDC_MINT = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
    const NVDA_ON_MINT = "gEGtLTPNQ7jcg25zTetkbmF7teoDLcrfTnQfmn2ondo";

    export function SwapToOndoComponent() {
        const { wallet } = useWallet();

        async function swapUsdcToOndo(ondoMint: string, amountUsdc: number) {
            if (!wallet) {
                return;
            }

            // 1. Get a quote from the Jupiter API
            const queryParams = new URLSearchParams({
                inputMint: USDC_MINT,
                outputMint: ondoMint,
                amount: amountUsdc.toString(),
                slippageBps: "300",
                maxAccounts: "33",
            });

            const quoteResponse = await fetch(
                `https://lite-api.jup.ag/swap/v1/quote?${queryParams}`
            );
            const quoteData = await quoteResponse.json();

            // 2. Build the swap transaction
            const swapResponse = await fetch("https://lite-api.jup.ag/swap/v1/swap", {
                method: "POST",
                headers: { "Content-Type": "application/json" },
                body: JSON.stringify({
                    userPublicKey: wallet.address,
                    quoteResponse: quoteData,
                }),
            });
            const swapData = await swapResponse.json();

            // 3. Sign and send the transaction
            const solanaWallet = SolanaWallet.from(wallet);
            const versionedTransaction = VersionedTransaction.deserialize(
                Buffer.from(swapData.swapTransaction, "base64")
            );

            const tx = await solanaWallet.sendTransaction({
                transaction: versionedTransaction,
            });

            console.log("Swap complete:", tx.hash);
        }

        return (
            <button onClick={() => swapUsdcToOndo(NVDA_ON_MINT, 1000000)}>
                Swap 1 USDC for NVDAon
            </button>
        );
    }
    ```
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { CrossmintWallets, createCrossmint, SolanaWallet } from "@crossmint/wallets-sdk";
    import { VersionedTransaction } from "@solana/web3.js";

    const USDC_MINT = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
    const NVDA_ON_MINT = "gEGtLTPNQ7jcg25zTetkbmF7teoDLcrfTnQfmn2ondo";

    const crossmint = createCrossmint({
        apiKey: "YOUR_SERVER_API_KEY",
    });

    const wallets = CrossmintWallets.from(crossmint);

    const wallet = await wallets.getWallet("email:USER_EMAIL:solana", {
        chain: "solana",
    });

    await wallet.useSigner({ type: "server", secret: "YOUR_SERVER_SIGNER_SECRET" });

    // 1. Get a quote from the Jupiter API
    const amountUsdc = "1000000"; // 1 USDC (6 decimals)
    const queryParams = new URLSearchParams({
        inputMint: USDC_MINT,
        outputMint: NVDA_ON_MINT,
        amount: amountUsdc,
        slippageBps: "300",
        maxAccounts: "33",
    });

    const quoteResponse = await fetch(
        `https://lite-api.jup.ag/swap/v1/quote?${queryParams}`
    );
    const quoteData = await quoteResponse.json();

    // 2. Build the swap transaction
    const swapResponse = await fetch("https://lite-api.jup.ag/swap/v1/swap", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
            userPublicKey: wallet.address,
            quoteResponse: quoteData,
        }),
    });
    const swapData = await swapResponse.json();

    // 3. Sign and send the transaction
    const solanaWallet = SolanaWallet.from(wallet);
    const versionedTransaction = VersionedTransaction.deserialize(
        Buffer.from(swapData.swapTransaction, "base64")
    );

    const tx = await solanaWallet.sendTransaction({
        transaction: versionedTransaction,
    });

    console.log("Swap complete:", tx.hash);
    ```
  </Tab>

  <Tab title="REST">
    Transactions must be approved by one of the wallet's [signers](/wallets/concepts/signers).
    The SDK handles this automatically, but with the REST API you must [approve the transaction](/api-reference/wallets/approve-transaction) to complete it.

    <Steps>
      <Step title="Get a quote from Jupiter">
        Call the Jupiter quote endpoint with the USDC mint as input and the Ondo token mint as output.

        ```bash cURL theme={null}
        curl --request GET \
            "https://lite-api.jup.ag/swap/v1/quote?inputMint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&outputMint=gEGtLTPNQ7jcg25zTetkbmF7teoDLcrfTnQfmn2ondo&amount=1000000&slippageBps=300&maxAccounts=33"
        ```
      </Step>

      <Step title="Build the swap transaction">
        Pass the quote response to the Jupiter swap endpoint along with your wallet address.

        ```bash cURL theme={null}
        curl --request POST \
            --url "https://lite-api.jup.ag/swap/v1/swap" \
            --header "Content-Type: application/json" \
            --data '{"userPublicKey": "YOUR_WALLET_ADDRESS", "quoteResponse": YOUR_QUOTE_RESPONSE}'
        ```
      </Step>

      <Step title="Send the transaction">
        Follow the steps in the [Send a transaction](/wallets/guides/send-transaction-solana#rest) guide to submit the returned transaction.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Next Steps

<CardGroup>
  <Card title="Jupiter Swap Guide" icon="arrow-right-arrow-left" href="/wallets/guides/wallet-extensions/swap-jupiter">
    Review the general Jupiter swap guide for additional configuration options.
  </Card>

  <Card title="Jupiter Ondo Screener" icon="magnifying-glass-chart" href="https://jup.ag/tokens/ondo">
    Explore all available Ondo tokens and their liquidity.
  </Card>

  <Card title="Ondo Global Markets" icon="building-columns" href="https://docs.ondo.finance/ondo-global-markets/overview">
    Learn about Ondo Global Markets tokenized assets.
  </Card>
</CardGroup>


# Swapping & Bridging Overview
Source: https://docs.crossmint.com/wallets/guides/wallet-extensions/swapping-and-bridging

Exchange tokens and move assets across chains with Crossmint wallets

Crossmint wallets support token swapping and cross-chain bridging through third-party protocols. This lets you build applications where users can exchange tokens or move assets between blockchains directly from their wallets.

## What is Swapping?

Token swapping is the exchange of one token for another on the **same blockchain**. For example, swapping USDC for SOL on Solana, or swapping ETH for USDC on Base. Swaps execute in a single transaction and settle instantly.

## What is Bridging?

Bridging moves tokens from one blockchain to another. For example, moving USDC from Base to Polygon. Bridges involve transactions on both the source and destination chains, and typically take a few minutes to complete depending on the chains involved.

## What are Cross-Chain Swaps?

Cross-chain swaps combine swapping and bridging into a single operation — converting a token on one chain into a different token on another chain. For example, swapping USDC on Ethereum for SOL on Solana in one step.

## Explore the Guides

<CardGroup>
  <Card title="Jupiter" icon="arrow-right-arrow-left" href="/wallets/guides/wallet-extensions/swap-jupiter" />

  <Card title="LI.FI" icon="bridge" href="/wallets/guides/wallet-extensions/bridge-lifi" />

  <Card title="Relay" icon="shuffle" href="/wallets/guides/wallet-extensions/relay" />
</CardGroup>


# Embedded Credit
Source: https://docs.crossmint.com/wallets/guides/wallet-extensions/tala

Offer Tala credit lines with your Crossmint wallet on Android

This guide explains how to embed <a href="https://docs.tala.co/">Tala</a> Credit-as-a-Service into an Android wallet built with Crossmint. You will learn how to authenticate a user, create or load a Crossmint wallet, launch Tala's lending flow, and handle the result.

## Prerequisites

To use Tala with Crossmint wallets, you need:

* **Crossmint wallet:** a [wallet](/wallets/guides/create-wallet) on Base Sepolia
* **API key:** a **staging** **Client API Key** with the scopes `users.create`, `users.read`, `wallets.create`, `wallets.read`, `wallets:transactions.create`, `wallets:transactions.sign`, `wallets:balance.read`, and `wallets.fund` (create in the <a href="https://console.crossmint.com/">Crossmint Console</a>). In staging, all scopes are included by default.
* **Android project:** an app with the Crossmint Kotlin SDK and the Tala Lending SDK AARs. This guide uses the sandbox module that Tala shares for evaluation.

This guide uses Base Sepolia and the Tala sandbox as examples. To follow along, you will also need:

* **Tala AARs:** the Tala SDK AAR (`lending-sdk-<VERSION>.aar`) and the sandbox AAR (`lending-sdk-sandbox-<VERSION>.aar`), which Tala shares with partners for evaluation. The sandbox AAR is a thin add-on and requires the main SDK AAR alongside it.
* **Test tokens:** test USDC or USDXM in the wallet (use [wallet.fund](/wallets/guides/fund-staging-wallet) or the <a href="https://faucet.circle.com/">Circle USDC Faucet</a>)
* **Gas:** ETH on Base Sepolia for gas fees (not required if [gas sponsorship](/wallets/guides/gas-sponsorship) is enabled)

In production, you need a Tala partnership and a production API key from the Tala team. Contact <a href="https://www.crossmint.com/contact/sales">Crossmint Sales</a> to get connected.

## What You Will Build

High-level steps:

1. Configure the Crossmint Kotlin SDK and the Tala sandbox SDK.
2. Authenticate the user with Crossmint Auth email OTP.
3. Create or load a Crossmint smart wallet on Base Sepolia.
4. Launch the Tala lending flow.
5. Handle the Tala result.

<Note>
  Tala's sandbox module is for UI/UX evaluation only. It does not call the Tala backend or move real funds.
  Production integration requires Tala partnership credentials.
</Note>

## Add the SDKs

<Steps>
  <Step title="Drop the Tala AARs into app/libs/">
    Tala provides the AARs directly to partners out-of-band. The main SDK artifact is `lending-sdk-<VERSION>.aar`; the sandbox artifact is `lending-sdk-sandbox-<VERSION>.aar`. For sandbox evaluation, drop both files into `app/libs/` (the sandbox module depends on the main SDK). In production, only the main SDK AAR is required.

    ```text theme={null}
    app/
    └── libs/
        ├── lending-sdk-<VERSION>.aar           ← from Tala
        └── lending-sdk-sandbox-<VERSION>.aar   ← from Tala (sandbox only)
    ```
  </Step>

  <Step title="Add repositories and dependencies">
    ```kotlin settings.gradle.kts theme={null}
    dependencyResolutionManagement {
        repositories {
            google()
            mavenCentral()
        }
    }
    ```

    ```kotlin app/build.gradle.kts theme={null}
    plugins {
        id("com.android.application")
        id("org.jetbrains.kotlin.android")
        id("org.jetbrains.kotlin.plugin.compose")
    }

    android {
        namespace = "com.example.app" // Replace with your package
        compileSdk = 35

        defaultConfig {
            applicationId = "com.example.app" // Replace with your app ID
            minSdk = 24
            targetSdk = 35
        }

        buildFeatures {
            compose = true
        }

        compileOptions {
            isCoreLibraryDesugaringEnabled = true
            sourceCompatibility = JavaVersion.VERSION_17
            targetCompatibility = JavaVersion.VERSION_17
        }

        kotlin {
            compilerOptions {
                jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17)
            }
        }
    }

    dependencies {
        // Crossmint Kotlin SDK
        implementation("com.crossmint:crossmint-sdk:1.1.1")
        implementation("com.crossmint:crossmint-compose:1.1.1")

        // Tala AARs — replace <VERSION> with the files Tala sent you
        implementation(files("libs/lending-sdk-<VERSION>.aar"))
        implementation(files("libs/lending-sdk-sandbox-<VERSION>.aar")) // sandbox only

        // Compose
        implementation("androidx.activity:activity-compose:1.9.3")
        implementation(platform("androidx.compose:compose-bom:2025.01.00"))
        implementation("androidx.compose.ui:ui")
        implementation("androidx.compose.material3:material3")

        // AARs referenced with files() do not carry transitive dependencies, so list the runtime deps explicitly
        implementation("androidx.core:core-ktx:1.13.1")
        implementation("androidx.appcompat:appcompat:1.7.0")
        implementation("androidx.cardview:cardview:1.0.0")
        implementation("androidx.recyclerview:recyclerview:1.3.2")
        implementation("androidx.databinding:viewbinding:8.7.3")
        implementation("androidx.fragment:fragment-ktx:1.8.5")
        implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.8.7")
        implementation("androidx.lifecycle:lifecycle-viewmodel-ktx:2.8.7")
        implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.9.0")

        coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.4")
    }
    ```
  </Step>

  <Step title="Initialize Crossmint and Tala">
    Initialize the Crossmint SDK in your `Application` class. For sandbox, call `TalaSandbox.init` instead of `TalaSDK.init` — it wires the SDK to bundled fixtures so no Tala backend or session token is needed.

    ```kotlin MyApplication.kt theme={null}
    import android.app.Application
    import com.crossmint.kotlin.CrossmintSDK
    import com.crossmint.kotlin.configure
    import com.crossmint.kotlin.core.LogLevel
    import com.tala.sdk.ConsentMode
    import com.tala.sdk.RepaymentConfig
    import com.tala.sdk.TalaConfig
    import com.tala.sdk.sandbox.TalaSandbox

    class MyApplication : Application() {
        override fun onCreate() {
            super.onCreate()

            CrossmintSDK.configure(
                apiKey = "YOUR_CROSSMINT_CLIENT_API_KEY",
                appContext = this,
                logLevel = LogLevel.DEBUG,
            )

            // Sandbox only — uses bundled fixtures, no Tala backend needed
            TalaSandbox.init(
                this,
                TalaConfig(
                    partnerName = "YOUR_PARTNER_NAME",
                    consentMode = ConsentMode.EXPLICIT,
                    privacyPolicyUrl = "YOUR_PRIVACY_POLICY_URL",
                    termsUrl = "YOUR_TERMS_URL",
                    repaymentConfig = RepaymentConfig.PartnerManaged(exitDeepLink = "YOUR_DEEP_LINK"),
                ),
            )
        }
    }
    ```

    <Note>
      `CrossmintSDK.configure` must be called on the main thread before any other Crossmint SDK call. The environment
      (staging vs production) is derived from the key prefix: staging keys start with `ck_staging_` and production keys
      with `ck_production_`.
    </Note>
  </Step>
</Steps>

## Authenticate and Create a Wallet

Wrap your Compose UI with `CrossmintNonCustodialSignerProvider` so the SDK can show the email OTP signer UI. Send an OTP, verify it, and create the wallet.

```kotlin MainActivity.kt theme={null}
import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.rememberLauncherForActivityResult
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.Button
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.material3.TextField
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.runtime.setValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import com.crossmint.kotlin.CrossmintSDK
import com.crossmint.kotlin.auth.CrossmintAuthManager
import com.crossmint.kotlin.auth.models.OTPAuthenticationStatus
import com.crossmint.kotlin.compose.CrossmintNonCustodialSignerProvider
import com.crossmint.kotlin.compose.LocalCrossmintSDK
import com.crossmint.kotlin.signers.SignerType
import com.crossmint.kotlin.types.EVMChain
import com.crossmint.kotlin.types.Result
import com.tala.sdk.TalaResult
import com.tala.sdk.TalaSDK
import com.tala.sdk.launch
import kotlinx.coroutines.launch

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            MaterialTheme {
                CrossmintNonCustodialSignerProvider {
                    TalaWalletApp()
                }
            }
        }
    }
}

@Composable
fun TalaWalletApp() {
    val sdk: CrossmintSDK = LocalCrossmintSDK.current
    val authManager = sdk.authManager as CrossmintAuthManager
    val scope = rememberCoroutineScope()

    var email by remember { mutableStateOf("") }
    var otp by remember { mutableStateOf("") }
    var status by remember { mutableStateOf("Ready") }
    var otpSent by remember { mutableStateOf(false) }

    val talaLauncher = rememberLauncherForActivityResult(
        contract = TalaSDK.Contract(),
    ) { result: TalaResult ->
        when (result) {
            is TalaResult.LoanAccepted -> { /* loan details arrive via the loan verification callback */ }
            is TalaResult.Abandoned -> { /* user dismissed the flow */ }
            is TalaResult.ConsentDeclined -> { /* user declined the consent screen */ }
            is TalaResult.NoLoanOffer -> { /* no offer available for this user */ }
            is TalaResult.Error -> { /* inspect the subtype and result.requestId */ }
        }
    }

    fun sendOtp() {
        scope.launch {
            when (authManager.sendOtp(email)) {
                is Result.Success -> {
                    otpSent = true
                    status = "OTP sent to $email"
                }
                is Result.Failure -> {
                    status = "Failed to send OTP"
                }
            }
        }
    }

    fun verifyOtpAndLaunchTala() {
        scope.launch {
            when (val verifyResult = authManager.verifyOtp(email, otp)) {
                is Result.Success -> {
                    if (verifyResult.value != OTPAuthenticationStatus.AUTHENTICATED) {
                        status = "Invalid OTP"
                        return@launch
                    }
                }
                is Result.Failure -> {
                    status = "OTP verification failed"
                    return@launch
                }
            }

            when (val walletResult = sdk.wallets.createWallet(
                chain = EVMChain.BaseSepolia,
                recoveryMethods = listOf(SignerType.Email(email)),
                deviceSigner = true,
            )) {
                is Result.Success -> {
                    val wallet = walletResult.value
                    // In production, register wallet.address with your backend before launching
                    // so the session token it mints is bound to this user.
                    talaLauncher.launch()
                }
                is Result.Failure -> {
                    status = "Wallet creation failed"
                }
            }
        }
    }

    Column(
        modifier = Modifier.fillMaxSize().padding(24.dp),
        verticalArrangement = Arrangement.spacedBy(12.dp, Alignment.CenterVertically),
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Text("Tala Embedded Credit Demo", style = MaterialTheme.typography.headlineSmall)

        TextField(
            value = email,
            onValueChange = { email = it },
            label = { Text("Email") },
        )

        Button(onClick = { sendOtp() }) {
            Text("Send OTP")
        }

        if (otpSent) {
            TextField(
                value = otp,
                onValueChange = { otp = it },
                label = { Text("OTP") },
            )

            Button(onClick = { verifyOtpAndLaunchTala() }) {
                Text("Verify and launch Tala")
            }
        }

        Text(status)
    }
}
```

This example sends the OTP first and only shows the OTP field after the email is sent. In a production app, split the OTP collection and wallet creation steps into separate screens.

## Launch the Tala Lending Flow

Register `TalaSDK.Contract` with `rememberLauncherForActivityResult` inside your composable (as shown in `MainActivity` above) and launch it with the `launch()` extension from `com.tala.sdk.launch`. The contract takes no input: the user identity is bound to the session token that the SDK fetches through `TalaSDK.setSessionTokenProvider`. In sandbox, `TalaSandbox.init` installs a test token provider for you.

```kotlin theme={null}
talaLauncher.launch()
```

The contract returns a `TalaResult`:

* `TalaResult.LoanAccepted` — the user accepted a loan. The loan details (reference ID, amount, currency) are delivered through `TalaSDK.setLoanVerificationCallback`, not on the result.
* `TalaResult.Abandoned` — the user dismissed the flow.
* `TalaResult.ConsentDeclined` — the user declined the consent screen.
* `TalaResult.NoLoanOffer` — Tala has no offer for this user.
* `TalaResult.Error` — a sealed hierarchy of typed errors, each carrying a `requestId` for support: `NetworkUnavailable`, `ServerError`, `SessionExpired`, `TokenProviderError`, `KycCallbackMissing`, and `Unknown`.

<Note>
  In production, the session token must come from your backend and is supplied through
  `TalaSDK.setSessionTokenProvider`. The Tala team provides the production setup details when you partner with them.
</Note>

## Sandbox Scenarios

`TalaSandbox.init` accepts an optional `scenario` argument so you can test each major flow without editing fixtures:

| `TalaSandbox.Scenario` | What the SDK shows |
| - | - |
| `HAPPY_PATH` | First-time user: Consent → OptIn → Decisioning → Offer → Borrowing Summary → Processing → Success. |
| `NEW_USER` | A brand-new user entering the onboarding flow. |
| `APPROVED_OFFER` | A user with an approved loan offer ready to accept. |
| `LOAN_DECLINED` | A user whose application was declined — routes to the **Declined** screen. |
| `NO_OFFER` | A user with no loan offer available. |
| `OVERDUE` | A returning user with an overdue loan. |
| `PAST_DUE` | A returning user with a past-due loan. |

```kotlin theme={null}
TalaSandbox.init(this, config, scenario = TalaSandbox.Scenario.LOAN_DECLINED)
```

`init` is idempotent, so you can re-initialize with the picked scenario right before launching.

## Repay a Loan from the Wallet

After Tala returns a repayment address or contract call, send USDC from the Crossmint wallet. `wallet` is the `EVMWallet` created in [Authenticate and Create a Wallet](#authenticate-and-create-a-wallet) (or loaded with `sdk.wallets.getWallet`):

```kotlin theme={null}
import com.crossmint.kotlin.types.Result

val repaymentAddress = "0x..." // provided by Tala
val amount = 10.0

when (val sendResult = wallet.send(
    recipient = repaymentAddress,
    tokenLocator = "base-sepolia:usdc",
    amount = amount,
)) {
    is Result.Success -> {
        val transaction = sendResult.value
        when (val approveResult = wallet.approve(transaction.id)) {
            is Result.Success -> { /* Repayment completed */ }
            is Result.Failure -> { /* Handle the error */ }
        }
    }
    is Result.Failure -> { /* Handle the error */ }
}
```

## Production

To enable Tala in production, you need a Tala partnership and a production API key provided by the Tala team. Contact <a href="https://www.crossmint.com/contact/sales">Crossmint Sales</a> to get connected.

## Customizing the Integration

Switch chains by changing the `chain` argument in `sdk.wallets.createWallet` — for example, `EVMChain.Base` in production or `EVMChain.BaseSepolia` for testing. To change Tala's consent mode, repayment handling, or legal links, update the `TalaConfig` you pass to `TalaSandbox.init`.

Tala supports specific emerging markets; confirm the country, currency, and disbursement token with the Tala team.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Tala SDK returns TalaResult.Error.SessionExpired or TokenProviderError in production">
    In production, the session token must come from your backend through `TalaSDK.setSessionTokenProvider`. In sandbox, `TalaSandbox.init` installs a test provider so no backend is needed. Contact <a href="https://www.crossmint.com/contact/sales">Crossmint Sales</a> to get connected with the Tala team and receive a production API key.
  </Accordion>

  <Accordion title="The Crossmint wallet fails to create with an API key error">
    Ensure you are using a client API key (`ck_...`) with the `wallets.create` scope. The SDK environment is derived
    from the key prefix: staging keys start with `ck_staging_` and production keys with `ck_production_`.
  </Accordion>

  <Accordion title="OTP dialog does not appear when signing a transaction">
    `CrossmintNonCustodialSignerProvider` must wrap your Compose content. If you are not using Compose, observe
    `CrossmintSDK.shared.isOTPRequired` and call `CrossmintSDK.shared.submit(otp)` from your own UI.
  </Accordion>

  <Accordion title="Tala sandbox UI shows the same scenario every time">
    `TalaSandbox.init` is idempotent. Call it again with the desired `TalaSandbox.Scenario` right before launching `TalaSDK.Contract`.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Check Wallet Balances" icon="wallet" href="/wallets/guides/check-balances">
    Query USDC and native token balances before and after a loan.
  </Card>

  <Card title="Send Custom EVM Transactions" icon="code" href="/wallets/guides/send-transaction-evm">
    Repay or disburse using raw contract calls when Tala provides the repayment contract.
  </Card>
</CardGroup>


# Yield.xyz
Source: https://docs.crossmint.com/wallets/guides/wallet-extensions/yield-xyz

Generate yield from your wallet's tokens using Crossmint and Yield.xyz

<Frame type="simple">
  <img alt="Generate Yield" />
</Frame>

<Info>
  New to yield? Learn about [yield strategies and mechanisms](/wallets/guides/wallet-extensions/overview) before diving into this implementation guide.
</Info>

<Card title="Live Demo" icon="play" href="https://fintech-starter-app.demos-crossmint.com/">
  Explore a working fintech app where users deposit USDC and earn yield
</Card>

## Supported Networks

Yield.xyz supports Ethereum, Base, Solana, and 50+ other chains across EVM and non-EVM networks. Testnet support includes Stellar-Testnet, Base-Sepolia, Ethereum-Sepolia, and Solana Devnet. For the complete and up-to-date list, see the [Yield.xyz Supported Networks documentation](https://docs.yield.xyz/docs/supported-networks).

<Info>
  This guide uses **Base** network with testnet wallets connected to mainnet
  yield opportunities, giving you a realistic experience without using real funds.
</Info>

## Prerequisites

Before you start, make sure you have:

* Completed the [React Quickstart](/wallets/quickstarts/react) to set up Crossmint providers and wallet creation
* A wallet funded with USDC testnet tokens (get test USDC from [Circle's Faucet](https://faucet.circle.com/))

<Warning>
  Since this guide uses testnet tokens, deposits will not actually earn yield. For production, use mainnet USDC and ensure your Crossmint wallet is configured for mainnet.

  Need help launching in production or getting access to Yield.xyz? [Contact sales](https://www.crossmint.com/contact/sales).
</Warning>

<Steps>
  <Step title="Get a Yield.xyz API Key">
    Request an API key from [Yield.xyz](https://yield.xyz) and add it to your environment:

    ```bash .env.local theme={null}
    NEXT_PUBLIC_YIELD_API_KEY=YOUR_YIELD_XYZ_API_KEY
    ```
  </Step>

  <Step title="Create the Yield API utilities">
    Create a file with all the Yield.xyz API functions and types:

    * **Fetch Yields**: Retrieve available USDC yield opportunities on Base
    * **Enter Yield**: Deposit USDC into a yield-generating position
    * **Exit Yield**: Withdraw USDC from an active yield position
    * **Get Yield Balance**: Check the current balance in a yield position
    * **Get Active Positions**: Retrieve all active yield positions for a wallet

    ```typescript yield-api.ts theme={null}
    const YIELD_API_URL = "https://api.yield.xyz";
    const YIELD_NETWORK = "base"; // Hardcoded to Base network

    // Types
    export interface YieldOpportunity {
      id: string;
      network: string;
      providerId: string;
      metadata: { name: string; description?: string };
      rewardRate: { total: number; rateType: "APY" | "APR" };
      status: { enter: boolean; exit: boolean };
    }

    export interface YieldAction {
      id: string;
      intent: "enter" | "exit";
      yieldId: string;
      amount: string;
      amountUsd: string;
      status: "CREATED" | "PROCESSING" | "SUCCESS" | "FAILED";
      createdAt: string;
    }

    // Fetch available yield opportunities
    export async function fetchYields(): Promise<YieldOpportunity[]> {
      const response = await fetch(
        `${YIELD_API_URL}/v1/yields?network=${YIELD_NETWORK}&token=USDC&limit=10`,
        {
          headers: {
            "Content-Type": "application/json",
            "X-API-KEY": process.env.NEXT_PUBLIC_YIELD_API_KEY!,
          },
        }
      );
      if (!response.ok) {
        throw new Error("Failed to fetch yields");
      }

      const data = await response.json();
      return data.data || data.items || [];
    }

    // Enter a yield position (deposit)
    export async function enterYield(yieldId: string, address: string, amount: string) {
      const response = await fetch(`${YIELD_API_URL}/v1/actions/enter`, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "X-API-KEY": process.env.NEXT_PUBLIC_YIELD_API_KEY!,
        },
        body: JSON.stringify({
          yieldId,
          address,
          arguments: { amount }, // Human-readable (e.g., "100" for 100 USDC)
        }),
      });

      if (!response.ok) {
        throw new Error("Failed to create deposit");
      }

      return response.json();
    }

    // Exit a yield position (withdraw)
    export async function exitYield(yieldId: string, address: string, amount?: string) {
      const response = await fetch(`${YIELD_API_URL}/v1/actions/exit`, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "X-API-KEY": process.env.NEXT_PUBLIC_YIELD_API_KEY!,
        },
        body: JSON.stringify({
          yieldId,
          address,
          arguments: amount ? { amount } : { useMaxAmount: true },
        }),
      });

      if (!response.ok) {
        throw new Error("Failed to create withdrawal");
      }

      return response.json();
    }

    // Get balance for a yield position
    export async function getYieldBalance(yieldId: string, address: string): Promise<string> {
      const response = await fetch(
        `${YIELD_API_URL}/v1/yields/${yieldId}/balances?address=${address}`,
        {
          headers: {
            "Content-Type": "application/json",
            "X-API-KEY": process.env.NEXT_PUBLIC_YIELD_API_KEY!,
          },
        }
      );

      if (!response.ok) {
        return "0";
      }

      const data = await response.json();
      const activeBalance = data.balances?.find((b: any) => b.type === "active");
      return activeBalance?.amount || "0";
    }

    // Get user's active positions
    export async function getActivePositions(address: string): Promise<YieldAction[]> {
      const response = await fetch(`${YIELD_API_URL}/v1/actions?address=${address}&limit=20`, {
        headers: {
          "Content-Type": "application/json",
          "X-API-KEY": process.env.NEXT_PUBLIC_YIELD_API_KEY!,
        },
      });

      if (!response.ok) {
        return [];
      }

      const { items = [] } = await response.json();

      // Group by yieldId and filter to active positions (no exit after enter)
      const byYield = new Map<string, YieldAction[]>();
      for (const action of items) {
        const list = byYield.get(action.yieldId) || [];
        list.push(action);
        byYield.set(action.yieldId, list);
      }

      const active: YieldAction[] = [];
      for (const [, actions] of byYield) {
        const sorted = actions.sort(
          (a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime()
        );
        const lastEnter = sorted.find((a) => a.intent === "enter");
        const hasExit = sorted.some(
          (a) =>
            a.intent === "exit" && lastEnter && new Date(a.createdAt) > new Date(lastEnter.createdAt)
        );
        if (lastEnter && !hasExit) active.push(lastEnter);
      }
      return active;
    }
    ```
  </Step>

  <Step title="Build a yield component with deposit and withdraw">
    Create a component that displays yields, handles deposits, and shows active positions:

    ```tsx yield-app.tsx theme={null}
    import { useState, useEffect } from "react";
    import { useWallet, EVMWallet } from "@crossmint/client-sdk-react-ui";
    import {
      fetchYields,
      enterYield,
      exitYield,
      getActivePositions,
      getYieldBalance,
      YieldOpportunity,
      YieldAction,
    } from "./yield-api";

    export function YieldApp() {
      const { wallet } = useWallet();
      const [yields, setYields] = useState<YieldOpportunity[]>([]);
      const [positions, setPositions] = useState<YieldAction[]>([]);
      const [selectedYield, setSelectedYield] = useState<string | null>(null);
      const [amount, setAmount] = useState("");
      const [loading, setLoading] = useState(false);

      // Load yields
      useEffect(() => {
        fetchYields().then(setYields);
      }, []);

      useEffect(() => {
        if (wallet?.address) {
          getActivePositions(wallet.address).then(setPositions);
        }
      }, [wallet?.address]);

      // Execute transactions through Crossmint wallet
      const executeTransactions = async (transactions: any[]) => {
        const evmWallet = EVMWallet.from(wallet!);
        const sorted = transactions.sort((a, b) => a.stepIndex - b.stepIndex);

        for (const tx of sorted) {
          const unsigned = JSON.parse(tx.unsignedTransaction);
          await evmWallet.sendTransaction({
            to: unsigned.to,
            data: unsigned.data,
            value: unsigned.value || "0x0",
          });
        }
      };

      const handleDeposit = async (yieldId: string) => {
        if (!wallet?.address || !amount) {
          return;
        }

        setLoading(true);
        try {
          const { transactions } = await enterYield(yieldId, wallet.address, amount);
          await executeTransactions(transactions);
          setPositions(await getActivePositions(wallet.address));
          setAmount("");
          setSelectedYield(null);
        } catch (err) {
          console.error("Deposit failed:", err);
        }
        setLoading(false);
      };

      const handleWithdraw = async (yieldId: string) => {
        if (!wallet?.address) {
          return;
        }

        setLoading(true);
        try {
          // Fetch current balance to pass to exit
          const balance = await getYieldBalance(yieldId, wallet.address);
          const { transactions } = await exitYield(yieldId, wallet.address, balance);
          await executeTransactions(transactions);
          setPositions(await getActivePositions(wallet.address));
        } catch (err) {
          console.error("Withdraw failed:", err);
        }
        setLoading(false);
      };

      if (!wallet) {
        return <p>Connect your wallet to view yield opportunities.</p>;
      }

      return (
        <div className="space-y-6 p-4">
          <h2 className="text-xl font-bold">💰 Earn Yield on USDC</h2>

          {/* Yield Opportunities */}
          <div className="space-y-3">
            <h3 className="font-semibold">Available Yields</h3>
            {yields.map((y) => (
              <div
                key={y.id}
                onClick={() => setSelectedYield(selectedYield === y.id ? null : y.id)}
                className={`cursor-pointer rounded-xl border p-4 ${
                  selectedYield === y.id ? "border-blue-500" : ""
                }`}
              >
                <div className="flex justify-between">
                  <span className="font-semibold">{y.metadata.name}</span>
                  <span className="text-green-600">{(y.rewardRate.total * 100).toFixed(2)}% APY</span>
                </div>
                <p className="text-sm text-gray-500">{y.providerId}</p>

                {selectedYield === y.id && (
                  <div className="mt-3 flex gap-2" onClick={(e) => e.stopPropagation()}>
                    <input
                      type="number"
                      placeholder="Amount (USDC)"
                      value={amount}
                      onChange={(e) => setAmount(e.target.value)}
                      className="flex-1 rounded border px-3 py-2"
                    />
                    <button
                      onClick={() => handleDeposit(y.id)}
                      disabled={loading || !amount}
                      className="rounded bg-blue-600 px-4 py-2 text-white hover:bg-blue-700 disabled:opacity-50"
                    >
                      {loading ? "..." : "Deposit"}
                    </button>
                  </div>
                )}
              </div>
            ))}
          </div>

          {/* Active Positions */}
          {positions.length > 0 && (
            <div className="space-y-3">
              <h3 className="font-semibold">Your Positions</h3>
              {positions.map((p) => (
                <div key={p.id} className="flex items-center justify-between rounded-xl border p-4">
                  <div>
                    <span className="font-semibold">{p.yieldId.split("-")[2]}</span>
                    <p className="text-sm text-gray-500">${p.amountUsd} USDC</p>
                  </div>
                  <button
                    onClick={() => handleWithdraw(p.yieldId)}
                    disabled={loading}
                    className="rounded border border-red-200 bg-red-50 px-4 py-2 text-red-600 hover:bg-red-100"
                  >
                    {loading ? "..." : "Withdraw"}
                  </button>
                </div>
              ))}
            </div>
          )}
        </div>
      );
    }
    ```
  </Step>

  <Step title="Render the yield app">
    Add the yield component to your application (inside your Crossmint providers):

    ```tsx page.tsx theme={null}
    "use client";

    import { Providers } from "./providers";
    import { YieldApp } from "./yield-app";

    export default function Home() {
      return (
        <Providers>
          <YieldApp />
        </Providers>
      );
    }
    ```
  </Step>
</Steps>

## Next Steps

<CardGroup>
  <Card title="Yield.xyz API Docs" icon="book" href="https://docs.yield.xyz">
    Full API reference for yields, actions, and balances
  </Card>

  <Card title="Credit Cards" icon="credit-card" href="/wallets/guides/wallet-extensions/credit-cards">
    Let users spend their wallet balance with virtual credit cards
  </Card>
</CardGroup>


# Wallet Webhooks
Source: https://docs.crossmint.com/wallets/guides/webhooks

Set up webhooks to receive real-time events including transfers and signer exports

Wallet webhooks allow you to receive real-time notifications for events that occur on wallets in your project. This enables you to track transfers, monitor signer exports, update your application state, and trigger automated workflows.

Crossmint currently supports the following wallet webhook event types:

| Event | Description |
| - | - |
| `wallets.transfer.in` | Tokens transferred **into** a project wallet |
| `wallets.transfer.out` | Tokens transferred **out of** a project wallet |
| `wallets.signer.exported` | A wallet's private key was exported for the first time |

## Transfer Webhooks

Transfer webhooks notify you when tokens are transferred in or out of wallets in your project.

## Supported Configurations

Transfer webhooks have different levels of support depending on the blockchain and wallet type:

| Chain | Wallet Types | Token Types |
| - | - | - |
| **EVM** (Ethereum, Polygon, Base, etc.) | Smart wallets and EOAs | ERC-20 tokens only (native tokens like ETH, MATIC not supported) |
| **Solana** | Smart wallets and EOAs | All SPL tokens including native SOL |
| **Stellar** | Smart wallets and EOAs | Soroban tokens (fungible) |

## Event Types

Crossmint provides two webhook event types for wallet transfers:

### `wallets.transfer.in`

Triggered when tokens are transferred **into** a wallet in your project. This event is only sent for successful transfers that have been confirmed onchain.

### `wallets.transfer.out`

Triggered when tokens are transferred **out of** a wallet in your project. This event is sent for both successful and failed transfer attempts, allowing you to track the complete lifecycle of outgoing transactions.

## Setup

To start receiving wallet transfer webhooks, configure a webhook endpoint in the Crossmint Console.

### Prerequisites

* A Crossmint project with API keys configured
* A wallet with tokens to transfer (see [Fund a Staging Wallet](/wallets/guides/fund-staging-wallet))
* The `svix` package installed for webhook signature verification:

<CodeGroup>
  ```bash npm theme={null}
  npm i svix
  ```

  ```bash yarn theme={null}
  yarn add svix
  ```

  ```bash pnpm theme={null}
  pnpm add svix
  ```

  ```bash bun theme={null}
  bun add svix
  ```
</CodeGroup>

There are two ways to test and integrate webhooks:

* **Option 1: Test using Svix Play** - Quick testing without setting up a local server
* **Option 2: Integrate with your local app** - Full integration with your development environment

### Option 1: Test using Svix Play

Use Svix Play to inspect webhook payloads without setting up a local server. This is useful for understanding the event structure before building your integration.

1. Navigate to the Webhooks page in the Crossmint Console
2. Click **Add Endpoint**
3. In the dialog that appears, click the **"with Svix Play"** button (instead of entering a custom URL)
4. Select the following event types:
   * `wallets.transfer.in` - Receive notifications when tokens arrive in your wallets
   * `wallets.transfer.out` - Receive notifications when tokens leave your wallets
5. Click **Create**

This automatically configures your endpoint to use Svix Play, which opens with a pre-filled URL like:

```
https://play.svix.com/in/e_0izvs3VwiAo8hvKf6Ygh2tujXre/
```

Trigger a transfer from your app by calling `wallet.send()`, and the event will appear in Svix Play:

```typescript theme={null}
const RECIPIENT_ADDRESS = "0x...";

const { hash, explorerLink } = await wallet.send(
    RECIPIENT_ADDRESS,
    "usdxm",
    "1.00"
);
```

For the complete transfer setup, see the [Transfer Tokens](/wallets/guides/transfer-tokens) guide.

### Option 2: Local development with ngrok

For full integration, set up a local server to receive and process webhook events.

Before registering a webhook endpoint, you need a publicly accessible URL. If your app runs locally on `http://localhost:3000`, use <a href="https://ngrok.com">ngrok</a> to create a public URL:

```bash theme={null}
ngrok http 3000
```

This gives you a public URL like `https://abc123.ngrok.io` that forwards to your local server.

Alternatively, if you have a staging or development server with a public URL, you can register that directly.

### Register your endpoint

1. Navigate to the Webhooks page in the Crossmint Console
2. Click **Add Endpoint**
3. Enter your public URL with the webhook path (e.g., `https://abc123.ngrok.io/api/webhooks/transfers`)
4. Select the following event types:
   * `wallets.transfer.in` - Receive notifications when tokens arrive in your wallets
   * `wallets.transfer.out` - Receive notifications when tokens leave your wallets
5. Click **Create**
6. Copy the **signing secret** from the endpoint details - you will need this to verify webhook signatures

For detailed setup instructions, see [Add an Endpoint](/introduction/platform/webhooks/add-endpoint).

<Tip>
  Your webhook endpoint must return a 2xx HTTP status code within 15 seconds to acknowledge receipt. This is critical for webhook delivery confirmation.
</Tip>

### Handle and verify events

Create an endpoint to receive and process webhook events. The following example shows how to handle both incoming and outgoing transfer events.

<Tabs>
  <Tab title="Node.js (Express)">
    ```javascript theme={null}
    import express from "express";
    import { Webhook } from "svix";

    const app = express();

    app.use("/api/webhooks", express.raw({ type: "application/json" }));

    const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

    app.post("/api/webhooks/transfers", async (req, res) => {
        const wh = new Webhook(WEBHOOK_SECRET);
        let payload;

        try {
            payload = wh.verify(req.body, {
                "svix-id": req.headers["svix-id"],
                "svix-timestamp": req.headers["svix-timestamp"],
                "svix-signature": req.headers["svix-signature"],
            });
        } catch (err) {
            console.error("Webhook verification failed:", err.message);
            return res.status(400).json({ error: "Invalid signature" });
        }

        res.status(200).json({ received: true });

        processTransferEvent(payload).catch(err => console.error("Event processing failed:", err));
    });

    async function processTransferEvent(event) {
        const { type, data } = event;

        if (type === "wallets.transfer.in") {
            console.log("Incoming transfer received:");
            console.log(`  From: ${data.sender.address}`);
            console.log(`  To: ${data.recipient.address}`);
            console.log(`  Amount: ${data.token.amount} ${data.token.symbol}`);
            console.log(`  Explorer: ${data.onChain.explorerLink}`);
        }

        if (type === "wallets.transfer.out") {
            if (data.status === "succeeded") {
                console.log("Outgoing transfer succeeded:");
                console.log(`  To: ${data.recipient.address}`);
                console.log(`  Amount: ${data.token.amount} ${data.token.symbol}`);
                console.log(`  Explorer: ${data.onChain.explorerLink}`);
            } else {
                console.error("Outgoing transfer failed:");
                console.error(`  Error: ${data.error.message}`);
                console.error(`  Reason: ${data.error.reason}`);
            }
        }
    }

    app.listen(3000, () => console.log("Webhook server running on port 3000"));
    ```
  </Tab>

  <Tab title="Next.js (App Router)">
    ```typescript theme={null}
    // app/api/webhooks/transfers/route.ts
    import { Webhook } from "svix";
    import { headers } from "next/headers";
    import { NextResponse } from "next/server";

    const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET!;

    export async function POST(req: Request) {
        const body = await req.text();
        const headerPayload = await headers();

        const svixId = headerPayload.get("svix-id");
        const svixTimestamp = headerPayload.get("svix-timestamp");
        const svixSignature = headerPayload.get("svix-signature");

        if (!svixId || !svixTimestamp || !svixSignature) {
            return NextResponse.json({ error: "Missing headers" }, { status: 400 });
        }

        const wh = new Webhook(WEBHOOK_SECRET);
        let payload: any;

        try {
            payload = wh.verify(body, {
                "svix-id": svixId,
                "svix-timestamp": svixTimestamp,
                "svix-signature": svixSignature,
            });
        } catch (err) {
            console.error("Webhook verification failed:", err);
            return NextResponse.json({ error: "Invalid signature" }, { status: 400 });
        }

        const { type, data } = payload;

        if (type === "wallets.transfer.in") {
            console.log(`Received ${data.token.amount} ${data.token.symbol}`);
            console.log(`From: ${data.sender.address}`);
            console.log(`Explorer: ${data.onChain.explorerLink}`);
        }

        if (type === "wallets.transfer.out") {
            if (data.status === "succeeded") {
                console.log(`Sent ${data.token.amount} ${data.token.symbol}`);
                console.log(`To: ${data.recipient.address}`);
            } else {
                console.error(`Transfer failed: ${data.error.message}`);
            }
        }

        return NextResponse.json({ received: true });
    }
    ```
  </Tab>

  <Tab title="Python (Flask)">
    ```python theme={null}
    import os
    from flask import Flask, request, jsonify
    from svix.webhooks import Webhook

    app = Flask(__name__)

    WEBHOOK_SECRET = os.environ["WEBHOOK_SECRET"]

    @app.route("/api/webhooks/transfers", methods=["POST"])
    def handle_transfer_webhook():
        headers = {
            "svix-id": request.headers.get("svix-id"),
            "svix-timestamp": request.headers.get("svix-timestamp"),
            "svix-signature": request.headers.get("svix-signature"),
        }

        wh = Webhook(WEBHOOK_SECRET)
        try:
            payload = wh.verify(request.get_data(as_text=True), headers)
        except Exception as e:
            print(f"Webhook verification failed: {e}")
            return jsonify({"error": "Invalid signature"}), 400

        event_type = payload.get("type")
        data = payload.get("data")

        if event_type == "wallets.transfer.in":
            print(f"Received {data['token']['amount']} {data['token']['symbol']}")
            print(f"From: {data['sender']['address']}")
            print(f"Explorer: {data['onChain']['explorerLink']}")

        if event_type == "wallets.transfer.out":
            if data["status"] == "succeeded":
                print(f"Sent {data['token']['amount']} {data['token']['symbol']}")
                print(f"To: {data['recipient']['address']}")
            else:
                print(f"Transfer failed: {data['error']['message']}")

        return jsonify({"received": True})

    if __name__ == "__main__":
        app.run(port=3000)
    ```
  </Tab>
</Tabs>

<Warning>
  Always use the **raw request body** when verifying webhooks. Parsing and re-stringifying JSON will alter the content and cause verification failure.
</Warning>

<Note>
  For more details on securing and verifying webhook requests, see [Verify Webhooks](/introduction/platform/webhooks/verify-webhooks).
</Note>

### Test your endpoint

Execute a transfer using the [Transfer Tokens](/wallets/guides/transfer-tokens) guide and observe the webhook event in your server logs. For a successful outgoing transfer, you should see output like:

```
Sent 0.40 USDXM
To: 0xdf8b5f9c19e187f1ea00730a1e46180152244315
```

## Event Schema

Both `wallets.transfer.in` and `wallets.transfer.out` events share a common structure with some key differences based on the transfer direction and outcome.

### Common Fields

All wallet transfer events include the following fields:

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique identifier for the webhook event |
| `type` | string | Event type: `"wallets.transfer.in"` or `"wallets.transfer.out"` |
| `data.sender` | object | Information about the sender wallet |
| `data.sender.address` | string | Blockchain address of the sender |
| `data.sender.chain` | string | Chain identifier (e.g., `"ethereum"`, `"polygon"`, `"solana"`, `"stellar"`) |
| `data.sender.locator` | string | Wallet locator in the format `chain:address` |
| `data.sender.owner` | string (optional) | Owner identifier if the sender is a Crossmint-managed wallet |
| `data.recipient` | object | Information about the recipient wallet |
| `data.recipient.address` | string | Blockchain address of the recipient |
| `data.recipient.chain` | string | Chain identifier |
| `data.recipient.locator` | string | Wallet locator in the format `chain:address` |
| `data.recipient.owner` | string (optional) | Owner identifier for the recipient wallet |
| `data.token` | object | Information about the transferred token |
| `data.token.type` | string | Token type, currently only `"fungible"` is supported |
| `data.token.chain` | string | Chain where the token exists |
| `data.token.locator` | string | Token locator in the format `chain:contractAddress` |
| `data.token.amount` | string | Human-readable amount (adjusted for decimals) |
| `data.token.rawAmount` | string | Raw amount in smallest unit (e.g., wei for ETH) |
| `data.token.contractAddress` | string (EVM) | Token contract address for EVM chains |
| `data.token.mintHash` | string (Solana) | Token mint address for Solana |
| `data.token.contractId` | string (Stellar) | Token contract ID for Stellar |
| `data.token.decimals` | number | Number of decimals for the token |
| `data.token.symbol` | string (optional) | Token symbol (e.g., `"USDC"`, `"ETH"`) |
| `data.status` | string | Transfer status: `"succeeded"` or `"failed"` |
| `data.transferId` | string (optional) | Unique identifier for the transfer, can be used with the [`Get Transaction API`](/api-reference/wallets/get-transaction) |
| `data.completedAt` | string | ISO 8601 timestamp when the transfer was completed. Timestamp may be off by a few seconds from the actual onchain transaction |

### Type-Specific Differences

**Incoming Transfers (`wallets.transfer.in`)**:

* `data.status` is always `"succeeded"` (only successful transfers are reported)
* `data.onChain` is always present with transaction details

**Outgoing Transfers (`wallets.transfer.out`)**:

* `data.status` can be `"succeeded"` or `"failed"`
* `data.onChain` is present only when `status` is `"succeeded"`
* `data.error` is present only when `status` is `"failed"`

<Note>
  The `transferId` field is only available for transfers initiated through the Crossmint API. It can be used to retrieve the transfer details from the [`Get Transaction API`](/api-reference/wallets/get-transaction).
</Note>

### Event Examples

<Accordion title="Incoming Transfer Example">
  ```json theme={null}
  {
    "id": "whevnt_12324",
    "type": "wallets.transfer.in",
    "data": {
      "transferId": "660e8400-e29b-41d4-a716-446655440002",
      "sender": {
        "address": "0x1234567890123456789012345678901234567890",
        "chain": "ethereum",
        "locator": "ethereum:0x1234567890123456789012345678901234567890"
      },
      "recipient": {
        "address": "0x0987654321098765432109876543210987654321",
        "chain": "ethereum",
        "locator": "ethereum:0x0987654321098765432109876543210987654321",
        "owner": "email:user@example.com"
      },
      "token": {
        "type": "fungible",
        "chain": "ethereum",
        "locator": "ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "amount": "100.50",
        "rawAmount": "100500000",
        "contractAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "decimals": 6,
        "symbol": "USDC"
      },
      "status": "succeeded",
      "completedAt": "2025-10-21T12:34:56.789Z",
      "onChain": {
        "txId": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
        "explorerLink": "https://etherscan.io/tx/0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
      }
    }
  }
  ```
</Accordion>

<Accordion title="Incoming Transfer (Stellar) Example">
  ```json theme={null}
  {
    "id": "whevnt_34567",
    "type": "wallets.transfer.in",
    "data": {
      "transferId": "770e8400-e29b-41d4-a716-446655440003",
      "sender": {
        "address": "GDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOUJ3DQMFX7AQZED",
        "chain": "stellar",
        "locator": "stellar:GDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOUJ3DQMFX7AQZED"
      },
      "recipient": {
        "address": "GBZXN7PIRZGNMHGA7MUUUF4GWPY5AYPV6LY4UV2GL6VJGIQRXFDNMADI",
        "chain": "stellar",
        "locator": "stellar:GBZXN7PIRZGNMHGA7MUUUF4GWPY5AYPV6LY4UV2GL6VJGIQRXFDNMADI",
        "owner": "email:user@example.com"
      },
      "token": {
        "type": "fungible",
        "chain": "stellar",
        "locator": "stellar:CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA",
        "amount": "100.5000000",
        "rawAmount": "1005000000",
        "contractId": "CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA",
        "decimals": 7,
        "symbol": "USDC"
      },
      "status": "succeeded",
      "completedAt": "2025-10-21T12:34:56.789Z",
      "onChain": {
        "txId": "abc123def456abc123def456abc123def456abc123def456abc123def456abc1",
        "explorerLink": "https://stellar.expert/explorer/public/tx/abc123def456abc123def456abc123def456abc123def456abc123def456abc1"
      }
    }
  }
  ```
</Accordion>

<Accordion title="Outgoing Transfer (Success) Example">
  ```json theme={null}
  {
    "id": "whevnt_56789",
    "type": "wallets.transfer.out",
    "data": {
      "transferId": "550e8400-e29b-41d4-a716-446655440000",
      "sender": {
        "address": "0x0987654321098765432109876543210987654321",
        "chain": "ethereum",
        "locator": "ethereum:0x0987654321098765432109876543210987654321",
        "owner": "email:user@example.com"
      },
      "recipient": {
        "address": "0x1234567890123456789012345678901234567890",
        "chain": "ethereum",
        "locator": "ethereum:0x1234567890123456789012345678901234567890"
      },
      "token": {
        "type": "fungible",
        "chain": "ethereum",
        "locator": "ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "amount": "50.25",
        "rawAmount": "50250000",
        "contractAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "decimals": 6,
        "symbol": "USDC"
      },
      "status": "succeeded",
      "completedAt": "2025-10-21T12:34:56.789Z",
      "onChain": {
        "txId": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
        "explorerLink": "https://etherscan.io/tx/0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
      }
    }
  }
  ```
</Accordion>

<Accordion title="Outgoing Transfer (Failed) Example">
  ```json theme={null}
  {
    "id": "whevnt_99999",
    "type": "wallets.transfer.out",
    "data": {
      "transferId": "550e8400-e29b-41d4-a716-446655440001",
      "sender": {
        "address": "0x0987654321098765432109876543210987654321",
        "chain": "ethereum",
        "locator": "ethereum:0x0987654321098765432109876543210987654321",
        "owner": "email:user@example.com"
      },
      "recipient": {
        "address": "0x1234567890123456789012345678901234567890",
        "chain": "ethereum",
        "locator": "ethereum:0x1234567890123456789012345678901234567890"
      },
      "token": {
        "type": "fungible",
        "chain": "ethereum",
        "locator": "ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "amount": "1000.00",
        "rawAmount": "1000000000",
        "contractAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "decimals": 6,
        "symbol": "USDC"
      },
      "status": "failed",
      "completedAt": "2025-10-21T12:34:56.789Z",
      "error": {
        "message": "Transaction reverted",
        "reason": "execution_reverted",
        "revert": {
          "type": "contract_call",
          "reason": "ERC20: transfer amount exceeds balance"
        }
      }
    }
  }
  ```
</Accordion>

### Error Fields (Outgoing Transfers Only)

When an outgoing transfer fails, the following error fields are included:

| Field | Type | Description |
| - | - | - |
| `data.error.message` | string | Error message |
| `data.error.reason` | string | Error reason (e.g., `"execution_reverted"`, `"program_error"`, `"build_failed"`) |
| `data.error.revert` | object | Revert details from smart contract |
| `data.error.revert.type` | string | Revert type: `"contract_call"`, `"wallet_authorization"`, or `"wallet_deployment"` |
| `data.error.revert.reason` | string | Revert reason message |
| `data.error.logs` | any (optional) | Additional error logs |

## Best Practices

For comprehensive guidance on implementing reliable webhook handlers, see [Webhook Best Practices](/introduction/platform/webhooks/best-practices).

## Signer Export Webhook

The `wallets.signer.exported` event is triggered when a user exports the private key of a wallet for the **first time**. This webhook is sent once per wallet — subsequent exports of the same wallet do not trigger additional events.

This is useful for compliance monitoring, alerting, or updating internal records when a user gains direct access to the underlying key material.

<Note>
  The webhook payload does not contain any private key material. It only identifies which wallet and signer were involved in the export.
</Note>

### Event Schema

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique identifier for the webhook event |
| `type` | string | `"wallets.signer.exported"` |
| `data.owner` | string | Signer locator of the wallet owner (e.g., `"email:user@example.com"`) |
| `data.walletAddress` | string | Blockchain address of the exported wallet |
| `data.chain` | string | Chain type: `"evm"`, `"solana"`, or `"stellar"` |
| `data.signerType` | string | Signer type that was exported: `"email"` or `"phone"` |

### Event Example

<Accordion title="Signer Export Example">
  ```json theme={null}
  {
    "id": "evt_abc123",
    "type": "wallets.signer.exported",
    "data": {
      "owner": "email:user@example.com",
      "walletAddress": "0x0987654321098765432109876543210987654321",
      "chain": "evm",
      "signerType": "email"
    }
  }
  ```
</Accordion>

### Setup

To start receiving signer export webhooks, add a webhook endpoint in the Crossmint Console and select the `wallets.signer.exported` event type. For detailed setup instructions, see [Add an Endpoint](/introduction/platform/webhooks/add-endpoint).

* **Respond quickly**: Return a 2xx status within 15 seconds to prevent retries
* **Verify signatures**: Always verify webhook signatures before processing

For comprehensive guidance on implementing reliable webhook handlers, see [Webhook Best Practices](/introduction/platform/webhooks/best-practices).

## Related Resources

* [Add an Endpoint](/introduction/platform/webhooks/add-endpoint) - Configure webhook endpoints
* [Verify Webhooks](/introduction/platform/webhooks/verify-webhooks) - Verify webhook signatures
* [Best Practices](/introduction/platform/webhooks/best-practices) - Webhook implementation best practices
* [Create Wallet](/wallets/guides/create-wallet) - Create wallets to receive transfers
* [Transfer Tokens](/wallets/guides/transfer-tokens) - Initiate token transfers
* [Export Private Key](/wallets/guides/export-private-key) - Allow users to export private keys


# Overview
Source: https://docs.crossmint.com/wallets/overview

Create smart wallets for your users, businesses, and agents, optimized for any use case

Crossmint offers secure, programmable smart wallet infrastructure through a single API that is configurable for any use case: embedded wallets for end users, high-throughput treasury wallets, or scoped wallets for AI agents, abstracting away all blockchain complexity from you and your users.

The chain-agnostic APIs handle every wallet operation, including creation, transaction execution, gas sponsorship, [onramps](/onramp/overview), [compliance](/stablecoin-orchestration/concepts/regulatory-landscape), and advanced policies, so you can launch in minutes and scale to millions of users and transactions. Crossmint also offers wallet extensions for cards, swapping, bridging, staking, and tokenized stocks, making it easy to plug into the best external tools.

<CardGroup>
  <Card title="Why Crossmint Wallets" icon="wallet" href="/wallets/architecture">
    Learn how Crossmint wallet architecture delivers the best UX, security, and future-proofing for any use case
  </Card>
</CardGroup>

## Where to Start

Select the type of wallet you want to implement: embedded wallets for your end users, treasury wallets to manage your company funds, or wallets for AI agents.

<Icon icon="window" />

<h3>Embedded Wallets</h3>

Deploy non-custodial wallets seamlessly embedded within your app.

<CardGroup>
  <Card title="Overview" icon="book-open" href="/wallets/concepts/embedded-wallets">
    What are embedded wallets
  </Card>

  <Card title="Quickstarts" icon="bolt" href="/wallets/quickstarts/react">
    [React](/wallets/quickstarts/react), [React Native](/wallets/quickstarts/react-native), [Flutter](/wallets/quickstarts/flutter), [Swift](/wallets/quickstarts/swift), [Kotlin](/wallets/quickstarts/kotlin)
  </Card>
</CardGroup>

<Icon icon="vault" />

<h3>Treasury Wallets</h3>

Secure, programmable wallets to manage and move company funds at scale.

<CardGroup>
  <Card title="Overview" icon="book-open" href="/wallets/concepts/treasury">
    What are treasury wallets
  </Card>

  <Card title="Setup Guide" icon="plus" href="/wallets/guides/treasury-wallets">
    Create and manage a treasury wallet
  </Card>
</CardGroup>

<Icon icon="robot" />

<h3>Agent Wallets</h3>

Give AI agents their own scoped wallets to transact autonomously within limits you set.

<CardGroup>
  <Card title="Overview" icon="book-open" href="/agents/stablecoin-wallet-quickstart">
    What are agent wallets
  </Card>

  <Card title="Setup Guide" icon="plus" href="/agents/payment-methods/stablecoin-wallets/create-user-wallet">
    Create a wallet for your AI agent
  </Card>
</CardGroup>

## Key Features

<CardGroup>
  <Card title="Seamless UX" icon="wand-magic-sparkles" href="/wallets/architecture#what-this-means-in-practice">
    No passphrases or blockchain gimmicks
  </Card>

  <Card title="Flexible Signers" icon="key" href="/wallets/concepts/signers">
    Passkeys, TEEs, server signers, HSMs, and more
  </Card>

  <Card title="Account Recovery" icon="rotate-left" href="/wallets/concepts/recovery">
    Multiple methods to recover wallets
  </Card>

  <Card title="Gas Sponsorship" icon="gas-pump" href="/wallets/guides/gas-sponsorship">
    Crossmint pays for gas and bills you in fiat
  </Card>

  <Card title="Multi-Chain" icon="globe" href="/introduction/supported-chains">
    50+ supported chains via one unified API
  </Card>

  <Card title="Policy Engine" icon="shield-check" href="/agents/payment-methods/stablecoin-wallets/on-chain-actions">
    Transaction rules enforced onchain
  </Card>

  <Card title="Built-in Onramps" icon="money-bill-transfer" href="/onramp/overview">
    Allow users to fund their wallets
  </Card>

  <Card title="Powerful Extensions" icon="puzzle-piece" href="/wallets/guides/wallet-extensions/overview">
    Cards, swaps, staking, trading, and more
  </Card>

  <Card title="No Vendor Lock-In" icon="lock-open" href="/wallets/guides/export-private-key">
    Switch providers without migrations
  </Card>
</CardGroup>

## Wallet Guides

<CardGroup>
  <Card title="Wallet Actions" icon="wallet">
    * [Create Wallet](/wallets/guides/create-wallet)
    * [Fund Wallets](/wallets/guides/fund-staging-wallet)
    * [Check Balances](/wallets/guides/check-balances)
    * [Transfer Tokens](/wallets/guides/transfer-tokens)
    * [Sign Message](/wallets/guides/sign-message)
    * [Custom Transactions](/wallets/guides/send-transaction-evm)
  </Card>

  <Card title="Signers" icon="key">
    * [Set Up Signers](/wallets/guides/signers/device-signer)
    * [Manage Signers](/wallets/guides/signers/add-signers)
  </Card>

  <Card title="Recovery Methods" icon="rotate-left" href="/wallets/concepts/recovery">
    Restore access without changing the wallet address
  </Card>

  <Card title="Wallet Recovery" icon="arrows-rotate">
    * [Configure Recovery](/wallets/guides/recovery/configure-recovery)
    * [Recover a Wallet](/wallets/guides/recovery/wallet-recovery)
  </Card>
</CardGroup>

## Need Assistance?

<a href="https://www.crossmint.com/contact/sales">Contact our sales team</a> for support with your integration.


# Flutter
Source: https://docs.crossmint.com/wallets/quickstarts/flutter

Create user wallets from your Flutter app in under 5 minutes

<CardGroup>
  <Snippet />

  <Card title="Flutter Wallets Example" icon="github" href="https://github.com/Paella-Labs/crossmint-flutter-sdk">
    See the full example app in the SDK repo.
  </Card>
</CardGroup>

<Steps>
  <Step title="Install the SDK">
    Run the following command to install the SDK:

    <Snippet />
  </Step>

  <Step title="Configure deep link scheme for OAuth">
    If you plan to use OAuth login (Google, Twitter), you need a deep link scheme so the browser
    can return to your app after authentication.

    **Android** — add to your `AndroidManifest.xml`:

    ```xml android/app/src/main/AndroidManifest.xml theme={null}
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="myapp" />
    </intent-filter>
    ```

    **iOS** — add to your `Info.plist`:

    ```xml ios/Runner/Info.plist theme={null}
    <key>CFBundleURLTypes</key>
    <array>
        <dict>
            <key>CFBundleURLSchemes</key>
            <array>
                <string>myapp</string>
            </array>
        </dict>
    </array>
    ```

    <Note>
      If you only use email OTP login (no OAuth), you can skip this step.
    </Note>
  </Step>

  <Step title="Initialize the client and add providers">
    Create a `CrossmintWalletProvider` at the root of your app. This example uses [Crossmint Auth](/authentication/introduction)
    but you can use [any authentication provider of your choice](/wallets/guides/bring-your-own-auth).

    With the current setup, a wallet will be created automatically on login.

    See all supported chains [here](/introduction/supported-chains).

    ```dart main.dart theme={null}
    import 'package:flutter/material.dart';
    import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

    void main() {
      runApp(const MyApp());
    }

    class MyApp extends StatelessWidget {
      const MyApp({super.key});

      @override
      Widget build(BuildContext context) {
        return MaterialApp(
          title: 'Crossmint Flutter Wallets',
          home: CrossmintWalletProvider(
            config: CrossmintWalletProviderConfig(
              clientConfig: CrossmintClientConfig(
                apiKey: const String.fromEnvironment('CROSSMINT_API_KEY'),
                appScheme: 'myapp',
              ),
              walletControllerConfig: CrossmintWalletControllerConfig(
                createOnLogin: CrossmintCreateOnLoginConfig(
                  chain: 'base-sepolia',
                  recovery: const CrossmintEmailSignerConfig(),
                ),
                showOtpSignerPrompt: true,
              ),
              otpPromptBuilder: crossmintDefaultOtpPromptBuilder,
            ),
            child: const HomeScreen(),
          ),
        );
      }
    }
    ```

    Pass the API key via `--dart-define` when running the app:

    ```bash theme={null}
    flutter run --dart-define=CROSSMINT_API_KEY=YOUR_CLIENT_API_KEY
    ```

    For detailed configuration options, see the [Flutter SDK Reference](/sdk-reference/wallets/flutter/providers#crossmintwalletprovider).
  </Step>

  <Step title="Allow users to login, logout, and access their wallet">
    Crossmint Auth in Flutter is **headless** — you build your own login UI and call the SDK directly.
    Use `CrossmintWalletContext` to access the auth client and wallet controller.

    ```dart home_screen.dart theme={null}
    import 'package:flutter/material.dart';
    import 'package:crossmint_flutter/crossmint_flutter_ui.dart';

    class HomeScreen extends StatelessWidget {
      const HomeScreen({super.key});

      @override
      Widget build(BuildContext context) {
        return CrossmintWalletGate(
          unauthenticatedBuilder: (context, data) {
            return const LoginScreen();
          },
          initializingBuilder: (context, data) {
            return const Scaffold(
              body: Center(child: CircularProgressIndicator()),
            );
          },
          readyBuilder: (context, data) {
            // The gate fires readyBuilder once authenticated, but
            // the wallet may still be loading. `hasWallet` is the
            // convenience predicate — equivalent to `currentWallet != null`.
            if (!data.state.hasWallet) {
              return const Scaffold(
                body: Center(child: CircularProgressIndicator()),
              );
            }
            return WalletScreen(wallet: data.state.currentWallet!);
          },
        );
      }
    }

    class LoginScreen extends StatefulWidget {
      const LoginScreen({super.key});

      @override
      State<LoginScreen> createState() => _LoginScreenState();
    }

    class _LoginScreenState extends State<LoginScreen> {
      final _emailController = TextEditingController();
      final _otpController = TextEditingController();
      String? _emailId;
      bool _otpSent = false;
      bool _isPending = false;

      Future<void> _sendOtp() async {
        final email = _emailController.text.trim();
        if (email.isEmpty) {
          ScaffoldMessenger.of(context).showSnackBar(
            const SnackBar(content: Text('Enter a valid email')),
          );
          return;
        }

        setState(() => _isPending = true);
        try {
          final walletContext = CrossmintWalletContext.of(context);
          final challenge = await walletContext.requireAuth.sendEmailOtp(email);
          setState(() {
            _emailId = challenge.id;
            _otpSent = true;
          });
        } catch (e) {
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(content: Text('Failed to send OTP: $e')),
          );
        } finally {
          setState(() => _isPending = false);
        }
      }

      Future<void> _verifyOtp() async {
        final otp = _otpController.text.trim();
        if (otp.isEmpty) {
          ScaffoldMessenger.of(context).showSnackBar(
            const SnackBar(content: Text('Enter the OTP code')),
          );
          return;
        }

        setState(() => _isPending = true);
        try {
          final walletContext = CrossmintWalletContext.of(context);
          await walletContext.requireAuth.confirmEmailOtp(
            email: _emailController.text.trim(),
            emailId: _emailId!,
            token: otp,
          );
        } catch (e) {
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(content: Text('Invalid OTP: $e')),
          );
        } finally {
          setState(() => _isPending = false);
        }
      }

      @override
      Widget build(BuildContext context) {
        final walletContext = CrossmintWalletContext.of(context);

        return Scaffold(
          body: Padding(
            padding: const EdgeInsets.all(20),
            child: Column(
              mainAxisAlignment: MainAxisAlignment.center,
              children: [
                const Text('Login', style: TextStyle(fontSize: 24)),
                const SizedBox(height: 20),
                TextField(
                  controller: _emailController,
                  decoration: const InputDecoration(
                    hintText: 'Enter your email',
                    border: OutlineInputBorder(),
                  ),
                  enabled: !_otpSent,
                ),
                const SizedBox(height: 10),
                if (!_otpSent) ...[
                  SizedBox(
                    width: double.infinity,
                    child: ElevatedButton(
                      onPressed: _isPending ? null : _sendOtp,
                      style: ElevatedButton.styleFrom(
                        backgroundColor: const Color(0xFF05B959),
                      ),
                      child: _isPending
                          ? const SizedBox(
                              height: 20,
                              width: 20,
                              child: CircularProgressIndicator(
                                color: Colors.white,
                                strokeWidth: 2,
                              ),
                            )
                          : const Text('Send OTP',
                              style: TextStyle(color: Colors.white)),
                    ),
                  ),
                ] else ...[
                  TextField(
                    controller: _otpController,
                    decoration: const InputDecoration(
                      hintText: 'Enter OTP code',
                      border: OutlineInputBorder(),
                    ),
                  ),
                  const SizedBox(height: 10),
                  SizedBox(
                    width: double.infinity,
                    child: ElevatedButton(
                      onPressed: _isPending ? null : _verifyOtp,
                      style: ElevatedButton.styleFrom(
                        backgroundColor: const Color(0xFF05B959),
                      ),
                      child: _isPending
                          ? const SizedBox(
                              height: 20,
                              width: 20,
                              child: CircularProgressIndicator(
                                color: Colors.white,
                                strokeWidth: 2,
                              ),
                            )
                          : const Text('Verify OTP',
                              style: TextStyle(color: Colors.white)),
                    ),
                  ),
                  const SizedBox(height: 10),
                  SizedBox(
                    width: double.infinity,
                    child: OutlinedButton(
                      onPressed: () => setState(() => _otpSent = false),
                      child: const Text('Back'),
                    ),
                  ),
                ],
                const SizedBox(height: 20),
                const Text('OR'),
                const SizedBox(height: 10),
                SizedBox(
                  width: double.infinity,
                  child: ElevatedButton(
                    onPressed: () => walletContext.requireAuth
                        .loginWithOAuth(CrossmintOAuthProvider.google),
                    style: ElevatedButton.styleFrom(
                      backgroundColor: const Color(0xFF4285F4),
                    ),
                    child: const Text('Sign in with Google',
                        style: TextStyle(color: Colors.white)),
                  ),
                ),
              ],
            ),
          ),
        );
      }

      @override
      void dispose() {
        _emailController.dispose();
        _otpController.dispose();
        super.dispose();
      }
    }

    class WalletScreen extends StatelessWidget {
      final CrossmintRuntimeWalletBase wallet;

      const WalletScreen({super.key, required this.wallet});

      @override
      Widget build(BuildContext context) {
        final walletContext = CrossmintWalletContext.of(context);

        return Scaffold(
          body: Padding(
            padding: const EdgeInsets.all(20),
            child: Column(
              crossAxisAlignment: CrossAxisAlignment.start,
              children: [
                Row(
                  mainAxisAlignment: MainAxisAlignment.spaceBetween,
                  children: [
                    const Text('Welcome!',
                        style: TextStyle(fontSize: 20)),
                    TextButton(
                      onPressed: () => walletContext.requireAuth.logout(),
                      child: const Text('Logout',
                          style: TextStyle(color: Colors.red)),
                    ),
                  ],
                ),
                const SizedBox(height: 20),
                const Text('Wallet Info:',
                    style: TextStyle(fontSize: 16)),
                Text('Address: ${wallet.address}'),
                Text('Chain: ${wallet.chain}'),
                const SizedBox(height: 20),
                const Text('You are now logged in and can access your wallet!'),
              ],
            ),
          ),
        );
      }
    }
    ```
  </Step>
</Steps>

## Launching in Production

For production, some changes are required:

1. Create a developer account on the <a href="https://www.crossmint.com/console">production console</a>
2. Create a production client API key on the <a href="https://www.crossmint.com/console/projects/apiKeys">API Keys</a> page with the API scopes `users.create`, `users.read`, `wallets.read`, `wallets.create`, `wallets:transactions.create`, `wallets:transactions.sign`, `wallets:balance.read`, `wallets.fund`
3. Replace your test API key with the production key
4. **Use your own authentication provider**: For production applications, Crossmint recommends using [third-party authentication](/wallets/guides/bring-your-own-auth) with providers like Auth0, Firebase, or Supabase, rather than Crossmint Auth. Configure JWT authentication in the <a href="https://www.crossmint.com/console/projects/apiKeys">Crossmint Console</a> under API Keys > JWT Authentication.
5. Switch your chains from testnets to their mainnet equivalents (for example, `base-sepolia` to `base`), and re-create your wallets. Staging wallet addresses do not carry over to production.
6. Replace test tokens with real assets (for example, `usdxm` to `usdc`), and plan for gas sponsorship as a real cost

See [Staging vs Production](/introduction/platform/staging-vs-production) for the full list of differences between environments

## Learn More

<CardGroup>
  <Card title="Check Balances" icon="money-bill-transfer" href="/wallets/guides/check-balances">
    Check the balance of a wallet.
  </Card>

  <Card title="Transfer Tokens" icon="coins" href="/wallets/guides/transfer-tokens">
    Send tokens between wallets.
  </Card>

  <Card title="Operational Signers" icon="key" href="/wallets/guides/signers/add-signers">
    Register operational signers on a wallet.
  </Card>
</CardGroup>

## Other Links

<CardGroup>
  <Card title="API Reference" icon="terminal" href="/api-reference/wallets/create-wallet">
    Deep dive into API reference docs.
  </Card>

  <Card title="Talk to an expert" icon="message" href="https://www.crossmint.com/contact/sales">
    Contact the Crossmint sales team for support.
  </Card>
</CardGroup>


# Kotlin
Source: https://docs.crossmint.com/wallets/quickstarts/kotlin

Create user wallets from your mobile app in under 5 minutes

This quickstart integrates the Crossmint Kotlin SDK into an Android app to create a non-custodial wallet for a user, fund it with testnet USDC on Base Sepolia, and send USDC to another wallet.

<CardGroup>
  <Snippet />

  <Card title="Android Demo App" icon="github" href="https://github.com/Crossmint/android-quickstart">
    See a full working example with a repository to clone.
  </Card>
</CardGroup>

<Steps>
  <Step title="Install the SDK">
    Add the Crossmint dependencies to your app's `build.gradle.kts` file:

    <Tabs>
      <Tab title="Version Catalog">
        ```kotlin build.gradle.kts theme={null}
        dependencies {
            implementation(libs.crossmint.sdk)
            implementation(libs.crossmint.compose)
        }
        ```

        ```toml libs.versions.toml theme={null}
        [versions]
        crossmint-sdk = "1.1.1"

        [libraries]
        crossmint-compose = { module = "com.crossmint:crossmint-compose", version.ref = "crossmint-sdk" }
        crossmint-sdk = { module = "com.crossmint:crossmint-sdk", version.ref = "crossmint-sdk" }
        ```
      </Tab>

      <Tab title="Direct">
        ```kotlin build.gradle.kts theme={null}
        dependencies {
            implementation("com.crossmint:crossmint-sdk:1.1.1")
            implementation("com.crossmint:crossmint-compose:1.1.1")
        }
        ```
      </Tab>
    </Tabs>

    ### Requirements

    * Minimum Android SDK: API 24 (Android 7.0+)
    * JDK 11 or newer
    * Jetpack Compose
  </Step>

  <Step title="Configure your API key">
    The Crossmint SDK requires a client API key for authentication. <br />
    [Get your client API key](/introduction/platform/api-keys/client-side) using the Crossmint Console.
  </Step>

  <Step title="Initialize the Crossmint SDK">
    Initialize the SDK in your `Application` class, then wrap your composable tree with `CrossmintNonCustodialSignerProvider` to enable the non-custodial signing layer. This example uses [Crossmint Auth](/authentication/introduction) but you can use [any authentication provider of your choice](/wallets/guides/bring-your-own-auth).

    ```kotlin MyApplication.kt theme={null}
    import android.app.Application
    import com.crossmint.kotlin.CrossmintSDK
    import com.crossmint.kotlin.configure
    import com.crossmint.kotlin.core.LogLevel

    val CROSSMINT_API_KEY = "ck_staging_your_key_here"

    class MyApplication : Application() {
        override fun onCreate() {
            super.onCreate()
            CrossmintSDK.configure(
                apiKey = CROSSMINT_API_KEY,
                appContext = this,
                logLevel = LogLevel.WARN,
            )
        }
    }
    ```

    Then wrap your top-level composable with `CrossmintNonCustodialSignerProvider`:

    ```kotlin theme={null}
    @Composable
    fun QuickstartApp() {
        CrossmintNonCustodialSignerProvider {
            // Your app content goes here
            AppContent()
        }
    }
    ```

    <Note>
      The environment (staging vs production) is automatically determined by your API key. Staging keys start with `ck_staging_`, production keys with `ck_production_`.
    </Note>

    ### Access SDK instances

    Inside the `CrossmintNonCustodialSignerProvider`, access SDK functionality using `LocalCrossmintSDK.current`:

    ```kotlin theme={null}
    import com.crossmint.kotlin.auth.CrossmintAuthManager
    import com.crossmint.kotlin.compose.LocalCrossmintSDK

    val sdk = LocalCrossmintSDK.current
    val authManager = sdk.authManager as CrossmintAuthManager
    val wallets = sdk.wallets
    ```
  </Step>

  <Step title="Authenticate users">
    Actions within the SDK are user-based, so first you need to authenticate a user.
    Choose your authentication method:

    <Tabs>
      <Tab title="Crossmint Auth (OTP)">
        Use Crossmint's built-in OTP authentication for easy, email-based login.

        <Steps>
          <Step title="Send OTP to user's email">
            ```kotlin theme={null}
            import com.crossmint.kotlin.auth.CrossmintAuthManager
            import com.crossmint.kotlin.compose.LocalCrossmintSDK
            import com.crossmint.kotlin.types.Result

            val authManager = LocalCrossmintSDK.current.authManager as CrossmintAuthManager
            val email = "user@example.com"

            when (val result = authManager.sendOtp(email)) {
                is Result.Success -> {
                    // OTP sent — show an input field for the code
                }
                is Result.Failure -> {
                    // Handle the error
                }
            }
            ```
          </Step>

          <Step title="Enter the OTP sent to the user's email">
            ```kotlin theme={null}
            import com.crossmint.kotlin.auth.CrossmintAuthManager
            import com.crossmint.kotlin.auth.models.OTPAuthenticationStatus
            import com.crossmint.kotlin.compose.LocalCrossmintSDK
            import com.crossmint.kotlin.types.Result

            val authManager = LocalCrossmintSDK.current.authManager as CrossmintAuthManager
            val email = "user@example.com"
            val otpCode = "123456" // code entered by the user

            when (val result = authManager.verifyOtp(email, otpCode)) {
                is Result.Success -> {
                    when (result.value) {
                        OTPAuthenticationStatus.AUTHENTICATED -> {
                            // User is authenticated, proceed to create wallet
                        }
                        OTPAuthenticationStatus.INVALID_CODE -> {
                            // Wrong code — ask the user to try again
                        }
                        else -> { /* handle other states */ }
                    }
                }
                is Result.Failure -> {
                    // Handle the error
                }
            }
            ```
          </Step>
        </Steps>

        <Note>
          See the <a href="https://github.com/Crossmint/android-quickstart">Android Demo App</a> repository for a complete UI implementation example with ViewModels and Compose screens.
        </Note>
      </Tab>

      <Tab title="Third-Party Auth (Prod)">
        If you have an existing auth provider (Auth0, Firebase, Supabase, etc.), authenticate users with your provider and pass the JWT to Crossmint.

        ```kotlin theme={null}
        import com.crossmint.kotlin.auth.CrossmintAuthManager
        import com.crossmint.kotlin.auth.models.AuthToken
        import com.crossmint.kotlin.compose.LocalCrossmintSDK
        import com.crossmint.kotlin.types.Result

        val authManager = LocalCrossmintSDK.current.authManager as CrossmintAuthManager

        // After user authenticates with your provider, get their JWT
        val token = AuthToken(
            jwt = yourProviderJWT,
            refreshToken = yourProviderRefreshToken, // optional
            userEmail = userEmail // optional
        )

        when (val result = authManager.authenticateWithToken(token)) {
            is Result.Success -> {
                // User authenticated with Crossmint
            }
            is Result.Failure -> {
                // Handle the error
            }
        }
        ```

        <Note>
          Configure JWT authentication in the [Crossmint Console](https://console.crossmint.com) under API Keys → JWT Authentication before using third-party auth. See the [Crossmint Demo App](https://github.com/Crossmint/crossmint-kotlin-sdk/tree/main/crossmintDemoApp) for a complete Supabase integration example.
        </Note>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Create a wallet">
    After authentication, create the user's wallet. This example uses Base Sepolia (Base testnet) but you can choose any [supported chain](/introduction/supported-chains).

    ```kotlin theme={null}
    import com.crossmint.kotlin.auth.CrossmintAuthManager
    import com.crossmint.kotlin.compose.LocalCrossmintSDK
    import com.crossmint.kotlin.signers.SignerType
    import com.crossmint.kotlin.types.EVMChain
    import com.crossmint.kotlin.types.Result

    val sdk = LocalCrossmintSDK.current
    val authManager = sdk.authManager as CrossmintAuthManager
    val wallets = sdk.wallets

    val email = authManager.authState.value.email ?: return

    when (val result = wallets.createWallet(
        chain = EVMChain.BaseSepolia,
        recoveryMethods = listOf(SignerType.Email(email))
    )) {
        is Result.Success -> {
            val wallet = result.value // Wallet is ready to use!
        }
        is Result.Failure -> {
            // Handle the error
        }
    }
    ```

    <Note>
      Use `getWallet(EVMChain.BaseSepolia)` for returning users to fetch their existing wallet without creating a new one.
    </Note>
  </Step>

  <Step title="Check wallet balance">
    Before sending tokens, check the wallet balance:

    ```kotlin theme={null}
    import com.crossmint.kotlin.types.Result

    when (val result = wallet.balances()) {
        is Result.Success -> {
            val balances = result.value

            // Native token (ETH on Base Sepolia)
            println("ETH: ${balances.nativeToken.amount}")

            // USDC balance
            println("USDC: ${balances.usdc.amount}")

            // All other tokens in this wallet
            for (token in balances.tokens) {
                println("${token.name}: ${token.amount}")
            }
        }
        is Result.Failure -> {
            // Handle the error
        }
    }
    ```
  </Step>

  <Step title="Fund the wallet">
    Before sending USDC, you need to get some into the wallet.

    **Option 1: Use the staging fund method (staging only)**

    ```kotlin theme={null}
    import com.crossmint.kotlin.types.Result

    when (val result = wallet.fund(token = "usdxm", amount = 10, chain = "base-sepolia")) {
        is Result.Success -> { /* Funded! */ }
        is Result.Failure -> {
            // Handle the error
        }
    }
    ```

    **Option 2: Use the USDC Faucet**

    Get the wallet address and use the <a href="https://faucet.circle.com/">USDC Faucet</a>:

    ```kotlin theme={null}
    val walletAddress = wallet.address
    ```

    Navigate to the faucet, select **Base Sepolia**, and enter the wallet address.

    <img alt="Circle faucet — Base Sepolia selected" />
  </Step>

  <Step title="Send USDC">
    Send USDC to another wallet using the `wallet.send` function:

    ```kotlin theme={null}
    import com.crossmint.kotlin.types.Result

    val recipient = "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb2"
    val tokenLocator = "base-sepolia:usdc"
    val amount = 0.01

    when (val sendResult = wallet.send(recipient, tokenLocator, amount)) {
        is Result.Failure -> {
            // Handle failure
        }
        is Result.Success -> {
            when (val approveResult = wallet.approve(sendResult.value.id)) {
                is Result.Success -> {
                    // Transaction successful
                }
                is Result.Failure -> {
                    // Handle failure
                }
            }
        }
    }
    ```

    The very first time that a wallet sends a transaction on this device, an OTP will be required, sent to the user via email.

    Following transactions sent from the same device will not need OTP verification.

    To handle the OTP flow, collect the `isOTPRequired` flow from the SDK in your composable:

    ```kotlin theme={null}
    import androidx.compose.runtime.collectAsState
    import androidx.compose.runtime.rememberCoroutineScope
    import com.crossmint.kotlin.compose.CrossmintNonCustodialSignerProvider
    import com.crossmint.kotlin.compose.LocalCrossmintSDK
    import kotlinx.coroutines.launch

    @Composable
    fun QuickstartApp() {
        CrossmintNonCustodialSignerProvider {
            val sdk = LocalCrossmintSDK.current
            val otpRequired by sdk.isOTPRequired.collectAsState(initial = false)
            val scope = rememberCoroutineScope()

            AppContent()

            if (otpRequired) {
                OTPDialog(
                    onOTPSubmit = { otp -> scope.launch { sdk.submit(otp) } },
                    onDismiss = { scope.launch { sdk.cancelTransaction() } }
                )
            }
        }
    }
    ```

    Here is a simple OTP dialog component you can use:

    <Accordion title="OTP Sample code">
      ```kotlin theme={null}
      @Composable
      fun OTPDialog(
          onOTPSubmit: (String) -> Unit,
          onDismiss: () -> Unit,
      ) {
          var otpCode by remember { mutableStateOf("") }

          AlertDialog(
              onDismissRequest = onDismiss,
              title = { Text("Enter OTP Code") },
              text = {
                  TextField(
                      value = otpCode,
                      onValueChange = { otpCode = it },
                      label = { Text("Enter OTP") },
                      singleLine = true,
                  )
              },
              confirmButton = {
                  Button(onClick = { onOTPSubmit(otpCode) }) {
                      Text("Submit")
                  }
              },
              dismissButton = {
                  TextButton(onClick = onDismiss) {
                      Text("Cancel")
                  }
              },
          )
      }
      ```
    </Accordion>

    And that is it! You just created a non-custodial wallet for your user and made a USDC transaction on Base Sepolia.
  </Step>
</Steps>

## Launching in Production

For production, the steps are almost identical, but some changes are required:

1. Create a developer account on the [production console](https://www.crossmint.com/console)
2. Create a production client API key on the [API Keys](https://www.crossmint.com/console/projects/apiKeys) page with the API scopes `users.create`, `users.read`, `wallets.read`, `wallets.create`, `wallets:transactions.create`, `wallets:transactions.sign`, `wallets:balance.read`, `wallets.fund`
3. Update your `local.properties` with the production API key
4. **Use your own authentication provider**: For production applications, Crossmint recommends using [third-party authentication](/wallets/guides/bring-your-own-auth) (Option 2 from Step 4) with providers like Auth0, Firebase, or Supabase, rather than Crossmint Auth (OTP). Configure JWT authentication in the [Crossmint Console](https://www.crossmint.com/console/projects/apiKeys) under API Keys → JWT Authentication.
5. Switch your chains from testnets to their mainnet equivalents (for example, `base-sepolia` to `base`), and re-create your wallets. Staging wallet addresses do not carry over to production.
6. Replace test tokens with real assets (for example, `usdxm` to `usdc`), and plan for gas sponsorship as a real cost

See [Staging vs Production](/introduction/platform/staging-vs-production) for the full list of differences between environments


# Node.js
Source: https://docs.crossmint.com/wallets/quickstarts/nodejs

Create and manage wallets from your backend in under 5 minutes

<CardGroup>
  <Snippet />
</CardGroup>

<Steps>
  <Step title="Install the SDK">
    Run the following command to install the SDK:

    <Snippet />
  </Step>

  <Step title="Create a wallet with a server signer">
    The server signer uses a secret key you provide to derive a
    blockchain address deterministically. The same secret always
    produces the same address.

    <Note>
      Before creating a wallet, you need a signer secret. Generate one using the [secret generator](/wallets/guides/signers/server-signer#signer-secret-generator) or [programmatically](/wallets/guides/signers/server-signer#generate-your-own-key-programmatically), then store it as an environment variable (e.g. `SIGNER_SECRET`). See the [Server Signer guide](/wallets/guides/signers/server-signer) for full details.
    </Note>

    See all supported chains [here](/introduction/supported-chains).

    ```typescript index.ts theme={null}
    import {
        CrossmintWallets,
        createCrossmint,
    } from "@crossmint/wallets-sdk";

    const crossmint = createCrossmint({
        apiKey: "YOUR_SERVER_API_KEY",
    });

    const wallets = CrossmintWallets.from(crossmint);

    const wallet = await wallets.createWallet({
        chain: "base-sepolia",
        recoveryMethods: [
            {
                type: "server",
                secret: process.env.SIGNER_SECRET!, // set in your .env file
            },
        ],
    });

    console.log("Wallet address:", wallet.address);
    ```

    <Note>
      The `secret` is never sent to Crossmint. The SDK derives the
      blockchain address locally from the secret and only sends the
      address to the API.
    </Note>
  </Step>

  <Step title="Check balances">
    ```typescript check-balance.ts theme={null}
    // Assumes `wallet` was created in the wallet creation step above
    const balances = await wallet.balances(["usdc", "usdxm"]);

    for (const token of balances.tokens) {
        console.log(`${token.symbol}: ${token.amount}`);
    }
    ```
  </Step>

  <Step title="Transfer tokens">
    ```typescript transfer.ts theme={null}
    // Assumes `wallet` was created in the wallet creation step above
    const tx = await wallet.send(
        "RECIPIENT_ADDRESS",
        "usdxm",
        "1"
    );

    console.log("Explorer:", tx.explorerLink);
    ```
  </Step>
</Steps>

## Launching in Production

For production, some changes are required:

1. Create a developer account on the <a href="https://www.crossmint.com/console">production console</a>
2. Create a production server API key on the <a href="https://www.crossmint.com/console/projects/apiKeys">API Keys</a> page with the API scopes `wallets.read`, `wallets.create`, `wallets:transactions.create`, `wallets:transactions.sign`, `wallets:balance.read`, `wallets.fund`
3. Replace your test API key with the production key
4. Switch your chains from testnets to their mainnet equivalents (for example, `base-sepolia` to `base`), and re-create your wallets. Staging wallet addresses do not carry over to production.
5. Replace test tokens with real assets (for example, `usdxm` to `usdc`), and plan for gas sponsorship as a real cost

See [Staging vs Production](/introduction/platform/staging-vs-production) for the full list of differences between environments

## Learn More

<CardGroup>
  <Card title="Check Balances" icon="money-bill-transfer" href="/wallets/guides/check-balances">
    Check the balance of a wallet.
  </Card>

  <Card title="Transfer Tokens" icon="coins" href="/wallets/guides/transfer-tokens">
    Send tokens between wallets.
  </Card>

  <Card title="Operational Signers" icon="key" href="/wallets/guides/signers/add-signers">
    Register operational signers on a wallet.
  </Card>
</CardGroup>

## Other Links

<CardGroup>
  <Card title="API Reference" icon="terminal" href="/api-reference/wallets/create-wallet">
    Deep dive into API reference docs.
  </Card>

  <Card title="Talk to an expert" icon="message" href="https://www.crossmint.com/contact/sales">
    Contact our sales team for support.
  </Card>
</CardGroup>


# React
Source: https://docs.crossmint.com/wallets/quickstarts/react

Create user wallets from your frontend in under 5 minutes

<CardGroup>
  <Snippet />

  <Card title="Wallets Quickstart" icon="github" href="https://github.com/Crossmint/wallets-quickstart">
    See a full working example.
  </Card>
</CardGroup>

<Steps>
  <Step title="Install the SDK">
    Run the following command to install the SDK:

    <Snippet />
  </Step>

  <Step title="Add the Crossmint providers to your app">
    Add the necessary Crossmint providers to your app. This example uses
    [Crossmint Auth](/authentication/introduction) but you can use
    [any authentication provider of your choice](/wallets/guides/bring-your-own-auth).

    With the current setup, a wallet will be created automatically on login.

    ```tsx providers.tsx theme={null}
    "use client";

    import {
        CrossmintProvider,
        CrossmintAuthProvider,
        CrossmintWalletProvider,
    } from "@crossmint/client-sdk-react-ui";

    export function Providers({
        children,
    }: {
        children: React.ReactNode;
    }) {
        return (
            <CrossmintProvider
                apiKey={process.env.NEXT_PUBLIC_CROSSMINT_API_KEY!}
            >
                <CrossmintAuthProvider
                    loginMethods={["email", "google"]}
                >
                    <CrossmintWalletProvider
                        createOnLogin={{
                            chain: "base-sepolia",
                            recoveryMethods: [{ type: "email" }],
                        }}
                    >
                        {children}
                    </CrossmintWalletProvider>
                </CrossmintAuthProvider>
            </CrossmintProvider>
        );
    }
    ```

    For detailed configuration options, see the
    [React SDK Reference](/sdk-reference/wallets/react/providers#crossmintwalletprovider).
  </Step>

  <Step title="Display wallet info">
    Use the `useWallet` hook to access the wallet once the user is
    authenticated.

    ```tsx wallet-display.tsx theme={null}
    "use client";

    import { useWallet } from "@crossmint/client-sdk-react-ui";

    export function WalletDisplay() {
        const { wallet, status } = useWallet();

        if (status === "in-progress") {
            return <p>Creating wallet...</p>;
        }

        if (!wallet) {
            return <p>No wallet connected</p>;
        }

        return (
            <div>
                <p>Address: {wallet.address}</p>
                <p>Chain: {wallet.chain}</p>
            </div>
        );
    }
    ```
  </Step>

  <Step title="Check balances and fund the wallet">
    Query token balances and fund the wallet in staging.

    ```tsx balance-card.tsx theme={null}
    "use client";

    import { useWallet } from "@crossmint/client-sdk-react-ui";
    import { useState } from "react";

    const TOKENS = ["usdxm", "usdc"];

    export function BalanceCard() {
        const { wallet } = useWallet();
        const [balances, setBalances] =
            useState<Record<string, string>>({});

        const refreshBalance = async () => {
            if (!wallet) return;
            const res = await wallet.balances(TOKENS);
            const map: Record<string, string> = {};
            for (const t of res.tokens) {
                map[t.symbol] = t.amount;
            }
            setBalances(map);
        };

        const handleFund = async () => {
            if (!wallet) return;
            // Note: stagingFund() is for testing only - remove in production
            await wallet.stagingFund(10);
            await refreshBalance();
        };

        return (
            <div>
                {TOKENS.map((token) => (
                    <p key={token}>
                        {token.toUpperCase()}: {balances[token] ?? "—"}
                    </p>
                ))}
                <button onClick={handleFund}>
                    Fund 10 USDXM
                </button>
                <button onClick={refreshBalance}>
                    Refresh
                </button>
            </div>
        );
    }
    ```
  </Step>

  <Step title="Transfer tokens">
    Send tokens to another wallet address.

    ```tsx transfer-form.tsx theme={null}
    "use client";

    import { useWallet } from "@crossmint/client-sdk-react-ui";
    import { useState } from "react";

    export function TransferForm() {
        const { wallet } = useWallet();
        const [recipient, setRecipient] = useState("");
        const [amount, setAmount] = useState("");
        const [explorerUrl, setExplorerUrl] = useState("");

        const handleTransfer = async () => {
            if (!wallet || !recipient || !amount) return;
            try {
                const { explorerLink } = await wallet.send(
                    recipient,
                    "usdxm",
                    amount
                );
                setExplorerUrl(explorerLink);
                setRecipient("");
                setAmount("");
            } catch (error) {
                console.error("Transfer failed:", error);
            }
        };

        return (
            <div>
                <input
                    placeholder="Recipient address"
                    value={recipient}
                    onChange={(e) => setRecipient(e.target.value)}
                />
                <input
                    type="number"
                    placeholder="Amount"
                    value={amount}
                    onChange={(e) => setAmount(e.target.value)}
                />
                <button
                    onClick={handleTransfer}
                    disabled={!recipient || !amount}
                >
                    Transfer
                </button>
                {explorerUrl && (
                    <a href={explorerUrl} target="_blank">
                        View transaction
                    </a>
                )}
            </div>
        );
    }
    ```
  </Step>

  <Step title="Render the app">
    Compose the providers and components in your app entry point.

    ```tsx app.tsx theme={null}
    "use client";

    import { Providers } from "./providers";
    import { WalletDisplay } from "./wallet-display";
    import { BalanceCard } from "./balance-card";
    import { TransferForm } from "./transfer-form";

    export default function Home() {
        return (
            <Providers>
                <WalletDisplay />
                <BalanceCard />
                <TransferForm />
            </Providers>
        );
    }
    ```
  </Step>
</Steps>

## Launching in Production

For production, some changes are required:

1. Create a developer account on the <a href="https://www.crossmint.com/console">production console</a>
2. Create a production client API key on the <a href="https://www.crossmint.com/console/projects/apiKeys">API Keys</a> page with the API scopes `users.create`, `users.read`, `wallets.read`, `wallets.create`, `wallets:transactions.create`, `wallets:transactions.sign`, `wallets:balance.read`, `wallets.fund`
3. Replace your test API key with the production key
4. **Use your own authentication provider**: For production applications, Crossmint recommends using [third-party authentication](/wallets/guides/bring-your-own-auth) with providers like Auth0, Firebase, or Supabase, rather than Crossmint Auth. Configure JWT authentication in the <a href="https://www.crossmint.com/console/projects/apiKeys">Crossmint Console</a> under API Keys > JWT Authentication.
5. Switch your chains from testnets to their mainnet equivalents (for example, `base-sepolia` to `base`), and re-create your wallets. Staging wallet addresses do not carry over to production.
6. Replace test tokens with real assets (for example, `usdxm` to `usdc`), and plan for gas sponsorship as a real cost

See [Staging vs Production](/introduction/platform/staging-vs-production) for the full list of differences between environments

## Learn More

<CardGroup>
  <Card title="Check Balances" icon="money-bill-transfer" href="/wallets/guides/check-balances">
    Check the balance of a wallet.
  </Card>

  <Card title="Transfer Tokens" icon="coins" href="/wallets/guides/transfer-tokens">
    Send tokens between wallets.
  </Card>

  <Card title="Operational Signers" icon="key" href="/wallets/guides/signers/add-signers">
    Register operational signers on a wallet.
  </Card>
</CardGroup>

## Other Links

<CardGroup>
  <Card title="API Reference" icon="terminal" href="/api-reference/wallets/create-wallet">
    Deep dive into API reference docs.
  </Card>

  <Card title="Talk to an expert" icon="message" href="https://www.crossmint.com/contact/sales">
    Contact our sales team for support.
  </Card>
</CardGroup>


# React Native
Source: https://docs.crossmint.com/wallets/quickstarts/react-native

Create user wallets from your Expo app in under 5 minutes

<CardGroup>
  <Snippet />

  <Card title="Expo Wallets Quickstart" icon="github" href="https://github.com/Crossmint/wallets-expo-quickstart">
    See a full working example.
  </Card>
</CardGroup>

<Steps>
  <Step title="Install the SDK">
    Run the following command to install the SDK:

    <Snippet />
  </Step>

  <Step title="Add the Crossmint providers to your app">
    Add the necessary Crossmint providers to your app. This example uses [Crossmint Auth](/authentication/introduction)
    but you can use [any authentication provider of your choice](/wallets/guides/bring-your-own-auth).

    With the current setup, a wallet will be created automatically on login.

    See all supported chains [here](/introduction/supported-chains).

    ```tsx providers.tsx theme={null}
    import {
        CrossmintProvider,
        CrossmintAuthProvider,
        CrossmintWalletProvider,
    } from "@crossmint/client-sdk-react-native-ui";

    type ProvidersProps = {
        children: React.ReactNode;
    };

    export default function CrossmintProviders(
        { children }: ProvidersProps
    ) {
        return (
            <CrossmintProvider
                apiKey={process.env.EXPO_PUBLIC_CROSSMINT_API_KEY!}
            >
                <CrossmintAuthProvider>
                    <CrossmintWalletProvider
                        createOnLogin={{
                            chain: "base-sepolia",
                            recoveryMethods: [{ type: "email" }],
                        }}
                    >
                        {children}
                    </CrossmintWalletProvider>
                </CrossmintAuthProvider>
            </CrossmintProvider>
        );
    }
    ```

    For detailed configuration options, see the [React Native SDK Reference](/sdk-reference/wallets/react-native/providers#crossmintwalletprovider).
  </Step>

  <Step title="Allow users to login and logout and access their wallet">
    Crossmint Auth in React Native is headless. You will need to implement your own login and logout buttons.

    ```tsx index.tsx theme={null}
    import React, { useEffect, useState } from "react";
    import {
        View,
        Text,
        TextInput,
        TouchableOpacity,
        ActivityIndicator,
        Alert,
    } from "react-native";
    import {
        useCrossmintAuth,
        useWallet,
    } from "@crossmint/client-sdk-react-native-ui";
    import * as Linking from "expo-linking";

    export default function Index() {
        const {
            loginWithOAuth,
            createAuthSession,
            user,
            crossmintAuth,
            logout,
            status,
        } = useCrossmintAuth();
        const { wallet } = useWallet();

        // Login state
        const [email, setEmail] = useState("");
        const [emailId, setEmailId] = useState("");
        const [otpSent, setOtpSent] = useState(false);
        const [otp, setOtp] = useState("");
        const [isPending, setIsPending] = useState(false);

        // Handle OAuth callback
        const url = Linking.useURL();

        // Handle OAuth callback
        useEffect(() => {
            if (url != null) {
                createAuthSession(url);
            }
        }, [url, createAuthSession]);

        // Login functions
        const sendOtp = async () => {
            if (!email.trim()) {
                Alert.alert("Error", "Please enter a valid email address");
                return;
            }

            setIsPending(true);
            try {
                const res = await crossmintAuth?.sendEmailOtp(email);
                setEmailId(res.emailId);
                setOtpSent(true);
            } catch (error) {
                console.error("sendOtp error:", error);
                const message =
                    error instanceof Error
                        ? error.message
                        : "Failed to send OTP.";
                Alert.alert("Error", message);
            } finally {
                setIsPending(false);
            }
        };

        const verifyOtp = async () => {
            if (!otp.trim()) {
                Alert.alert("Error", "Please enter the OTP code");
                return;
            }

            setIsPending(true);
            try {
                const oneTimeSecret =
                    await crossmintAuth?.confirmEmailOtp(
                        email,
                        emailId,
                        otp
                    );
                await createAuthSession(oneTimeSecret);
            } catch (error) {
                console.error("verifyOtp error:", error);
                const message =
                    error instanceof Error
                        ? error.message
                        : "Invalid OTP. Try again.";
                Alert.alert("Error", message);
            } finally {
                setIsPending(false);
            }
        };

        const handleLogout = async () => {
            try {
                logout();
                // Reset login state
                setEmail("");
                setEmailId("");
                setOtpSent(false);
                setOtp("");
            } catch (error) {
                Alert.alert("Error", "Failed to logout. Please try again.");
            }
        };

        // Loading state
        if (status === "initializing") {
            return (
                <View style={{
                    flex: 1,
                    justifyContent: "center",
                    alignItems: "center",
                }}>
                    <ActivityIndicator size="large" />
                    <Text>Initializing...</Text>
                </View>
            );
        }

        // Login screen
        if (status === "logged-out") {
            return (
                <View style={{
                    flex: 1,
                    padding: 20,
                    justifyContent: "center",
                }}>
                    <Text style={{
                        fontSize: 24,
                        marginBottom: 20,
                        textAlign: "center",
                    }}>
                        Login
                    </Text>

                    <TextInput
                        style={{
                            borderWidth: 1,
                            padding: 10,
                            marginBottom: 10,
                        }}
                        placeholder="Enter your email"
                        value={email}
                        onChangeText={setEmail}
                        editable={!otpSent}
                    />

                    {!otpSent ? (
                        <TouchableOpacity
                            style={{
                                backgroundColor: "#05b959",
                                padding: 15,
                                alignItems: "center",
                            }}
                            onPress={sendOtp}
                            disabled={isPending}
                        >
                            {isPending ? (
                                <ActivityIndicator
                                    color="#fff"
                                    size="small"
                                />
                            ) : (
                                <Text style={{ color: "#fff" }}>
                                    Send OTP
                                </Text>
                            )}
                        </TouchableOpacity>
                    ) : (
                        <>
                            <TextInput
                                style={{
                                    borderWidth: 1,
                                    padding: 10,
                                    marginBottom: 10,
                                }}
                                placeholder="Enter OTP code"
                                value={otp}
                                onChangeText={setOtp}
                            />
                            <TouchableOpacity
                                style={{
                                    backgroundColor: "#05b959",
                                    padding: 15,
                                    alignItems: "center",
                                    marginBottom: 10,
                                }}
                                onPress={verifyOtp}
                                disabled={isPending}
                            >
                                {isPending ? (
                                    <ActivityIndicator
                                        color="#fff"
                                        size="small"
                                    />
                                ) : (
                                    <Text style={{ color: "#fff" }}>
                                        Verify OTP
                                    </Text>
                                )}
                            </TouchableOpacity>
                            <TouchableOpacity
                                style={{
                                    backgroundColor: "#ccc",
                                    padding: 15,
                                    alignItems: "center",
                                }}
                                onPress={() => setOtpSent(false)}
                                disabled={isPending}
                            >
                                <Text>Back</Text>
                            </TouchableOpacity>
                        </>
                    )}

                    <View style={{ marginVertical: 20 }}>
                        <Text style={{
                            textAlign: "center",
                            marginBottom: 10,
                        }}>
                            OR
                        </Text>
                        <TouchableOpacity
                            style={{
                                backgroundColor: "#4285f4",
                                padding: 15,
                                alignItems: "center",
                            }}
                            onPress={
                                () => loginWithOAuth("google")
                            }
                        >
                            <Text style={{ color: "#fff" }}>
                                Sign in with Google
                            </Text>
                        </TouchableOpacity>
                    </View>
                </View>
            );
        }

        // Main app screen (logged in)
        return (
            <View style={{ flex: 1, padding: 20 }}>
                <View
                    style={{
                        flexDirection: "row",
                        justifyContent: "space-between",
                        marginBottom: 20,
                    }}
                >
                    <Text style={{ fontSize: 20 }}>
                        Welcome!
                    </Text>
                    <TouchableOpacity onPress={handleLogout}>
                        <Text style={{ color: "red" }}>
                            Logout
                        </Text>
                    </TouchableOpacity>
                </View>

                <View style={{ marginBottom: 20 }}>
                    <Text style={{
                        fontSize: 16,
                        marginBottom: 5,
                    }}>
                        User Info:
                    </Text>
                    <Text>Email: {user?.email}</Text>
                    <Text>User ID: {user?.id}</Text>
                </View>

                {wallet && (
                    <View style={{ marginBottom: 20 }}>
                        <Text style={{
                            fontSize: 16,
                            marginBottom: 5,
                        }}>
                            Wallet Info:
                        </Text>
                        <Text>
                            Address: {wallet.address}
                        </Text>
                    </View>
                )}

                <View>
                    <Text style={{
                        fontSize: 16,
                        marginBottom: 10,
                    }}>
                        App Content:
                    </Text>
                    <Text>
                        You are now logged in and can
                        access your wallet!
                    </Text>
                </View>
            </View>
        );
    }
    ```
  </Step>
</Steps>

## Launching in Production

For production, some changes are required:

1. Create a developer account on the <a href="https://www.crossmint.com/console">production console</a>
2. Create a production client API key on the <a href="https://www.crossmint.com/console/projects/apiKeys">API Keys</a> page with the API scopes `users.create`, `users.read`, `wallets.read`, `wallets.create`, `wallets:transactions.create`, `wallets:transactions.sign`, `wallets:balance.read`, `wallets.fund`
3. Replace your test API key with the production key
4. **Use your own authentication provider**: For production applications, Crossmint recommends using [third-party authentication](/wallets/guides/bring-your-own-auth) with providers like Auth0, Firebase, or Supabase, rather than Crossmint Auth. Configure JWT authentication in the <a href="https://www.crossmint.com/console/projects/apiKeys">Crossmint Console</a> under API Keys > JWT Authentication.
5. Switch your chains from testnets to their mainnet equivalents (for example, `base-sepolia` to `base`), and re-create your wallets. Staging wallet addresses do not carry over to production.
6. Replace test tokens with real assets (for example, `usdxm` to `usdc`), and plan for gas sponsorship as a real cost

See [Staging vs Production](/introduction/platform/staging-vs-production) for the full list of differences between environments

## Learn More

<CardGroup>
  <Card title="Check Balances" icon="money-bill-transfer" href="/wallets/guides/check-balances">
    Check the balance of a wallet.
  </Card>

  <Card title="Transfer Tokens" icon="coins" href="/wallets/guides/transfer-tokens">
    Send tokens between wallets.
  </Card>

  <Card title="Operational Signers" icon="key" href="/wallets/guides/signers/add-signers">
    Register operational signers on a wallet.
  </Card>
</CardGroup>

## Other Links

<CardGroup>
  <Card title="API Reference" icon="terminal" href="/api-reference/wallets/create-wallet">
    Deep dive into API reference docs.
  </Card>

  <Card title="Talk to an expert" icon="message" href="https://www.crossmint.com/contact/sales">
    Contact our sales team for support.
  </Card>
</CardGroup>


# REST API
Source: https://docs.crossmint.com/wallets/quickstarts/restapi

Create and manage wallets from your backend using the Crossmint REST API

In this quickstart you will learn how to create wallets, check balances, and transfer tokens from your backend using the Crossmint REST API.

<CardGroup>
  <Snippet />

  <Card title="Wallets Quickstart" icon="github" href="https://github.com/Crossmint/wallets-quickstart">
    See a full working example.
  </Card>
</CardGroup>

## Understanding Wallet Types

Crossmint supports two types of wallets:

* **Smart Wallets**: Account abstraction wallets with configurable signers. You control who can sign transactions (external wallets, server signers, passkeys, etc.).
* **MPC Wallets**: Custodial wallets where Crossmint manages the private keys using multi-party computation. Simpler setup with no signer configuration needed. <a href="https://www.crossmint.com/contact/sales">Contact us</a> for access.

<Steps>
  <Step title="Create a wallet">
    <Tabs>
      <Tab title="EVM Smart Wallet (Server Signer)">
        Smart wallets on EVM chains using a server signer you control.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: YOUR_SERVER_API_KEY' \
              --data '{
                  "chainType": "evm",
                  "type": "smart",
                  "config": {
                      "recoveryMethods": [
                          {
                              "type": "server",
                              "address": "YOUR_SERVER_SIGNER_ADDRESS"
                          }
                      ]
                  },
                  "owner": "email:user@example.com"
              }'
          ```

          ```javascript Node.js theme={null}
          const options = {
              method: "POST",
              headers: {
                  "X-API-KEY": "YOUR_SERVER_API_KEY",
                  "Content-Type": "application/json",
              },
              body: JSON.stringify({
                  chainType: "evm",
                  type: "smart",
                  config: {
                      recoveryMethods: [
                          {
                              type: "server",
                              address: "YOUR_SERVER_SIGNER_ADDRESS",
                          },
                      ],
                  },
                  owner: "email:user@example.com",
              }),
          };

          fetch(
              "https://staging.crossmint.com/api/2025-06-09/wallets",
              options
          )
              .then((response) => response.json())
              .then((data) => console.log("Wallet:", data.address))
              .catch((err) => console.error(err));
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets"

          payload = {
              "chainType": "evm",
              "type": "smart",
              "config": {
                  "recoveryMethods": [
                      {
                          "type": "server",
                          "address": "YOUR_SERVER_SIGNER_ADDRESS"
                      }
                  ]
              },
              "owner": "email:user@example.com"
          }
          headers = {
              "X-API-KEY": "YOUR_SERVER_API_KEY",
              "Content-Type": "application/json"
          }

          response = requests.post(url, json=payload, headers=headers)
          data = response.json()
          print(f"Wallet created: {data['address']}")
          ```
        </CodeGroup>

        <Note>
          The `address` is the blockchain address derived from your server
          signer's secret key. You must derive this yourself before calling
          the API -- the REST API never sees your secret. See the
          [server signer guide](/wallets/guides/signers/server-signer)
          for how to generate and derive this address.
        </Note>

        **Key Parameters:**

        * `chainType`: The blockchain family (`evm` for Ethereum-compatible chains)
        * `type`: Wallet type (`smart` for smart wallets)
        * `config.recoveryMethods`: The recovery methods for the wallet, each able to recover it on its own
          * `type: "server"`: A signer key you manage on your server
          * `address`: The blockchain address derived from your secret
        * `owner`: User identifier in format `email:user@example.com` (optional but recommended)

        <Accordion title="Sample Response (201 Created)">
          ```json theme={null}
          {
              "chainType": "evm",
              "type": "smart",
              "address": "0xABC1234567890DEF1234567890ABCDEF12345678",
              "owner": "email:user@example.com",
              "config": {
                  "recoveryMethods": [
                      {
                          "type": "server",
                          "address": "YOUR_SERVER_SIGNER_ADDRESS",
                          "locator": "server:YOUR_SERVER_SIGNER_ADDRESS"
                      }
                  ]
              },
              "createdAt": "2025-12-15T10:30:00.000Z"
          }
          ```

          **Save the** `address` **field** -- you'll need it to interact with this wallet.
        </Accordion>
      </Tab>

      <Tab title="EVM Smart Wallet (External Wallet)">
        Smart wallets on EVM chains with an external wallet you control as the signer.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: YOUR_SERVER_API_KEY' \
              --data '{
                  "chainType": "evm",
                  "type": "smart",
                  "config": {
                      "recoveryMethods": [
                          {
                              "type": "external-wallet",
                              "address": "YOUR_EXTERNAL_WALLET_ADDRESS"
                          }
                      ]
                  },
                  "owner": "email:user@example.com"
              }'
          ```

          ```javascript Node.js theme={null}
          const options = {
              method: "POST",
              headers: {
                  "X-API-KEY": "YOUR_SERVER_API_KEY",
                  "Content-Type": "application/json",
              },
              body: JSON.stringify({
                  chainType: "evm",
                  type: "smart",
                  config: {
                      recoveryMethods: [
                          {
                              type: "external-wallet",
                              address: "YOUR_EXTERNAL_WALLET_ADDRESS",
                          },
                      ],
                  },
                  owner: "email:user@example.com",
              }),
          };

          fetch(
              "https://staging.crossmint.com/api/2025-06-09/wallets",
              options
          )
              .then((response) => response.json())
              .then((data) => console.log("Wallet:", data.address))
              .catch((err) => console.error(err));
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets"

          payload = {
              "chainType": "evm",
              "type": "smart",
              "config": {
                  "recoveryMethods": [
                      {
                          "type": "external-wallet",
                          "address": "YOUR_EXTERNAL_WALLET_ADDRESS"
                      }
                  ]
              },
              "owner": "email:user@example.com"
          }
          headers = {
              "X-API-KEY": "YOUR_SERVER_API_KEY",
              "Content-Type": "application/json"
          }

          response = requests.post(url, json=payload, headers=headers)
          data = response.json()
          print(f"Wallet created: {data['address']}")
          ```
        </CodeGroup>

        <Accordion title="Sample Response (201 Created)">
          ```json theme={null}
          {
              "chainType": "evm",
              "type": "smart",
              "address": "0xABC1234567890DEF1234567890ABCDEF12345678",
              "owner": "email:user@example.com",
              "config": {
                  "recoveryMethods": [
                      {
                          "type": "external-wallet",
                          "address": "YOUR_EXTERNAL_WALLET_ADDRESS",
                          "locator": "external-wallet:YOUR_EXTERNAL_WALLET_ADDRESS"
                      }
                  ]
              },
              "createdAt": "2025-12-15T10:30:00.000Z"
          }
          ```
        </Accordion>
      </Tab>

      <Tab title="Solana Smart Wallet">
        Smart wallets on Solana with configurable signers.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: YOUR_SERVER_API_KEY' \
              --data '{
                  "chainType": "solana",
                  "type": "smart",
                  "config": {
                      "recoveryMethods": [
                          {
                              "type": "external-wallet",
                              "address": "YOUR_EXTERNAL_WALLET_ADDRESS"
                          }
                      ]
                  },
                  "owner": "email:user@example.com"
              }'
          ```

          ```javascript Node.js theme={null}
          const options = {
              method: "POST",
              headers: {
                  "X-API-KEY": "YOUR_SERVER_API_KEY",
                  "Content-Type": "application/json",
              },
              body: JSON.stringify({
                  chainType: "solana",
                  type: "smart",
                  config: {
                      recoveryMethods: [
                          {
                              type: "external-wallet",
                              address: "YOUR_EXTERNAL_WALLET_ADDRESS",
                          },
                      ],
                  },
                  owner: "email:user@example.com",
              }),
          };

          fetch(
              "https://staging.crossmint.com/api/2025-06-09/wallets",
              options
          )
              .then((response) => response.json())
              .then((data) => console.log("Wallet:", data.address))
              .catch((err) => console.error(err));
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets"

          payload = {
              "chainType": "solana",
              "type": "smart",
              "config": {
                  "recoveryMethods": [
                      {
                          "type": "external-wallet",
                          "address": "YOUR_EXTERNAL_WALLET_ADDRESS"
                      }
                  ]
              },
              "owner": "email:user@example.com"
          }
          headers = {
              "X-API-KEY": "YOUR_SERVER_API_KEY",
              "Content-Type": "application/json"
          }

          response = requests.post(url, json=payload, headers=headers)
          print(f"Wallet created: {response.json()['address']}")
          ```
        </CodeGroup>
      </Tab>

      <Tab title="EVM MPC Wallet">
        <Note><a href="https://www.crossmint.com/contact/sales">Contact us</a> for access to MPC wallets.</Note>

        Custodial wallets on EVM chains.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: YOUR_SERVER_API_KEY' \
              --data '{
                  "chainType": "evm",
                  "type": "mpc",
                  "owner": "email:user@example.com"
              }'
          ```

          ```javascript Node.js theme={null}
          const options = {
              method: "POST",
              headers: {
                  "X-API-KEY": "YOUR_SERVER_API_KEY",
                  "Content-Type": "application/json",
              },
              body: JSON.stringify({
                  chainType: "evm",
                  type: "mpc",
                  owner: "email:user@example.com",
              }),
          };

          fetch(
              "https://staging.crossmint.com/api/2025-06-09/wallets",
              options
          )
              .then((response) => response.json())
              .then((data) => console.log("Wallet:", data.address))
              .catch((err) => console.error(err));
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets"

          payload = {
              "chainType": "evm",
              "type": "mpc",
              "owner": "email:user@example.com"
          }
          headers = {
              "X-API-KEY": "YOUR_SERVER_API_KEY",
              "Content-Type": "application/json"
          }

          response = requests.post(url, json=payload, headers=headers)
          print(f"Wallet created: {response.json()['address']}")
          ```
        </CodeGroup>

        <Note>
          MPC wallets don't require a `config` section. Crossmint manages the private keys securely using multi-party computation.
        </Note>
      </Tab>

      <Tab title="Solana MPC Wallet">
        <Note><a href="https://www.crossmint.com/contact/sales">Contact us</a> for access to MPC wallets.</Note>

        Custodial wallets on Solana.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: YOUR_SERVER_API_KEY' \
              --data '{
                  "chainType": "solana",
                  "type": "mpc",
                  "owner": "email:user@example.com"
              }'
          ```

          ```javascript Node.js theme={null}
          const options = {
              method: "POST",
              headers: {
                  "X-API-KEY": "YOUR_SERVER_API_KEY",
                  "Content-Type": "application/json",
              },
              body: JSON.stringify({
                  chainType: "solana",
                  type: "mpc",
                  owner: "email:user@example.com",
              }),
          };

          fetch(
              "https://staging.crossmint.com/api/2025-06-09/wallets",
              options
          )
              .then((response) => response.json())
              .then((data) => console.log("Wallet:", data.address))
              .catch((err) => console.error(err));
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets"

          payload = {
              "chainType": "solana",
              "type": "mpc",
              "owner": "email:user@example.com"
          }
          headers = {
              "X-API-KEY": "YOUR_SERVER_API_KEY",
              "Content-Type": "application/json"
          }

          response = requests.post(url, json=payload, headers=headers)
          print(f"Wallet created: {response.json()['address']}")
          ```
        </CodeGroup>
      </Tab>
    </Tabs>

    See the [API reference](/api-reference/wallets/create-wallet) for all available parameters.
  </Step>

  <Step title="Retrieve a wallet">
    Retrieve wallet information using a <Tooltip>wallet locator</Tooltip>.

    **Wallet Locator Formats:**

    * By address: `0xABC...` or `GbA2NZ...`
    * By email: `email:user@example.com:evm:smart`
    * By user ID: `userId:507f1f77bcf86cd799439011:solana:mpc`

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request GET \
          --url https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm:smart \
          --header 'X-API-KEY: YOUR_SERVER_API_KEY'
      ```

      ```javascript Node.js theme={null}
      const walletLocator = "email:user@example.com:evm:smart";
      const options = {
          method: "GET",
          headers: { "X-API-KEY": "YOUR_SERVER_API_KEY" },
      };

      fetch(
          `https://staging.crossmint.com/api/2025-06-09/wallets/${walletLocator}`,
          options
      )
          .then((response) => response.json())
          .then((data) => {
              console.log("Wallet address:", data.address);
              console.log("Owner:", data.owner);
          })
          .catch((err) => console.error(err));
      ```

      ```python Python theme={null}
      import requests

      wallet_locator = "email:user@example.com:evm:smart"
      url = f"https://staging.crossmint.com/api/2025-06-09/wallets/{wallet_locator}"

      headers = {"X-API-KEY": "YOUR_SERVER_API_KEY"}

      response = requests.get(url, headers=headers)
      data = response.json()

      print(f"Wallet address: {data['address']}")
      print(f"Owner: {data['owner']}")
      ```
    </CodeGroup>

    <Accordion title="Sample Response (200 OK)">
      ```json theme={null}
      {
          "chainType": "evm",
          "type": "smart",
          "address": "0xABC1234567890DEF1234567890ABCDEF12345678",
          "owner": "email:user@example.com",
          "config": {
              "recoveryMethods": [
                  {
                      "type": "server",
                      "address": "YOUR_SERVER_SIGNER_ADDRESS",
                      "locator": "server:YOUR_SERVER_SIGNER_ADDRESS"
                  }
              ]
          },
          "createdAt": "2025-12-15T10:30:00.000Z"
      }
      ```
    </Accordion>

    <Accordion title="More Wallet Locator Examples">
      * `0x1234567890123456789012345678901234567890` - Direct address
      * `email:user@example.com:evm:smart` - Email + wallet type
      * `userId:507f1f77bcf86cd799439011:solana:mpc` - User ID + wallet type
      * `phoneNumber:+12125551234:evm:smart` - Phone + wallet type
      * `twitter:johndoe:evm:smart` or `x:@johndoe:evm:smart` - Twitter/X + wallet type
    </Accordion>
  </Step>

  <Step title="Check wallet balance">
    Check token balances for a wallet. You can query multiple tokens at once by providing a comma-separated list.

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request GET \
          --url 'https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/balances?tokens=usdc,eth' \
          --header 'X-API-KEY: YOUR_SERVER_API_KEY'
      ```

      ```javascript Node.js theme={null}
      const walletLocator = "email:user@example.com:evm";
      const tokens = "usdc,eth";
      const url =
          `https://staging.crossmint.com/api/2025-06-09/wallets/` +
          `${walletLocator}/balances?tokens=${tokens}`;

      const options = {
          method: "GET",
          headers: { "X-API-KEY": "YOUR_SERVER_API_KEY" },
      };

      fetch(url, options)
          .then((response) => response.json())
          .then((data) => {
              console.log("Native token:", data.nativeToken);
              console.log("Token balances:", data.tokens);
          })
          .catch((err) => console.error(err));
      ```

      ```python Python theme={null}
      import requests

      wallet_locator = "email:user@example.com:evm"
      url = f"https://staging.crossmint.com/api/2025-06-09/wallets/{wallet_locator}/balances"

      params = {"tokens": "usdc,eth"}
      headers = {"X-API-KEY": "YOUR_SERVER_API_KEY"}

      response = requests.get(url, params=params, headers=headers)
      data = response.json()

      print(f"Native token: {data['nativeToken']}")
      print(f"Token balances: {data['tokens']}")
      ```
    </CodeGroup>

    **Query Parameters:**

    * `tokens` (required): Comma-separated list of token symbols (e.g., `usdc,eth,usdxm`)
    * `chains` (optional): Filter by specific chains when using multi-chain wallets

    <Accordion title="Sample Response (200 OK)">
      ```json theme={null}
      {
          "nativeToken": {
              "symbol": "ETH",
              "decimals": 18,
              "balance": "1500000000000000000",
              "balanceUSD": "4500.00"
          },
          "tokens": [
              {
                  "symbol": "USDC",
                  "decimals": 6,
                  "balance": "1000000000",
                  "balanceUSD": "1000.00",
                  "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
              }
          ]
      }
      ```

      Balances are returned as strings in the token's smallest unit (wei for ETH, lamports for SOL, etc.).
    </Accordion>
  </Step>

  <Step title="Transfer tokens">
    Send tokens from a wallet to a recipient. Smart wallets handle gas fees automatically through Crossmint's paymaster.

    **Token Locator Format**: `{chain}:{symbol}` or `{chain}:{contractAddress}` (e.g., `base-sepolia:eth`, `polygon:usdc`, `base-sepolia:0x123...`)

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request POST \
          --url 'https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/tokens/base-sepolia:eth/transfers' \
          --header 'Content-Type: application/json' \
          --header 'X-API-KEY: YOUR_SERVER_API_KEY' \
          --data '{
              "recipient": "RECIPIENT_ADDRESS",
              "amount": "0.001"
          }'
      ```

      ```javascript Node.js theme={null}
      const walletLocator = "email:user@example.com:evm";
      const tokenLocator = "base-sepolia:eth";
      const url =
          `https://staging.crossmint.com/api/2025-06-09/wallets/` +
          `${walletLocator}/tokens/${tokenLocator}/transfers`;

      const options = {
          method: "POST",
          headers: {
              "X-API-KEY": "YOUR_SERVER_API_KEY",
              "Content-Type": "application/json",
          },
          body: JSON.stringify({
              recipient: "RECIPIENT_ADDRESS",
              amount: "0.001",
          }),
      };

      fetch(url, options)
          .then((response) => response.json())
          .then((data) => {
              console.log("Transaction ID:", data.id);
              console.log("Status:", data.status);
          })
          .catch((err) => console.error(err));
      ```

      ```python Python theme={null}
      import requests

      wallet_locator = "email:user@example.com:evm"
      token_locator = "base-sepolia:eth"
      base = "https://staging.crossmint.com/api/2025-06-09"
      url = f"{base}/wallets/{wallet_locator}/tokens/{token_locator}/transfers"

      payload = {
          "recipient": "RECIPIENT_ADDRESS",
          "amount": "0.001"
      }
      headers = {
          "X-API-KEY": "YOUR_SERVER_API_KEY",
          "Content-Type": "application/json"
      }

      response = requests.post(url, json=payload, headers=headers)
      data = response.json()

      print(f"Transaction ID: {data['id']}")
      print(f"Status: {data['status']}")
      ```
    </CodeGroup>

    **Request Parameters:**

    * `recipient` (required): Destination address or locator (e.g., `0x...`, `email:user@example.com`)
    * `amount` (required): Amount to transfer in decimal format (e.g., `"0.001"` for 0.001 ETH)

    <Accordion title="Sample Response (201 Created)">
      ```json theme={null}
      {
          "id": "cm47h2m8e0003vn0zf8yz1234",
          "chainType": "evm",
          "walletType": "smart",
          "status": "pending",
          "params": {
              "calls": [],
              "chain": "base-sepolia",
              "signer": {
                  "type": "evm-keypair",
                  "address": "0x..."
              }
          },
          "onChain": {
              "userOperationHash": "0x...",
              "txId": null
          },
          "sendParams": {
              "token": "base-sepolia:eth",
              "recipient": "RECIPIENT_ADDRESS",
              "amount": "0.001"
          },
          "createdAt": "2025-12-15T10:35:00.000Z"
      }
      ```

      **Transaction Status Values:**

      * `awaiting-approval` - Transaction created, waiting for signer approval
      * `pending` - Transaction submitted to the blockchain
      * `success` - Transaction confirmed onchain
      * `failed` - Transaction failed

      Poll the transaction status using the transaction ID, or set up [webhooks](/wallets/guides/webhooks) for real-time updates.
    </Accordion>

    <Accordion title="Common Token Locators">
      **EVM Chains:**

      * `base-sepolia:eth` - ETH on Base Sepolia testnet
      * `base-sepolia:usdc` - USDC on Base Sepolia
      * `polygon:usdc` - USDC on Polygon mainnet
      * `ethereum:usdt` - USDT on Ethereum mainnet

      **Solana:**

      * `solana:sol` - Native SOL token
      * `solana:usdc` - USDC on Solana

      For contract tokens, use the contract address: `base-sepolia:0x123...`
    </Accordion>
  </Step>
</Steps>

### Using Idempotency Keys

Prevent duplicate wallet creation by using idempotency keys:

```bash theme={null}
curl --request POST \
    --url https://staging.crossmint.com/api/2025-06-09/wallets \
    --header 'Content-Type: application/json' \
    --header 'X-API-KEY: YOUR_SERVER_API_KEY' \
    --header 'x-idempotency-key: unique-operation-id-123' \
    --data '{
        "chainType": "evm",
        "type": "smart",
        "config": {
            "recoveryMethods": [
                {
                    "type": "server",
                    "address": "YOUR_SERVER_SIGNER_ADDRESS"
                }
            ]
        },
        "owner": "email:user@example.com"
    }'
```

If you retry with the same idempotency key, you'll receive the same wallet without creating a duplicate.

## Launching in Production

Ready to go live? Here's what you need to do:

1. Create a production account at <a href="https://www.crossmint.com/console">[www.crossmint.com/console](http://www.crossmint.com/console)</a>
2. Create a production API key with the required scopes:
   * `wallets.create`, `wallets.read`, `wallets:balance.read`, `wallets:transactions.create`
3. Update your API endpoint from `staging.crossmint.com` to `www.crossmint.com`
4. Update your API key in your code to use the production key
5. Switch your chains from testnets to their mainnet equivalents (for example, `base-sepolia` to `base`), and re-create your wallets. Staging wallet addresses do not carry over to production.
6. Replace test tokens with real assets (for example, `usdxm` to `usdc`), and plan for gas sponsorship as a real cost

See [Staging vs Production](/introduction/platform/staging-vs-production) for the full list of differences between environments

<Warning>
  Never expose your server-side API keys in client-side code or public repositories. Store them securely in environment variables or a secrets manager.
</Warning>

## Learn More

<CardGroup>
  <Card title="Check Balances" icon="money-bill-transfer" href="/wallets/guides/check-balances">
    Check the balance of a wallet.
  </Card>

  <Card title="Transfer Tokens" icon="coins" href="/wallets/guides/transfer-tokens">
    Send tokens between wallets.
  </Card>

  <Card title="Operational Signers" icon="key" href="/wallets/guides/signers/add-signers">
    Register operational signers on a wallet.
  </Card>
</CardGroup>


# Swift
Source: https://docs.crossmint.com/wallets/quickstarts/swift

Create user wallets from your iOS app in under 5 minutes

This quickstart integrates the Crossmint Swift SDK into an iOS app to create a non-custodial wallet for a user, fund it with testnet USDC on Base Sepolia, and send USDC to another wallet.

<CardGroup>
  <Snippet />

  <Card title="iOS Demo App" icon="github" href="https://github.com/Crossmint/crossmint-swift-sdk/tree/main/Examples/SmartWalletsDemo">
    See a full working example with a repository to clone.
  </Card>
</CardGroup>

<Steps>
  <Step title="Install the SDK">
    Add the Crossmint Swift SDK to your project using Swift Package Manager.

    In Xcode, go to **File > Add Package Dependencies** and enter the repository URL:

    ```text theme={null}
    https://github.com/Crossmint/crossmint-swift-sdk
    ```

    Select the `CrossmintClientSDK` product to add to your target.

    ### Requirements

    * iOS 15.0+
    * Xcode 16.0+
    * Swift 5.9+
  </Step>

  <Step title="Configure your API key">
    The Crossmint SDK requires a client API key for authentication.
    [Get your client API key](/introduction/platform/api-keys/client-side) using the Crossmint Console.

    Create a file to store your configuration:

    ```swift CrossmintConfig.swift theme={null}
    import CrossmintClient

    let crossmintApiKey = "<YOUR_API_KEY>"
    @MainActor var crossmintAuthManager: CrossmintAuthManager { CrossmintSDK.shared.authManager }
    ```

    <Note>
      The environment (staging vs production) is automatically determined by your API key. Staging keys start with `ck_staging_`, production keys with `ck_production_`.
    </Note>
  </Step>

  <Step title="Initialize the Crossmint SDK">
    Configure the SDK in your app's entry point and add the non-custodial signer view modifier. This example uses [Crossmint Auth](/authentication/introduction) but you can use [any authentication provider of your choice](/wallets/guides/bring-your-own-auth).

    ```swift YourApp.swift theme={null}
    import SwiftUI
    import CrossmintClient

    @main
    struct YourApp: App {
        init() {
            CrossmintSDK.configure(apiKey: crossmintApiKey)
        }

        var body: some Scene {
            WindowGroup {
                ContentView()
                    .crossmintNonCustodialSigner()
            }
        }
    }
    ```

    The `.crossmintNonCustodialSigner()` modifier is required for transaction signing. It embeds a hidden web view that securely manages the signing process.

    ### Access SDK instances

    Inside your views, access SDK functionality using `CrossmintSDK.shared`:

    ```swift theme={null}
    import CrossmintClient

    let sdk = CrossmintSDK.shared
    let authManager = sdk.authManager
    let wallets = sdk.crossmintWallets
    ```
  </Step>

  <Step title="Authenticate users">
    Actions within the SDK are user-based, so first you need to authenticate a user.
    Choose your authentication method:

    <Tabs>
      <Tab title="Crossmint Auth (OTP)">
        Use Crossmint's built-in OTP authentication for easy, email-based login.

        <Steps>
          <Step title="Send OTP to user's email">
            ```swift theme={null}
            import CrossmintAuth

            let email = "user@example.com"

            do {
                try await crossmintAuthManager.sendEmailOtp(email: email)
                // OTP sent — show an input field for the code
            } catch let error as AuthManagerError {
                // Handle error: error.message
            }
            ```
          </Step>

          <Step title="Verify the OTP sent to the user's email">
            ```swift theme={null}
            import CrossmintAuth

            let email = "user@example.com"
            let otpCode = "123456" // Code entered by user

            do {
                let status = try await crossmintAuthManager.confirmEmailOtp(
                    email: email,
                    code: otpCode
                )

                if case .authenticationStatus(.authenticated) = status {
                    // User is authenticated, proceed to create wallet
                }
            } catch let error as AuthManagerError {
                // Handle error: error.message
            }
            ```
          </Step>
        </Steps>

        <Note>
          See the [iOS Demo App](https://github.com/Crossmint/crossmint-swift-sdk/tree/main/Examples/SmartWalletsDemo) repository for a complete UI implementation example with SwiftUI views.
        </Note>
      </Tab>

      <Tab title="Third-Party Auth (Prod)">
        If you have an existing auth provider (Auth0, Firebase, Supabase, etc.), authenticate users with your provider and pass the JWT to Crossmint.

        ```swift theme={null}
        import CrossmintClient

        // After the user authenticates with your provider, set their JWT
        let authManager = CrossmintSDK.shared.authManager
        await authManager.setJWT(yourProviderJWT)
        // User is now authenticated with Crossmint
        ```

        <Note>
          Configure JWT authentication in the [Crossmint Console](https://console.crossmint.com) under API Keys > JWT Authentication before using third-party auth.
        </Note>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Create a wallet">
    After authentication, create the user's wallet. This example uses Base Sepolia (Base testnet) but you can choose any [supported chain](/introduction/supported-chains).

    ```swift theme={null}
    import CrossmintClient
    import CrossmintAuth

    let sdk = CrossmintSDK.shared

    do {
        guard let email = await crossmintAuthManager.email else {
            // User not authenticated — return to the auth step
            return
        }

        let wallet = try await sdk.crossmintWallets.createWallet(
            chain: EVMChain.baseSepolia,
            recoveryMethods: [EVMSigners.email(email)]
        )

        // Wallet is ready to use!
        print("Wallet address: \(wallet.address)")
    } catch let error as WalletError {
        // Handle error: error.message
    }
    ```

    <Note>
      Use `createWallet` for new users. For returning users, call `getWallet(chain: EVMChain.baseSepolia)` to fetch their existing wallet without creating a new one.
    </Note>
  </Step>

  <Step title="Check wallet balance">
    Before sending tokens, check the wallet balance:

    ```swift theme={null}
    import CrossmintClient

    do {
        let balance = try await wallet.balances()

        // Native token (ETH on Base Sepolia)
        print("ETH: \(balance.nativeToken.amount)")

        // USDC balance
        print("USDC: \(balance.usdc.amount)")

        // All other tokens in this wallet
        for token in balance.tokens {
            print("\(token.name): \(token.amount)")
        }
    } catch let error as WalletError {
        // Handle error: error.message
    }
    ```
  </Step>

  <Step title="Fund the wallet">
    Before sending USDC, you need to get some into the wallet.

    **Option 1: Use the staging fund method (staging only)**

    ```swift theme={null}
    do {
        try await wallet.fund(token: .usdxm, amount: 10)
    } catch {
        // Handle error
    }
    ```

    **Option 2: Use the USDC Faucet**

    Get the wallet address and use the [USDC Faucet](https://faucet.circle.com/):

    ```swift theme={null}
    let walletAddress = wallet.address
    print("Fund this address: \(walletAddress)")
    ```

    Navigate to the faucet, select **Base Sepolia**, and enter the wallet address.

    <img alt="Circle faucet - Base Sepolia selected" />
  </Step>

  <Step title="Send USDC">
    Send USDC to another wallet using the `wallet.send` function:

    ```swift theme={null}
    import CrossmintClient

    let recipientAddress = "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb2"

    do {
        let summary = try await wallet.send(
            recipientAddress,
            "base-sepolia:usdc",
            0.01
        )
        print("Transaction hash: \(summary.hash)")
    } catch let error as TransactionError {
        switch error {
        case .userCancelled:
            // User cancelled the transaction
            break
        default:
            // Handle error: error.message
            break
        }
    }
    ```

    <Note>
      The Swift SDK handles transaction approval automatically inside `send()`. Unlike the Kotlin SDK, no explicit `approve()` call is needed.
    </Note>

    The first time a wallet sends a transaction on a device, an OTP verification is required. The SDK automatically handles this by presenting an OTP input view.

    To handle the OTP flow, observe the `isOTPRequired` publisher in your view:

    ```swift theme={null}
    import SwiftUI
    import CrossmintClient

    struct ContentView: View {
        @State private var showOTPView = false

        var body: some View {
            YourMainView()
                .onReceive(CrossmintSDK.shared.isOTPRequired) { required in
                    showOTPView = required
                }
                .sheet(isPresented: $showOTPView) {
                    EmptyView() // Replace with your OTP input UI, then call CrossmintSDK.shared.submit(otp: enteredCode)
                }
        }
    }
    ```

    Following transactions sent from the same device do not need OTP verification.

    And that is it! You just created a non-custodial wallet for your user and made a USDC transaction on Base Sepolia.
  </Step>
</Steps>

## Launching in Production

For production, the steps are almost identical, but some changes are required:

1. Create a developer account on the [production console](https://www.crossmint.com/console)
2. Create a production client API key on the [API Keys](https://www.crossmint.com/console/projects/apiKeys) page with the API scopes `users.create`, `users.read`, `wallets.read`, `wallets.create`, `wallets:transactions.create`, `wallets:transactions.sign`, `wallets:balance.read`, `wallets.fund`
3. Update your configuration with the production API key
4. **Use your own authentication provider**: For production applications, Crossmint recommends using [third-party authentication](/wallets/guides/bring-your-own-auth) with providers like Auth0, Firebase, or Supabase, rather than Crossmint Auth (OTP). Configure JWT authentication in the [Crossmint Console](https://www.crossmint.com/console/projects/apiKeys) under API Keys > JWT Authentication
5. Switch your chains from testnets to their mainnet equivalents (for example, `base-sepolia` to `base`), and re-create your wallets. Staging wallet addresses do not carry over to production.
6. Replace test tokens with real assets (for example, `usdxm` to `usdc`), and plan for gas sponsorship as a real cost

See [Staging vs Production](/introduction/platform/staging-vs-production) for the full list of differences between environments

## Learn More

<CardGroup>
  <Card title="Check Balances" icon="money-bill-transfer" href="/wallets/guides/check-balances">
    Check the balance of a wallet.
  </Card>

  <Card title="Transfer Tokens" icon="coins" href="/wallets/guides/transfer-tokens">
    Send tokens between wallets.
  </Card>

  <Card title="Operational Signers" icon="key" href="/wallets/guides/signers/add-signers">
    Register operational signers on a wallet.
  </Card>
</CardGroup>

## Other Links

<CardGroup>
  <Card title="Swift SDK Reference" icon="https://mintcdn.com/crossmint/GBIHIdhwMt6rU_EY/images/icons/swift.svg?fit=max&auto=format&n=GBIHIdhwMt6rU_EY&q=85&s=91137deeec19366731790dd77c0982bc" href="/sdk-reference/wallets/swift/classes/wallet">
    Deep dive into Swift SDK reference docs.
  </Card>

  <Card title="Talk to an expert" icon="message" href="https://www.crossmint.com/contact/sales">
    Contact the Crossmint sales team for support.
  </Card>
</CardGroup>


# Architecture
Source: https://docs.crossmint.com/wallets/v0/architecture

Crossmint Wallets Architecture

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/architecture) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

Crossmint wallets are designed to provide:

1. **Flexibility**: A single wallet primitive that supports many use cases — end-user wallets, treasury management, disbursements, and more.
2. **High throughput and availability**: Wallets scale to the maximum throughput available per chain, at the fastest speeds possible.
3. **True ownership**: You and your users fully own every wallet. Even if Crossmint were to disappear, wallets continue to function — no vendor lock-in, no dependency on Crossmint infrastructure.

All while abstracting out all blockchain complexity — operate with them via simple REST APIs and SDKs.

## Dual Layer Architecture

Crossmint achieves this by separating two concerns: **the wallet itself** and **the signers that control it**.

<img alt="Crossmint Wallet Dual Layer Architecture" />

### The Core: Smart Contract Wallets

On EVM chains, Crossmint wallets are **smart contract wallets** implementing <a href="https://eips.ethereum.org/EIPS/eip-4337">ERC-4337</a> with <a href="https://eips.ethereum.org/EIPS/eip-7579">ERC-7579</a> modular extensions. Because the wallet is a smart contract, it lives natively on the blockchain — not in a private third-party server that you cannot audit or control.

On Solana, wallets use <a href="https://solana.com/docs/core/pda">program-derived addresses (PDAs)</a> with equivalent programmatic control.

On Stellar, wallets use Soroban smart contracts, with equivalent functionality and additional cost and developer experience improvements around the use of trustlines.

This smart contract foundation enables:

* **Seamless provider migration**: If you wish to migrate, you can update the wallet's recovery signers without changing the wallet address. Your users keep their address, balances, and transaction history regardless of infrastructure changes.
* **Programmable authorization logic**: Add multiple operational and recovery signers, with optional scoped permissions, with logic fully auditable onchain.
* **Flexible gas sponsorship**: Wallets can pay gas in USDC, native token, or billed to your Crossmint account.
* **Easier post-quantum migration**: Unlike wallets that couple wallet address with the underlying signer, Crossmint wallets will continue to operate with the same address once keys are upgraded to post-quantum cryptography.

All permissions are enforced **onchain and fully auditable**, removing the need to trust opaque infrastructure or Crossmint's backend. The wallet logic stays visible, enforceable, and portable.

<Info>
  Because the wallet is a smart contract on a public blockchain, it does not depend on Crossmint's servers to function. If Crossmint were to stop operating, you can interact with the wallet's smart contract directly — adding new signers, transferring assets, or migrating to another provider — using standard blockchain tools.
</Info>

### The Control Layer: Signers

A **[signer](/introduction/glossary)** is a digital identity — such as a passkey, external wallet, or cloud key — authorized to approve actions on the wallet's behalf. By decoupling signers from the wallet, Crossmint obtains higher performance signing with equivalent security, while reducing cost and lock-in significantly compared with cloud-TEE based systems.

**For end-user wallets**, Crossmint uses the native key enclaves already present on your users' devices: the Secure Enclave on iOS and the Keystore on Android. Signatures happen directly on user hardware with no network round-trip to Crossmint or any third-party server. This means signing adds zero latency compared to a direct blockchain transaction — unlike MPC-based architectures that require key reconstruction across distributed infrastructure before every signature, or cloud TEEs which require a network round trip.

**For company and treasury wallets**, Crossmint integrates with your existing cloud infrastructure — AWS KMS, Azure Key Vault, or GCP Cloud HSM. These are the same signing services trusted across tens of thousands of companies outside of crypto, supporting up to 1,000 cryptographic signing operations per second per key.

**For recovery**, Crossmint provides additional signers based on email, phone number, or social login. These recovery signers are added to the wallet's onchain signer set, meaning recovery is enforced by the smart contract itself — not by Crossmint's backend. See [Wallet Signers](/wallets/v0/concepts/wallet-signers#recovery-signers) for recovery signer types and [Custody modalities](/wallets/v0/concepts/custody-modalities) for the custody implications.

## What This Means in Practice

**For end-user wallets**, this architecture enables completely invisible, self-custodial wallets. Users sign transactions on their own device hardware without knowing a blockchain is involved. Gas is fully sponsored. There is no dependency on a third-party server to sign in or transact. And because the wallet is a smart contract, you have a clear migration path away from any provider — update the recovery signer and move on, keeping the same wallet address and all its assets.

**For company and treasury wallets**, you get bank-grade signing infrastructure at a fraction of the cost of specialized custody providers. An AWS KMS signer costs pennies per signing operation and supports throughput that exceeds what most chains can settle. Compare this to custody providers that charge thousands per month for equivalent functionality.

<Card title="Why smart contract wallets?" icon="lightbulb" href="/wallets/v0/why-smart-wallets">
  Learn why Crossmint chose smart contract wallets over MPC and off-chain key storage.
</Card>


# Common Signer Configurations
Source: https://docs.crossmint.com/wallets/v0/concepts/common-signer-configurations

Recommended operational and recovery signer setups for common wallet architectures.

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/concepts/signers) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

This guide provides practical, opinionated signer configurations for common wallet architectures. Use it as a starting point, then adapt based on your threat model, regulatory constraints, and product requirements.

## Non-custodial user wallets

This is the most common configuration. Users are the custodians of their wallets, and your company is not.

| Slot | Recommended signers |
| - | - |
| Operational signers | [Device key](/wallets/v0/concepts/wallet-signers#device-key)<br />[Passkey](/wallets/v0/concepts/wallet-signers#passkey) |
| Recovery signers | [Email OTP](/wallets/v0/concepts/wallet-signers#email-otp)<br />[SMS OTP](/wallets/v0/concepts/wallet-signers#sms-otp) (optional)<br />[Managed support center](/wallets/v0/concepts/wallet-signers#managed-support-center) (optional) |

## Custodial user wallets

If you want to take custody over user wallets, two common approaches are: (1) you act as custodian, or (2) a licensed third-party custodian acts as custodian.

### You are the custodian

You hold the operational signer in your infrastructure and sign operations on behalf of users.

| Slot | Recommended signers |
| - | - |
| Operational signers | [Server signer](/wallets/v0/concepts/wallet-signers#server-signer) (lower risk / early stage)<br />[Cloud KMS](/wallets/v0/concepts/wallet-signers#cloud-kms) (recommended for production) |
| Recovery signers | [Cloud KMS (recovery)](/wallets/v0/concepts/wallet-signers#cloud-kms-recovery) (separate account/region recommended)<br />[Externally custodied key](/wallets/v0/concepts/wallet-signers#externally-custodied-key) (optional)<br />[Managed support center](/wallets/v0/concepts/wallet-signers#managed-support-center) (optional) |

### Licensed third-party custodian

A licensed custodian holds the keys and operates the wallet. This can provide custodial features without your company taking custody directly.

Each custodian has specific integration requirements and signer configurations that depend on their infrastructure and compliance model.

<Note>
  Crossmint can help you set up a third-party custodian integration. <a href="https://www.crossmint.com/contact/sales">Contact our team</a> to get started.
</Note>

## Treasury wallets

Treasury wallets typically prioritize strong controls, auditability, and operational safety.

| Slot | Recommended signers |
| - | - |
| Operational signers | [Cloud KMS](/wallets/v0/concepts/wallet-signers#cloud-kms) |
| Recovery signers | [Cloud KMS (recovery)](/wallets/v0/concepts/wallet-signers#cloud-kms-recovery) (separate account/region recommended)<br />[Externally custodied key](/wallets/v0/concepts/wallet-signers#externally-custodied-key) (optional)<br />[Managed support center](/wallets/v0/concepts/wallet-signers#managed-support-center) (optional) |

## Agent wallets

Custody for AI agents depends on where the agent runs and who can access its runtime environment.

### User-hosted agents

When an agent runs in a user-controlled environment (for example, self-hosted), the user should remain the custodian.

| Slot | Recommended signers |
| - | - |
| Operational signers | [Server signer](/wallets/v0/concepts/wallet-signers#server-signer) (user-managed)<br />[Cloud KMS](/wallets/v0/concepts/wallet-signers#cloud-kms) (user-managed) |
| Recovery signers | [Email OTP](/wallets/v0/concepts/wallet-signers#email-otp) (optional)<br />[Externally custodied key](/wallets/v0/concepts/wallet-signers#externally-custodied-key) |

### Platform-hosted agents

When you host agents on behalf of users, the key principle is to avoid a configuration where the platform host can unilaterally control agent wallets.

A common pattern is to use narrowly-scoped operational signers and require explicit user authorization for higher-risk actions.

| Slot | Recommended signers |
| - | - |
| Operational signers | [Passkey](/wallets/v0/concepts/wallet-signers#passkey) (user confirmation for sensitive actions)<br />[Server signer](/wallets/v0/concepts/wallet-signers#server-signer) (customer-managed, scoped permissions) |
| Recovery signers | [Email OTP](/wallets/v0/concepts/wallet-signers#email-otp)<br />[Managed support center](/wallets/v0/concepts/wallet-signers#managed-support-center) (optional) |

## Scoped custody

Some products need a self-custodial user wallet *plus* a limited, revocable company signer (for example, for repayments, subscriptions, or card settlement).

| Slot | Recommended signers |
| - | - |
| Operational signers | User: [Device key](/wallets/v0/concepts/wallet-signers#device-key) or [Passkey](/wallets/v0/concepts/wallet-signers#passkey)<br />Company (scoped, revocable): [Server signer](/wallets/v0/concepts/wallet-signers#server-signer) or [Cloud KMS](/wallets/v0/concepts/wallet-signers#cloud-kms) |
| Recovery signers | User recovery: [Email OTP](/wallets/v0/concepts/wallet-signers#email-otp) (recommended)<br />Optional hard fallback: [Externally custodied key](/wallets/v0/concepts/wallet-signers#externally-custodied-key) |

<Note>
  Whether a scoped company signer makes your company a custodian depends on whether you can unilaterally execute or block transactions and whether the user can revoke your access. See [Custody modalities](/wallets/v0/concepts/custody-modalities) for the definition.
</Note>


# Custody Modalities
Source: https://docs.crossmint.com/wallets/v0/concepts/custody-modalities

Understand custodial, non-custodial, and hybrid custody models in Crossmint wallets.

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/concepts/custody-models) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

This guide explains what custody means in the context of wallets, why it matters, and how Crossmint lets you choose (and evolve) the right custody modality for your use case.

<Info>
  If you have not yet read it, start with the [Architecture overview](/wallets/v0/architecture). This guide builds on the concepts introduced there.
</Info>

Crossmint wallets support **flexible custody**. You can deploy custodial, non-custodial, or hybrid configurations using the same wallet primitive and APIs. Because wallets are smart contracts, you can migrate between custody modalities over time without changing wallet addresses.

## What Is Custody?

A **[custodian](/introduction/glossary)** of a wallet is any entity for which **either** of the following is true:

1. The entity can **unilaterally execute transactions** on the wallet (for example, transferring funds out).
2. The entity can **unilaterally block transactions** on the wallet (for example, preventing a transfer from going through).

If an entity has either of these powers, it is a custodian of that wallet.

**Non-custodial** means your company is *not* a custodian. Your company cannot unilaterally move funds and cannot unilaterally prevent them from moving.

<Note>
  A wallet can have multiple custodians. Custody is not exclusive — it applies independently to every entity that meets either of the two criteria above.
</Note>

## Why Custody Matters

### Regulation and compliance

In many jurisdictions, if you are a custodian of wallets holding user funds, you must comply with additional regulatory obligations (for example, AML programs, money transmitter registration, and relevant licensing).

Some companies choose to take on these obligations. Others prefer to avoid custodial responsibilities. Either path can be valid, but it is important to understand the operational overhead and compliance costs that come with custody.

A third option is to use a **licensed third-party custodian** to hold custody on your behalf. This can be a good middle ground when you need custodial features without obtaining licenses yourself.

### Business control

There are scenarios where you want the ability to move funds from a backend (for example, for company treasury wallets, automated flows, or delegated workflows). In these cases, a custodial architecture may be the right choice.

Hybrid approaches are also common. For example, you can keep a user as the primary custodian while adding a scoped company signer with revocable permissions. See [Common Signer Configurations](/wallets/v0/concepts/common-signer-configurations#scoped-custody) for a concrete example.

### User perception

In many applications — especially fintech products and savings platforms — users may prefer to be the ultimate custodians of their funds. A non-custodial architecture can be a competitive differentiator because it guarantees that no company can unilaterally access or freeze funds.

### Security

Custodial and non-custodial architectures have different threat models:

* In a **custodial** architecture where your company holds keys, a compromise of your infrastructure can impact many wallets at once. The benefit is that security investment can be centralized.
* In a **non-custodial** architecture where users control their own keys, large-scale compromise is harder because each user is an independent endpoint. The tradeoff is that individual users may be targeted through phishing, social engineering, or device compromise.

Neither model is inherently more secure. The right choice depends on your threat model, your users, and your operational capabilities.

### User experience

Custody is not a reliable proxy for user experience.

Modern smart contract wallets and signing mechanisms (passkeys, device keys, user-friendly recovery, and gas sponsorship) make non-custodial architectures capable of a fully seamless UX.

### Cost

Non-custodial architectures are often cheaper to operate. Using user-controlled signers reduces the need for key management infrastructure, custodial insurance, and custody licensing.

## Custody in Crossmint

Crossmint wallets implement custody through **signers**. The custody modality of a wallet is determined by the signer configuration, not by the wallet itself.

<Info>
  Crossmint never takes custody of your or your users' funds. Custody is held by your users, your company, or a third-party custodian you choose.
</Info>

This means you can:

* Deploy **non-custodial wallets** using user-controlled operational signers (for example, [device keys](/wallets/v0/concepts/wallet-signers#device-key) or [passkeys](/wallets/v0/concepts/wallet-signers#passkey)).
* Deploy **custodial wallets** using server-side operational signers (for example, [server signers](/wallets/v0/concepts/wallet-signers#server-signer) or [Cloud KMS](/wallets/v0/concepts/wallet-signers#cloud-kms)).
* Integrate a **licensed third-party custodian** to operate signers on your behalf.
* Deploy **hybrid configurations** (for example, user custody plus a scoped operational company signer).
* Mix custody modalities across geographies while keeping one implementation.
* Migrate between modalities over time by rotating signers without changing wallet addresses.

<Info>
  A wallet is only non-custodial (from your company’s perspective) if your company cannot unilaterally execute or block transactions.
</Info>

## Next steps

<CardGroup>
  <Card title="Wallet Signers" icon="key" href="/wallets/v0/concepts/wallet-signers">
    Learn the available operational and recovery signer types.
  </Card>

  <Card title="Common Signer Configurations" icon="sitemap" href="/wallets/v0/concepts/common-signer-configurations">
    See recommended signer setups for common wallet architectures.
  </Card>
</CardGroup>


# Signer Decision Tree
Source: https://docs.crossmint.com/wallets/v0/concepts/decision-tree

A step-by-step guide to picking the right operational and recovery signers for your wallet architecture.

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/concepts/custody-models) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

Use this decision tree to identify the right signer configuration for your use case. If you are not yet familiar with the different signer types, start with [Wallet Signers](/wallets/v0/concepts/wallet-signers) first.

## Step 1: Who is the wallet for?

| Controller | Go to |
| - | - |
| End users (consumers, retail) | Step 2a (below) |
| Your company (treasury, operations, disbursements) | Step 2b (below) |
| AI agents | Step 2c (below) |

## Step 2a: User wallets — does the user need self-custody?

| Answer | Operational signer | Recovery signer | Configuration |
| - | - | - | - |
| Yes — user must be sole custodian | [Device key](/wallets/v0/concepts/wallet-signers#device-key) or [Passkey](/wallets/v0/concepts/wallet-signers#passkey) | [Email OTP](/wallets/v0/concepts/wallet-signers#email-otp) + optional [SMS OTP](/wallets/v0/concepts/wallet-signers#sms-otp) | [Non-custodial user wallet](/wallets/v0/concepts/common-signer-configurations#non-custodial-user-wallets) |
| No — your company manages wallets on behalf of users | [Cloud KMS](/wallets/v0/concepts/wallet-signers#cloud-kms) or [Server signer](/wallets/v0/concepts/wallet-signers#server-signer) | [Cloud KMS (recovery)](/wallets/v0/concepts/wallet-signers#cloud-kms-recovery) | [Custodial user wallet](/wallets/v0/concepts/common-signer-configurations#custodial-user-wallets) |
| Hybrid — user custody with limited company access | User: [Device key](/wallets/v0/concepts/wallet-signers#device-key) / [Passkey](/wallets/v0/concepts/wallet-signers#passkey) + Company: [Server signer](/wallets/v0/concepts/wallet-signers#server-signer) (scoped) | [Email OTP](/wallets/v0/concepts/wallet-signers#email-otp) | [Scoped custody](/wallets/v0/concepts/common-signer-configurations#scoped-custody) |

<Accordion title="Choosing between device key and passkey">
  | Criterion | Device key | Passkey |
  | - | - | - |
  | Silent signing (no user prompt per tx) | ✓ (default) | ✗ (always requires biometric) |
  | Cross-device sync | ✗ (single device) | ✓ (via iCloud, Google, 1Password) |
  | Best for | High-frequency actions, invisible UX | Explicit user confirmation, multi-device |
</Accordion>

## Step 2b: Company wallets — what level of key security do you need?

| Scenario | Operational signer | Recovery signer | Configuration |
| - | - | - | - |
| Production treasury or high-value operations | [Cloud KMS](/wallets/v0/concepts/wallet-signers#cloud-kms) | [Cloud KMS (recovery)](/wallets/v0/concepts/wallet-signers#cloud-kms-recovery) in a separate account/region | [Treasury wallet](/wallets/v0/concepts/common-signer-configurations#treasury-wallets) |
| Development, staging, or low-risk operations | [Server signer](/wallets/v0/concepts/wallet-signers#server-signer) | [Cloud KMS (recovery)](/wallets/v0/concepts/wallet-signers#cloud-kms-recovery) or [Externally custodied key](/wallets/v0/concepts/wallet-signers#externally-custodied-key) | [Treasury wallet](/wallets/v0/concepts/common-signer-configurations#treasury-wallets) |

## Step 2c: Agent wallets — who hosts the agent?

| Host | Operational signer | Recovery signer | Configuration |
| - | - | - | - |
| User-hosted (self-managed infrastructure) | [Server signer](/wallets/v0/concepts/wallet-signers#server-signer) or [Cloud KMS](/wallets/v0/concepts/wallet-signers#cloud-kms) | [Externally custodied key](/wallets/v0/concepts/wallet-signers#externally-custodied-key) | [User-hosted agent](/wallets/v0/concepts/common-signer-configurations#user-hosted-agents) |
| Platform-hosted (you run agents on behalf of users) | User: [Passkey](/wallets/v0/concepts/wallet-signers#passkey) + Agent: [Server signer](/wallets/v0/concepts/wallet-signers#server-signer) (scoped) | [Email OTP](/wallets/v0/concepts/wallet-signers#email-otp) | [Platform-hosted agent](/wallets/v0/concepts/common-signer-configurations#platform-hosted-agents) |

## Step 3: Do you need account recovery?

Almost always **yes**. The only exception is server-side wallets where you control all key material and have your own backup procedures.

| Wallet type | Minimum recommended recovery | Enhanced recovery |
| - | - | - |
| User wallets | [Email OTP](/wallets/v0/concepts/wallet-signers#email-otp) | Email OTP + [SMS OTP](/wallets/v0/concepts/wallet-signers#sms-otp) + [Managed support center](/wallets/v0/concepts/wallet-signers#managed-support-center) |
| Company wallets | [Cloud KMS (recovery)](/wallets/v0/concepts/wallet-signers#cloud-kms-recovery) | Cloud KMS + [Externally custodied key](/wallets/v0/concepts/wallet-signers#externally-custodied-key) |
| Agent wallets | [Email OTP](/wallets/v0/concepts/wallet-signers#email-otp) or [Externally custodied key](/wallets/v0/concepts/wallet-signers#externally-custodied-key) | Depends on hosting model |

<Note>
  For enterprise clients, the Crossmint team is happy to provide architectural guidance and review your setup before you go to production. <a href="https://www.crossmint.com/contact/sales">Get in touch</a> to schedule a session with the solutions team.
</Note>

## Next Steps

<CardGroup>
  <Card title="Registering a Signer" icon="plus" href="/wallets/v0/guides/signers/registering-a-signer">
    Learn how to add operational signers to a wallet.
  </Card>

  <Card title="Common Signer Configurations" icon="sitemap" href="/wallets/v0/concepts/common-signer-configurations">
    Blueprints for common configurations we see amongst our clients.
  </Card>
</CardGroup>


# Wallet Signers
Source: https://docs.crossmint.com/wallets/v0/concepts/wallet-signers

Understand the different signer types available for Crossmint wallets and how they work.

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/concepts/signers) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

This guide covers the different signer types Crossmint supports — what they are, how they work, and when to use each one. For a step-by-step decision guide, see [Signer Decision Tree](/wallets/v0/concepts/decision-tree).

Once you have chosen your signers, head to [Registering a Signer](/wallets/v0/guides/signers/registering-a-signer) to learn how to add them to a wallet.

<Warning>
  **Terminology update:** In previous versions of the Crossmint documentation and SDKs, the terms **"admin signer"** and **"delegated signer"** were used. These have been renamed:

  * **Admin signer** is now called **recovery signer**.
  * **Delegated signer** is now called **operational signer**.

  Current SDK method names (such as `addDelegatedSigner` and `delegatedSigners`) still use the old terminology. These will be updated in the next breaking API/SDK release. See the [Glossary](/introduction/glossary) for full definitions.
</Warning>

## What Is a Signer?

As a quick refresher from the [Architecture overview](/wallets/v0/architecture): signers are keys and other mechanisms that authorize operations on a wallet. They go beyond what most blockchains natively support. Rather than being limited to raw secp256k1 or ed25519 keypairs, Crossmint wallets support a wide range of signing mechanisms — including P-256 keys native to device secure enclaves, passkeys backed by biometrics, cloud key management services, email- and phone-based credentials, and more.

This flexibility is intentional. A wallet may need to be controlled by a user on a mobile app, an enterprise treasury team using HSMs, an AI agent running in the cloud, or all three at different times. The signer model is designed to make wallets securely controllable regardless of the operating environment.

## Signer Slots in a Wallet

<img alt="Crossmint wallet signer architecture — operational signers and recovery signers" />

Every Crossmint wallet supports two categories of signers, each serving a different purpose:

### Operational Signers

Operational signers handle the day-to-day operations of a wallet — authorizing transactions, signing messages, and interacting with protocols.

The right operational signer depends on who or what controls the wallet:

* **User wallets** — A key stored on the user's own device. For example, a passkey backed by Face ID or fingerprint, or a credential derived inside the device's secure enclave. The user signs each time they transact.
* **Server-side or treasury wallets** — A key stored in your cloud infrastructure, such as an environment variable (for lower-stakes use cases) or a cloud key management service like AWS KMS, Azure Key Vault, or GCP Cloud HSM. No user interaction required.
* **AI agent wallets** — A key available to the agent at runtime. For example, a securely injected secret that the agent uses to autonomously sign transactions on its own behalf.

When choosing an operational signer, optimize for:

<CardGroup>
  <Card title="Performance and cost" icon="gauge-high">
    Operational signers are used for every transaction. They should add minimal latency and not become a throughput bottleneck.
  </Card>

  <Card title="Native fit for the controlling entity" icon="bullseye">
    The signer should live where decisions are made. For a user, that is their device. For a server, that is your cloud. For an agent, that is its runtime environment.
  </Card>
</CardGroup>

### Recovery Signers

Recovery signers are used to regain access to a wallet when the operational signer is no longer available — for example, when a user gets a new phone and loses access to their old device key, or when a company rotates an infrastructure key.

Recovery signers allow you to enroll a new operational signer on a new device or environment — in a secure and self-custodial way — without changing the smart wallet's address or losing any of its assets and history.

Some examples of recovery signers:

* **Email-based recovery** — The user proves ownership of their email address to authorize the enrollment of a new device. A common pattern is to email the user a one-time code when they log in on a new phone.
* **Phone number-based recovery** — Similar to email, but via SMS.
* **Managed recovery (contact center)** — For enterprise clients or high-value wallets, Crossmint can support recovery flows that involve identity verification through a contact center — for cases where users may need human-assisted recovery if they have lost all credentials.

When choosing recovery signers, optimize for:

<CardGroup>
  <Card title="Identity guarantees" icon="shield-check">
    The most critical property is that only the true wallet owner can trigger a recovery. Choose a mechanism with strong authentication — ideally one that is hard to social-engineer or SIM-swap.
  </Card>

  <Card title="Acceptable friction" icon="clock">
    Recovery is an infrequent operation. A small amount of added friction is acceptable and often desirable, since it raises the bar for attackers.
  </Card>
</CardGroup>

## Designing Your Wallet Architecture

<Note>
  Crossmint abstracts away the complexity of implementing any of these signers. You do not need to understand the cryptographic internals or manage key derivation, storage, or rotation yourself — you just pick the signer types that make sense for your use case, and Crossmint handles the rest.
</Note>

When setting up your wallet architecture, the two key decisions are:

1. **What are my operational signers?** Pick something that lives where the controlling entity — user, server, or agent — naturally operates.
2. **How will the wallet be recovered?** Pick recovery signers that give you strong guarantees that only the legitimate owner can regain access.

Most wallet architectures use one operational signer and at least one recovery signer. For high-security use cases, you may want multiple recovery options (e.g., both email and phone) to reduce the chance of permanent lockout.

<Card title="Not sure which signers to pick?" icon="map" href="/wallets/v0/concepts/decision-tree">
  Use the decision tree to find the right signer configuration for your use case.
</Card>

## Signer Types

### Operational Signers

| Signer | User wallets | Company / server wallets | Agent wallets | Cost per signature | Performance |
| - | :-: | :-: | :-: | - | - |
| [Device key](#device-key) | ✓ | | ✓ | Free | Highest — no network round-trip |
| [Passkey](#passkey) | ✓ | ✓ (human dashboards) | | Free | Highest — no network round-trip |
| [Server signer](#server-signer) | | ✓ (programmatic, lower-risk) | ✓ | Free | Highest — no network round-trip |
| [Cloud KMS](#cloud-kms) | | ✓ (programmatic) | ✓ | Low (\~\$30 / million ops on AWS) | High — \~10 ms latency, \~1,000 TPS |
| [API key (deprecated)](#api-key) | | ✓ (legacy) | ✓ (legacy) | Deprecated | Deprecated |
| [External wallet](#external-wallet) | ✓ (crypto users) | ✓ | ✓ | Free | Highest — no network round-trip |
| [Email OTP](#email-otp) | ✓ | ✓ (admins) | ✓ | Low | Medium — OTP verification required |
| [SMS OTP](#sms-otp) | ✓ | | ✓ | Medium | Medium — OTP verification required |

***

#### Device key

P-256 keys that are non-extractable and generated securely inside the secure storage of the user's phone, computer, or browser (e.g., iOS Secure Enclave, Android Keystore, or the browser's built-in credential store).

<AccordionGroup>
  <Accordion title="Additional notes">
    * By default, signing is silent — transactions can be authorized without requiring the user to actively confirm each one. However, device keys can optionally be configured to require biometric authentication on every use, or after a configurable idle period.
    * If a device does not have a dedicated secure enclave, Crossmint automatically falls back to the most secure storage mechanism available on that platform.
  </Accordion>
</AccordionGroup>

<Card title="Device key implementation guide" icon="arrow-right" href="/wallets/v0/guides/signers/device-key" />

***

#### Passkey

Passkeys are <a href="https://www.w3.org/TR/webauthn-3/">WebAuthn</a> credentials stored on-device and synchronized across devices by platform providers such as Apple Keychain, Google Password Manager, or third-party password managers like 1Password and Dashlane.

Every transaction signed with a passkey requires the user to authenticate using their device's biometric sensor — Face ID, Touch ID, fingerprint reader, or Windows Hello — or their password manager's unlock mechanism. This makes passkeys one of the most secure operational signer options because each signature is explicitly authorized by the user.

Passkeys are available across the user's ecosystem of devices rather than being tied to a single one. For example, a passkey created on an iPhone and synced through iCloud Keychain is immediately available on the user's iPad and Mac. Similarly, passkeys stored in 1Password or Google Password Manager are accessible on any device where that password manager is installed.

<AccordionGroup>
  <Accordion title="Additional notes">
    * The cross-device synchronization is convenient but introduces some UX edge cases. A user who changes ecosystems (for example, switching from Apple to Android) may not have immediate access to their passkeys unless they use a cross-platform password manager like 1Password. Using passkeys in conjunction with a recovery signer is recommended to handle these scenarios.
    * Passkeys require a user interaction (biometric or password manager unlock) for every signing operation. This is a security feature, not a limitation — but it means passkeys are best suited for workflows where explicit user confirmation per transaction is acceptable.
    * On devices without a biometric sensor, the passkey provider falls back to a PIN or device password for confirmation.
  </Accordion>
</AccordionGroup>

<Card title="Passkey implementation guide" icon="arrow-right" href="/wallets/v0/guides/signers/passkey" />

***

#### Server signer

A P-256 or native blockchain keypair injected as an environment variable (or equivalent secret) into a server-side application. Signing happens entirely in-process with no external network call, making this the lowest-latency option available.

<AccordionGroup>
  <Accordion title="Additional notes">
    Because this key lives as a secret in your infrastructure, enforcing regular rotations is recommended — for example, quarterly — to limit exposure in the event of a compromised environment, a departed employee, or an infrastructure incident.
  </Accordion>
</AccordionGroup>

<Card title="Server signer implementation guide" icon="arrow-right" href="/wallets/guides/signers/server-signer" />

***

#### Cloud KMS

A signing key generated and stored inside a cloud key management service — AWS KMS, Azure Key Vault, or GCP Cloud HSM. The key is non-extractable by design: no employee at your company (or at the cloud provider) can ever retrieve the raw key material.

Cloud KMS signers support advanced enterprise security controls natively, including IP allowlisting, cloud IAM-based access policies, rate limiting, circuit breakers, and detailed audit logs and alerting.

This is the most secure option for server-side signing: bank-grade key security without the key ever leaving your cloud.

<AccordionGroup>
  <Accordion title="Performance and cost details">
    **Performance:** Up to \~1,000 signing operations per second per key, with latency as low as \~10 ms. Slightly higher latency than a plain server key due to the network call to the KMS endpoint, but well within acceptable range for most production workloads.

    **Cost:** Not free, but low. On AWS KMS, signing operations start at approximately $0.03 per 10,000 requests (~$30 per million).
  </Accordion>
</AccordionGroup>

<Card title="Cloud KMS implementation guide" icon="arrow-right" href="/wallets/guides/signers/cloud-kms" />

***

#### API key

<Warning>
  Server signers are the standard for server-side and agent operations. Unlike API key signers — which used your primary API key as the signing mechanism itself — server signers are dedicated signing credentials, giving you stronger isolation and a smaller blast radius if credentials are ever rotated or compromised.

  API key signers are deprecated and will be removed in a future release. To take advantage of the improved security model, migrate any server-side or agent workflows to [server signers](#server-signer).
</Warning>

In earlier versions of the Crossmint Wallets API, an API key could be used directly as an operational signer. This model is deprecated in favor of dedicated signer types that separate authentication (API key) from transaction authorization (signer key).

<Card title="API key migration guide" icon="arrow-right" href="/wallets/v0/guides/signers/api-key" />

***

#### External wallet

An existing blockchain wallet or keypair — such as a MetaMask wallet, a Phantom wallet, or a raw keypair — used as an operational signer on a Crossmint smart wallet. The external wallet signs transactions on behalf of the smart wallet, and the user retains full control of the signing key.

This signer type is designed for **crypto-native users who already have a wallet** and want to use it to control a Crossmint smart wallet. It is not intended for general consumer onboarding.

**Best used for**: Users, companies, or agents that already hold blockchain keypairs and want to connect them to Crossmint wallets without adopting a new key management approach.

<AccordionGroup>
  <Accordion title="Additional notes">
    * Custody depends on who controls the external wallet. If the user holds the private key, the wallet is non-custodial. If a server or third party holds it, the wallet is custodial.
    * Every transaction requires a signature from the external wallet. For user-facing wallets, this means the user must confirm each operation in their wallet application (for example, MetaMask or Phantom).
    * External wallets do not benefit from Crossmint's built-in recovery mechanisms. If the user loses access to the external wallet's private key, wallet recovery depends on whatever backup the user has for that key.
  </Accordion>
</AccordionGroup>

<Card title="External wallet implementation guide" icon="arrow-right" href="/wallets/v0/guides/signers/external-wallet" />

### Recovery Signers

| Signer | User wallets | Company / server wallets | Agent wallets | Cost | Recoverability | Security |
| - | :-: | :-: | :-: | - | - | - |
| [Email OTP](#email-otp) | ✓ | ✓ (admins) | ✓ | Low | High | Medium |
| [SMS OTP](#sms-otp) | ✓ | | ✓ | Medium | Medium | Medium |
| [Social recovery](#social-recovery) | ✓ | | | Low | Low alone / High when paired | Medium |
| [Managed support center](#managed-support-center) | ✓ | ✓ | | Highest | Highest | Highest |
| [Externally custodied key](#externally-custodied-key) | ✓ | ✓ | ✓ | Lowest | High (sophisticated users) / Low (general users) | High |
| [Cloud KMS (recovery)](#cloud-kms-recovery) | | ✓ | ✓ | Low | High | Highest |

***

#### Email OTP

The user receives a one-time code to their email address to authenticate and authorize operations. Simple to set up, works across devices and platforms, and most users already have a stable email address. Email OTP can be used as both a recovery signer and an operational signer. A wallet can have multiple email signers.

**Best used for**: User wallets, agent wallets, and company wallets where admins need a fallback recovery path. Also suitable as an operational signer for workflows that require email-based authorization.

| | |
| - | - |
| **Cost** | Low |
| **Recoverability** | High — email addresses tend to be stable and long-lived |
| **Security** | Medium — protected by the security of the user's email account; pairing with a second factor is recommended for high-value wallets |

<AccordionGroup>
  <Accordion title="How does it work?">
    Email OTP recovery uses a master secret that is deterministically derived inside a Trusted Execution Environment (TEE) running open-source, verifiable code. The master secret is never stored anywhere — it only exists ephemerally during derivation and is immediately encrypted for secure distribution.

    **Key components:**

    * **TEE (Trusted Execution Environment)**: A hardware-attested secure enclave (Intel TDX) that derives master secrets using HKDF from a TEE-protected root key combined with the user's identifier and email address. The TEE's authenticity is cryptographically verifiable via Intel TDX attestation.
    * **Device identity keys**: Each user device generates a P-256 ECDH keypair stored securely in the browser's IndexedDB. These keys are non-extractable and used to decrypt the encrypted master secret. The device identity keys never leave the device.
    * **Encrypted master secret**: After authentication, the TEE encrypts the master secret directly to the device's public key using HPKE (Hybrid Public Key Encryption). This encrypted master secret is stored by Crossmint's relay service but can only be decrypted by the device holding the corresponding private key.

    **Authentication flow:**

    When a user needs to recover on a new device, they authenticate via email using a one-time password (OTP):

    1. The device generates identity keys and requests onboarding from the TEE.
    2. The TEE generates a 9-digit OTP and encrypts it using Format Preserving Encryption (FPE) to the device's public key.
    3. The encrypted OTP is sent to the user's email — neither Crossmint nor the host application can read it.
    4. The user enters the encrypted OTP, which the device decrypts locally.
    5. The device sends the decrypted OTP to the TEE via an HPKE-encrypted channel.
    6. The TEE verifies the OTP, confirming the user controls the email.
    7. The TEE derives the master secret and encrypts it to the device's public key using HPKE authenticated encryption.
    8. The encrypted master secret is stored by Crossmint's relay for future access.

    At no point do the host application or Crossmint have access to the unencrypted master secret or private keys.
  </Accordion>

  <Accordion title="Why is this non-custodial?">
    Neither the host application nor Crossmint can unilaterally access or control the user's keys.

    * **Master secret derivation**: The master secret is cryptographically bound to the user's email through HKDF derivation. Only someone who can authenticate with that email can trigger the TEE to derive and distribute the master secret.
    * **Device-only decryption**: Crossmint stores only the encrypted master secret, which is encrypted using HPKE directly to the device's public key. Without the device's private identity key (which never leaves the device and is non-extractable), the encrypted master secret cannot be decrypted.
    * **TEE attestation**: The TEE code is open-source and its execution is verifiable through Intel TDX hardware attestation. Anyone can verify that the deployed TEE code matches the audited source code and that it only derives master secrets after proper authentication.
    * **Authentication requirement**: Every device must complete TEE-attested authentication (OTP verification) before receiving an encrypted master secret. The OTP is encrypted to the device and cannot be intercepted by Crossmint or the host application.

    **What Crossmint cannot do:**

    * Decrypt the encrypted master secret without the device's private key.
    * Derive the master secret without the TEE's protected root key.
    * Bypass the OTP authentication flow enforced by the TEE.
    * Sign transactions on behalf of users without their device and authentication.
  </Accordion>
</AccordionGroup>

<Card title="Email OTP implementation guide" icon="arrow-right" href="/wallets/v0/guides/signers/email-otp" />

***

#### SMS OTP

Similar to email OTP, but delivered via SMS — or optionally via WhatsApp, for markets where it is the preferred channel. SMS OTP can be used as both a recovery signer and an operational signer. A wallet can have multiple phone signers.

**Best used for**: Consumer user wallets and agent wallets, particularly in markets where SMS or WhatsApp is more accessible than email. Also suitable as an operational signer for workflows that require phone-based authorization.

| | |
| - | - |
| **Cost** | Medium — SMS delivery has per-message costs |
| **Recoverability** | Medium — phone numbers change more often than email addresses, and porting a number to a new carrier can take time |
| **Security** | Medium — vulnerable to SIM-swap attacks; not recommended as the sole recovery mechanism for high-value wallets |

<AccordionGroup>
  <Accordion title="How does it work?">
    SMS OTP recovery uses the same TEE-based architecture as email OTP. The master secret is deterministically derived inside a hardware-attested Trusted Execution Environment (Intel TDX) and is never stored in the clear.

    The flow is identical to email OTP, except that the one-time password is delivered via SMS (or optionally WhatsApp) instead of email:

    1. The device generates identity keys and requests onboarding from the TEE.
    2. The TEE generates a 9-digit OTP and encrypts it to the device's public key.
    3. The encrypted OTP is sent to the user's phone number via SMS or WhatsApp — neither Crossmint nor the host application can read it.
    4. The user enters the OTP, which the device decrypts locally.
    5. The device sends the decrypted OTP to the TEE via an HPKE-encrypted channel.
    6. The TEE verifies the OTP, derives the master secret, and encrypts it to the device's public key.

    All cryptographic operations are performed locally on the user's device. The master secret and derived private keys are immediately wiped from memory after use.
  </Accordion>

  <Accordion title="Why is this non-custodial?">
    The same non-custodial guarantees as email OTP apply. The phone number is used only to prove identity — it is not used to derive or store keys.

    * **TEE-enforced authentication**: The master secret can only be derived after the user proves control of their phone number through the TEE-attested OTP flow.
    * **Device-only decryption**: The encrypted master secret can only be decrypted by the device's non-extractable private identity key.
    * **Verifiable execution**: The TEE code is open-source and its integrity is verifiable via Intel TDX attestation.

    Crossmint cannot decrypt the master secret, bypass the OTP flow, or sign transactions without the user's device and authentication.
  </Accordion>
</AccordionGroup>

<Card title="SMS OTP implementation guide" icon="arrow-right" href="/wallets/v0/guides/signers/sms-otp" />

***

#### Social recovery

Designate a trusted contact — a friend, family member, or colleague — who can authorize wallet recovery on the owner's behalf via their own email or phone OTP. The trusted contact does not have access to the wallet itself; they can only co-authorize a recovery event.

**Best used for**: Consumer user wallets, ideally paired with another recovery mechanism rather than used in isolation.

| | |
| - | - |
| **Cost** | Low — same as email or SMS OTP |
| **Recoverability** | Low on its own; High when paired with another recovery signer |
| **Security** | Medium — depends on the trustworthiness and security hygiene of the designated contact |

<Note>
  Social recovery is coming in Q2 2026.
</Note>

<Card title="Social recovery details" icon="arrow-right" href="/wallets/v0/guides/signers/social-recovery" />

***

#### Managed support center

A white-glove recovery option: the wallet owner contacts a specialized support center, completes identity verification (KYC), and a trained agent facilitates the enrollment of a new operational signer. This is the most robust recovery option available and is best reserved as a last resort for situations where all other recovery methods have been exhausted.

**Best used for**: High-value user wallets and company wallets. Best deployed in tandem with another recovery mechanism as a safety net.

| | |
| - | - |
| **Cost** | Highest |
| **Recoverability** | Highest — human-in-the-loop with identity verification means recovery is possible even when all credentials are lost |
| **Security** | Highest — KYC-based verification provides the strongest identity guarantees |

<Card title="Managed support center details" icon="arrow-right" href="/wallets/guides/signers/wallet-recovery" />

***

#### Externally custodied key

The wallet owner generates and stores a cryptographic key or passphrase in cold storage — for example, a hardware wallet, an encrypted offline backup, or a printed seed phrase kept in a secure location. When recovery is needed, they present this credential to authorize enrollment of a new operational signer.

**Best used for**: All wallet types, but the practical effectiveness depends heavily on the owner's level of technical sophistication. Crypto-native users and enterprises with proper key management procedures find this highly reliable. General consumers often struggle with cold storage and are at risk of losing the backup itself.

| | |
| - | - |
| **Cost** | Lowest — no ongoing infrastructure cost |
| **Recoverability** | High for sophisticated users; Low for general consumers who may lose or mismanage cold storage |
| **Security** | High — the key is entirely offline and outside of any third-party infrastructure |

<Card title="External wallet implementation guide" icon="arrow-right" href="/wallets/v0/guides/signers/external-wallet" />

***

#### Cloud KMS (recovery)

A non-extractable key stored in a cloud key management service — AWS KMS, Azure Key Vault, or GCP Cloud HSM — configured with the most restrictive access settings available. When an operational signer needs to be rotated (for example, after a suspected compromise or a scheduled key rotation), the Cloud KMS recovery key authorizes the enrollment of the new operational signer.

Because the recovery key never leaves the KMS and access is governed by your cloud IAM policies, this approach provides the strongest possible security guarantees for server-side recovery. No individual employee can trigger a recovery unilaterally — access can be scoped to require multi-party approval, specific IP ranges, or other controls enforced at the cloud infrastructure level.

**Best used for**: Company and server wallets that need to rotate operational server keys on a regular or incident-driven basis. Also appropriate for custodial architectures where the operator manages keys on behalf of users and needs a secure, auditable path to rotate those keys.

| | |
| - | - |
| **Cost** | Low — same per-operation pricing as Cloud KMS operational signers (\~\$30 / million ops on AWS) |
| **Recoverability** | High — always available as long as your cloud infrastructure is operational |
| **Security** | Highest — non-extractable key, full cloud IAM controls, audit logging, and optional multi-party approval |

<Card title="Cloud KMS implementation guide" icon="arrow-right" href="/wallets/guides/signers/cloud-kms" />

## Related guides

<CardGroup>
  <Card title="Decision Tree" icon="map" href="/wallets/v0/concepts/decision-tree">
    Step-by-step guide to picking the right signers for your use case.
  </Card>

  <Card title="Common Signer Configurations" icon="sitemap" href="/wallets/v0/concepts/common-signer-configurations">
    Pre-built signer configurations for common wallet architectures.
  </Card>

  <Card title="Registering a Signer" icon="key" href="/wallets/v0/guides/signers/registering-a-signer">
    Learn how to add operational signers to a wallet.
  </Card>
</CardGroup>


# Bring Your Own Auth
Source: https://docs.crossmint.com/wallets/v0/guides/bring-your-own-auth

Bring your own auth provider

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/guides/bring-your-own-auth) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

Crossmint provides turn-key connectors for the most popular auth providers, including Auth0, Firebase, Supabase, Stytch, Cognito, and Kinde.

When you bring your own auth, Crossmint automatically extracts the user ID from your provider's JWT and assigns it to the wallet's `owner` property. Wallet creation, transaction signing, and balance reads all work the same way regardless of which auth provider you use.

If you're just getting started or prototyping, [Crossmint Auth](/authentication/introduction) is a great way to move fast in staging before connecting your own provider.

## Prerequisites

* **API Key**: Ensure you have an API key with the scopes: `wallets.create`.

## Using your own auth provider

<Tabs>
  <Tab title="React">
    <Steps>
      <Step title="Configure JWT Authentication in the Crossmint Console">
        1. Navigate to your project in the Crossmint Console.
        2. Go to the API Keys section from the sidebar.
        3. Scroll down to the JWT authentication section.
        4. Choose your preferred authentication method:

        * **3P Auth providers**: Select from supported providers such as Auth0, Stytch, Cognito, Firebase, Kinde, or Supabase. Enter any required environment IDs or configuration details.
        * **Custom tokens**: Opt to issue and manage your own JWTs.

        5. After making your selection and providing any necessary details, click **Save JWT auth settings** to apply your configuration.

        <img alt="JWT Authentication Settings" />
      </Step>

      <Step title="Add the Crossmint providers to your app">
        Add the necessary Crossmint providers to your app together with your own auth provider.
        With the current setup, a wallet will be created automatically on login.

        <CodeGroup>
          ```tsx next.js theme={null}
          "use client";

          import {
              CrossmintProvider,
              CrossmintWalletProvider,
              useCrossmint,
          } from "@crossmint/client-sdk-react-ui";

          import { YourAuthProvider } from "@your-auth-provider";

          // Get the JWT from your auth provider and pass it to the Crossmint provider
          const { jwt } = useYourAuthProviderHook();
          const { setJwt } = useCrossmint();

          useEffect(() => {
              setJwt(jwt);
          }, [jwt]);

          export function Providers({ children }: { children: React.ReactNode }) {
              return (
                  <YourAuthProvider>
                      <CrossmintProvider apiKey="<crossmint-client-api-key>">
                          <CrossmintWalletProvider>
                              {children}
                          </CrossmintWalletProvider>
                      </CrossmintProvider>
                  </YourAuthProvider>
              );
          }
          ```
        </CodeGroup>
      </Step>

      <Step title="Passthrough the jwt information to the Crossmint provider">
        Create the wallet on login once the jwt and the email are available.

        <CodeGroup>
          ```tsx next.js theme={null}
          "use client";

          import { useYourAuthProviderHook } from "@your-auth-provider";
          import { useEffect } from "react";
          import { useCrossmint, useWallet } from "@crossmint/client-sdk-react-ui";

          export function YourComponent() {
              const { email } = useYourAuthProviderHook();
              const { jwt } = useCrossmint();
              const { getOrCreateWallet } = useWallet();

              useEffect(() => {
                  if (email != null && jwt != null) {
                      getOrCreateWallet({ signer: { type: "email", email: email } });
                  }
              }, [email, jwt]);

              // your component logic here
              return (
                  <div>
                      <h1>Your Component</h1>
                  </div>
              );
          }
          ```
        </CodeGroup>
      </Step>

      See the [React SDK reference](/sdk-reference/wallets/v0/react/get-started) for more details on providers and hooks.
    </Steps>
  </Tab>

  <Tab title="React Native">
    <Steps>
      <Step title="Configure JWT Authentication in the Crossmint Console">
        1. Navigate to your project in the Crossmint Console.
        2. Go to the API Keys section from the sidebar.
        3. Scroll down to the JWT authentication section.
        4. Choose your preferred authentication method:

        * **3P Auth providers**: Select from supported providers such as Auth0, Stytch, Cognito, Firebase, Kinde, or Supabase. Enter any required environment IDs or configuration details.
        * **Custom tokens**: Opt to issue and manage your own JWTs.

        5. After making your selection and providing any necessary details, click **Save JWT auth settings** to apply your configuration.

        <img alt="JWT Authentication Settings" />
      </Step>

      <Step title="Add the Crossmint providers to your app">
        Add the necessary Crossmint providers to your app together with your own auth provider.
        With the current setup, a wallet will be created automatically on login.

        ```tsx theme={null}
        import {
            CrossmintProvider,
            CrossmintWalletProvider,
            useCrossmint,
        } from "@crossmint/client-sdk-react-native-ui";

        import { YourAuthProvider, useYourAuthProviderHook } from "@your-auth-provider";

        // Get the JWT from your auth provider and pass it to the Crossmint provider
        const { jwt } = useYourAuthProviderHook();
        const { setJwt } = useCrossmint();

        useEffect(() => {
            setJwt(jwt);
        }, [jwt]);

        type ProvidersProps = {
            children: React.ReactNode;
        };

        export default function Providers({ children }: ProvidersProps) {
            return (
                <CrossmintProvider apiKey="<crossmint-client-api-key>">
                    <YourAuthProvider>
                        <CrossmintWalletProvider>
                            {children}
                        </CrossmintWalletProvider>
                    </YourAuthProvider>
                </CrossmintProvider>
            );
        }
        ```
      </Step>

      <Step title="Passthrough the jwt information to the Crossmint provider">
        Create the wallet on login once the jwt and the email are available.

        ```tsx theme={null}
        import { useYourAuthProviderHook } from "@your-auth-provider";
        import { useEffect } from "react";
        import { View, Text } from "react-native";
        import { useCrossmint, useWallet } from "@crossmint/client-sdk-react-native-ui";

        export function YourAuthComponent() {
            const { email } = useYourAuthProviderHook();
            const { jwt } = useCrossmint();
            const { getOrCreateWallet } = useWallet();

            useEffect(() => {
                if (jwt != null && email != null) {
                    getOrCreateWallet({ signer: { type: "email", email: email } });
                }
            }, [jwt, email]);

            // your component logic here
            return (
                <View>
                    <Text>Your Auth Component</Text>
                </View>
            );
        }
        ```
      </Step>

      See the [React Native SDK reference](/sdk-reference/wallets/v0/react-native/get-started) for more details on providers and hooks.
    </Steps>
  </Tab>
</Tabs>


# Check Balances
Source: https://docs.crossmint.com/wallets/v0/guides/check-balances

Retrieve and manage wallet balances using Crossmint's APIs

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/guides/check-balances) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

<Tabs>
  <Tab title="Token Balances">
    ## Prerequisites

    * Ensure you have a wallet created.
    * **API Key**: Ensure you have an API key with the scopes: `wallets.read` and `wallets:balance.read`.

    ## Retrieving Wallet Balances

    <Tabs>
      <Tab title="React">
        ```typescript theme={null}
        import { useWallet } from '@crossmint/client-sdk-react-ui';

        const { wallet } = useWallet();

        const { nativeToken, usdc, tokens } = await wallet.balances(["usdc"]);
        ```

        See the [React SDK reference](/sdk-reference/wallets/v0/react/hooks#wallet-methods) for more details.
      </Tab>

      <Tab title="Node.js">
        ```typescript theme={null}
        import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";

        const crossmint = createCrossmint({
            apiKey: "<your-server-api-key>",
        });

        const crossmintWallets = CrossmintWallets.from(crossmint);

        const wallet = await crossmintWallets.getWallet(
            "<wallet-address>",
            { chain: "base-sepolia", signer: { type: "external-wallet" } }
        );

        const { nativeToken, usdc, tokens } = await wallet.balances(["usdc"]);
        ```

        See the [SDK reference](/sdk-reference/wallets/v0/typescript/classes/Wallet#balances) for all parameters and return types.
      </Tab>

      <Tab title="React Native">
        ```typescript theme={null}
        import { useWallet } from '@crossmint/client-sdk-react-native-ui';

        const { wallet } = useWallet();

        const { nativeToken, usdc, tokens } = await wallet.balances(["usdc"]);
        ```

        See the [React Native SDK reference](/sdk-reference/wallets/v0/react-native/hooks#wallet-methods) for more details.
      </Tab>

      <Tab title="Swift">
        ```swift theme={null}
        import CrossmintClient
        import Wallet

        let sdk = CrossmintSDK.shared

        let wallet = try await sdk.crossmintWallets.getOrCreateWallet(
            chain: .baseSepolia,
            signer: .email("user@example.com")
        )

        let balances = try await wallet.balances(["usdc"])
        ```

        ### Parameters

        <ResponseField name="tokens" type="string[]">
          The tokens to get the balances for. This can be a token symbol or a token address.
        </ResponseField>

        ### Returns

        <ResponseField name="balances" type="Balances">
          The balances of the wallet.

          <Expandable title="properties">
            <ResponseField name="nativeToken" type="TokenBalance">
              The native token balance.

              <Snippet />
            </ResponseField>

            <ResponseField name="usdc" type="TokenBalance">
              The USDC balance.

              <Snippet />
            </ResponseField>

            <ResponseField name="tokens" type="TokenBalance[]">
              The tokens balances.

              <Snippet />
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Tab>

      <Tab title="REST">
        <CodeGroup>
          ```bash cURL theme={null}
          curl --request GET \
              --url 'https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/balances?tokens=usdc&chains=base-sepolia' \
              --header 'X-API-KEY: <x-api-key>'
          ```

          ```js Node.js theme={null}
          const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/balances?tokens=usdc&chains=base-sepolia';

          const options = {
              method: 'GET',
              headers: {
                  'X-API-KEY': '<x-api-key>'
              }
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/balances"

          querystring = {"tokens":"usdc","chains":"base-sepolia"}

          headers = {"X-API-KEY": "<x-api-key>"}

          response = requests.get(url, params=querystring, headers=headers)

          print(response.json())
          ```
        </CodeGroup>

        See the [API reference](/api-reference/wallets/get-wallet-balance) for more details.
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="NFT Balances">
    ## Prerequisites

    * Ensure you have a wallet created.
    * **API Key**: Ensure you have an API key with the scopes: `wallets.read`, `wallets.nfts.read`.

    ## Retrieving NFTs

    <Tabs>
      <Tab title="React">
        ```typescript theme={null}
        import { useWallet } from '@crossmint/client-sdk-react-ui';

        const { wallet } = useWallet();

        const nfts = await wallet.experimental_nfts({ page: 1, perPage: 10 });
        ```

        See the [React SDK reference](/sdk-reference/wallets/v0/react/hooks#wallet-methods) for more details.
      </Tab>

      <Tab title="Node.js">
        ```typescript theme={null}
        import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";

        const crossmint = createCrossmint({
            apiKey: "<your-server-api-key>",
        });

        const crossmintWallets = CrossmintWallets.from(crossmint);

        const wallet = await crossmintWallets.getWallet(
            "<wallet-address>",
            { chain: "base-sepolia", signer: { type: "external-wallet" } }
        );

        const nfts = await wallet.experimental_nfts({ page: 1, perPage: 10 });
        ```

        See the [SDK reference](/sdk-reference/wallets/v0/typescript/classes/Wallet#experimental_nfts) for all parameters and return types.
      </Tab>

      <Tab title="React Native">
        ```typescript theme={null}
        import { useWallet } from '@crossmint/client-sdk-react-native-ui';

        const { wallet } = useWallet();

        const nfts = await wallet.experimental_nfts({ page: 1, perPage: 10 });
        ```

        See the [React Native SDK reference](/sdk-reference/wallets/v0/react-native/hooks#wallet-methods) for more details.
      </Tab>

      <Tab title="Swift">
        ```swift theme={null}
        import CrossmintClient
        import Wallet

        let sdk = CrossmintSDK.shared

        let wallet = try await sdk.crossmintWallets.getOrCreateWallet(
            chain: .baseSepolia,
            signer: .email("user@example.com")
        )

        let nfts = try await wallet.nfts(page: 1, nftsPerPage: 10)
        ```

        ### Parameters

        <ParamField type="number">
          The number of NFTs to return per page.
        </ParamField>

        <ParamField type="number">
          The page number to return.
        </ParamField>

        ### Returns

        <ParamField type="Promise<GetNftsResponse>">
          The NFTs.
        </ParamField>
      </Tab>

      <Tab title="REST">
        <CodeGroup>
          ```bash cURL theme={null}
          curl --request GET \
              --url 'https://staging.crossmint.com/api/2022-06-09/wallets/email:user@example.com:base/nfts?page=1&perPage=20' \
              --header 'X-API-KEY: <x-api-key>'
          ```

          ```js Node.js theme={null}
          const url = 'https://staging.crossmint.com/api/2022-06-09/wallets/email:user@example.com:base/nfts?page=1&perPage=20';

          const options = {
              method: 'GET',
              headers: {
                  'X-API-KEY': '<x-api-key>'
              }
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2022-06-09/wallets/email:user@example.com:base/nfts"

          querystring = {"page":"1","perPage":"20"}

          headers = {"X-API-KEY": "<x-api-key>"}

          response = requests.get(url, params=querystring, headers=headers)

          print(response.json())
          ```
        </CodeGroup>

        See the [API reference](/api-reference/wallets/get-nfts-from-wallet) for more details.
      </Tab>
    </Tabs>
  </Tab>
</Tabs>


# Create Wallet
Source: https://docs.crossmint.com/wallets/v0/guides/create-wallet

Create a wallet using Crossmint's APIs

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/guides/create-wallet) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

## Prerequisites

* **API Key**: Ensure you have an API key with the scopes: `wallets.create`.

## Try it Live

Experience wallet creation in action with this interactive demo. Create a Solana testnet wallet using just your email address:

<WalletCreationDemo />

## Create a Wallet

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet } from '@crossmint/client-sdk-react-ui';

    const { getOrCreateWallet } = useWallet();

    const wallet = await getOrCreateWallet({
        chain: "base-sepolia",
        signer: {
            type: "email",
            email: "user@example.com"
        },
    });
    ```

    See the [React SDK reference](/sdk-reference/wallets/v0/react/hooks#usewallet) for all parameters.
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";

    const crossmint = createCrossmint({
        apiKey: "<your-server-api-key>",
    });

    const crossmintWallets = CrossmintWallets.from(crossmint);

    const wallet = await crossmintWallets.createWallet({
        chain: "base-sepolia",
        signer: {
            type: "external-wallet",
            address: "0x1234567890123456789012345678901234567890"
        },
    });
    ```

    See the [SDK reference](/sdk-reference/wallets/v0/typescript/classes/CrossmintWallets) for all parameters and return types.
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { useWallet } from '@crossmint/client-sdk-react-native-ui';

    const { getOrCreateWallet } = useWallet();

    const wallet = await getOrCreateWallet({
        chain: "base-sepolia",
        signer: {
            type: "email",
            email: "user@example.com"
        },
    });
    ```

    See the [React Native SDK reference](/sdk-reference/wallets/v0/react-native/hooks#usewallet) for all parameters.
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    import CrossmintClient
    import Wallet

    let sdk = CrossmintSDK.shared

    let wallet = try await sdk.crossmintWallets.getOrCreateWallet(
        chain: .baseSepolia,
        signer: .email(email: "user@example.com")
    )
    ```

    ### Parameters

    <ResponseField name="chain" type="string">
      The chain to use the wallet on.

      See all [supported chains](/introduction/supported-chains) for more details. On [staging](/introduction/platform/staging-vs-production) only testnet chains are supported.

      Note: For EVM-compatible chains, wallets are created for all
      chains as part of the shared address space derived from the same private key. However, to
      interact with a specific chain using the SDK, you must instantiate a wallet object per chain.
      This allows the SDK to correctly route interactions to the appropriate network configuration.
    </ResponseField>

    <ResponseField name="signer" type="Signer">
      The [signer](/wallets/concepts/signers) to use the wallet with.
    </ResponseField>

    <ResponseField name="alias" type="string">
      An optional identifier for the wallet, used to organize multiple wallets on the same chain.

      Aliases are:

      * Unique per wallet type and chain.
      * Must use only lowercase letters, numbers, underscores, or hyphens (`a-z`, `0-9`, `_`, `-`).
      * No spaces or empty strings allowed.

      Examples:
      `trading`, `long-term-holdings`, `treasury`
    </ResponseField>

    ### Returns

    <ResponseField name="wallet" type="Wallet">
      The created wallet.
    </ResponseField>
  </Tab>

  <Tab title="REST">
    <CodeGroup>
      ```bash cURL theme={null}
      curl --request POST \
          --url https://staging.crossmint.com/api/2025-06-09/wallets \
          --header 'Content-Type: application/json' \
          --header 'X-API-KEY: <x-api-key>' \
          --data '{
              "chainType": "evm",
              "config": {
                  "adminSigner": {
                      "type": "email",
                      "email": "user@example.com"
                  }
              },
              "owner": "email:user@example.com"
          }'
      ```

      ```js Node.js theme={null}
      const url = 'https://staging.crossmint.com/api/2025-06-09/wallets';

      const payload = {
          chainType: "evm",
          config: {
              adminSigner: {
                  type: "email",
                  email: "user@example.com"
              }
          },
          owner: "email:user@example.com"
      };

      const options = {
          method: 'POST',
          headers: {
              'X-API-KEY': '<x-api-key>',
              'Content-Type': 'application/json'
          },
          body: JSON.stringify(payload)
      };

      try {
          const response = await fetch(url, options);
          const data = await response.json();
          console.log(data);
      } catch (error) {
          console.error(error);
      }
      ```

      ```python Python theme={null}
      import requests

      url = "https://staging.crossmint.com/api/2025-06-09/wallets"

      payload = {
          "chainType": "evm",
          "config": {
              "adminSigner": {
                  "type": "email",
                  "email": "user@example.com"
              }
          },
          "owner": "email:user@example.com"
      }
      headers = {
          "X-API-KEY": "<x-api-key>",
          "Content-Type": "application/json"
      }

      response = requests.post(url, json=payload, headers=headers)

      print(response.json())
      ```
    </CodeGroup>

    See the [API reference](/api-reference/wallets/create-wallet) for more details.
  </Tab>
</Tabs>


# Error Handling
Source: https://docs.crossmint.com/wallets/v0/guides/error-handling

Catching and troubleshooting wallet transaction errors

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/guides/troubleshooting) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

Sometimes transactions fail. This guide outlines common failure reasons and provides tools to help you identify the underlying causes.

<Note>
  Reverted transactions are marked as "failed" and won't be executed. There is no auto-retry mechanism for failed
  transactions; you must manually resubmit them if needed.
</Note>

## Common Error Types

Transaction errors typically fall into two categories: validation failures and execution failures.

### Validation Errors

Validation errors occur when the provided transaction data is invalid. These errors commonly relate to invalid data (e.g., `signature`) during transaction approval. Common issues include:

* Malformed signatures
* Invalid signatures (e.g., from an unauthorized wallet)
* Insufficient signer permissions for transaction approval

An example of a validation error:

```json theme={null}
"error": {
  "reason": "execution_reverted",
  "message": "Execution reverted, see 'revert' for details",
  "revert": {
    "type": "wallet_authorization",
    "reason": "Invalid signature",
    "reasonData": "AA24"
  }
}
```

Troubleshooting steps:

* Verify the transaction signer is valid
* Confirm you're signing the correct `message` data
* Verify the signing private key matches the `signer` wallet

### Execution Errors

Execution errors occur when a transaction is reverted during runtime. These typically relate to the `calls` provided during transaction creation. Common causes include:

* Another transaction with the same call was executed already
* State changes between transaction creation and execution (e.g. asset price updated exceeding slippage allowance)

The Crossmint API typically provides specific revert reasons:

```json theme={null}
"error": {
  "reason": "execution_reverted",
  "message": "Execution reverted, see 'revert' for details",
  "revert": {
    "type": "contract_call",
    "reason": "ERC20: transfer amount exceeds balance"
  }
}
```

Troubleshooting:

* Review the simulation to understand the revert cause
* Check for similar previous transactions
* Attempt to resubmit with the same parameters

### Other Errors

If you encounter transaction failures without error details or receive no error message, there may be an issue with the Crossmint infrastructure. First, check [our status page](https://status.crossmint.com) to verify API availability and try again later. If the problem continues, please contact our support team.

## Debugging

The Crossmint API simulates all transactions before submitting them onchain. Failed simulations prevent onchain execution.

In most cases, the transaction will fail during the simulation. If that's the case, the `revert.reason` and `revert.reasonData` fields describe the failure. Otherwise, you can use a block explorer to inspect the transaction.

### Block Explorer

If the transaction was included onchain, you can check its status using a block explorer.


# Export Private Key
Source: https://docs.crossmint.com/wallets/v0/guides/export-private-key

Allow users to export private keys using email or phone signers

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/guides/export-private-key) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

## Introduction

Exporting a private key allows users to extract the cryptographic key that controls their non-custodial wallet. This key can be imported into other wallet applications, enabling users to access their assets across different platforms.

The `ExportPrivateKeyButton` component provides a secure interface for users to export their private keys from wallets that use email or phone signers. Other signer types (passkey, external wallet, API key) do not expose private keys by design, so export does not apply to them.

<Warning>
  **Security Warning**: Exporting a private key is a sensitive operation that should be handled with extreme care. Anyone who obtains the private key has full control over the wallet and all its assets. Users should:

  * Never share their private key with anyone
  * Store exported keys securely in password managers or hardware wallets
  * Consider the security implications before exporting
</Warning>

### When to Export Private Keys

Users might need to export their private key in scenarios such as:

* Creating a backup of their wallet credentials
* Migrating to a different wallet provider
* Accessing their wallet through alternative interfaces

## Prerequisites

Before using the `ExportPrivateKeyButton` component, ensure:

* Your client-side API key has the **`wallets.export`** scope enabled. You can configure this in the <a href="https://www.crossmint.com/console/projects/apiKeys">Crossmint Console</a>
* The wallet is using an **email or phone signer type**
* The wallet has been successfully created and is accessible

## Implementation Examples

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { ExportPrivateKeyButton, useWallet } from '@crossmint/client-sdk-react-ui';

    function WalletSettings() {
        const { wallet } = useWallet();

        return (
            <div>
                <h2>Wallet Settings</h2>
                <p>Address: {wallet?.address}</p>
                
                <ExportPrivateKeyButton />
            </div>
        );
    }
    ```

    See the [React SDK reference](/sdk-reference/wallets/react/components#exportprivatekeybutton) for more details.
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { ExportPrivateKeyButton, useWallet } from '@crossmint/client-sdk-react-native-ui';
    import { View, Text } from 'react-native';

    function WalletSettings() {
        const { wallet } = useWallet();

        return (
            <View>
                <Text>Wallet Settings</Text>
                <Text>Address: {wallet?.address}</Text>
                
                <ExportPrivateKeyButton />
            </View>
        );
    }
    ```

    See the [React Native SDK reference](/sdk-reference/wallets/react-native/components#exportprivatekeybutton) for more details.
  </Tab>
</Tabs>

## Security Considerations

When exporting private keys, users should store them securely using password managers or hardware wallets. Anyone with access to a private key has full control over the associated wallet.

As a developer integrating this component, it is important to communicate these security implications clearly to your users. Consider displaying warnings or educational content before allowing users to export their private keys, ensuring they understand the risks and best practices for secure key storage.

## How It Works

The `ExportPrivateKeyButton` component uses a secure multi-step process to export private keys:

### 1. Signer Validation

The component first checks if the wallet uses an exportable signer type (email or phone). If the wallet uses a different signer type, the component renders nothing.

### 2. Secure Iframe/WebView Loading

The component loads a secure iframe (web) or WebView (mobile) from Crossmint's TEE infrastructure. This isolated environment ensures that the private key is never exposed to the host application.

### 3. TEE Communication Protocol

The component establishes a secure communication channel with the TEE using the handshake protocol:

* The parent application initiates a handshake with the secure iframe/WebView
* Authentication credentials (JWT and API key) are passed through the secure channel
* The TEE verifies the user's identity and authorization

### 4. Private Key Derivation

Inside the TEE, the private key is derived from the master secret:

* The master secret is reconstructed from the device share and auth share
* The private key is derived using HKDF (HMAC-based Key Derivation Function)
* Supported cryptographic schemes: **ed25519** (Solana, Stellar) and **secp256k1** (EVM chains)
* Supported encoding formats: **base58**, **hex**, and **strkey**

### 5. Clipboard Copy

When the user clicks the export button, the private key is:

* Formatted in the appropriate encoding for the blockchain
* Copied directly to the user's clipboard
* Never exposed to the host application or stored in memory outside the TEE

For more details on the TEE architecture, see the [Email OTP](/wallets/v0/concepts/wallet-signers#email-otp) section in the Wallet Signers guide.

## Related Documentation

* [Wallet Signers](/wallets/v0/concepts/wallet-signers) - Learn about different signer types and custody models
* [Create Wallet](/wallets/v0/guides/create-wallet) - Create wallets with email or phone signers
* [Bring Your Own Auth](/wallets/v0/guides/bring-your-own-auth) - Integrate custom authentication systems
* [Wallets Quickstart](/wallets/v0/quickstarts/react) - Get started with Crossmint Wallets


# Get Staging Tokens (USDXM)
Source: https://docs.crossmint.com/wallets/v0/guides/get-staging-tokens

Fund your staging wallets with testnet tokens using Crossmint's USDXM stablecoin

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/guides/fund-staging-wallet) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

## What are testnet tokens?

Testnet tokens are tokens deployed on blockchain testnets for development and testing purposes. These tokens do not have real-world monetary value, allowing you to simulate onchain behavior—such as sending, receiving, and paying gas fees—without financial risk. You can use testnet tokens to validate your integration before moving to production.

## What is USDXM?

USDXM is Crossmint's staging/testnet stablecoin, designed specifically for testing. Think about USDXM as the USDC of testnets. Crossmint has deployed the USDXM contract on all supported testnets making it easier for you to test tokens in staging.

USDXM is only available in staging environments and is not available in production.

# How to fund your wallet?

There are several options to fund your wallets on staging with USDXM

## Option 1: Fund with the SDK

The `stagingFund` method is the easiest way to add USDXM to your wallet programmatically. This method funds the wallet with USDXM only, is only available in staging environments.

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet } from '@crossmint/client-sdk-react-ui';

    const { wallet } = useWallet();

    const balances = await wallet.stagingFund(10);
    console.log("Wallet funded! New balances:", balances);
    ```

    See the [React SDK reference](/sdk-reference/wallets/v0/react/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { useWallet } from '@crossmint/client-sdk-react-native-ui';

    const { wallet } = useWallet();

    const balances = await wallet.stagingFund(10);
    console.log("Wallet funded! New balances:", balances);
    ```

    See the [React Native SDK reference](/sdk-reference/wallets/v0/react-native/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";

    const crossmint = createCrossmint({
        apiKey: "<your-server-api-key>",
    });

    const crossmintWallets = CrossmintWallets.from(crossmint);

    const wallet = await crossmintWallets.getWallet(
        "<wallet-address>",
        { chain: "base-sepolia", signer: { type: "external-wallet" } }
    );

    const balances = await wallet.stagingFund(10);
    console.log("Wallet funded! New balances:", balances);
    ```

    See the [SDK reference](/sdk-reference/wallets/v0/typescript/classes/Wallet#stagingfund) for all parameters and return types.
  </Tab>
</Tabs>

## Option 2: Fund via API

You can also fund staging wallets directly using the HTTP API. This is useful for server-side integrations or when you need more control over the funding process.

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
      --url https://staging.crossmint.com/api/v1-alpha2/wallets/{walletLocator}/balances \
      --header 'Content-Type: application/json' \
      --header 'X-API-KEY: <x-api-key>' \
      --data '{
          "amount": 10,
          "token": "usdxm",
          "chain": "base-sepolia"
      }'
  ```

  ```js Node.js theme={null}
  const walletLocator = "email:user@example.com:evm";
  const url = `https://staging.crossmint.com/api/v1-alpha2/wallets/${walletLocator}/balances`;

  const payload = {
      amount: 10,
      token: "usdxm",
      chain: "base-sepolia"
  };

  const options = {
      method: 'POST',
      headers: {
          'X-API-KEY': '<x-api-key>',
          'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
  };

  try {
      const response = await fetch(url, options);
      const data = await response.json();
      console.log(data);
  } catch (error) {
      console.error(error);
  }
  ```

  ```python Python theme={null}
  import requests

  wallet_locator = "email:user@example.com:evm"
  url = f"https://staging.crossmint.com/api/v1-alpha2/wallets/{wallet_locator}/balances"

  payload = {
      "amount": 10,
      "token": "usdxm",
      "chain": "base-sepolia"
  }
  headers = {
      "X-API-KEY": "<x-api-key>",
      "Content-Type": "application/json"
  }

  response = requests.post(url, json=payload, headers=headers)

  print(response.json())
  ```
</CodeGroup>

### Request parameters

<ParamField type="string">
  The wallet to fund. Can be a wallet address or a locator like `email:user@example.com:evm`.
</ParamField>

<ParamField type="number">
  The amount of USDXM to add.
</ParamField>

<ParamField type="string">
  The token to fund with. Use `usdxm` for staging environments.
</ParamField>

<ParamField type="string">
  The chain to fund on (e.g., `base-sepolia`, `polygon-amoy`).
</ParamField>

### Getting your API key

You can get your staging API key from the [Crossmint Console](https://staging.crossmint.com). Navigate to your project settings and create an API key with the `wallets:balance.create` scope.

See the [API reference](/api-reference/wallets/fund-wallet) for more details.

## Option 3: Use the faucet web app

For quick manual testing without writing code, you can use Crossmint's hosted faucet web app to get staging tokens.

<Card title="USDXM Faucet" icon="faucet" href="https://usdc-faucet.vercel.app/">
  Get testnet USDXM tokens instantly through a simple web interface.
</Card>

To use the faucet:

1. Visit [https://usdc-faucet.vercel.app/](https://usdc-faucet.vercel.app/)
2. Enter your wallet address or connect your wallet
3. Select the chain you want to receive tokens on
4. Request tokens

<Note>The faucet is intended for development use only and may have rate limits to prevent abuse.</Note>

## When should I use which option?

| Option | Best for |
| - | - |
| **SDK (`stagingFund`)** | Automated flows, integration tests, and when you're already using the Crossmint SDK |
| **API** | Server-side integrations, custom tooling, or when you need direct HTTP access |
| **Faucet web app** | Quick manual testing, getting started quickly, or when you don't want to write code |

## Related guides

<CardGroup>
  <Card title="Transfer Tokens" icon="arrow-right-arrow-left" href="/wallets/v0/guides/transfer-tokens">
    Learn how to transfer tokens between wallets
  </Card>

  <Card title="Check Balances" icon="wallet" href="/wallets/v0/guides/check-balances">
    Retrieve and manage wallet balances
  </Card>
</CardGroup>


# List Wallet Transfers
Source: https://docs.crossmint.com/wallets/v0/guides/list-transfers

Retrieve inbound and outbound transfer history for a wallet

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/guides/list-transfers) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

<Warning>
  This is an **unstable API** that may change with time. The `unstable` prefix indicates that breaking changes may occur in future releases.
</Warning>

## Overview

The List Wallet Transfers API allows you to retrieve the transfer history for a wallet, including both inbound and outbound token transfers. This endpoint supports multiple blockchains and provides cursor-based pagination for efficient data retrieval.

## Prerequisites

* You have a wallet created.
* **API Key**: You have an API key with the scope: `wallets.transaction.read`. In staging, all scopes are included.

## Retrieving Wallet Transfers

<Tabs>
  <Tab title="EVM Chains">
    ### Get Ethereum Sepolia USDC Transfers

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request GET \
        --url 'https://staging.crossmint.com/api/unstable/wallets/email:user@example.com:evm-smart-wallet/transfers?chain=ethereum-sepolia&tokens=usdc&status=successful&limit=10' \
        --header 'X-API-KEY: <your-server-api-key>'
      ```

      ```javascript Node.js theme={null}
      const url = "https://staging.crossmint.com/api/unstable/wallets/email:user@example.com:evm-smart-wallet/transfers";
      const params = new URLSearchParams({
          chain: "ethereum-sepolia",
          tokens: "usdc",
          status: "successful",
          limit: "10"
      });

      const response = await fetch(`${url}?${params}`, {
          method: "GET",
          headers: {
              "X-API-KEY": "<your-server-api-key>"
          }
      });

      const data = await response.json();
      console.log(data);
      ```

      ```python Python theme={null}
      import requests

      url = "https://staging.crossmint.com/api/unstable/wallets/email:user@example.com:evm-smart-wallet/transfers"
      params = {
          "chain": "ethereum-sepolia",
          "tokens": "usdc",
          "status": "successful",
          "limit": "10"
      }
      headers = {"X-API-KEY": "<your-server-api-key>"}

      response = requests.get(url, params=params, headers=headers)
      data = response.json()
      print(data)
      ```
    </CodeGroup>

    ### Paginating Through Results

    When your wallet has a lot of transactions, results are split into pages. Use the `nextCursor` value from each response in your next API call to get the next page of results.

    <CodeGroup>
      ```javascript Node.js theme={null}
      async function getAllTransfers(walletLocator, chain, tokens) {
          const baseUrl = `https://staging.crossmint.com/api/unstable/wallets/${walletLocator}/transfers`;
          const allTransfers = [];
          let cursor = null;

          do {
              const params = new URLSearchParams({
                  chain,
                  tokens,
                  status: "successful",
                  limit: "30"
              });

              if (cursor) {
                  params.set("cursor", cursor);
              }

              const response = await fetch(`${baseUrl}?${params}`, {
                  headers: { "X-API-KEY": "<your-server-api-key>" }
              });

              const result = await response.json();
              allTransfers.push(...result.data);
              cursor = result.nextCursor;
          } while (cursor);

          return allTransfers;
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Solana">
    ### Get Solana USDC Transfers

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request GET \
        --url 'https://staging.crossmint.com/api/unstable/wallets/email:user@example.com:solana:smart/transfers?chain=solana&tokens=usdc&status=successful&limit=10' \
        --header 'X-API-KEY: <your-server-api-key>'
      ```

      ```javascript Node.js theme={null}
      const url = "https://staging.crossmint.com/api/unstable/wallets/email:user@example.com:solana:smart/transfers";
      const params = new URLSearchParams({
          chain: "solana",
          tokens: "usdc",
          status: "successful",
          limit: "10"
      });

      const response = await fetch(`${url}?${params}`, {
          method: "GET",
          headers: {
              "X-API-KEY": "<your-server-api-key>"
          }
      });

      const data = await response.json();
      console.log(data);
      ```

      ```python Python theme={null}
      import requests

      url = "https://staging.crossmint.com/api/unstable/wallets/email:user@example.com:solana:smart/transfers"
      params = {
          "chain": "solana",
          "tokens": "usdc",
          "status": "successful",
          "limit": "10"
      }
      headers = {"X-API-KEY": "<your-server-api-key>"}

      response = requests.get(url, params=params, headers=headers)
      data = response.json()
      print(data)
      ```
    </CodeGroup>

    ### Paginating Through Results

    When your wallet has a lot of transactions, results are split into pages. Use the `nextCursor` value from each response in your next API call to get the next page of results.

    <CodeGroup>
      ```javascript Node.js theme={null}
      async function getAllTransfers(walletLocator, chain, tokens) {
          const baseUrl = `https://staging.crossmint.com/api/unstable/wallets/${walletLocator}/transfers`;
          const allTransfers = [];
          let cursor = null;

          do {
              const params = new URLSearchParams({
                  chain,
                  tokens,
                  status: "successful",
                  limit: "30"
              });

              if (cursor) {
                  params.set("cursor", cursor);
              }

              const response = await fetch(`${baseUrl}?${params}`, {
                  headers: { "X-API-KEY": "<your-server-api-key>" }
              });

              const result = await response.json();
              allTransfers.push(...result.data);
              cursor = result.nextCursor;
          } while (cursor);

          return allTransfers;
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Stellar">
    ### Get Stellar USDC Transfers

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request GET \
        --url 'https://staging.crossmint.com/api/unstable/wallets/GABCD1234.../transfers?chain=stellar&tokens=usdc&status=successful' \
        --header 'X-API-KEY: <your-server-api-key>'
      ```

      ```javascript Node.js theme={null}
      const url = "https://staging.crossmint.com/api/unstable/wallets/GABCD1234.../transfers";
      const params = new URLSearchParams({
          chain: "stellar",
          tokens: "usdc",
          status: "successful"
      });

      const response = await fetch(`${url}?${params}`, {
          method: "GET",
          headers: {
              "X-API-KEY": "<your-server-api-key>"
          }
      });

      const data = await response.json();
      console.log(data);
      ```
    </CodeGroup>

    ### Paginating Through Results

    When your wallet has a lot of transactions, results are split into pages. Use the `nextCursor` value from each response in your next API call to get the next page of results.

    <CodeGroup>
      ```javascript Node.js theme={null}
      async function getAllTransfers(walletLocator, chain, tokens) {
          const baseUrl = `https://staging.crossmint.com/api/unstable/wallets/${walletLocator}/transfers`;
          const allTransfers = [];
          let cursor = null;

          do {
              const params = new URLSearchParams({
                  chain,
                  tokens,
                  status: "successful",
                  limit: "30"
              });

              if (cursor) {
                  params.set("cursor", cursor);
              }

              const response = await fetch(`${baseUrl}?${params}`, {
                  headers: { "X-API-KEY": "<your-server-api-key>" }
              });

              const result = await response.json();
              allTransfers.push(...result.data);
              cursor = result.nextCursor;
          } while (cursor);

          return allTransfers;
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## API Reference

Two endpoints are available:

* `GET /unstable/wallets/{walletLocator}/transfers` — Server-side API key authentication
* `GET /unstable/wallets/me:walletLocator/transfers` — JWT authentication for the current user's wallet

See the [API reference](/api-reference/wallets/list-transfers) for full parameter details and to test requests in the playground.

## Important Notes

<AccordionGroup>
  <Accordion title="Chain Support">
    * **EVM chains**: Fully supported. Results are cached for 10 minutes to improve performance.
    * **Solana**: Supported. Includes native SOL and SPL token transfers (e.g., USDC). Results are cached for 10 minutes.
    * **Stellar**: Supported for all Soroban and SEP-41 tokens.
  </Accordion>

  <Accordion title="EVM Limitations">
    Outgoing smart wallet native token transfers (e.g., ETH, MATIC) are not supported on all EVM chains. This limitation affects chains where internal transaction tracing is not available.
  </Accordion>

  <Accordion title="Pagination">
    * Uses cursor-based pagination for efficient data retrieval
    * Supports bidirectional pagination with `nextCursor` and `previousCursor`
    * The cursor encodes the sort order, so you don't need to re-specify it when paginating
    * Activity sessions expire after 10 minutes on EVM and Solana chains; refresh to load the latest data if the cursor expires
  </Accordion>

  <Accordion title="Timestamps">
    All timestamps are returned in ISO 8601 format (e.g., `2025-01-15T10:30:00.000Z`).
  </Accordion>

  <Accordion title="Transfer Types">
    The API returns both inbound (`wallets.transfer.in`) and outbound (`wallets.transfer.out`) transfers. Transfers initiated through Crossmint include a `transferId` that can be used with the [Get Transaction API](/api-reference/wallets/get-transaction).
  </Accordion>
</AccordionGroup>


# EVM
Source: https://docs.crossmint.com/wallets/v0/guides/send-transaction-evm

Send transactions from your wallet

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/guides/send-transaction-evm) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

## Prerequisites

* Ensure you have a wallet created.
* **Operational Signer**: The signing wallet must be registered as an operational signer on the wallet. You can do this [at wallet creation](/wallets/v0/guides/create-wallet) by passing `delegatedSigners`, or afterward by [registering a signer](/wallets/v0/guides/signers/registering-a-signer).
* **API Key**: Ensure you have an API key with the scopes: `wallets:transactions.create`.

## What is sending a custom transaction?

Sending a custom transaction lets you interact with any smart contract on the blockchain beyond simple transfers. Common use cases include minting free tokens, claiming rewards, or registering for allowlists—all without needing to manage private keys yourself.

## Sending a Transaction

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet, EVMWallet } from '@crossmint/client-sdk-react-ui';

    const { wallet } = useWallet();

    const evmWallet = EVMWallet.from(wallet);

    const { hash, explorerLink } = await evmWallet.sendTransaction({
        to: '0x...',
        value: BigInt('0x1234abcd'),
        data: '0x1234abcd...',
    });
    ```

    See the [React SDK reference](/sdk-reference/wallets/v0/react/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { CrossmintWallets, WalletsApiClient, createCrossmint, EVMWallet } from "@crossmint/wallets-sdk";
    import { privateKeyToAccount } from "viem/accounts";

    const crossmint = createCrossmint({
        apiKey: "<your-server-api-key>",
    });

    const crossmintWallets = CrossmintWallets.from(crossmint);
    const apiClient = new WalletsApiClient(crossmint);

    const account = privateKeyToAccount(
        process.env.EXTERNAL_WALLET_PRIVATE_KEY as `0x${string}`
    );

    const wallet = await crossmintWallets.getWallet(
        "<wallet-address>",
        { chain: "base-sepolia", signer: { type: "external-wallet" } }
    );

    const evmWallet = EVMWallet.from(wallet);

    // 1. Create the transaction in prepare-only mode
    const { transactionId } = await evmWallet.sendTransaction(
        {
            to: '0x...',
            value: BigInt('0x1234abcd'),
            data: '0x1234abcd...',
        },
        {
            experimental_prepareOnly: true,
            experimental_signer: `external-wallet:${account.address}`,
        }
    );

    // 2. Fetch the pending transaction to get the message that needs signing
    const txResponse = await apiClient.getTransaction(wallet.address, transactionId);
    if ("error" in txResponse) {
        throw new Error(`Failed to get transaction: ${JSON.stringify(txResponse)}`);
    }

    const pendingApproval = txResponse.approvals?.pending[0];
    if (!pendingApproval) {
        throw new Error("No pending approval found");
    }

    // 3. Sign the pending approval message with your viem private key
    const signature = await account.signMessage({
        message: { raw: pendingApproval.message as `0x${string}` },
    });

    // 4. Submit the approval
    const result = await wallet.approve({
        transactionId,
        options: {
            experimental_approval: {
                signature,
                signer: `external-wallet:${account.address}`,
            },
        },
    });

    console.log("Transaction approved:", result);
    ```

    See the [SDK reference](/sdk-reference/wallets/v0/typescript/classes/EVMWallet#sendtransaction) for all parameters and return types.
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { useWallet, EVMWallet } from '@crossmint/client-sdk-react-native-ui';

    const { wallet } = useWallet();

    const evmWallet = EVMWallet.from(wallet);

    const { hash, explorerLink } = await evmWallet.sendTransaction({
        to: '0x...',
        value: BigInt('0x1234abcd'),
        data: '0x1234abcd...',
    });
    ```

    See the [React Native SDK reference](/sdk-reference/wallets/v0/react-native/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    import CrossmintClient
    import Wallet

    let sdk = CrossmintSDK.shared

    let wallet = try await sdk.crossmintWallets.getOrCreateWallet(
        chain: .baseSepolia,
        signer: .email("user@example.com")
    )

    let evmWallet = try EVMWallet.from(wallet: wallet)

    let result = try await evmWallet.sendTransaction(transaction)
    ```

    ### Parameters

    <ParamField type="EVMTransactionInput">
      The transaction to send.
    </ParamField>

    ### Returns

    <ParamField type="string">
      The hash of the transaction.
    </ParamField>

    <ParamField type="string">
      The explorer link of the transaction.
    </ParamField>
  </Tab>

  <Tab title="REST">
    Transactions must be approved by one of the wallet's [signers](/wallets/v0/concepts/wallet-signers).
    The SDK handles this automatically, but with the REST API you must [approve the transaction](/api-reference/wallets/approve-transaction) to complete it.

    <Steps>
      <Step title="Create the transaction">
        Call the [create transaction](/api-reference/wallets/create-transaction) endpoint.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets/<wallet-locator>/transactions \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: <x-api-key>' \
              --data '{
                  "params": {
                      "calls": [{
                          "to": "0x...",
                          "value": "0x",
                          "data": "0x1234abcd..."
                      }],
                      "chain": "base-sepolia",
                      "signer": "external-wallet:<externalWalletAddress>"
                  }
              }'
          ```

          ```js Node.js theme={null}
          const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/<wallet-locator>/transactions';

          const payload = {
              params: {
                  calls: [{
                      to: "0x...",
                      value: "0x",
                      data: "0x1234abcd..."
                  }],
                  chain: "base-sepolia",
                  signer: "external-wallet:<externalWalletAddress>"
              }
          };

          const options = {
              method: 'POST',
              headers: {
                  'X-API-KEY': '<x-api-key>',
                  'Content-Type': 'application/json'
              },
              body: JSON.stringify(payload)
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions"

          payload = {
              "params": {
                  "calls": [{
                      "to": "0x...",
                      "value": "0x",
                      "data": "0x1234abcd..."
                  }],
                  "chain": "base-sepolia",
                  "signer": "external-wallet:<externalWalletAddress>"
              }
          }
          headers = {
              "X-API-KEY": "<x-api-key>",
              "Content-Type": "application/json"
          }

          response = requests.post(url, json=payload, headers=headers)

          print(response.json())
          ```
        </CodeGroup>

        See the [API reference](/api-reference/wallets/create-transaction) for more details.
      </Step>

      <Step title="Choose your signer type">
        The next steps depend on which signer type you specified in the previous step.

        <Tabs>
          <Tab title="Server Signer">
            [Server](/wallets/guides/signers/server-signer) signers derive a private key from your signer secret using HKDF-SHA256 and sign transactions locally.

            When using the **SDK**, signing and approval are handled automatically — no additional steps are needed.

            When using the **REST API** directly, you must:

            1. Derive the signing key from your signer secret (scoped to your project, environment, and chain type). See the <a href="https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/server/helpers/derive-server-signer.ts">derive-server-signer helper</a> for a reference implementation.
            2. Sign the approval message returned from the transaction creation step.
            3. Submit the signature via the [approve transaction](/api-reference/wallets/approve-transaction) endpoint.

            <Warning>
              Crossmint recommends using the <a href="https://www.npmjs.com/package/@crossmint/wallets-sdk">Wallets SDK</a> for server signer flows. The SDK handles key derivation and signing automatically.
            </Warning>

            See the [Server Signer guide](/wallets/guides/signers/server-signer) for full configuration and setup details.
          </Tab>

          <Tab title="Device Signer">
            [Device](/wallets/guides/signers/device-signer) signers generate a P256 keypair inside the device's secure hardware (Secure Enclave, Android Keystore, or browser Web Crypto API). Because the private key never leaves the device, device signers are **client-side only** and cannot be used directly with the REST API.

            <Warning>
              Crossmint recommends using the React, React Native, or Swift SDK for device signer flows. The SDK handles device key generation, storage, and signing automatically.
            </Warning>

            See the [Device Signer guide](/wallets/guides/signers/device-signer) for setup instructions.
          </Tab>

          <Tab title="External Wallet">
            For [External Wallet](/wallets/guides/signers/add-signers) signers, you must manually sign the approval message and submit it via the API. The response from Step 1 includes a pending approval with a `message` field that must be signed exactly as returned.

            From the previous step's response, extract:

            * `id` - The transaction ID (used in the next step)
            * `approvals.pending[0].message` - The hex message to sign

            Sign the message using your external wallet. The message is a raw hex string and must be signed exactly as returned. Here's an example using an EVM wallet with [Viem](https://viem.sh/):

            ```typescript theme={null}
            import { privateKeyToAccount } from "viem/accounts";

            // The message from tx.approvals.pending[0].message
            const messageToSign = "<messageFromResponse>";

            // Sign the message exactly as returned (raw hex)
            const account = privateKeyToAccount(`0x${"<privateKey>"}`);
            const signature = await account.signMessage({
                message: { raw: messageToSign },
            });
            ```
          </Tab>

          <Tab title="Email and Phone">
            [Email and phone](/wallets/guides/recovery/configure-recovery) signers require client-side OTP verification and key derivation, which the Crossmint SDK handles automatically. While REST API signing is technically possible, you still need client-side SDK integration for the signing step.

            <Warning>
              Crossmint recommends using the React, React Native, Swift, or Node.js SDK examples instead. The SDK handles the full signing flow for email and phone signers.
            </Warning>
          </Tab>

          <Tab title="Passkey">
            [Passkey](/wallets/guides/signers/add-signers) signers use WebAuthn for biometric or password manager authentication, which requires browser interaction. While REST API signing is technically possible, Crossmint does not recommend it because you would still need client-side SDK integration for the WebAuthn signing step.

            <Warning>
              Crossmint recommends using the React, React Native, Swift, or Node.js SDK examples instead. The SDK handles the full passkey signing flow automatically.
            </Warning>
          </Tab>
        </Tabs>
      </Step>

      <Step title="Submit the approval">
        <Note>
          Skip this step if using the **SDK with a server signer** — the SDK handles signing and approval automatically.
        </Note>

        Call the [approve transaction](/api-reference/wallets/approve-transaction) endpoint with the signature from Step 2 and the transaction ID from Step 1. Set `approvals[].signer` to the locator of the signer or recovery method that produced the signature.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions/<txId>/approvals \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: <x-api-key>' \
              --data '{
                  "approvals": [{
                      "signer": "external-wallet:<externalWalletAddress>",
                      "signature": "<signature>"
                  }]
              }'
          ```

          ```js Node.js theme={null}
          const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions/<txId>/approvals';

          const payload = {
              approvals: [{
                  signer: "external-wallet:<externalWalletAddress>",
                  signature: "<signature>"
              }]
          };

          const options = {
              method: 'POST',
              headers: {
                  'X-API-KEY': '<x-api-key>',
                  'Content-Type': 'application/json'
              },
              body: JSON.stringify(payload)
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions/<txId>/approvals"

          payload = {
              "approvals": [{
                  "signer": "external-wallet:<externalWalletAddress>",
                  "signature": "<signature>"
              }]
          }
          headers = {
              "X-API-KEY": "<x-api-key>",
              "Content-Type": "application/json"
          }

          response = requests.post(url, json=payload, headers=headers)

          print(response.json())
          ```
        </CodeGroup>

        See the [API reference](/api-reference/wallets/approve-transaction) for more details.
      </Step>
    </Steps>
  </Tab>
</Tabs>


# Solana
Source: https://docs.crossmint.com/wallets/v0/guides/send-transaction-solana

Send transactions from your wallet

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/guides/send-transaction-solana) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

## Prerequisites

* Ensure you have a wallet created.
* **Operational Signer**: The signing wallet must be registered as an operational signer on the wallet. You can do this [at wallet creation](/wallets/v0/guides/create-wallet) by passing `delegatedSigners`, or afterward by [registering a signer](/wallets/v0/guides/signers/registering-a-signer).
* **API Key**: Ensure you have an API key with the scopes: `wallets:transactions.create`.

## What is sending a custom transaction?

Sending a custom transaction lets you interact with any smart contract on the blockchain beyond simple transfers. Common use cases include minting free tokens, claiming rewards, or registering for allowlists—all without needing to manage private keys yourself.

## Sending a Transaction

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet, SolanaWallet } from '@crossmint/client-sdk-react-ui';

    const { wallet } = useWallet();

    const solanaWallet = SolanaWallet.from(wallet);

    const { hash, explorerLink } = await solanaWallet.sendTransaction({
        transaction: versionedTransaction,
        additionalSigners: additionalSigners,
    });
    ```

    See the [React SDK reference](/sdk-reference/wallets/v0/react/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { CrossmintWallets, WalletsApiClient, createCrossmint, SolanaWallet } from "@crossmint/wallets-sdk";
    import { Keypair } from "@solana/web3.js";
    import nacl from "tweetnacl";
    import bs58 from "bs58";

    const crossmint = createCrossmint({
        apiKey: "<your-server-api-key>",
    });

    const crossmintWallets = CrossmintWallets.from(crossmint);
    const apiClient = new WalletsApiClient(crossmint);

    const keypair = Keypair.fromSecretKey(
        bs58.decode(process.env.EXTERNAL_WALLET_PRIVATE_KEY!)
    );

    const wallet = await crossmintWallets.getWallet(
        "<wallet-address>",
        { chain: "solana", signer: { type: "external-wallet" } }
    );

    const solanaWallet = SolanaWallet.from(wallet);

    // 1. Create the transaction in prepare-only mode
    const { transactionId } = await solanaWallet.sendTransaction(
        {
            transaction: versionedTransaction, // your VersionedTransaction instance
        },
        {
            experimental_prepareOnly: true,
            experimental_signer: `external-wallet:${keypair.publicKey.toBase58()}`,
        }
    );

    // 2. Fetch the pending transaction to get the message that needs signing
    const txResponse = await apiClient.getTransaction(wallet.address, transactionId);
    if ("error" in txResponse) {
        throw new Error(`Failed to get transaction: ${JSON.stringify(txResponse)}`);
    }

    const pendingApproval = txResponse.approvals?.pending[0];
    if (!pendingApproval) {
        throw new Error("No pending approval found");
    }

    // 3. Sign the pending approval message with your Solana keypair
    const messageBytes = Buffer.from(pendingApproval.message, "base64");
    const sig = nacl.sign.detached(messageBytes, keypair.secretKey);
    const signature = Buffer.from(sig).toString("base64");

    // 4. Submit the approval
    const result = await wallet.approve({
        transactionId,
        options: {
            experimental_approval: {
                signature,
                signer: `external-wallet:${keypair.publicKey.toBase58()}`,
            },
        },
    });

    console.log("Transaction approved:", result);
    ```

    See the [SDK reference](/sdk-reference/wallets/v0/typescript/classes/SolanaWallet#sendtransaction) for all parameters and return types.
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { useWallet, SolanaWallet } from '@crossmint/client-sdk-react-native-ui';

    const { wallet } = useWallet();

    const solanaWallet = SolanaWallet.from(wallet);

    const { hash, explorerLink } = await solanaWallet.sendTransaction({
        transaction: versionedTransaction,
        additionalSigners: additionalSigners,
    });
    ```

    See the [React Native SDK reference](/sdk-reference/wallets/v0/react-native/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    import CrossmintClient
    import Wallet

    let sdk = CrossmintSDK.shared

    let wallet = try await sdk.crossmintWallets.getOrCreateWallet(
        chain: .solana,
        signer: .email("user@example.com")
    )

    let solanaWallet = try SolanaWallet.from(wallet: wallet)

    let result = try await solanaWallet.sendTransaction(transaction)
    ```

    ### Parameters

    <ParamField type="VersionedTransaction">
      The transaction to send.
    </ParamField>

    ### Returns

    <ParamField type="string">
      The hash of the transaction.
    </ParamField>

    <ParamField type="string">
      The explorer link of the transaction.
    </ParamField>
  </Tab>

  <Tab title="REST">
    Transactions must be approved by one of the wallet's [signers](/wallets/v0/concepts/wallet-signers).
    The SDK handles this automatically, but with the REST API you must [approve the transaction](/api-reference/wallets/approve-transaction) to complete it.

    <Steps>
      <Step title="Create the transaction">
        Call the [create transaction](/api-reference/wallets/create-transaction) endpoint.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: <x-api-key>' \
              --data '{
                  "params": {
                      "transaction": "AQAAAAAAAAAAAAA...",
                      "signer": "external-wallet:<externalWalletAddress>"
                  }
              }'
          ```

          ```js Node.js theme={null}
          const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions';

          const payload = {
              params: {
                  transaction: "AQAAAAAAAAAAAAA...",
                  signer: "external-wallet:<externalWalletAddress>"
              }
          };

          const options = {
              method: 'POST',
              headers: {
                  'X-API-KEY': '<x-api-key>',
                  'Content-Type': 'application/json'
              },
              body: JSON.stringify(payload)
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions"

          payload = {
              "params": {
                  "transaction": "AQAAAAAAAAAAAAA...",
                  "signer": "external-wallet:<externalWalletAddress>"
              }
          }
          headers = {
              "X-API-KEY": "<x-api-key>",
              "Content-Type": "application/json"
          }

          response = requests.post(url, json=payload, headers=headers)

          print(response.json())
          ```
        </CodeGroup>

        See the [API reference](/api-reference/wallets/create-transaction) for more details.
      </Step>

      <Step title="Choose your signer type">
        The next steps depend on which signer type you specified in the previous step.

        <Tabs>
          <Tab title="Server Signer">
            [Server](/wallets/guides/signers/server-signer) signers derive a private key from your signer secret using HKDF-SHA256 and sign transactions locally.

            When using the **SDK**, signing and approval are handled automatically — no additional steps are needed.

            When using the **REST API** directly, you must:

            1. Derive the signing key from your signer secret (scoped to your project, environment, and chain type). See the <a href="https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/server/helpers/derive-server-signer.ts">derive-server-signer helper</a> for a reference implementation.
            2. Sign the approval message returned from the transaction creation step.
            3. Submit the signature via the [approve transaction](/api-reference/wallets/approve-transaction) endpoint.

            <Warning>
              Crossmint recommends using the <a href="https://www.npmjs.com/package/@crossmint/wallets-sdk">Wallets SDK</a> for server signer flows. The SDK handles key derivation and signing automatically.
            </Warning>

            See the [Server Signer guide](/wallets/guides/signers/server-signer) for full configuration and setup details.
          </Tab>

          <Tab title="Device Signer">
            [Device](/wallets/guides/signers/device-signer) signers generate a P256 keypair inside the device's secure hardware (Secure Enclave, Android Keystore, or browser Web Crypto API). Because the private key never leaves the device, device signers are **client-side only** and cannot be used directly with the REST API.

            <Warning>
              Crossmint recommends using the React, React Native, or Swift SDK for device signer flows. The SDK handles device key generation, storage, and signing automatically.
            </Warning>

            See the [Device Signer guide](/wallets/guides/signers/device-signer) for setup instructions.
          </Tab>

          <Tab title="External Wallet">
            For [External Wallet](/wallets/guides/signers/add-signers) signers, you must manually sign the approval message and submit it via the API. The response from Step 1 includes a pending approval with a `message` field that must be signed exactly as returned.

            From the previous step's response, extract:

            * `id` - The transaction ID (used in the next step)
            * `approvals.pending[0].message` - The hex message to sign

            Sign the message using your external wallet. The message is a raw hex string and must be signed exactly as returned. Here's an example using an EVM wallet with [Viem](https://viem.sh/):

            ```typescript theme={null}
            import { privateKeyToAccount } from "viem/accounts";

            // The message from tx.approvals.pending[0].message
            const messageToSign = "<messageFromResponse>";

            // Sign the message exactly as returned (raw hex)
            const account = privateKeyToAccount(`0x${"<privateKey>"}`);
            const signature = await account.signMessage({
                message: { raw: messageToSign },
            });
            ```
          </Tab>

          <Tab title="Email and Phone">
            [Email and phone](/wallets/guides/recovery/configure-recovery) signers require client-side OTP verification and key derivation, which the Crossmint SDK handles automatically. While REST API signing is technically possible, you still need client-side SDK integration for the signing step.

            <Warning>
              Crossmint recommends using the React, React Native, Swift, or Node.js SDK examples instead. The SDK handles the full signing flow for email and phone signers.
            </Warning>
          </Tab>

          <Tab title="Passkey">
            [Passkey](/wallets/guides/signers/add-signers) signers use WebAuthn for biometric or password manager authentication, which requires browser interaction. While REST API signing is technically possible, Crossmint does not recommend it because you would still need client-side SDK integration for the WebAuthn signing step.

            <Warning>
              Crossmint recommends using the React, React Native, Swift, or Node.js SDK examples instead. The SDK handles the full passkey signing flow automatically.
            </Warning>
          </Tab>
        </Tabs>
      </Step>

      <Step title="Submit the approval">
        <Note>
          Skip this step if using the **SDK with a server signer** — the SDK handles signing and approval automatically.
        </Note>

        Call the [approve transaction](/api-reference/wallets/approve-transaction) endpoint with the signature from Step 2 and the transaction ID from Step 1. Set `approvals[].signer` to the locator of the signer or recovery method that produced the signature.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions/<txId>/approvals \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: <x-api-key>' \
              --data '{
                  "approvals": [{
                      "signer": "external-wallet:<externalWalletAddress>",
                      "signature": "<signature>"
                  }]
              }'
          ```

          ```js Node.js theme={null}
          const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions/<txId>/approvals';

          const payload = {
              approvals: [{
                  signer: "external-wallet:<externalWalletAddress>",
                  signature: "<signature>"
              }]
          };

          const options = {
              method: 'POST',
              headers: {
                  'X-API-KEY': '<x-api-key>',
                  'Content-Type': 'application/json'
              },
              body: JSON.stringify(payload)
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions/<txId>/approvals"

          payload = {
              "approvals": [{
                  "signer": "external-wallet:<externalWalletAddress>",
                  "signature": "<signature>"
              }]
          }
          headers = {
              "X-API-KEY": "<x-api-key>",
              "Content-Type": "application/json"
          }

          response = requests.post(url, json=payload, headers=headers)

          print(response.json())
          ```
        </CodeGroup>

        See the [API reference](/api-reference/wallets/approve-transaction) for more details.
      </Step>
    </Steps>
  </Tab>
</Tabs>


# Stellar
Source: https://docs.crossmint.com/wallets/v0/guides/send-transaction-stellar

Send transactions from your wallet

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/guides/send-transaction-stellar) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

## Prerequisites

* Ensure you have a wallet created.
* **Operational Signer**: The signing wallet must be registered as an operational signer on the wallet. You can do this [at wallet creation](/wallets/v0/guides/create-wallet) by passing `delegatedSigners`, or afterward by [registering a signer](/wallets/v0/guides/signers/registering-a-signer).
* **API Key**: Ensure you have an API key with the scopes: `wallets:transactions.create`.

## What is sending a custom transaction?

Sending a custom transaction lets you interact with any smart contract on the blockchain beyond simple transfers. Common use cases include minting free tokens, claiming rewards, or registering for allowlists—all without needing to manage private keys yourself.

## Sending a contract call transaction

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet, StellarWallet } from '@crossmint/client-sdk-react-ui';

    const { wallet } = useWallet();

    const stellarWallet = StellarWallet.from(wallet);

    const { hash, explorerLink } = await stellarWallet.sendTransaction({
        contractId: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
        method: "transfer",
        args: {
            to: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
            from: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
            amount: "1000000000000000000"
        }
    });
    ```

    See the [React SDK reference](/sdk-reference/wallets/v0/react/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { CrossmintWallets, WalletsApiClient, createCrossmint, StellarWallet } from "@crossmint/wallets-sdk";
    import { Keypair } from "@stellar/stellar-sdk";

    const crossmint = createCrossmint({
        apiKey: "<your-server-api-key>",
    });

    const crossmintWallets = CrossmintWallets.from(crossmint);
    const apiClient = new WalletsApiClient(crossmint);

    const keypair = Keypair.fromSecret(process.env.EXTERNAL_WALLET_PRIVATE_KEY!);

    const wallet = await crossmintWallets.getWallet(
        "<wallet-address>",
        { chain: "stellar", signer: { type: "external-wallet" } }
    );

    const stellarWallet = StellarWallet.from(wallet);

    // 1. Create the transaction in prepare-only mode
    const { transactionId } = await stellarWallet.sendTransaction(
        {
            contractId: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
            method: "transfer",
            args: {
                to: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
                from: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
                amount: "1000000000000000000"
            }
        },
        {
            experimental_prepareOnly: true,
            experimental_signer: `external-wallet:${keypair.publicKey()}`,
        }
    );

    // 2. Fetch the pending transaction to get the message that needs signing
    const txResponse = await apiClient.getTransaction(wallet.address, transactionId);
    if ("error" in txResponse) {
        throw new Error(`Failed to get transaction: ${JSON.stringify(txResponse)}`);
    }

    const pendingApproval = txResponse.approvals?.pending[0];
    if (!pendingApproval) {
        throw new Error("No pending approval found");
    }

    // 3. Sign the pending approval message with your Stellar keypair
    const signature = keypair.sign(Buffer.from(pendingApproval.message, "base64")).toString("base64");

    // 4. Submit the approval
    const result = await wallet.approve({
        transactionId,
        options: {
            experimental_approval: {
                signature,
                signer: `external-wallet:${keypair.publicKey()}`,
            },
        },
    });

    console.log("Transaction approved:", result);
    ```

    See the [SDK reference](/sdk-reference/wallets/v0/typescript/classes/StellarWallet#sendtransaction) for all parameters and return types.
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { useWallet, StellarWallet } from '@crossmint/client-sdk-react-native-ui';

    const { wallet } = useWallet();

    const stellarWallet = StellarWallet.from(wallet);

    const { hash, explorerLink } = await stellarWallet.sendTransaction({
        contractId: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
        method: "transfer",
        args: {
            to: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
            from: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
            amount: "1000000000000000000"
        }
    });
    ```

    See the [React Native SDK reference](/sdk-reference/wallets/v0/react-native/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="REST">
    Transactions must be approved by one of the wallet's [signers](/wallets/v0/concepts/wallet-signers).
    The SDK handles this automatically, but with the REST API you must [approve the transaction](/api-reference/wallets/approve-transaction) to complete it.

    <Steps>
      <Step title="Create the transaction">
        Call the [create transaction](/api-reference/wallets/create-transaction) endpoint.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: <x-api-key>' \
              --data '{
                  "params": {
                      "transaction": {
                          "type": "contract-call",
                          "contractId": "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
                          "method": "transfer",
                          "args": {
                              "to": "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
                              "from": "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
                              "amount": "1000000000000000000"
                          }
                      }
                  }
              }'
          ```

          ```js Node.js theme={null}
          const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions';

          const payload = {
              params: {
                  transaction: {
                      type: "contract-call",
                      contractId: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
                      method: "transfer",
                      args: {
                          to: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
                          from: "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
                          amount: "1000000000000000000"
                      }
                  }
              }
          };

          const options = {
              method: 'POST',
              headers: {
                  'X-API-KEY': '<x-api-key>',
                  'Content-Type': 'application/json'
              },
              body: JSON.stringify(payload)
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions"

          payload = {
              "params": {
                  "transaction": {
                      "type": "contract-call",
                      "contractId": "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
                      "method": "transfer",
                      "args": {
                          "to": "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
                          "from": "GB3KQJ6N2YIE62YVO67X7W5TQK6Q5ZZ4P2LUVK2U6AU26CJQ626J",
                          "amount": "1000000000000000000"
                      }
                  }
              }
          }
          headers = {
              "X-API-KEY": "<x-api-key>",
              "Content-Type": "application/json"
          }

          response = requests.post(url, json=payload, headers=headers)

          print(response.json())
          ```
        </CodeGroup>

        See the [API reference](/api-reference/wallets/create-transaction) for more details.
      </Step>

      <Step title="Choose your signer type">
        The next steps depend on which signer type you specified in the previous step.

        <Tabs>
          <Tab title="Server Signer">
            [Server](/wallets/guides/signers/server-signer) signers derive a private key from your signer secret using HKDF-SHA256 and sign transactions locally.

            When using the **SDK**, signing and approval are handled automatically — no additional steps are needed.

            When using the **REST API** directly, you must:

            1. Derive the signing key from your signer secret (scoped to your project, environment, and chain type). See the <a href="https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/server/helpers/derive-server-signer.ts">derive-server-signer helper</a> for a reference implementation.
            2. Sign the approval message returned from the transaction creation step.
            3. Submit the signature via the [approve transaction](/api-reference/wallets/approve-transaction) endpoint.

            <Warning>
              Crossmint recommends using the <a href="https://www.npmjs.com/package/@crossmint/wallets-sdk">Wallets SDK</a> for server signer flows. The SDK handles key derivation and signing automatically.
            </Warning>

            See the [Server Signer guide](/wallets/guides/signers/server-signer) for full configuration and setup details.
          </Tab>

          <Tab title="Device Signer">
            [Device](/wallets/guides/signers/device-signer) signers generate a P256 keypair inside the device's secure hardware (Secure Enclave, Android Keystore, or browser Web Crypto API). Because the private key never leaves the device, device signers are **client-side only** and cannot be used directly with the REST API.

            <Warning>
              Crossmint recommends using the React, React Native, or Swift SDK for device signer flows. The SDK handles device key generation, storage, and signing automatically.
            </Warning>

            See the [Device Signer guide](/wallets/guides/signers/device-signer) for setup instructions.
          </Tab>

          <Tab title="External Wallet">
            For [External Wallet](/wallets/guides/signers/add-signers) signers, you must manually sign the approval message and submit it via the API. The response from Step 1 includes a pending approval with a `message` field that must be signed exactly as returned.

            From the previous step's response, extract:

            * `id` - The transaction ID (used in the next step)
            * `approvals.pending[0].message` - The hex message to sign

            Sign the message using your external wallet. The message is a raw hex string and must be signed exactly as returned. Here's an example using an EVM wallet with [Viem](https://viem.sh/):

            ```typescript theme={null}
            import { privateKeyToAccount } from "viem/accounts";

            // The message from tx.approvals.pending[0].message
            const messageToSign = "<messageFromResponse>";

            // Sign the message exactly as returned (raw hex)
            const account = privateKeyToAccount(`0x${"<privateKey>"}`);
            const signature = await account.signMessage({
                message: { raw: messageToSign },
            });
            ```
          </Tab>

          <Tab title="Email and Phone">
            [Email and phone](/wallets/guides/recovery/configure-recovery) signers require client-side OTP verification and key derivation, which the Crossmint SDK handles automatically. While REST API signing is technically possible, you still need client-side SDK integration for the signing step.

            <Warning>
              Crossmint recommends using the React, React Native, Swift, or Node.js SDK examples instead. The SDK handles the full signing flow for email and phone signers.
            </Warning>
          </Tab>

          <Tab title="Passkey">
            [Passkey](/wallets/guides/signers/add-signers) signers use WebAuthn for biometric or password manager authentication, which requires browser interaction. While REST API signing is technically possible, Crossmint does not recommend it because you would still need client-side SDK integration for the WebAuthn signing step.

            <Warning>
              Crossmint recommends using the React, React Native, Swift, or Node.js SDK examples instead. The SDK handles the full passkey signing flow automatically.
            </Warning>
          </Tab>
        </Tabs>
      </Step>

      <Step title="Submit the approval">
        <Note>
          Skip this step if using the **SDK with a server signer** — the SDK handles signing and approval automatically.
        </Note>

        Call the [approve transaction](/api-reference/wallets/approve-transaction) endpoint with the signature from Step 2 and the transaction ID from Step 1. Set `approvals[].signer` to the locator of the signer or recovery method that produced the signature.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions/<txId>/approvals \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: <x-api-key>' \
              --data '{
                  "approvals": [{
                      "signer": "external-wallet:<externalWalletAddress>",
                      "signature": "<signature>"
                  }]
              }'
          ```

          ```js Node.js theme={null}
          const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions/<txId>/approvals';

          const payload = {
              approvals: [{
                  signer: "external-wallet:<externalWalletAddress>",
                  signature: "<signature>"
              }]
          };

          const options = {
              method: 'POST',
              headers: {
                  'X-API-KEY': '<x-api-key>',
                  'Content-Type': 'application/json'
              },
              body: JSON.stringify(payload)
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions/<txId>/approvals"

          payload = {
              "approvals": [{
                  "signer": "external-wallet:<externalWalletAddress>",
                  "signature": "<signature>"
              }]
          }
          headers = {
              "X-API-KEY": "<x-api-key>",
              "Content-Type": "application/json"
          }

          response = requests.post(url, json=payload, headers=headers)

          print(response.json())
          ```
        </CodeGroup>

        See the [API reference](/api-reference/wallets/approve-transaction) for more details.
      </Step>
    </Steps>
  </Tab>
</Tabs>


# EVM
Source: https://docs.crossmint.com/wallets/v0/guides/sign-message-evm

Sign messages from your wallet

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/guides/sign-message) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

## Prerequisites

* Ensure you have a wallet created.
* **API Key**: Ensure you have an API key with the scopes: `wallets:signatures.create`.

<Warning>
  If you are signing with an [operational signer](/wallets/v0/guides/signers/registering-a-signer), the wallet must have executed at least one transaction before signatures will work. This is because the wallet needs to be deployed onchain first.
</Warning>

## Signing a Message

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet, EVMWallet } from '@crossmint/client-sdk-react-ui';

    const { wallet } = useWallet();

    const evmWallet = EVMWallet.from(wallet);

    const signedMessage = await evmWallet.signMessage({ message: "Hello, world!" });
    ```

    See the [React SDK reference](/sdk-reference/wallets/v0/react/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { CrossmintWallets, createCrossmint, EVMWallet } from "@crossmint/wallets-sdk";

    const crossmint = createCrossmint({
        apiKey: "<your-server-api-key>",
    });

    const crossmintWallets = CrossmintWallets.from(crossmint);

    const wallet = await crossmintWallets.getWallet(
        "email:user@example.com:evm",
        { chain: "base-sepolia", signer: { type: "email" } }
    );

    const evmWallet = EVMWallet.from(wallet);

    const signedMessage = await evmWallet.signMessage({ message: "Hello, world!" });
    ```

    ### Parameters

    <ParamField type="string">
      The message to sign.
    </ParamField>

    ### Returns

    <ParamField type="string">
      The signature of the message.
    </ParamField>
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { useWallet, EVMWallet } from '@crossmint/client-sdk-react-native-ui';

    const { wallet } = useWallet();

    const evmWallet = EVMWallet.from(wallet);

    const signedMessage = await evmWallet.signMessage({ message: "Hello, world!" });
    ```

    See the [React Native SDK reference](/sdk-reference/wallets/v0/react-native/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    import CrossmintClient
    import Wallet

    let sdk = CrossmintSDK.shared

    let wallet = try await sdk.crossmintWallets.getOrCreateWallet(
        chain: .baseSepolia,
        signer: .email("user@example.com")
    )

    let evmWallet = try EVMWallet.from(wallet: wallet)

    let signature = try await evmWallet.signMessage("Hello, world!")
    ```

    ### Parameters

    <ParamField type="string">
      The message to sign.
    </ParamField>

    ### Returns

    <ParamField type="string">
      The signature of the message.
    </ParamField>
  </Tab>

  <Tab title="REST">
    Signatures must be approved by one of the wallet's [signers](/wallets/v0/concepts/wallet-signers).
    The SDK handles this automatically, but with the REST API you must [approve the signature](/api-reference/wallets/approve-signature) to complete it.

    <Steps>
      <Step title="Create the signature">
        Call the [create signature](/api-reference/wallets/create-signature) endpoint.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/signatures \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: <x-api-key>' \
              --data '{
                  "type": "message",
                  "params": {
                      "message": "Hello, world!",
                      "signer": "email:user@example.com",
                      "chain": "base-sepolia"
                  }
              }'
          ```

          ```js Node.js theme={null}
          const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/signatures';

          const payload = {
              type: "message",
              params: {
                  message: "Hello, world!",
                  signer: "email:user@example.com",
                  chain: "base-sepolia"
              }
          };

          const options = {
              method: 'POST',
              headers: {
                  'X-API-KEY': '<x-api-key>',
                  'Content-Type': 'application/json'
              },
              body: JSON.stringify(payload)
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/signatures"

          payload = {
              "type": "message",
              "params": {
                  "message": "Hello, world!",
                  "signer": "email:user@example.com",
                  "chain": "base-sepolia"
              }
          }
          headers = {
              "X-API-KEY": "<x-api-key>",
              "Content-Type": "application/json"
          }

          response = requests.post(url, json=payload, headers=headers)

          print(response.json())
          ```
        </CodeGroup>

        See the [API reference](/api-reference/wallets/create-signature) for more details.
      </Step>

      <Step title="Sign the approval returned in the response">
        <Note>
          If you are using an `api-key` recovery method, you can skip the following steps.
        </Note>

        Sign the message returned in `signature.approvals` with the signer selected when creating the signature. When you submit the approval, set `approvals[].signer` to that signer's locator.
      </Step>

      <Step title="Approve the signature">
        Call the [approve signature](/api-reference/wallets/approve-signature) endpoint using the signature from the previous step and the signature id returned in the call from Step 1.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/signatures/91e90094-9fe0-43a7-bab6-e5725767a3ad/approvals \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: <x-api-key>' \
              --data '{
                  "approvals": [{
                      "signer": "email:user@example.com",
                      "signature": "0x1234567890abcdef..."
                  }]
              }'
          ```

          ```js Node.js theme={null}
          const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/signatures/91e90094-9fe0-43a7-bab6-e5725767a3ad/approvals';

          const payload = {
              approvals: [{
                  signer: "email:user@example.com",
                  signature: "0x1234567890abcdef..."
              }]
          };

          const options = {
              method: 'POST',
              headers: {
                  'X-API-KEY': '<x-api-key>',
                  'Content-Type': 'application/json'
              },
              body: JSON.stringify(payload)
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/signatures/91e90094-9fe0-43a7-bab6-e5725767a3ad/approvals"

          payload = {
              "approvals": [{
                  "signer": "email:user@example.com",
                  "signature": "0x1234567890abcdef..."
              }]
          }
          headers = {
              "X-API-KEY": "<x-api-key>",
              "Content-Type": "application/json"
          }

          response = requests.post(url, json=payload, headers=headers)

          print(response.json())
          ```
        </CodeGroup>

        See the [API reference](/api-reference/wallets/approve-signature) for more details.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Signing Typed Data

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet, EVMWallet } from '@crossmint/client-sdk-react-ui';

    const { wallet } = useWallet();

    const evmWallet = EVMWallet.from(wallet);
    const typedData = {
        "types": {
            "EIP712Domain": [{
                "name": "name",
                "type": "string"
            }],
        },
        "primaryType": "Mail",
        "domain": {
            "name": "example.com",
            "version": "1"
        },
        "message": {
            "from": {
                "name": "John Doe"
            },
            "to": {
                "name": "Jane Doe"
            },
            "contents": "Hello, world!"
        }
    };
    const signedMessage = await evmWallet.signTypedData(typedData);
    ```

    See the [React SDK reference](/sdk-reference/wallets/v0/react/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { CrossmintWallets, createCrossmint, EVMWallet } from "@crossmint/wallets-sdk";

    const crossmint = createCrossmint({
        apiKey: "<your-server-api-key>",
    });

    const crossmintWallets = CrossmintWallets.from(crossmint);

    const wallet = await crossmintWallets.getWallet(
        "email:user@example.com:evm",
        { chain: "base-sepolia", signer: { type: "email" } }
    );
    const evmWallet = EVMWallet.from(wallet);

    const typedData = {
        "types": {
            "EIP712Domain": [{
                "name": "name",
                "type": "string"
            }],
        },
        "primaryType": "Mail",
        "domain": {
            "name": "example.com",
            "version": "1"
        },
        "message": {
            "from": {
                "name": "John Doe"
            },
            "to": {
                "name": "Jane Doe"
            },
            "contents": "Hello, world!"
        }
    };
    const signedMessage = await evmWallet.signTypedData(typedData);
    ```
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { useWallet, EVMWallet } from '@crossmint/client-sdk-react-native-ui';

    const { wallet } = useWallet();

    const evmWallet = EVMWallet.from(wallet);

    const typedData = {
        "types": {
            "EIP712Domain": [{
                "name": "name",
                "type": "string"
            }],
        },
        "primaryType": "Mail",
        "domain": {
            "name": "example.com",
            "version": "1"
        },
        "message": {
            "from": {
                "name": "John Doe"
            },
            "to": {
                "name": "Jane Doe"
            },
            "contents": "Hello, world!"
        }
    };
    const signedMessage = await evmWallet.signTypedData(typedData);
    ```

    See the [React Native SDK reference](/sdk-reference/wallets/v0/react-native/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    import CrossmintClient
    import Wallet

    let sdk = CrossmintSDK.shared

    let wallet = try await sdk.crossmintWallets.getOrCreateWallet(
        chain: .baseSepolia,
        signer: .email("user@example.com")
    )

    let evmWallet = try EVMWallet.from(wallet: wallet)

    let signature = try await evmWallet.signTypedData(typedData)
    ```

    ### Parameters

    <ParamField type="TypedData">
      The typed data to sign.
    </ParamField>

    ### Returns

    <ParamField type="string">
      The signature of the message.
    </ParamField>
  </Tab>

  <Tab title="REST">
    Signatures must be approved by one of the wallet's [signers](/wallets/v0/concepts/wallet-signers).
    The SDK handles this automatically, but with the REST API you must [approve the signature](/api-reference/wallets/approve-signature) to complete it.

    <Steps>
      <Step title="Create the signature">
        Call the [create signature](/api-reference/wallets/create-signature) endpoint.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/signatures \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: <x-api-key>' \
              --data '{
                  "type": "typed-data",
                  "params": {
                      "typedData": {
                          "types": {
                              "EIP712Domain": [{
                                  "name": "name",
                                  "type": "string"
                              }],
                          },
                          "primaryType": "Mail",
                          "domain": {
                              "name": "example.com",
                              "version": "1"
                          },
                          "message": {
                              "from": {
                                  "name": "John Doe"
                              },
                              "to": {
                                  "name": "Jane Doe"
                              },
                              "contents": "Hello, world!"
                          }
                      },
                      "signer": "email:user@example.com",
                      "chain": "base-sepolia"
                  }
              }'
          ```

          ```js Node.js theme={null}
          const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/signatures';

          const payload = {
              type: "typed-data",
              params: {
                  typedData: {
                      types: {
                          EIP712Domain: [{
                              name: "name",
                              type: "string"
                          }]
                      },
                      primaryType: "Mail",
                      domain: {
                          name: "example.com",
                          version: "1"
                      },
                      message: {
                          from: {
                              name: "John Doe"
                          },
                          to: {
                              name: "Jane Doe"
                          },
                          contents: "Hello, world!"
                      }
                  },
                  signer: "email:user@example.com",
                  chain: "base-sepolia"
              }
          };

          const options = {
              method: 'POST',
              headers: {
                  'X-API-KEY': '<x-api-key>',
                  'Content-Type': 'application/json'
              },
              body: JSON.stringify(payload)
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/signatures"

          payload = {
              "type": "typed-data",
              "params": {
                  "typedData": {
                      "types": {
                          "EIP712Domain": [{
                              "name": "name",
                              "type": "string"
                          }],
                      },
                      "primaryType": "Mail",
                      "domain": {
                          "name": "example.com",
                          "version": "1"
                      },
                      "message": {
                          "from": {
                              "name": "John Doe"
                          },
                          "to": {
                              "name": "Jane Doe"
                          },
                          "contents": "Hello, world!"
                      }
                  },
                  "signer": "email:user@example.com",
                  "chain": "base-sepolia"
              }
          }
          headers = {
              "X-API-KEY": "<x-api-key>",
              "Content-Type": "application/json"
          }

          response = requests.post(url, json=payload, headers=headers)

          print(response.json())
          ```
        </CodeGroup>

        See the [API reference](/api-reference/wallets/create-signature) for more details.
      </Step>

      <Step title="Sign the approval returned in the response">
        <Note>
          If you are using an `api-key` recovery method, you can skip the following steps.
        </Note>

        Sign the message returned in `signature.approvals` with the signer selected when creating the signature. When you submit the approval, set `approvals[].signer` to that signer's locator.
      </Step>

      <Step title="Approve the signature">
        Call the [approve signature](/api-reference/wallets/approve-signature) endpoint using the signature from the previous step and the signature id returned in the call from Step 1.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/signatures/91e90094-9fe0-43a7-bab6-e5725767a3ad/approvals \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: <x-api-key>' \
              --data '{
                  "approvals": [{
                      "signer": "email:user@example.com",
                      "signature": "0x1234567890abcdef..."
                  }]
              }'
          ```

          ```js Node.js theme={null}
          const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/signatures/91e90094-9fe0-43a7-bab6-e5725767a3ad/approvals';

          const payload = {
              approvals: [{
                  signer: "email:user@example.com",
                  signature: "0x1234567890abcdef..."
              }]
          };

          const options = {
              method: 'POST',
              headers: {
                  'X-API-KEY': '<x-api-key>',
                  'Content-Type': 'application/json'
              },
              body: JSON.stringify(payload)
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/signatures/91e90094-9fe0-43a7-bab6-e5725767a3ad/approvals"

          payload = {
              "approvals": [{
                  "signer": "email:user@example.com",
                  "signature": "0x1234567890abcdef..."
              }]
          }
          headers = {
              "X-API-KEY": "<x-api-key>",
              "Content-Type": "application/json"
          }

          response = requests.post(url, json=payload, headers=headers)

          print(response.json())
          ```
        </CodeGroup>

        See the [API reference](/api-reference/wallets/approve-signature) for more details.
      </Step>
    </Steps>
  </Tab>
</Tabs>


# Solana
Source: https://docs.crossmint.com/wallets/v0/guides/sign-message-solana

Sign messages from your wallet

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/guides/sign-message) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

<Note>
  Signing messages is not yet supported in Solana smart wallets. To send a transaction, check the [Send Transaction
  guide](/wallets/v0/guides/send-transaction-solana).
</Note>


# Stellar
Source: https://docs.crossmint.com/wallets/v0/guides/sign-message-stellar

Sign messages from your wallet

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/guides/sign-message) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

<Note>
  Signing messages is not yet supported in Stellar smart wallets. To send a transaction, check the [Send Transaction
  guide](/wallets/v0/guides/send-transaction-stellar).
</Note>


# API Key Signer (Deprecated)
Source: https://docs.crossmint.com/wallets/v0/guides/signers/api-key

Configure an API key signer for wallet creation. This signer type is deprecated.

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/guides/signers/server-signer) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

<Warning>
  Server signers are the standard for server-side and agent operations. Unlike API key signers — which used your primary API key as the signing mechanism itself — server signers are dedicated signing credentials, giving you stronger isolation and a smaller blast radius if credentials are ever rotated or compromised.

  API key signers are deprecated and will be removed in a future release. To take advantage of the improved security model, migrate any server-side or agent workflows to [server signers](/wallets/guides/signers/server-signer).
</Warning>

In earlier versions of the Crossmint Wallets API, an API key could be used directly as an operational signer. This model is deprecated in favor of dedicated signer types that separate authentication (API key) from transaction authorization (signer key).

For a conceptual overview, see [API key](/wallets/v0/concepts/wallet-signers#api-key) in the Wallet Signers guide.

## Configuration

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet } from '@crossmint/client-sdk-react-ui';

    const { getOrCreateWallet } = useWallet();

    const wallet = await getOrCreateWallet({
        chain: "evm",
        signer: {
            type: "api-key",
        },
    });
    ```
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";

    const crossmint = createCrossmint({
        apiKey: "<your-server-api-key>",
    });
    const crossmintWallets = CrossmintWallets.from(crossmint);

    const wallet = await crossmintWallets.createWallet({
        chain: "evm",
        signer: {
            type: "api-key",
        },
    });
    ```
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { useWallet } from '@crossmint/client-sdk-react-native-ui';

    const { getOrCreateWallet } = useWallet();

    const wallet = await getOrCreateWallet({
        chain: "evm",
        signer: {
            type: "api-key",
        },
    });
    ```
  </Tab>

  <Tab title="REST">
    <CodeGroup>
      ```bash cURL theme={null}
      curl --request POST \
          --url https://staging.crossmint.com/api/2025-06-09/wallets \
          --header 'Content-Type: application/json' \
          --header 'X-API-KEY: <x-api-key>' \
          --data '{
              "chainType": "evm",
              "config": {
                  "adminSigner": {
                      "type": "api-key"
                  }
              }
          }'
      ```

      ```js Node.js theme={null}
      const url = 'https://staging.crossmint.com/api/2025-06-09/wallets';

      const payload = {
          chainType: "evm",
          config: {
              adminSigner: {
                  type: "api-key"
              }
          }
      };

      const options = {
          method: 'POST',
          headers: {
              'X-API-KEY': '<x-api-key>',
              'Content-Type': 'application/json'
          },
          body: JSON.stringify(payload)
      };

      try {
          const response = await fetch(url, options);
          const data = await response.json();
          console.log(data);
      } catch (error) {
          console.error(error);
      }
      ```

      ```python Python theme={null}
      import requests

      url = "https://staging.crossmint.com/api/2025-06-09/wallets"

      payload = {
          "chainType": "evm",
          "config": {
              "adminSigner": {
                  "type": "api-key"
              }
          }
      }
      headers = {
          "X-API-KEY": "<x-api-key>",
          "Content-Type": "application/json"
      }

      response = requests.post(url, json=payload, headers=headers)

      print(response.json())
      ```
    </CodeGroup>
  </Tab>
</Tabs>


# Device Key Signer
Source: https://docs.crossmint.com/wallets/v0/guides/signers/device-key

Configure a device key signer that uses the device's secure enclave for wallet operations.

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/guides/signers/device-signer) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

A device key signer uses P-256 keys generated inside the secure storage of the user's phone, computer, or browser — such as the iOS Secure Enclave, Android Keystore, or the browser's built-in credential store. These keys are non-extractable and never leave the device.

By default, signing is silent — transactions can be authorized without requiring the user to actively confirm each one. Device keys can optionally be configured to require biometric authentication on every use, or after a configurable idle period.

For a conceptual overview, see [Device key](/wallets/v0/concepts/wallet-signers#device-key) in the Wallet Signers guide. To learn how to register additional operational signers on an existing wallet, see [Registering a signer](/wallets/v0/guides/signers/registering-a-signer).

## Configuration

<Info>
  Detailed configuration guides for device key signers are coming soon. <a href="https://www.crossmint.com/contact/sales">Contact our team</a> if you need help setting up device key signers for your project.
</Info>


# Email OTP Signer
Source: https://docs.crossmint.com/wallets/v0/guides/signers/email-otp

Configure an email OTP signer for wallet recovery.

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/guides/signers/device-signer) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

Use an email OTP signer to let users authenticate via a one-time password sent to their email address. Email signers can be configured as a **recovery signer** (to regain wallet access on a new device) or as an **operational signer** (to authorize day-to-day transactions). A wallet can have multiple email signers.

For a conceptual overview, see [Email OTP](/wallets/v0/concepts/wallet-signers#email-otp) in the Wallet Signers guide. To learn how to register operational signers on a wallet, see [Registering a signer](/wallets/v0/guides/signers/registering-a-signer).

## Configuration

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet } from '@crossmint/client-sdk-react-ui';

    const { getOrCreateWallet } = useWallet();

    const wallet = await getOrCreateWallet({
        chain: "base",
        signer: {
            type: "email",
            email: "user@example.com"
        },
    });
    ```
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";

    const crossmint = createCrossmint({
        apiKey: "<your-server-api-key>",
    });
    const crossmintWallets = CrossmintWallets.from(crossmint);

    const wallet = await crossmintWallets.createWallet({
        chain: "base",
        signer: {
            type: "email",
            email: "user@example.com"
        },
    });
    ```
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { useWallet } from '@crossmint/client-sdk-react-native-ui';

    const { getOrCreateWallet } = useWallet();

    const wallet = await getOrCreateWallet({
        chain: "base",
        signer: {
            type: "email",
            email: "user@example.com"
        },
    });
    ```
  </Tab>

  <Tab title="REST">
    <CodeGroup>
      ```bash cURL theme={null}
      curl --request POST \
          --url https://staging.crossmint.com/api/2025-06-09/wallets \
          --header 'Content-Type: application/json' \
          --header 'X-API-KEY: <x-api-key>' \
          --data '{
              "chainType": "evm",
              "config": {
                  "adminSigner": {
                      "type": "email",
                      "email": "user@example.com"
                  }
              }
          }'
      ```

      ```js Node.js theme={null}
      const url = 'https://staging.crossmint.com/api/2025-06-09/wallets';

      const payload = {
          chainType: "evm",
          config: {
              adminSigner: {
                  type: "email",
                  email: "user@example.com"
              }
          }
      };

      const options = {
          method: 'POST',
          headers: {
              'X-API-KEY': '<x-api-key>',
              'Content-Type': 'application/json'
          },
          body: JSON.stringify(payload)
      };

      try {
          const response = await fetch(url, options);
          const data = await response.json();
          console.log(data);
      } catch (error) {
          console.error(error);
      }
      ```

      ```python Python theme={null}
      import requests

      url = "https://staging.crossmint.com/api/2025-06-09/wallets"

      payload = {
          "chainType": "evm",
          "config": {
              "adminSigner": {
                  "type": "email",
                  "email": "user@example.com"
              }
          }
      }
      headers = {
          "X-API-KEY": "<x-api-key>",
          "Content-Type": "application/json"
      }

      response = requests.post(url, json=payload, headers=headers)

      print(response.json())
      ```
    </CodeGroup>
  </Tab>
</Tabs>


# External Wallet Signer
Source: https://docs.crossmint.com/wallets/v0/guides/signers/external-wallet

Configure an external wallet or keypair as a signer for your Crossmint smart wallet.

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/guides/signers/external-wallet) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

Use an external wallet signer to connect an existing blockchain wallet or keypair — such as MetaMask, Phantom, or a raw keypair — as an operational signer on a Crossmint smart wallet. This signer type is designed for crypto-native users who already have a wallet and want to use it to control a Crossmint smart wallet.

For a conceptual overview, see [External wallet](/wallets/v0/concepts/wallet-signers#external-wallet) in the Wallet Signers guide. To learn how to register additional operational signers on an existing wallet, see [Registering a signer](/wallets/v0/guides/signers/registering-a-signer).

## Configuration

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet } from '@crossmint/client-sdk-react-ui';

    const { getOrCreateWallet } = useWallet();

    const wallet = await getOrCreateWallet({
        chain: "solana",
        signer: {
            type: "external-wallet",
            address: "WUyB2nCgAFhcf9vJ34s7vUK4KJc77bgoeM3swMcwfWn",
        },
    });
    ```
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";

    const crossmint = createCrossmint({
        apiKey: "<your-server-api-key>",
    });
    const crossmintWallets = CrossmintWallets.from(crossmint);

    const wallet = await crossmintWallets.createWallet({
        chain: "solana",
        signer: {
            type: "external-wallet",
            address: "WUyB2nCgAFhcf9vJ34s7vUK4KJc77bgoeM3swMcwfWn",
        },
    });
    ```
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { useWallet } from '@crossmint/client-sdk-react-native-ui';

    const { getOrCreateWallet } = useWallet();

    const wallet = await getOrCreateWallet({
        chain: "solana",
        signer: {
            type: "external-wallet",
            address: "WUyB2nCgAFhcf9vJ34s7vUK4KJc77bgoeM3swMcwfWn",
        },
    });
    ```
  </Tab>

  <Tab title="REST">
    <CodeGroup>
      ```bash cURL theme={null}
      curl --request POST \
          --url https://staging.crossmint.com/api/2025-06-09/wallets \
          --header 'Content-Type: application/json' \
          --header 'X-API-KEY: <x-api-key>' \
          --data '{
              "chainType": "solana",
              "config": {
                  "adminSigner": {
                      "type": "external-wallet",
                      "address": "WUyB2nCgAFhcf9vJ34s7vUK4KJc77bgoeM3swMcwfWn"
                  }
              }
          }'
      ```

      ```js Node.js theme={null}
      const url = 'https://staging.crossmint.com/api/2025-06-09/wallets';

      const payload = {
          chainType: "solana",
          config: {
              adminSigner: {
                  type: "external-wallet",
                  address: "WUyB2nCgAFhcf9vJ34s7vUK4KJc77bgoeM3swMcwfWn"
              }
          }
      };

      const options = {
          method: 'POST',
          headers: {
              'X-API-KEY': '<x-api-key>',
              'Content-Type': 'application/json'
          },
          body: JSON.stringify(payload)
      };

      try {
          const response = await fetch(url, options);
          const data = await response.json();
          console.log(data);
      } catch (error) {
          console.error(error);
      }
      ```

      ```python Python theme={null}
      import requests

      url = "https://staging.crossmint.com/api/2025-06-09/wallets"

      payload = {
          "chainType": "solana",
          "config": {
              "adminSigner": {
                  "type": "external-wallet",
                  "address": "WUyB2nCgAFhcf9vJ34s7vUK4KJc77bgoeM3swMcwfWn"
              }
          }
      }
      headers = {
          "X-API-KEY": "<x-api-key>",
          "Content-Type": "application/json"
      }

      response = requests.post(url, json=payload, headers=headers)

      print(response.json())
      ```
    </CodeGroup>
  </Tab>
</Tabs>


# Passkey Signer
Source: https://docs.crossmint.com/wallets/v0/guides/signers/passkey

Configure a passkey signer for wallet creation using WebAuthn biometrics.

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/guides/signers/passkey) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

Use a passkey signer to let users access their wallets and authorize transactions using biometric authentication — Face ID, Touch ID, fingerprint, or Windows Hello — or their password manager's unlock mechanism. Passkeys are built on the <a href="https://www.w3.org/TR/webauthn-3/">WebAuthn</a> standard and are synchronized across devices by providers such as Apple Keychain, Google Password Manager, 1Password, and Dashlane.

Every transaction signed with a passkey requires the user to authenticate, making this one of the most secure operational signer options.

For a conceptual overview, see [Passkey](/wallets/v0/concepts/wallet-signers#passkey) in the Wallet Signers guide. To learn how to register additional operational signers on an existing wallet, see [Registering a signer](/wallets/v0/guides/signers/registering-a-signer).

## Configuration

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet } from '@crossmint/client-sdk-react-ui';

    const { getOrCreateWallet } = useWallet();

    const wallet = await getOrCreateWallet({
        chain: "base",
        signer: {
            type: "passkey",
        },
    });
    ```
  </Tab>

  <Tab title="REST">
    When using a passkey as the recovery signer (admin signer) via REST, you must provide the credential details from your passkey registration flow (WebAuthn). The `id` is the credential identifier, `name` is a human-readable label for the passkey, and `publicKey.x` / `publicKey.y` are the public key coordinates from the registration response. In the browser, you can implement this registration flow using a WebAuthn helper library such as [`@simplewebauthn/browser`](https://www.npmjs.com/package/@simplewebauthn/browser).

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request POST \
          --url https://staging.crossmint.com/api/2025-06-09/wallets \
          --header 'Content-Type: application/json' \
          --header 'X-API-KEY: <x-api-key>' \
          --data '{
              "chainType": "evm",
              "config": {
                  "adminSigner": {
                      "type": "passkey",
                      "id": "cWtP7gmZbd98HbKUuGXx5Q",
                      "name": "hgranger",
                      "publicKey": {
                          "x": "38035223810536273945556366218149112558607829411547667975304293530457502824247",
                          "y": "91117823763706733837104303008228095481082989039135234750508288790583476078729"
                      }
                  }
              }
          }'
      ```

      ```js Node.js theme={null}
      const url = 'https://staging.crossmint.com/api/2025-06-09/wallets';

      const payload = {
          chainType: "evm",
          config: {
              adminSigner: {
                  type: "passkey",
                  id: "cWtP7gmZbd98HbKUuGXx5Q",
                  name: "hgranger",
                  publicKey: {
                      x: "38035223810536273945556366218149112558607829411547667975304293530457502824247",
                      y: "91117823763706733837104303008228095481082989039135234750508288790583476078729"
                  }
              }
          }
      };

      const options = {
          method: 'POST',
          headers: {
              'X-API-KEY': '<x-api-key>',
              'Content-Type': 'application/json'
          },
          body: JSON.stringify(payload)
      };

      try {
          const response = await fetch(url, options);
          const data = await response.json();
          console.log(data);
      } catch (error) {
          console.error(error);
      }
      ```

      ```python Python theme={null}
      import requests

      url = "https://staging.crossmint.com/api/2025-06-09/wallets"

      payload = {
          "chainType": "evm",
          "config": {
              "adminSigner": {
                  "type": "passkey",
                  "id": "cWtP7gmZbd98HbKUuGXx5Q",
                  "name": "hgranger",
                  "publicKey": {
                      "x": "38035223810536273945556366218149112558607829411547667975304293530457502824247",
                      "y": "91117823763706733837104303008228095481082989039135234750508288790583476078729"
                  }
              }
          }
      }
      headers = {
          "X-API-KEY": "<x-api-key>",
          "Content-Type": "application/json"
      }

      response = requests.post(url, json=payload, headers=headers)

      print(response.json())
      ```
    </CodeGroup>
  </Tab>
</Tabs>


# Registering a Signer
Source: https://docs.crossmint.com/wallets/v0/guides/signers/registering-a-signer

Register an operational signer on an existing Crossmint wallet.

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/guides/signers/add-signers) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

<Warning>
  Previous versions of these guides used the term **delegated signer**. We have moved to **operational signer** as the standard terminology. The next breaking API / SDK version will adopt this naming convention in method signatures and types. Until then, the code snippets below still reference `addDelegatedSigner` and `delegatedSigners`.
</Warning>

Register an operational signer on an existing wallet for day-to-day operations. This signer can be set up with the wallet owner — for example, a device key for user wallets or a server key for company wallets.

For an overview of available signer types, see [Wallet Signers](/wallets/v0/concepts/wallet-signers).

## Prerequisites

* Ensure you have a wallet created.
* **API Key**: Ensure you have an API key with the scopes: `wallets:signatures.create` and `wallets:transactions.create`.

## Adding an operational signer

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet } from '@crossmint/client-sdk-react-ui';

    const { wallet } = useWallet();

    const externalSigner = {
        type: "external-wallet",
        address: "0x1234567890123456789012345678901234567890"
    }

    await wallet.addDelegatedSigner({
        signer: externalSigner,
    });
    ```

    See the [React SDK reference](/sdk-reference/wallets/v0/react/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { CrossmintWallets, WalletsApiClient, createCrossmint } from "@crossmint/wallets-sdk";
    import { privateKeyToAccount } from "viem/accounts";

    const crossmint = createCrossmint({
        apiKey: "<your-server-api-key>",
    });

    const crossmintWallets = CrossmintWallets.from(crossmint);
    const apiClient = new WalletsApiClient(crossmint);

    // The wallet's admin (recovery) signer — used to approve adding the new signer
    const adminAccount = privateKeyToAccount(
        process.env.ADMIN_WALLET_PRIVATE_KEY as `0x${string}`
    );

    // The new operational signer to register
    const operationalSignerAddress = "0x1234567890123456789012345678901234567890";

    const wallet = await crossmintWallets.getWallet(
        "<wallet-address>",
        { chain: "base-sepolia", signer: { type: "external-wallet" } }
    );

    // 1. Add the operational signer in prepare-only mode
    const { signatureId } = await wallet.addDelegatedSigner({
        signer: `external-wallet:${operationalSignerAddress}`,
        options: { experimental_prepareOnly: true },
    });

    // 2. Fetch the pending signature to get the message that needs signing
    const delegatedSignatureResponse = await apiClient.getSignature(
        wallet.address,
        signatureId
    );
    if ("error" in delegatedSignatureResponse) {
        throw new Error(
            `Failed to get signature: ${JSON.stringify(delegatedSignatureResponse)}`
        );
    }

    const pendingApproval = delegatedSignatureResponse.approvals?.pending?.[0];
    if (!pendingApproval) {
        throw new Error("No pending approval found");
    }

    // 3. Sign the pending approval with the admin signer's private key
    //    (the wallet's original signer, not the signer being added)
    const signature = await adminAccount.signMessage({
        message: { raw: pendingApproval.message as `0x${string}` },
    });

    // 4. Submit the approval using the admin signer
    await wallet.approve({
        signatureId,
        options: {
            experimental_approval: {
                signature,
                signer: `external-wallet:${adminAccount.address}`,
            },
        },
    });

    console.log("Operational signer added successfully");
    ```

    <Note>
      If the wallet's admin (recovery) signer is an `api-key` type, the approval is handled automatically — you can call `addDelegatedSigner` without `experimental_prepareOnly` and skip the approval steps.
    </Note>

    See the [SDK reference](/sdk-reference/wallets/v0/typescript/classes/Wallet#adddelegatedsigner) for all parameters and return types.
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { useWallet } from '@crossmint/client-sdk-react-native-ui';

    const { wallet } = useWallet();

    const externalSigner = {
        type: "external-wallet",
        address: "0x1234567890123456789012345678901234567890"
    }

    await wallet.addDelegatedSigner({
        signer: externalSigner,
    });
    ```

    See the [React Native SDK reference](/sdk-reference/wallets/v0/react-native/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="REST">
    Operational signers must be approved by the wallet's recovery signer (called `adminSigner` in the current API).
    The SDK handles this automatically, but with the REST API you must [approve the transaction](/api-reference/wallets/approve-transaction) (if using Solana, Stellar)
    or [signature](/api-reference/wallets/approve-signature) (if using EVM) to complete it.

    <Steps>
      <Step title="Create the operational signer">
        Call the [create delegated signer](/api-reference/wallets/register-delegated-key) endpoint.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/signers \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: <x-api-key>' \
              --data '{
                  "chain": "base",
                  "signer": "external-wallet:0x1234567890123456789012345678901234567890"
              }'
          ```

          ```js Node.js theme={null}
          const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/signers';

          const payload = {
              chain: "base",
              signer: "external-wallet:0x1234567890123456789012345678901234567890"
          };

          const options = {
              method: 'POST',
              headers: {
                  'X-API-KEY': '<x-api-key>',
                  'Content-Type': 'application/json'
              },
              body: JSON.stringify(payload)
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/signers"

          payload = {
              "chain": "base",
              "signer": "external-wallet:0x1234567890123456789012345678901234567890"
          }
          headers = {
              "X-API-KEY": "<x-api-key>",
              "Content-Type": "application/json"
          }

          response = requests.post(url, json=payload, headers=headers)

          print(response.json())
          ```
        </CodeGroup>

        See the [API reference](/api-reference/wallets/register-delegated-key) for more details.
      </Step>

      <Step title="Sign the approval returned in the response">
        <Note>
          If you are using an `api-key` as the recovery signer (admin signer) you can skip the following steps.
        </Note>

        Sign the approval message field returned in the response inside `transaction.approvals` (for EVM) or `signature.approvals` (for Solana and Stellar)             using the recovery signer (admin signer).
      </Step>

      <Step title="Approve the transaction or signature to register the operational signer">
        <Tabs>
          <Tab title="EVM">
            Call the [approve signature](/api-reference/wallets/approve-signature) endpoint using the signature from the previous step and the signature id returned in the call from Step 1.

            <CodeGroup>
              ```bash cURL theme={null}
              curl --request POST \
                  --url https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/signatures/b984491a-5785-43c0-8811-45d46fe6e520/approvals \
                  --header 'Content-Type: application/json' \
                  --header 'X-API-KEY: <x-api-key>' \
                  --data '{
                      "approvals": [{
                          "signer": "email:user@example.com",
                          "signature": "0x1234567890abcdef..."
                      }]
                  }'
              ```

              ```js Node.js theme={null}
              const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/signatures/b984491a-5785-43c0-8811-45d46fe6e520/approvals';

              const payload = {
                  approvals: [{
                      signer: "email:user@example.com",
                      signature: "0x1234567890abcdef..."
                  }]
              };

              const options = {
                  method: 'POST',
                  headers: {
                      'X-API-KEY': '<x-api-key>',
                      'Content-Type': 'application/json'
                  },
                  body: JSON.stringify(payload)
              };

              try {
                  const response = await fetch(url, options);
                  const data = await response.json();
                  console.log(data);
              } catch (error) {
                  console.error(error);
              }
              ```

              ```python Python theme={null}
              import requests

              url = "https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/signatures/b984491a-5785-43c0-8811-45d46fe6e520/approvals"

              payload = {
                  "approvals": [{
                      "signer": "email:user@example.com",
                      "signature": "0x1234567890abcdef..."
                  }]
              }
              headers = {
                  "X-API-KEY": "<x-api-key>",
                  "Content-Type": "application/json"
              }

              response = requests.post(url, json=payload, headers=headers)

              print(response.json())
              ```
            </CodeGroup>

            See the [API reference](/api-reference/wallets/approve-signature) for more details.
          </Tab>

          <Tab title="Solana and Stellar">
            Call the [approve transaction](/api-reference/wallets/approve-transaction) endpoint using the signature from the previous step and the transaction id returned in the call from Step 1.

            <CodeGroup>
              ```bash cURL theme={null}
              curl --request POST \
                  --url https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:solana/transactions/b984491a-5785-43c0-8811-45d46fe6e520/approvals \
                  --header 'Content-Type: application/json' \
                  --header 'X-API-KEY: <x-api-key>' \
                  --data '{
                      "approvals": [{
                          "signer": "email:user@example.com",
                          "signature": "5qY6wXw6zTn7..."
                      }]
                  }'
              ```

              ```js Node.js theme={null}
              const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:solana/transactions/b984491a-5785-43c0-8811-45d46fe6e520/approvals';

              const payload = {
                  approvals: [{
                      signer: "email:user@example.com",
                      signature: "5qY6wXw6zTn7..."
                  }]
              };

              const options = {
                  method: 'POST',
                  headers: {
                      'X-API-KEY': '<x-api-key>',
                      'Content-Type': 'application/json'
                  },
                  body: JSON.stringify(payload)
              };

              try {
                  const response = await fetch(url, options);
                  const data = await response.json();
                  console.log(data);
              } catch (error) {
                  console.error(error);
              }
              ```

              ```python Python theme={null}
              import requests

              url = "https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:solana/transactions/b984491a-5785-43c0-8811-45d46fe6e520/approvals"

              payload = {
                  "approvals": [{
                      "signer": "email:user@example.com",
                      "signature": "5qY6wXw6zTn7..."
                  }]
              }
              headers = {
                  "X-API-KEY": "<x-api-key>",
                  "Content-Type": "application/json"
              }

              response = requests.post(url, json=payload, headers=headers)

              print(response.json())
              ```
            </CodeGroup>

            See the [API reference](/api-reference/wallets/approve-transaction) for more details.
          </Tab>
        </Tabs>
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Listing all operational signers

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet } from '@crossmint/client-sdk-react-ui';

    const { wallet } = useWallet();

    const signers = await wallet.delegatedSigners();
    ```

    See the [React SDK reference](/sdk-reference/wallets/v0/react/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";

    const crossmint = createCrossmint({
        apiKey: "<your-server-api-key>",
    });

    const crossmintWallets = CrossmintWallets.from(crossmint);

    const wallet = await crossmintWallets.getWallet(
        "<wallet-address>",
        { chain: "base-sepolia", signer: { type: "external-wallet" } }
    );

    const signers = await wallet.delegatedSigners();
    ```

    See the [SDK reference](/sdk-reference/wallets/v0/typescript/classes/Wallet#delegatedsigners) for all parameters and return types.
  </Tab>

  <Tab title="React Native">
    ```typescript React Native theme={null}
    import { useWallet } from '@crossmint/client-sdk-react-native-ui';

    const { wallet } = useWallet();

    const signers = await wallet.delegatedSigners();
    ```

    See the [React Native SDK reference](/sdk-reference/wallets/v0/react-native/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="REST">
    <CodeGroup>
      ```bash cURL theme={null}
      curl --request GET \
          --url https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm \
          --header 'X-API-KEY: <x-api-key>'
      ```

      ```js Node.js theme={null}
      const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm';

      const options = {
          method: 'GET',
          headers: {
              'X-API-KEY': '<x-api-key>'
          }
      };

      try {
          const response = await fetch(url, options);
          const data = await response.json();
          console.log(data);
      } catch (error) {
          console.error(error);
      }
      ```

      ```python Python theme={null}
      import requests

      url = "https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm"

      headers = {"X-API-KEY": "<x-api-key>"}

      response = requests.get(url, headers=headers)

      print(response.json())
      ```
    </CodeGroup>

    See the [API reference](/api-reference/wallets/get-wallet-by-locator) for more details.
  </Tab>
</Tabs>


# Server Signer
Source: https://docs.crossmint.com/wallets/v0/guides/signers/server-key

Authorize wallet operations directly from your server, using an API key and secret.

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/guides/signers/server-signer) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

Authorize transactions directly from a server environment using a Crossmint API key, and a secret provided by you. Signing happens entirely in-process with no external network call, making this the lowest-latency option available.

Because this key lives as a secret in your infrastructure, enforcing regular rotations is recommended — for example, quarterly — to limit exposure in the event of a compromised environment, a departed employee, or an infrastructure incident.

For a conceptual overview, see [Server signer](/wallets/v0/concepts/wallet-signers#server-signer) in the Wallet Signers guide. To learn how to register additional operational signers on an existing wallet, see [Registering a signer](/wallets/v0/guides/signers/registering-a-signer).

## Configuration

<Steps>
  <Step title="Generate a Signer Secret">
    You must generate a signer secret to ensure that no one — including Crossmint — can access or control your wallet. This secret:

    1. Must be either 64 hex characters (case-insensitive) or use the prefixed format `xmsk1_<64-hex-chars>`.
    2. Remains on your server and is never transmitted to Crossmint. The SDK derives a private/public keypair from it locally and uses public-key infrastructure (PKI) for authorization — only the public key is ever shared.

    <Warning>
      Generate and store this secret securely. This secret can grant full signing authority over the wallet.
    </Warning>

    Generate a secret using the [tool below](#hkdf-sha256-key-derivation-tool) or [programmatically](#generate-your-own-key-programmatically), and store it as the `CROSSMINT_SIGNER_SECRET` environment variable on your server:

    ```bash theme={null}
    CROSSMINT_SIGNER_SECRET="xmsk1_<your-64-hex-character-secret>"
    # OR
    CROSSMINT_SIGNER_SECRET="<your-64-hex-character-secret>"

    # EXAMPLE
    CROSSMINT_SIGNER_SECRET="b62b473b3ba7d3d72bf7c3a397f1eb61c305a4193ce670dd056686c13d95bbaa"
    ```

    The Crossmint SDK automatically derives chain-specific signing keys from this secret, scoped to your **project ID**, **environment**, and target **chain**. A single secret can be safely reused across chains within a project.
  </Step>

  <Step title="Create a Wallet with a Server Signer">
    Pass `type: "server"` as the signer type when creating a wallet. The SDK handles key derivation and address resolution automatically.

    <Tabs>
      <Tab title="Node.js">
        ```typescript theme={null}
        import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";

        const crossmint = createCrossmint({
            apiKey: "<your-server-api-key>",
        });
        const crossmintWallets = CrossmintWallets.from(crossmint);

        const wallet = await crossmintWallets.createWallet({
            chain: "base-sepolia",
            signer: {
                type: "server",
                secret: process.env.CROSSMINT_SIGNER_SECRET,
            },
            alias: "my-server-wallet"
        });
        ```

        <Tip>
          The `alias` parameter lets you retrieve the wallet later without storing the wallet address:

          ```typescript theme={null}
          const wallet = await crossmintWallets.getWallet(
              "evm:alias:my-server-wallet",
              { signer: { type: "server", secret: process.env.CROSSMINT_SIGNER_SECRET } }
          );
          ```
        </Tip>
      </Tab>

      <Tab title="REST">
        Server wallets require using the Crossmint SDK because the SDK handles key derivation and transaction signing locally. If you need to work with the REST API directly, use an [external wallet signer](/wallets/v0/guides/signers/external-wallet) instead — it provides equivalent functionality and lets you manage your own keys while calling the API without the SDK.
      </Tab>
    </Tabs>
  </Step>
</Steps>

## HKDF-SHA256 Key Derivation Tool

Use this tool to generate a master signer secret for your server-side or agent wallet environment. The secret is generated entirely in your browser — nothing is transmitted to any server.

<SignerSecretGenerator />

### Generate Your Own Key Programmatically

You can also generate a signer secret programmatically:

<CodeGroup>
  ```typescript Node.js / TypeScript theme={null}
  import { randomBytes } from "crypto";

  function generateSignerSecret(): string {
    const bytes = randomBytes(32);
    const hex = bytes.toString("hex");
    return `xmsk1_${hex}`;
  }

  const secret = generateSignerSecret();
  console.log(`CROSSMINT_SIGNER_SECRET="${secret}"`);
  ```

  ```python Python theme={null}
  import secrets

  def generate_signer_secret() -> str:
      hex_bytes = secrets.token_hex(32)
      return f"xmsk1_{hex_bytes}"

  secret = generate_signer_secret()
  print(f'CROSSMINT_SIGNER_SECRET="{secret}"')
  ```

  ```bash Shell (openssl) theme={null}
  echo "CROSSMINT_SIGNER_SECRET=\"xmsk1_$(openssl rand -hex 32)\""
  ```
</CodeGroup>

## Under the Hood

A server signer is, at its core, a secret that gets deterministically mapped into a private key compatible with the underlying blockchain network. You provide a master secret, and the Crossmint SDK derives chain-specific signing keys from it — so a single secret works across all supported chains within a project.

### How Key Derivation Works

A 32-byte (256-bit) random value serves as your master secret. The SDK derives chain-specific private keys from this master secret using **HKDF-SHA256**, scoped to your project ID, environment, and target chain:

```text theme={null}
key = HKDF-SHA256(
  ikm:  <master secret>,
  salt: "crossmint",
  info: "<projectId>:<environment>:<chain>-<algorithm>"
)
```

The `projectId` and `environment` are extracted automatically from your server API key by the SDK — the same master secret produces entirely different signing keys per project, environment, and chain. This means a single secret can be safely reused across chains within a single project.

You can derive the public address using Crossmint's wallets SDK — see the <a href="https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/server/helpers/derive-server-signer.ts">derive-server-signer helper</a> for reference.

### How Are Server Signer Locators Derived

When referencing a server signer in API calls (for example, when submitting approvals or registering it as an operational signer), use the locator format `server:<address>`:

```text theme={null}
server:0x1234567890123456789012345678901234567890
```

The `<address>` is the public address derived from your signer secret for the target chain. The SDK computes this automatically when you use `type: "server"` — you only need the locator format when working with the REST API directly.


# SMS OTP Signer
Source: https://docs.crossmint.com/wallets/v0/guides/signers/sms-otp

Configure an SMS OTP signer for wallet recovery.

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/guides/signers/device-signer) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

Use an SMS OTP signer to let users authenticate via a one-time password delivered by SMS or optionally WhatsApp. Phone signers can be configured as a **recovery signer** (to regain wallet access on a new device) or as an **operational signer** (to authorize day-to-day transactions). A wallet can have multiple phone signers.

For a conceptual overview, see [SMS OTP](/wallets/v0/concepts/wallet-signers#sms-otp) in the Wallet Signers guide. To learn how to register operational signers on a wallet, see [Registering a signer](/wallets/v0/guides/signers/registering-a-signer).

## Configuration

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet } from '@crossmint/client-sdk-react-ui';

    const { getOrCreateWallet } = useWallet();

    const wallet = await getOrCreateWallet({
        chain: "base",
        signer: {
            type: "phone",
            phone: "+1234567890"
        },
    });
    ```
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";

    const crossmint = createCrossmint({
        apiKey: "<your-server-api-key>",
    });
    const crossmintWallets = CrossmintWallets.from(crossmint);

    const wallet = await crossmintWallets.createWallet({
        chain: "base",
        signer: {
            type: "phone",
            phone: "+1234567890"
        },
    });
    ```
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { useWallet } from '@crossmint/client-sdk-react-native-ui';

    const { getOrCreateWallet } = useWallet();

    const wallet = await getOrCreateWallet({
        chain: "base",
        signer: {
            type: "phone",
            phone: "+1234567890"
        },
    });
    ```
  </Tab>

  <Tab title="REST">
    <CodeGroup>
      ```bash cURL theme={null}
      curl --request POST \
          --url https://staging.crossmint.com/api/2025-06-09/wallets \
          --header 'Content-Type: application/json' \
          --header 'X-API-KEY: <x-api-key>' \
          --data '{
              "chainType": "evm",
              "config": {
                  "adminSigner": {
                      "type": "phone",
                      "phone": "+1234567890"
                  }
              }
          }'
      ```

      ```js Node.js theme={null}
      const url = 'https://staging.crossmint.com/api/2025-06-09/wallets';

      const payload = {
          chainType: "evm",
          config: {
              adminSigner: {
                  type: "phone",
                  phone: "+1234567890"
              }
          }
      };

      const options = {
          method: 'POST',
          headers: {
              'X-API-KEY': '<x-api-key>',
              'Content-Type': 'application/json'
          },
          body: JSON.stringify(payload)
      };

      try {
          const response = await fetch(url, options);
          const data = await response.json();
          console.log(data);
      } catch (error) {
          console.error(error);
      }
      ```

      ```python Python theme={null}
      import requests

      url = "https://staging.crossmint.com/api/2025-06-09/wallets"

      payload = {
          "chainType": "evm",
          "config": {
              "adminSigner": {
                  "type": "phone",
                  "phone": "+1234567890"
              }
          }
      }
      headers = {
          "X-API-KEY": "<x-api-key>",
          "Content-Type": "application/json"
      }

      response = requests.post(url, json=payload, headers=headers)

      print(response.json())
      ```
    </CodeGroup>
  </Tab>
</Tabs>


# Social Recovery Signer
Source: https://docs.crossmint.com/wallets/v0/guides/signers/social-recovery

Configure social recovery to let a trusted contact authorize wallet recovery.

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/concepts/recovery) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

Social recovery lets a wallet owner designate a trusted contact — a friend, family member, or colleague — who can authorize wallet recovery on the owner's behalf via their own email or phone OTP. The trusted contact does not have access to the wallet itself; they can only co-authorize a recovery event.

This recovery mechanism is best used in combination with another recovery signer (such as email or SMS OTP) rather than in isolation.

For a conceptual overview, see [Social recovery](/wallets/v0/concepts/wallet-signers#social-recovery) in the Wallet Signers guide.

## Configuration

<Note>
  Social recovery is coming in Q2 2026. <a href="https://www.crossmint.com/contact/sales">Contact our team</a> to learn more or get early access.
</Note>


# Transfer Tokens
Source: https://docs.crossmint.com/wallets/v0/guides/transfer-tokens

Transfer tokens between wallets using Crossmint's APIs

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/guides/transfer-tokens) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

## Prerequisites

* **Wallet**: [Create a wallet](/wallets/v0/guides/create-wallet) to transfer from.
* **Operational Signer**: The signing wallet must be registered as an operational signer on the wallet. You can do this [at wallet creation](/wallets/v0/guides/create-wallet) by passing `delegatedSigners`, or afterward by [registering a signer](/wallets/v0/guides/signers/registering-a-signer).
* **Test Tokens**: Fund your wallet with [USDXM testnet tokens](/wallets/v0/guides/get-staging-tokens) before transferring.
* **API Key**: Get an API key with the `wallets:transactions.create` scope. In staging, all scopes are included by default.

## What is a token transfer?

A token transfer moves a token from one wallet address to another onchain. This creates an onchain transaction that costs gas, which Crossmint handles for you. Once the blockchain confirms the transaction, the transfer is final and cannot be reversed.

## Sending tokens

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet } from '@crossmint/client-sdk-react-ui';

    const { wallet } = useWallet();

    const { hash, explorerLink } = await wallet.send("0x0D282906CDD8F6934d60E4dCAa79fa5B1c7a1925", "usdxm", "3.14");
    ```

    See the [React SDK reference](/sdk-reference/wallets/v0/react/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { CrossmintWallets, WalletsApiClient, createCrossmint } from "@crossmint/wallets-sdk";
    import { privateKeyToAccount } from "viem/accounts";

    const crossmint = createCrossmint({
        apiKey: "<your-server-api-key>",
    });

    const crossmintWallets = CrossmintWallets.from(crossmint);
    const apiClient = new WalletsApiClient(crossmint);

    const account = privateKeyToAccount(
        process.env.EXTERNAL_WALLET_PRIVATE_KEY as `0x${string}`
    );

    const wallet = await crossmintWallets.getWallet(
        "<wallet-address>",
        { chain: "base-sepolia", signer: { type: "external-wallet" } }
    );

    // 1. Create the transaction in prepare-only mode
    const { transactionId } = await wallet.send(
        "0x0D282906CDD8F6934d60E4dCAa79fa5B1c7a1925",
        "usdxm",
        "3.14",
        {
            experimental_prepareOnly: true,
            experimental_signer: `external-wallet:${account.address}`,
        }
    );

    // 2. Fetch the pending transaction to get the message that needs signing
    const txResponse = await apiClient.getTransaction(
        wallet.address,
        transactionId
    );
    if ("error" in txResponse) {
        throw new Error(`Failed to get transaction: ${JSON.stringify(txResponse)}`);
    }

    const pendingApproval = txResponse.approvals?.pending[0];
    if (!pendingApproval) {
        throw new Error("No pending approval found");
    }

    // 3. Sign the pending approval message with your viem private key
    const signature = await account.signMessage({
        message: { raw: pendingApproval.message as `0x${string}` },
    });

    // 4. Submit the approval
    const result = await wallet.approve({
        transactionId,
        options: {
            experimental_approval: {
                signature,
                signer: `external-wallet:${account.address}`,
            },
        },
    });

    console.log("Transaction approved:", result);
    ```

    See the [SDK reference](/sdk-reference/wallets/v0/typescript/classes/Wallet#send) for all parameters and return types.
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { useWallet } from '@crossmint/client-sdk-react-native-ui';

    const { wallet } = useWallet();

    const { hash, explorerLink } = await wallet.send("0x0D282906CDD8F6934d60E4dCAa79fa5B1c7a1925", "usdxm", "3.14");
    ```

    See the [React Native SDK reference](/sdk-reference/wallets/v0/react-native/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    import CrossmintClient
    import Wallet

    let sdk = CrossmintSDK.shared

    let wallet = try await sdk.crossmintWallets.getOrCreateWallet(
        chain: .baseSepolia,
        signer: .email("user@example.com")
    )

    let result = try await wallet.send("0x0D282906CDD8F6934d60E4dCAa79fa5B1c7a1925", "usdxm", 3.14)
    ```
  </Tab>

  <Tab title="REST">
    Transfers must be approved by one of the wallet's [signers](/wallets/v0/concepts/wallet-signers).
    The SDK handles this automatically, but with the REST API you may need to craft, sign, and submit the approval manually.

    <Steps>
      <Step title="Create the transaction">
        Call the [transfer token](/api-reference/wallets/transfer-token) endpoint.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/tokens/base-sepolia:usdc/transfers \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: <x-api-key>' \
              --data '{
                  "recipient": "<recipientAddress>",
                  "amount": "3.14",
                  "signer": "external-wallet:<externalWalletAddress>"
              }'
          ```

          ```js Node.js theme={null}
          const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/tokens/base-sepolia:usdc/transfers';

          const payload = {
              recipient: "<recipientAddress>",
              amount: "3.14",
              signer: "external-wallet:<externalWalletAddress>"
          };

          const options = {
              method: 'POST',
              headers: {
                  'X-API-KEY': '<x-api-key>',
                  'Content-Type': 'application/json'
              },
              body: JSON.stringify(payload)
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/tokens/base-sepolia:usdc/transfers"

          payload = {
              "recipient": "<recipientAddress>",
              "amount": "3.14",
              "signer": "external-wallet:<externalWalletAddress>"
          }
          headers = {
              "X-API-KEY": "<x-api-key>",
              "Content-Type": "application/json"
          }

          response = requests.post(url, json=payload, headers=headers)

          print(response.json())
          ```
        </CodeGroup>

        See the [API reference](/api-reference/wallets/transfer-token) for more details.
      </Step>

      <Step title="Choose your signer type">
        The next steps depend on which signer type you specified in the previous step.

        <Tabs>
          <Tab title="Server Signer">
            [Server](/wallets/guides/signers/server-signer) signers derive a private key from your signer secret using HKDF-SHA256 and sign transactions locally.

            When using the **SDK**, signing and approval are handled automatically — no additional steps are needed.

            When using the **REST API** directly, you must:

            1. Derive the signing key from your signer secret (scoped to your project, environment, and chain type). See the <a href="https://github.com/Crossmint/crossmint-sdk/blob/main/packages/wallets/src/signers/server/helpers/derive-server-signer.ts">derive-server-signer helper</a> for a reference implementation.
            2. Sign the approval message returned from the transaction creation step.
            3. Submit the signature via the [approve transaction](/api-reference/wallets/approve-transaction) endpoint.

            <Warning>
              Crossmint recommends using the <a href="https://www.npmjs.com/package/@crossmint/wallets-sdk">Wallets SDK</a> for server signer flows. The SDK handles key derivation and signing automatically.
            </Warning>

            See the [Server Signer guide](/wallets/guides/signers/server-signer) for full configuration and setup details.
          </Tab>

          <Tab title="Device Signer">
            [Device](/wallets/guides/signers/device-signer) signers generate a P256 keypair inside the device's secure hardware (Secure Enclave, Android Keystore, or browser Web Crypto API). Because the private key never leaves the device, device signers are **client-side only** and cannot be used directly with the REST API.

            <Warning>
              Crossmint recommends using the React, React Native, or Swift SDK for device signer flows. The SDK handles device key generation, storage, and signing automatically.
            </Warning>

            See the [Device Signer guide](/wallets/guides/signers/device-signer) for setup instructions.
          </Tab>

          <Tab title="External Wallet">
            For [External Wallet](/wallets/guides/signers/add-signers) signers, you must manually sign the approval message and submit it via the API. The response from Step 1 includes a pending approval with a `message` field that must be signed exactly as returned.

            From the previous step's response, extract:

            * `id` - The transaction ID (used in the next step)
            * `approvals.pending[0].message` - The hex message to sign

            Sign the message using your external wallet. The message is a raw hex string and must be signed exactly as returned. Here's an example using an EVM wallet with [Viem](https://viem.sh/):

            ```typescript theme={null}
            import { privateKeyToAccount } from "viem/accounts";

            // The message from tx.approvals.pending[0].message
            const messageToSign = "<messageFromResponse>";

            // Sign the message exactly as returned (raw hex)
            const account = privateKeyToAccount(`0x${"<privateKey>"}`);
            const signature = await account.signMessage({
                message: { raw: messageToSign },
            });
            ```
          </Tab>

          <Tab title="Email and Phone">
            [Email and phone](/wallets/guides/recovery/configure-recovery) signers require client-side OTP verification and key derivation, which the Crossmint SDK handles automatically. While REST API signing is technically possible, you still need client-side SDK integration for the signing step.

            <Warning>
              Crossmint recommends using the React, React Native, Swift, or Node.js SDK examples instead. The SDK handles the full signing flow for email and phone signers.
            </Warning>
          </Tab>

          <Tab title="Passkey">
            [Passkey](/wallets/guides/signers/add-signers) signers use WebAuthn for biometric or password manager authentication, which requires browser interaction. While REST API signing is technically possible, Crossmint does not recommend it because you would still need client-side SDK integration for the WebAuthn signing step.

            <Warning>
              Crossmint recommends using the React, React Native, Swift, or Node.js SDK examples instead. The SDK handles the full passkey signing flow automatically.
            </Warning>
          </Tab>
        </Tabs>
      </Step>

      <Step title="Submit the approval">
        <Note>
          Skip this step if using the **SDK with a server signer** — the SDK handles signing and approval automatically.
        </Note>

        Call the [approve transaction](/api-reference/wallets/approve-transaction) endpoint with the signature from Step 2 and the transaction ID from Step 1. Set `approvals[].signer` to the locator of the signer or recovery method that produced the signature.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions/<txId>/approvals \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: <x-api-key>' \
              --data '{
                  "approvals": [{
                      "signer": "external-wallet:<externalWalletAddress>",
                      "signature": "<signature>"
                  }]
              }'
          ```

          ```js Node.js theme={null}
          const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions/<txId>/approvals';

          const payload = {
              approvals: [{
                  signer: "external-wallet:<externalWalletAddress>",
                  signature: "<signature>"
              }]
          };

          const options = {
              method: 'POST',
              headers: {
                  'X-API-KEY': '<x-api-key>',
                  'Content-Type': 'application/json'
              },
              body: JSON.stringify(payload)
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions/<txId>/approvals"

          payload = {
              "approvals": [{
                  "signer": "external-wallet:<externalWalletAddress>",
                  "signature": "<signature>"
              }]
          }
          headers = {
              "X-API-KEY": "<x-api-key>",
              "Content-Type": "application/json"
          }

          response = requests.post(url, json=payload, headers=headers)

          print(response.json())
          ```
        </CodeGroup>

        See the [API reference](/api-reference/wallets/approve-transaction) for more details.
      </Step>

      <Step title="(Optional) Check transaction status">
        You can poll the transaction status to confirm it completed successfully.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request GET \
              --url https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions/<txId> \
              --header 'X-API-KEY: <x-api-key>'
          ```

          ```js Node.js theme={null}
          const url = 'https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions/<txId>';

          const options = {
              method: 'GET',
              headers: {
                  'X-API-KEY': '<x-api-key>'
              }
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets/<walletAddress>/transactions/<txId>"

          headers = {
              "X-API-KEY": "<x-api-key>"
          }

          response = requests.get(url, headers=headers)

          print(response.json())
          ```
        </CodeGroup>
      </Step>
    </Steps>

    ### Complete example

    Here's a complete, copy-pastable example for the `external-wallet` signer flow using <Tooltip>Viem</Tooltip>:

    ```typescript theme={null}
    import { privateKeyToAccount } from "viem/accounts";

    // ============================
    // Config (replace placeholders)
    // ============================
    const API_BASE_URL = "https://staging.crossmint.com";
    const API_VERSION = "2025-06-09";

    const API_KEY = "<x-api-key>";
    const WALLET_ADDRESS = "<walletAddress>";
    const CHAIN = "base-sepolia";
    const TOKEN = "usdc";

    // The externally-owned address that will sign the approval message:
    const EXTERNAL_WALLET_ADDRESS = "<externalWalletAddress>";

    const RECIPIENT_ADDRESS = "<recipientAddress>";

    const AMOUNT = "0.69";

    const headers = {
        "X-API-KEY": API_KEY,
        "Content-Type": "application/json",
    };

    // ============================
    // STEP 1: Create the transaction
    // ============================
    const createTransferUrl = `${API_BASE_URL}/api/${API_VERSION}/wallets/${WALLET_ADDRESS}/tokens/${CHAIN}:${TOKEN}/transfers`;

    const createTransferPayload = {
        recipient: RECIPIENT_ADDRESS,
        amount: AMOUNT,
        signer: `external-wallet:${EXTERNAL_WALLET_ADDRESS}`,
    };

    const createTransferRes = await fetch(createTransferUrl, {
        method: "POST",
        headers,
        body: JSON.stringify(createTransferPayload),
    });

    if (!createTransferRes.ok) {
        throw new Error(
            `Failed to create transfer: ${createTransferRes.status} ${await createTransferRes.text()}`
        );
    }

    const tx = await createTransferRes.json();
    const txId = tx.id;
    const messageToSign = tx?.approvals?.pending?.[0]?.message;

    if (!messageToSign) {
        throw new Error(
            "No approval message found. Ensure signer is external-wallet and that an approval is pending."
        );
    }

    console.log("txId:", txId);
    console.log("messageToSign:", messageToSign);

    // ============================
    // STEP 2: Sign the approval message (Viem)
    // ============================
    // IMPORTANT: sign the message EXACTLY as returned (a raw hex string).
    const account = privateKeyToAccount(`0x${"<privateKey>"}`);

    const signature = await account.signMessage({
        message: { raw: messageToSign },
    });

    console.log("signature:", signature);

    // ============================
    // STEP 3: Submit the signature
    // ============================
    const submitApprovalUrl = `${API_BASE_URL}/api/${API_VERSION}/wallets/${WALLET_ADDRESS}/transactions/${txId}/approvals`;

    const submitApprovalPayload = {
        approvals: [
            {
                signer: `external-wallet:${EXTERNAL_WALLET_ADDRESS}`,
                signature,
            },
        ],
    };

    const submitApprovalRes = await fetch(submitApprovalUrl, {
        method: "POST",
        headers,
        body: JSON.stringify(submitApprovalPayload),
    });

    if (!submitApprovalRes.ok) {
        throw new Error(
            `Failed to submit approval: ${submitApprovalRes.status} ${await submitApprovalRes.text()}`
        );
    }

    const approvalResult = await submitApprovalRes.json();
    console.log("approvalResult:", approvalResult);

    // ============================
    // STEP 4 (optional): Check transaction status
    // ============================
    const getTxUrl = `${API_BASE_URL}/api/${API_VERSION}/wallets/${WALLET_ADDRESS}/transactions/${txId}`;

    const getTxRes = await fetch(getTxUrl, { method: "GET", headers });

    if (!getTxRes.ok) {
        throw new Error(
            `Failed to fetch transaction: ${getTxRes.status} ${await getTxRes.text()}`
        );
    }

    const txStatus = await getTxRes.json();
    console.log("txStatus:", txStatus);
    ```
  </Tab>
</Tabs>

See the [API reference](/api-reference/wallets/transfer-token) for all supported locator formats.

## Verify your transfer

Once the transfer completes, you can verify it in two ways:

1. **View the onchain transaction** using the `explorerLink` returned by the `send` method (available in the React and React Native SDKs):

```typescript theme={null}
console.log("View transaction:", explorerLink);
// Example: https://sepolia.basescan.org/tx/0xe5844116732d6cd21127bfc100ba29aee02b82cc4ab51e134d44e719ca8d0b48
```

<Note>
  When using the Node.js SDK with `experimental_prepareOnly` mode, `explorerLink` is not returned. You can check the transaction status using the `transactionId` via the [API reference](/api-reference/wallets/get-transaction).
</Note>

2. **Check the recipient's balance** programmatically using the [check balances API](/wallets/v0/guides/check-balances).

## Next steps

<CardGroup>
  <Card title="Monitor transfers with webhooks" icon="bell" href="/wallets/guides/webhooks">
    Track transactions and receive completion notifications
  </Card>

  <Card title="How to check wallet balances" icon="wallet" href="/wallets/v0/guides/check-balances">
    Query token balances across your wallets
  </Card>

  <Card title="Test the Transfer Tokens API" icon="code" href="/api-reference/wallets/transfer-token">
    Try out the API in the interactive playground
  </Card>
</CardGroup>


# LI.FI
Source: https://docs.crossmint.com/wallets/v0/guides/wallet-extensions/bridge-lifi

Bridge tokens between chains using Crossmint wallets and LI.FI

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/guides/wallet-extensions/bridge-lifi) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

This guide explains how to bridge tokens across chains using the <a href="https://docs.li.fi/li.fi-api/li.fi-api">LI.FI</a> API with Crossmint wallets. LI.FI aggregates bridges and DEXs to find optimal cross-chain routes.

## Prerequisites

To use LI.FI bridging with Crossmint wallets, you need:

* A Crossmint [wallet](/wallets/v0/guides/create-wallet) on any supported EVM chain
* A **production** **API Key** with the scope: `wallets:transactions.create` (create in the <a href="https://www.crossmint.com/console">Production Console</a>)

This guide uses Base → Polygon as an example. To follow along, you will also need:

* USDC on Base mainnet in the wallet
* ETH on Base for gas fees (not required if [gas sponsorship](/wallets/guides/gas-sponsorship) is enabled)

You can adapt the code to bridge between any chains and tokens that LI.FI supports. See [Customizing the Bridge](#customizing-the-bridge) below.

## Bridge Tokens

High level steps to bridging tokens with LI.FI and Crossmint:

1. Request a bridge quote from the LI.FI API
2. Approve the LI.FI router to spend the source token
3. Execute the bridge transaction using the quote calldata
4. Poll the LI.FI status endpoint until the bridge completes

<Warning>
  Cross-chain bridges operate on mainnet only. The wallet must hold sufficient tokens on the source chain and ETH for gas fees.
</Warning>

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet, EVMWallet } from "@crossmint/client-sdk-react-ui";
    import { encodeFunctionData, erc20Abi, parseUnits } from "viem";

    const LIFI_API = "https://li.quest/v1";
    const FROM_CHAIN = "8453"; // Base
    const TO_CHAIN = "137"; // Polygon
    const FROM_TOKEN = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"; // USDC on Base
    const TO_TOKEN = "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359"; // USDC on Polygon
    const USDC_DECIMALS = 6;

    export function BridgeComponent() {
        const { wallet } = useWallet();

        async function bridge(amount: string) {
            if(!wallet) return;
            const evmWallet = EVMWallet.from(wallet);

            // 1. Get a bridge quote from the LI.FI API
            const quoteRes = await fetch(
                `${LIFI_API}/quote?` +
                    new URLSearchParams({
                        fromChain: FROM_CHAIN,
                        toChain: TO_CHAIN,
                        fromToken: FROM_TOKEN,
                        toToken: TO_TOKEN,
                        fromAmount: parseUnits(amount, USDC_DECIMALS).toString(),
                        fromAddress: wallet.address,
                        integrator: "crossmint",
                    })
            );
            if (!quoteRes.ok) {
                throw new Error(`Quote request failed: ${quoteRes.status}`);
            }
            const quote = await quoteRes.json();

            // 2. Approve the LI.FI router to spend USDC
            if (quote.estimate.approvalAddress) {
                await evmWallet.sendTransaction({
                    to: FROM_TOKEN,
                    data: encodeFunctionData({
                        abi: erc20Abi,
                        functionName: "approve",
                        args: [
                            quote.estimate.approvalAddress,
                            parseUnits(amount, USDC_DECIMALS),
                        ],
                    }),
                });
            }

            // 3. Execute the bridge transaction
            const tx = await evmWallet.sendTransaction({
                to: quote.transactionRequest.to,
                data: quote.transactionRequest.data,
                value: quote.transactionRequest.value
                    ? BigInt(quote.transactionRequest.value)
                    : 0n,
            });

            // 4. Poll the LI.FI status endpoint until completion
            let status = "PENDING";
            while (status === "PENDING" || status === "NOT_FOUND") {
                await new Promise((r) => setTimeout(r, 5000));
                const statusRes = await fetch(
                    `${LIFI_API}/status?` +
                        new URLSearchParams({
                            txHash: tx.hash,
                            fromChain: FROM_CHAIN,
                            toChain: TO_CHAIN,
                        })
                );
                const s = await statusRes.json();
                status = s.status;
            }
        }

        return (
            <button onClick={() => bridge("5")}>Bridge Tokens</button>
        );
    }
    ```

    See the [React SDK reference](/sdk-reference/wallets/v0/react/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { CrossmintWallets, createCrossmint, EVMWallet } from "@crossmint/wallets-sdk";
    import { encodeFunctionData, erc20Abi, parseUnits } from "viem";

    const crossmint = createCrossmint({
        apiKey: <YOUR_SERVER_API_KEY>,
    });
    const crossmintWallets = CrossmintWallets.from(crossmint);

    const wallet = await crossmintWallets.getWallet(
        "email:user@example.com:evm",
        { chain: "base", signer: { type: "email" } }
    );
    if(!wallet) throw new Error("Wallet not found");
    const evmWallet = EVMWallet.from(wallet);

    const LIFI_API = "https://li.quest/v1";
    const FROM_CHAIN = "8453"; // Base
    const TO_CHAIN = "137"; // Polygon
    const FROM_TOKEN = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"; // USDC on Base
    const TO_TOKEN = "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359"; // USDC on Polygon
    const USDC_DECIMALS = 6;
    const amount = "5";

    // 1. Get a bridge quote from the LI.FI API
    const quoteRes = await fetch(
        `${LIFI_API}/quote?` +
            new URLSearchParams({
                fromChain: FROM_CHAIN,
                toChain: TO_CHAIN,
                fromToken: FROM_TOKEN,
                toToken: TO_TOKEN,
                fromAmount: parseUnits(amount, USDC_DECIMALS).toString(),
                fromAddress: wallet.address,
                integrator: "crossmint",
            })
    );
    if (!quoteRes.ok) {
        throw new Error(`Quote request failed: ${quoteRes.status}`);
    }
    const quote = await quoteRes.json();

    // 2. Approve the LI.FI router to spend USDC
    if (quote.estimate.approvalAddress) {
        await evmWallet.sendTransaction({
            to: FROM_TOKEN,
            data: encodeFunctionData({
                abi: erc20Abi,
                functionName: "approve",
                args: [
                    quote.estimate.approvalAddress,
                    parseUnits(amount, USDC_DECIMALS),
                ],
            }),
        });
    }

    // 3. Execute the bridge transaction
    const tx = await evmWallet.sendTransaction({
        to: quote.transactionRequest.to,
        data: quote.transactionRequest.data,
        value: quote.transactionRequest.value
            ? BigInt(quote.transactionRequest.value)
            : 0n,
    });

    // 4. Poll the LI.FI status endpoint until completion
    let status = "PENDING";
    while (status === "PENDING" || status === "NOT_FOUND") {
        await new Promise((r) => setTimeout(r, 5000));
        const statusRes = await fetch(
            `${LIFI_API}/status?` +
                new URLSearchParams({
                    txHash: tx.hash,
                    fromChain: FROM_CHAIN,
                    toChain: TO_CHAIN,
                })
        );
        const s = await statusRes.json();
        status = s.status;
    }

    console.log("Bridge complete!");
    ```
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { useWallet, EVMWallet } from "@crossmint/client-sdk-react-native-ui";
    import { View, Button } from "react-native";
    import { encodeFunctionData, erc20Abi, parseUnits } from "viem";

    const LIFI_API = "https://li.quest/v1";
    const FROM_CHAIN = "8453"; // Base
    const TO_CHAIN = "137"; // Polygon
    const FROM_TOKEN = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"; // USDC on Base
    const TO_TOKEN = "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359"; // USDC on Polygon
    const USDC_DECIMALS = 6;

    export function BridgeComponent() {
        const { wallet } = useWallet();

        async function bridge(amount: string) {
            if(!wallet) return;
            const evmWallet = EVMWallet.from(wallet);

            // 1. Get a bridge quote from the LI.FI API
            const quoteRes = await fetch(
                `${LIFI_API}/quote?` +
                    new URLSearchParams({
                        fromChain: FROM_CHAIN,
                        toChain: TO_CHAIN,
                        fromToken: FROM_TOKEN,
                        toToken: TO_TOKEN,
                        fromAmount: parseUnits(amount, USDC_DECIMALS).toString(),
                        fromAddress: wallet.address,
                        integrator: "crossmint",
                    })
            );
            if (!quoteRes.ok) {
                throw new Error(`Quote request failed: ${quoteRes.status}`);
            }
            const quote = await quoteRes.json();

            // 2. Approve the LI.FI router to spend USDC
            if (quote.estimate.approvalAddress) {
                await evmWallet.sendTransaction({
                    to: FROM_TOKEN,
                    data: encodeFunctionData({
                        abi: erc20Abi,
                        functionName: "approve",
                        args: [
                            quote.estimate.approvalAddress,
                            parseUnits(amount, USDC_DECIMALS),
                        ],
                    }),
                });
            }

            // 3. Execute the bridge transaction
            const tx = await evmWallet.sendTransaction({
                to: quote.transactionRequest.to,
                data: quote.transactionRequest.data,
                value: quote.transactionRequest.value
                    ? BigInt(quote.transactionRequest.value)
                    : 0n,
            });

            // 4. Poll the LI.FI status endpoint until completion
            let status = "PENDING";
            while (status === "PENDING" || status === "NOT_FOUND") {
                await new Promise((r) => setTimeout(r, 5000));
                const statusRes = await fetch(
                    `${LIFI_API}/status?` +
                        new URLSearchParams({
                            txHash: tx.hash,
                            fromChain: FROM_CHAIN,
                            toChain: TO_CHAIN,
                        })
                );
                const s = await statusRes.json();
                status = s.status;
            }
        }

        return (
            <View>
                <Button title="Bridge Tokens" onPress={() => bridge("5")} />
            </View>
        );
    }
    ```

    See the [React Native SDK reference](/sdk-reference/wallets/v0/react-native/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    import CrossmintClient
    import Wallet
    import Foundation

    let sdk = CrossmintSDK.shared

    let wallet = try await sdk.crossmintWallets
        .getOrCreateWallet(
            chain: .base,
            signer: .email(email: "user@example.com")
        )

    let evmWallet = try EVMWallet.from(wallet: wallet)

    let fromChain = "8453"
    let toChain = "137"
    let fromToken = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
    let toToken = "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359"
    let amount = "5000000" // 5 USDC (6 decimals)

    // 1. Get a bridge quote from the LI.FI API
    var quoteURL = URLComponents(string: "https://li.quest/v1/quote")!
    quoteURL.queryItems = [
        URLQueryItem(name: "fromChain", value: fromChain),
        URLQueryItem(name: "toChain", value: toChain),
        URLQueryItem(name: "fromToken", value: fromToken),
        URLQueryItem(name: "toToken", value: toToken),
        URLQueryItem(name: "fromAmount", value: amount),
        URLQueryItem(name: "fromAddress", value: wallet.address),
        URLQueryItem(name: "integrator", value: "crossmint"),
    ]

    let (quoteData, quoteResponse) = try await URLSession.shared.data(from: quoteURL.url!)
    guard let httpResponse = quoteResponse as? HTTPURLResponse,
          httpResponse.statusCode == 200 else {
        throw URLError(.badServerResponse)
    }
    let quote = try JSONSerialization.jsonObject(with: quoteData) as! [String: Any]
    let estimate = quote["estimate"] as! [String: Any]
    let txRequest = quote["transactionRequest"] as! [String: Any]

    // 2. Approve the LI.FI router to spend USDC
    //    Encodes ERC-20 approve(address,uint256) — selector 0x095ea7b3
    //    Note: UInt64 supports up to ~18.4e18. For tokens with 18 decimals
    //    and large amounts, use a big-integer hex conversion instead.
    func leftPad(_ str: String, toLength len: Int) -> String {
        String(repeating: "0", count: max(0, len - str.count)) + str
    }

    if let approvalAddress = estimate["approvalAddress"] as? String {
        let addr = leftPad(String(approvalAddress.dropFirst(2)), toLength: 64)
        let amt = leftPad(String(UInt64(amount)!, radix: 16), toLength: 64)
        let approveData = "0x095ea7b3" + addr + amt
        let _ = try await evmWallet.sendTransaction(
            to: fromToken,
            value: "0",
            data: approveData
        )
    }

    // 3. Execute the bridge transaction
    let result = try await evmWallet.sendTransaction(
        to: txRequest["to"] as! String,
        value: (txRequest["value"] as? String) ?? "0",
        data: txRequest["data"] as! String
    )

    // 4. Poll the LI.FI status endpoint until completion
    var bridgeStatus = "PENDING"
    while bridgeStatus == "PENDING" || bridgeStatus == "NOT_FOUND" {
        try await Task.sleep(nanoseconds: 5_000_000_000)

        var statusURL = URLComponents(string: "https://li.quest/v1/status")!
        statusURL.queryItems = [
            URLQueryItem(name: "txHash", value: result.hash),
            URLQueryItem(name: "fromChain", value: fromChain),
            URLQueryItem(name: "toChain", value: toChain),
        ]
        let (statusData, _) = try await URLSession.shared.data(from: statusURL.url!)
        let statusJSON = try JSONSerialization.jsonObject(with: statusData) as! [String: Any]
        bridgeStatus = statusJSON["status"] as! String
    }
    ```

    See the [Swift SDK reference](/sdk-reference/wallets/swift/classes/evmwallet) for more details.
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    import com.crossmint.kotlin.compose.LocalCrossmintSDK
    import com.crossmint.kotlin.types.EVMChain
    import com.crossmint.kotlin.types.SignerData
    import kotlinx.coroutines.Dispatchers
    import kotlinx.coroutines.delay
    import kotlinx.coroutines.withContext
    import kotlinx.serialization.json.Json
    import kotlinx.serialization.json.buildJsonObject
    import kotlinx.serialization.json.contentOrNull
    import kotlinx.serialization.json.jsonObject
    import kotlinx.serialization.json.jsonPrimitive
    import kotlinx.serialization.json.put
    import kotlinx.serialization.json.putJsonArray
    import kotlinx.serialization.json.putJsonObject
    import java.net.HttpURLConnection
    import java.net.URL

    val API_KEY = "<YOUR_API_KEY>"
    val SIGNER_EMAIL = "user@example.com"
    val LIFI_API = "https://li.quest/v1"
    val CROSSMINT_API = "https://www.crossmint.com/api/2025-06-09"
    val FROM_CHAIN = "8453"  // Base
    val TO_CHAIN = "137"     // Polygon
    val FROM_TOKEN = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"  // USDC on Base
    val TO_TOKEN = "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359"    // USDC on Polygon
    val AMOUNT = "5000000"   // 5 USDC (6 decimals)

    // Access the SDK — must be called inside a CrossmintSDKProvider composable
    val sdk = LocalCrossmintSDK.current
    val wallet = sdk.crossmintWallets
        .getOrCreateWallet(EVMChain.Base, SignerData.Email(SIGNER_EMAIL))
        .getOrThrow()

    val json = Json { ignoreUnknownKeys = true }

    // 1. Get a bridge quote from the LI.FI API
    val quoteText = withContext(Dispatchers.IO) {
        val conn = URL(
            "$LIFI_API/quote?fromChain=$FROM_CHAIN&toChain=$TO_CHAIN" +
                "&fromToken=$FROM_TOKEN&toToken=$TO_TOKEN" +
                "&fromAmount=$AMOUNT&fromAddress=${wallet.address}&integrator=crossmint"
        ).openConnection() as HttpURLConnection
        check(conn.responseCode == 200) { "Quote request failed: ${conn.responseCode}" }
        conn.inputStream.bufferedReader().readText()
    }
    val quote = json.parseToJsonElement(quoteText).jsonObject
    val estimate = quote["estimate"]!!.jsonObject
    val txRequest = quote["transactionRequest"]!!.jsonObject

    // The Kotlin SDK's send() only supports simple token transfers, not raw calldata.
    // The REST API is used here to create approval and bridge transactions directly.
    suspend fun sendEvmTransaction(to: String, data: String, value: String = "0"): String {
        val body = buildJsonObject {
            putJsonObject("params") {
                put("chain", "base")
                put("signer", "email:$SIGNER_EMAIL")
                putJsonArray("calls") {
                    add(buildJsonObject {
                        put("to", to)
                        put("value", value)
                        put("data", data)
                    })
                }
            }
        }.toString()
        val responseText = withContext(Dispatchers.IO) {
            val conn = URL("$CROSSMINT_API/wallets/${wallet.address}/transactions")
                .openConnection() as HttpURLConnection
            conn.requestMethod = "POST"
            conn.setRequestProperty("X-API-KEY", API_KEY)
            conn.setRequestProperty("Content-Type", "application/json")
            conn.doOutput = true
            conn.outputStream.write(body.toByteArray())
            val code = conn.responseCode
            if (code !in 200..299) {
                val err = conn.errorStream?.bufferedReader()?.readText()
                error("Transaction request failed ($code): $err")
            }
            conn.inputStream.bufferedReader().readText()
        }
        val transactionId = json.parseToJsonElement(responseText)
            .jsonObject["id"]!!.jsonPrimitive.content
        val tx = wallet.approve(transactionId).getOrThrow()
        return tx.onChain.txId ?: tx.onChain.userOperationHash
            ?: error("Transaction completed but no hash was returned")
    }

    // 2. Approve the LI.FI router to spend USDC
    //    Encodes ERC-20 approve(address,uint256) — selector 0x095ea7b3
    //    Note: Long supports up to ~9.2e18. For tokens with 18 decimals
    //    and large amounts, use a BigInteger hex conversion instead.
    val approvalAddress = estimate["approvalAddress"]?.jsonPrimitive?.contentOrNull
    if (approvalAddress != null) {
        val addr = approvalAddress.removePrefix("0x").padStart(64, '0')
        val amt = AMOUNT.toLong().toString(16).padStart(64, '0')
        sendEvmTransaction(to = FROM_TOKEN, data = "0x095ea7b3$addr$amt")
    }

    // 3. Execute the bridge transaction
    val txHash = sendEvmTransaction(
        to = txRequest["to"]!!.jsonPrimitive.content,
        data = txRequest["data"]!!.jsonPrimitive.content,
        value = txRequest["value"]?.jsonPrimitive?.contentOrNull ?: "0",
    )

    // 4. Poll the LI.FI status endpoint until completion
    var bridgeStatus = "PENDING"
    while (bridgeStatus == "PENDING" || bridgeStatus == "NOT_FOUND") {
        delay(5_000)
        val statusText = withContext(Dispatchers.IO) {
            val conn = URL("$LIFI_API/status?txHash=$txHash&fromChain=$FROM_CHAIN&toChain=$TO_CHAIN")
                .openConnection() as HttpURLConnection
            check(conn.responseCode == 200) { "Status request failed: ${conn.responseCode}" }
            conn.inputStream.bufferedReader().readText()
        }
        bridgeStatus = json.parseToJsonElement(statusText).jsonObject["status"]!!.jsonPrimitive.content
    }
    ```

    See the [Kotlin SDK reference](/sdk-reference/wallets/kotlin/classes/wallet) for more details.
  </Tab>

  <Tab title="REST">
    Transactions must be approved by one of the wallet's [signers](/wallets/v0/concepts/wallet-signers).
    The SDK handles this automatically, but with the REST API you must [approve the transaction](/api-reference/wallets/approve-transaction) to complete it.

    <Steps>
      <Step title="Get a bridge quote from the LI.FI API">
        Call the <a href="https://docs.li.fi/li.fi-api/li.fi-api">LI.FI API</a> `/quote` endpoint with the source and destination chain, token addresses, and amount.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request GET \
              --url 'https://li.quest/v1/quote?fromChain=8453&toChain=137&fromToken=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913&toToken=0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359&fromAmount=5000000&fromAddress=<wallet-address>&integrator=crossmint' \
              --header 'Content-Type: application/json'
          ```

          ```js Node.js theme={null}
          const params = new URLSearchParams({
              fromChain: "8453",
              toChain: "137",
              fromToken:
                  "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
              toToken:
                  "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
              fromAmount: "5000000",
              fromAddress: "<wallet-address>",
              integrator: "crossmint",
          });

          const response = await fetch(
              `https://li.quest/v1/quote?${params}`
          );
          const quote = await response.json();
          ```

          ```python Python theme={null}
          import requests

          response = requests.get(
              "https://li.quest/v1/quote",
              params={
                  "fromChain": "8453",
                  "toChain": "137",
                  "fromToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                  "toToken": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
                  "fromAmount": "5000000",
                  "fromAddress": "<wallet-address>",
                  "integrator": "crossmint",
              }
          )
          quote = response.json()
          ```
        </CodeGroup>

        The response includes `estimate.approvalAddress` and `transactionRequest` with the bridge calldata.
      </Step>

      <Step title="Send the approve and bridge transactions">
        Use the quote response to send two transactions via the Crossmint REST API:

        1. **Approve** — call the USDC contract with ERC-20 `approve` calldata targeting `estimate.approvalAddress`
        2. **Bridge** — send `transactionRequest.to`, `transactionRequest.data`, and `transactionRequest.value`

        Follow the steps in the [Send a transaction](/wallets/v0/guides/send-transaction-evm#rest) guide to submit each transaction via the Crossmint REST API.
      </Step>

      <Step title="Poll for bridge status">
        Call the LI.FI `/status` endpoint every five seconds until the bridge completes.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request GET \
              --url 'https://li.quest/v1/status?txHash=<bridge-tx-hash>&fromChain=8453&toChain=137' \
              --header 'Content-Type: application/json'
          ```

          ```js Node.js theme={null}
          const statusParams = new URLSearchParams({
              txHash: "<bridge-tx-hash>",
              fromChain: "8453",
              toChain: "137",
          });

          const statusRes = await fetch(
              `https://li.quest/v1/status?${statusParams}`
          );
          const status = await statusRes.json();
          // status.status is "DONE", "FAILED",
          // "PENDING", or "NOT_FOUND"
          ```

          ```python Python theme={null}
          import requests

          response = requests.get(
              "https://li.quest/v1/status",
              params={
                  "txHash": "<bridge-tx-hash>",
                  "fromChain": "8453",
                  "toChain": "137",
              }
          )
          status = response.json()
          # status["status"] is "DONE", "FAILED",
          # "PENDING", or "NOT_FOUND"
          ```
        </CodeGroup>

        The bridge is complete when `status` is `DONE`. If `FAILED`, check the transaction on the block explorer for details.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Customizing the Bridge

You can bridge any token pair that LI.FI supports by changing the chain and token constants. You can also perform cross-chain swaps — changing both the asset and the chain in a single operation:

```typescript theme={null}
const FROM_CHAIN = "1"; // Ethereum
const TO_CHAIN = "42161"; // Arbitrum
const FROM_TOKEN =
    "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"; // USDC on Ethereum
const TO_TOKEN =
    "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"; // USDC on Arbitrum
```

See the full list of supported chains and tokens in the <a href="https://docs.li.fi/introduction/chains#chain-overview">LI.FI Documentation</a>.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Transaction fails with insufficient balance">
    Verify the wallet holds enough USDC on Base and ETH for gas fees.
    Use the [Check Balances](/wallets/v0/guides/check-balances) guide to confirm token balances before bridging.
  </Accordion>

  <Accordion title="ERC-20 approval transaction is rejected">
    Ensure the approval amount is greater than or equal to the bridge amount.
    If a previous approval exists for a smaller amount, send a new approval transaction with the correct value.
    Verify the API key has the `wallets:transactions.create` scope.
  </Accordion>

  <Accordion title="Bridge status stays PENDING for a long time">
    Cross-chain bridges can take several minutes depending on the route and chain congestion.
    The LI.FI `/status` endpoint returns `PENDING` until both the source and destination chain transactions confirm.
    If the status does not change after 10 minutes, check the source transaction on a block explorer to verify it was included.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Check Balances" icon="wallet" href="/wallets/v0/guides/check-balances">
    Verify updated token balances after bridging on any chain
  </Card>

  <Card title="Send a Transaction" icon="arrow-right" href="/wallets/v0/guides/transfer-tokens">
    Transfer tokens from any chain
  </Card>
</CardGroup>


# Yield Generation
Source: https://docs.crossmint.com/wallets/v0/guides/wallet-extensions/generate-yield

Generate yield from your wallet's tokens using Crossmint and Yield.xyz

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/guides/wallet-extensions/yield-xyz) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

<Frame type="simple">
  <img alt="Generate Yield" />
</Frame>

<Info>
  New to yield? Learn about [yield strategies and mechanisms](/wallets/guides/wallet-extensions/overview) before diving into this implementation guide.
</Info>

<Card title="Live Demo" icon="play" href="https://fintech-starter-app.demos-crossmint.com/">
  Explore a working fintech app where users deposit USDC and earn yield
</Card>

## Supported Networks

Yield.xyz supports Ethereum, Base, Solana, and 50+ other chains across EVM and non-EVM networks. Testnet support includes Stellar-Testnet, Base-Sepolia, Ethereum-Sepolia, and Solana Devnet. For the complete and up-to-date list, see the [Yield.xyz Supported Networks documentation](https://docs.yield.xyz/docs/supported-networks).

<Info>
  This guide uses **Base** network with testnet wallets connected to mainnet
  yield opportunities, giving you a realistic experience without using real funds.
</Info>

## Prerequisites

Before you start, make sure you have:

* Completed the [React Quickstart](/wallets/v0/quickstarts/react) to set up Crossmint providers and wallet creation
* A wallet funded with USDC testnet tokens (get test USDC from [Circle's Faucet](https://faucet.circle.com/))

<Warning>
  Since this guide uses testnet tokens, deposits will not actually earn yield. For production, use mainnet USDC and ensure your Crossmint wallet is configured for mainnet.

  Need help launching in production or getting access to Yield.xyz? [Contact sales](https://www.crossmint.com/contact/sales).
</Warning>

<Steps>
  <Step title="Get a Yield.xyz API Key">
    Request an API key from [Yield.xyz](https://yield.xyz) and add it to your environment:

    ```bash .env.local theme={null}
    NEXT_PUBLIC_YIELD_API_KEY=YOUR_YIELD_XYZ_API_KEY
    ```
  </Step>

  <Step title="Create the Yield API utilities">
    Create a file with all the Yield.xyz API functions and types:

    * **Fetch Yields**: Retrieve available USDC yield opportunities on Base
    * **Enter Yield**: Deposit USDC into a yield-generating position
    * **Exit Yield**: Withdraw USDC from an active yield position
    * **Get Yield Balance**: Check the current balance in a yield position
    * **Get Active Positions**: Retrieve all active yield positions for a wallet

    ```typescript yield-api.ts theme={null}
    const YIELD_API_URL = "https://api.yield.xyz";
    const YIELD_NETWORK = "base"; // Hardcoded to Base network

    // Types
    export interface YieldOpportunity {
      id: string;
      network: string;
      providerId: string;
      metadata: { name: string; description?: string };
      rewardRate: { total: number; rateType: "APY" | "APR" };
      status: { enter: boolean; exit: boolean };
    }

    export interface YieldAction {
      id: string;
      intent: "enter" | "exit";
      yieldId: string;
      amount: string;
      amountUsd: string;
      status: "CREATED" | "PROCESSING" | "SUCCESS" | "FAILED";
      createdAt: string;
    }

    // Fetch available yield opportunities
    export async function fetchYields(): Promise<YieldOpportunity[]> {
      const response = await fetch(
        `${YIELD_API_URL}/v1/yields?network=${YIELD_NETWORK}&token=USDC&limit=10`,
        {
          headers: {
            "Content-Type": "application/json",
            "X-API-KEY": process.env.NEXT_PUBLIC_YIELD_API_KEY!,
          },
        }
      );
      if (!response.ok) {
        throw new Error("Failed to fetch yields");
      }

      const data = await response.json();
      return data.data || data.items || [];
    }

    // Enter a yield position (deposit)
    export async function enterYield(yieldId: string, address: string, amount: string) {
      const response = await fetch(`${YIELD_API_URL}/v1/actions/enter`, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "X-API-KEY": process.env.NEXT_PUBLIC_YIELD_API_KEY!,
        },
        body: JSON.stringify({
          yieldId,
          address,
          arguments: { amount }, // Human-readable (e.g., "100" for 100 USDC)
        }),
      });

      if (!response.ok) {
        throw new Error("Failed to create deposit");
      }

      return response.json();
    }

    // Exit a yield position (withdraw)
    export async function exitYield(yieldId: string, address: string, amount?: string) {
      const response = await fetch(`${YIELD_API_URL}/v1/actions/exit`, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "X-API-KEY": process.env.NEXT_PUBLIC_YIELD_API_KEY!,
        },
        body: JSON.stringify({
          yieldId,
          address,
          arguments: amount ? { amount } : { useMaxAmount: true },
        }),
      });

      if (!response.ok) {
        throw new Error("Failed to create withdrawal");
      }

      return response.json();
    }

    // Get balance for a yield position
    export async function getYieldBalance(yieldId: string, address: string): Promise<string> {
      const response = await fetch(
        `${YIELD_API_URL}/v1/yields/${yieldId}/balances?address=${address}`,
        {
          headers: {
            "Content-Type": "application/json",
            "X-API-KEY": process.env.NEXT_PUBLIC_YIELD_API_KEY!,
          },
        }
      );

      if (!response.ok) {
        return "0";
      }

      const data = await response.json();
      const activeBalance = data.balances?.find((b: any) => b.type === "active");
      return activeBalance?.amount || "0";
    }

    // Get user's active positions
    export async function getActivePositions(address: string): Promise<YieldAction[]> {
      const response = await fetch(`${YIELD_API_URL}/v1/actions?address=${address}&limit=20`, {
        headers: {
          "Content-Type": "application/json",
          "X-API-KEY": process.env.NEXT_PUBLIC_YIELD_API_KEY!,
        },
      });

      if (!response.ok) {
        return [];
      }

      const { items = [] } = await response.json();

      // Group by yieldId and filter to active positions (no exit after enter)
      const byYield = new Map<string, YieldAction[]>();
      for (const action of items) {
        const list = byYield.get(action.yieldId) || [];
        list.push(action);
        byYield.set(action.yieldId, list);
      }

      const active: YieldAction[] = [];
      for (const [, actions] of byYield) {
        const sorted = actions.sort(
          (a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime()
        );
        const lastEnter = sorted.find((a) => a.intent === "enter");
        const hasExit = sorted.some(
          (a) =>
            a.intent === "exit" && lastEnter && new Date(a.createdAt) > new Date(lastEnter.createdAt)
        );
        if (lastEnter && !hasExit) active.push(lastEnter);
      }
      return active;
    }
    ```
  </Step>

  <Step title="Build a yield component with deposit and withdraw">
    Create a component that displays yields, handles deposits, and shows active positions:

    ```tsx yield-app.tsx theme={null}
    import { useState, useEffect } from "react";
    import { useWallet, EVMWallet } from "@crossmint/client-sdk-react-ui";
    import {
      fetchYields,
      enterYield,
      exitYield,
      getActivePositions,
      getYieldBalance,
      YieldOpportunity,
      YieldAction,
    } from "./yield-api";

    export function YieldApp() {
      const { wallet } = useWallet();
      const [yields, setYields] = useState<YieldOpportunity[]>([]);
      const [positions, setPositions] = useState<YieldAction[]>([]);
      const [selectedYield, setSelectedYield] = useState<string | null>(null);
      const [amount, setAmount] = useState("");
      const [loading, setLoading] = useState(false);

      // Load yields
      useEffect(() => {
        fetchYields().then(setYields);
      }, []);

      useEffect(() => {
        if (wallet?.address) {
          getActivePositions(wallet.address).then(setPositions);
        }
      }, [wallet?.address]);

      // Execute transactions through Crossmint wallet
      const executeTransactions = async (transactions: any[]) => {
        const evmWallet = EVMWallet.from(wallet!);
        const sorted = transactions.sort((a, b) => a.stepIndex - b.stepIndex);

        for (const tx of sorted) {
          const unsigned = JSON.parse(tx.unsignedTransaction);
          await evmWallet.sendTransaction({
            to: unsigned.to,
            data: unsigned.data,
            value: unsigned.value || "0x0",
          });
        }
      };

      const handleDeposit = async (yieldId: string) => {
        if (!wallet?.address || !amount) {
          return;
        }

        setLoading(true);
        try {
          const { transactions } = await enterYield(yieldId, wallet.address, amount);
          await executeTransactions(transactions);
          setPositions(await getActivePositions(wallet.address));
          setAmount("");
          setSelectedYield(null);
        } catch (err) {
          console.error("Deposit failed:", err);
        }
        setLoading(false);
      };

      const handleWithdraw = async (yieldId: string) => {
        if (!wallet?.address) {
          return;
        }

        setLoading(true);
        try {
          // Fetch current balance to pass to exit
          const balance = await getYieldBalance(yieldId, wallet.address);
          const { transactions } = await exitYield(yieldId, wallet.address, balance);
          await executeTransactions(transactions);
          setPositions(await getActivePositions(wallet.address));
        } catch (err) {
          console.error("Withdraw failed:", err);
        }
        setLoading(false);
      };

      if (!wallet) {
        return <p>Connect your wallet to view yield opportunities.</p>;
      }

      return (
        <div className="space-y-6 p-4">
          <h2 className="text-xl font-bold">💰 Earn Yield on USDC</h2>

          {/* Yield Opportunities */}
          <div className="space-y-3">
            <h3 className="font-semibold">Available Yields</h3>
            {yields.map((y) => (
              <div
                key={y.id}
                onClick={() => setSelectedYield(selectedYield === y.id ? null : y.id)}
                className={`cursor-pointer rounded-xl border p-4 ${
                  selectedYield === y.id ? "border-blue-500" : ""
                }`}
              >
                <div className="flex justify-between">
                  <span className="font-semibold">{y.metadata.name}</span>
                  <span className="text-green-600">{(y.rewardRate.total * 100).toFixed(2)}% APY</span>
                </div>
                <p className="text-sm text-gray-500">{y.providerId}</p>

                {selectedYield === y.id && (
                  <div className="mt-3 flex gap-2" onClick={(e) => e.stopPropagation()}>
                    <input
                      type="number"
                      placeholder="Amount (USDC)"
                      value={amount}
                      onChange={(e) => setAmount(e.target.value)}
                      className="flex-1 rounded border px-3 py-2"
                    />
                    <button
                      onClick={() => handleDeposit(y.id)}
                      disabled={loading || !amount}
                      className="rounded bg-blue-600 px-4 py-2 text-white hover:bg-blue-700 disabled:opacity-50"
                    >
                      {loading ? "..." : "Deposit"}
                    </button>
                  </div>
                )}
              </div>
            ))}
          </div>

          {/* Active Positions */}
          {positions.length > 0 && (
            <div className="space-y-3">
              <h3 className="font-semibold">Your Positions</h3>
              {positions.map((p) => (
                <div key={p.id} className="flex items-center justify-between rounded-xl border p-4">
                  <div>
                    <span className="font-semibold">{p.yieldId.split("-")[2]}</span>
                    <p className="text-sm text-gray-500">${p.amountUsd} USDC</p>
                  </div>
                  <button
                    onClick={() => handleWithdraw(p.yieldId)}
                    disabled={loading}
                    className="rounded border border-red-200 bg-red-50 px-4 py-2 text-red-600 hover:bg-red-100"
                  >
                    {loading ? "..." : "Withdraw"}
                  </button>
                </div>
              ))}
            </div>
          )}
        </div>
      );
    }
    ```
  </Step>

  <Step title="Render the yield app">
    Add the yield component to your application (inside your Crossmint providers):

    ```tsx page.tsx theme={null}
    "use client";

    import { Providers } from "./providers";
    import { YieldApp } from "./yield-app";

    export default function Home() {
      return (
        <Providers>
          <YieldApp />
        </Providers>
      );
    }
    ```
  </Step>
</Steps>

## Next Steps

<CardGroup>
  <Card title="Yield.xyz API Docs" icon="book" href="https://docs.yield.xyz">
    Full API reference for yields, actions, and balances
  </Card>

  <Card title="Credit Cards" icon="credit-card" href="/wallets/guides/wallet-extensions/credit-cards">
    Let users spend their wallet balance with virtual credit cards
  </Card>
</CardGroup>


# Jupiter
Source: https://docs.crossmint.com/wallets/v0/guides/wallet-extensions/swap-jupiter

Swap tokens using Jupiter in Solana

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/guides/wallet-extensions/swap-jupiter) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

## Prerequisites

* Ensure you have a wallet created.
* **API Key**: Ensure you have an API key with the scopes: `wallets:transactions.create`.

## Swap Tokens

This guide explains how to swap tokens in Solana using the Jupiter advanced routing engine, which requires special configuration to work with smart wallets.
If you're using EVM chains, you can use [0x](https://0x.org/docs/api) or [1inch](https://1inch.io/page-api/) directly.

To perform a swap with the Jupiter Swap API and Crossmint wallets, follow these steps:

1. [Request a quote from the Jupiter API](https://dev.jup.ag/docs/api/swap-api/quote).
2. [Build the swap transaction for that quote using the Jupiter API](https://dev.jup.ag/docs/api/swap-api/swap).
3. Send the transaction using the Crossmint wallet.

<Note>
  For tokens with lower liquidity, the number of hops required to reach the destination token may be higher. This can
  make the transaction size larger and increase the risk of failure. To minimize this risk, always set maxAccounts=33
  when building the swap transaction. This ensures that even multi-hop swaps fit within Solana's transaction account
  limits and execute reliably.
</Note>

<Tabs>
  <Tab title="React">
    ```typescript theme={null}
    import { useWallet, SolanaWallet } from '@crossmint/client-sdk-react-ui';
    import { VersionedTransaction } from '@solana/web3.js';

    export function SwapTokensComponent() {
        const { wallet } = useWallet();

        async function swapTokens(tokenIn: string, tokenOut: string, amount: number) {
            // Get a quote from the Jupiter API
            const queryParams = new URLSearchParams({
                inputMint: tokenIn, // e.g "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
                outputMint: tokenOut, // e.g "XsCPL9dNWBMvFtTmwcCA5v3xWPSMEBCszbQdiLLq6aN"
                amount: amount.toString(), // In lamports!
                slippageBps: "50",
                maxAccounts: "33", // This ensures that even multi-hop swaps fit within Solana's transaction account limits and execute reliably.
            });

            const response = await fetch(`https://lite-api.jup.ag/swap/v1/quote?${queryParams}`, {
                method: "GET",
                headers: {
                    "Content-Type": "application/json",
                },
            });

            const quoteResponse = await response.json();

            // Build the swap transaction
            const swapResponse = await fetch("https://lite-api.jup.ag/swap/v1/swap", {
                method: "POST",
                headers: {
                    "Content-Type": "application/json",
                },
                body: JSON.stringify({
                    userPublicKey: wallet.address,
                    quoteResponse: quoteResponse,
                }),
            });

            const swapResponseData = await swapResponse.json();

            // Send the transaction
            const solanaWallet = SolanaWallet.from(wallet);

            const versionedTransaction = VersionedTransaction.deserialize(
                Buffer.from(swapResponseData.swapTransaction, "base64")
            );

            const tx = await solanaWallet.sendTransaction({
                transaction: versionedTransaction,
            });

            console.log("Swap transaction sent successfully!");
        }

        return (
            <div>
                <button onClick={() => swapTokens("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "XsCPL9dNWBMvFtTmwcCA5v3xWPSMEBCszbQdiLLq6aN", 1)}>Swap Tokens</button>
            </div>
        );
    }
    ```

    See the [React SDK reference](/sdk-reference/wallets/v0/react/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    import { CrossmintWallets, createCrossmint, SolanaWallet } from "@crossmint/wallets-sdk";
    import { VersionedTransaction } from "@solana/web3.js";

    const crossmint = createCrossmint({
        apiKey: "<your-server-api-key>",
    });

    const crossmintWallets = CrossmintWallets.from(crossmint);

    const wallet = await crossmintWallets.getWallet(
        "email:user@example.com:solana",
        { chain: "solana", signer: { type: "email" } }
    );

    // Get a quote from the Jupiter API
    const tokenIn = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
    const tokenOut = "XsCPL9dNWBMvFtTmwcCA5v3xWPSMEBCszbQdiLLq6aN";
    const amount = 1000000000;

    const queryParams = new URLSearchParams({
        inputMint: tokenIn,
        outputMint: tokenOut,
        amount: amount.toString(), // In lamports!
        slippageBps: "50",
        maxAccounts: "33", // This ensures that even multi-hop swaps fit within Solana's transaction account limits and execute reliably.
    });

    const response = await fetch(`https://lite-api.jup.ag/swap/v1/quote?${queryParams}`, {
        method: "GET",
        headers: {
            "Content-Type": "application/json",
        },
    });

    const quoteResponse = await response.json();

    // Build the swap transaction
    const swapResponse = await fetch("https://lite-api.jup.ag/swap/v1/swap", {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
        },
        body: JSON.stringify({
            userPublicKey: wallet.address,
            quoteResponse: quoteResponse,
        }),
    });

    const swapResponseData = await swapResponse.json();

    // Send the transaction
    const solanaWallet = SolanaWallet.from(wallet);

    const versionedTransaction = VersionedTransaction.deserialize(
        Buffer.from(swapResponseData.swapTransaction, "base64")
    );

    const tx = await solanaWallet.sendTransaction({
        transaction: versionedTransaction,
    });

    console.log("Swap transaction sent successfully!");
    ```
  </Tab>

  <Tab title="React Native">
    ```typescript theme={null}
    import { useWallet, SolanaWallet } from '@crossmint/client-sdk-react-native-ui';
    import { View, Button } from 'react-native';
    import { VersionedTransaction } from '@solana/web3.js';

    export function SwapTokensComponent() {
        const { wallet } = useWallet();

        async function swapTokens(tokenIn: string, tokenOut: string, amount: number) {
            // Get a quote from the Jupiter API
            const queryParams = new URLSearchParams({
                inputMint: tokenIn, // e.g "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
                outputMint: tokenOut, // e.g "XsCPL9dNWBMvFtTmwcCA5v3xWPSMEBCszbQdiLLq6aN"
                amount: amount.toString(), // In lamports!
                slippageBps: "50",
                maxAccounts: "33", // This ensures that even multi-hop swaps fit within Solana's transaction account limits and execute reliably.
            });

            const response = await fetch(`https://lite-api.jup.ag/swap/v1/quote?${queryParams}`, {
                method: "GET",
                headers: {
                    "Content-Type": "application/json",
                },
            });

            const quoteResponse = await response.json();

            // Build the swap transaction
            const swapResponse = await fetch("https://lite-api.jup.ag/swap/v1/swap", {
                method: "POST",
                headers: {
                    "Content-Type": "application/json",
                },
                body: JSON.stringify({
                    userPublicKey: wallet.address,
                    quoteResponse: quoteResponse,
                }),
            });

            const swapResponseData = await swapResponse.json();

            // Send the transaction
            const solanaWallet = SolanaWallet.from(wallet);

            const versionedTransaction = VersionedTransaction.deserialize(
                Buffer.from(swapResponseData.swapTransaction, "base64")
            );

            const tx = await solanaWallet.sendTransaction({
                transaction: versionedTransaction,
            });

            console.log("Swap transaction sent successfully!");
        }

        return (
            <View>
                <Button onPress={() => swapTokens("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "XsCPL9dNWBMvFtTmwcCA5v3xWPSMEBCszbQdiLLq6aN", 1)}>Swap Tokens</Button>
            </View>
        );
    }
    ```

    See the [React Native SDK reference](/sdk-reference/wallets/v0/react-native/hooks#wallet-methods) for more details.
  </Tab>

  <Tab title="REST">
    Transactions must be approved by one of the wallet's [signers](/wallets/v0/concepts/wallet-signers).
    The SDK handles this automatically, but with the REST API you must [approve the transaction](/api-reference/wallets/approve-transaction) to complete it.

    <Steps>
      <Step title="Call the get quote endpoint">
        Call the [get quote endpoint](https://dev.jup.ag/docs/api/swap-api/quote) to get a quote for the swap.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://lite-api.jup.ag/swap/v1/quote?inputMint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&outputMint=XsCPL9dNWBMvFtTmwcCA5v3xWPSMEBCszbQdiLLq6aN&amount=1000000000&slippageBps=50&maxAccounts=33 \
              --header 'Content-Type: application/json'
          ```

          ```js Node.js theme={null}
          const url = 'https://lite-api.jup.ag/swap/v1/quote?inputMint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&outputMint=XsCPL9dNWBMvFtTmwcCA5v3xWPSMEBCszbQdiLLq6aN&amount=1000000000&slippageBps=50&maxAccounts=33';
          const options = {
              method: 'GET',
              headers: {'Content-Type': 'application/json'},
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```python Python theme={null}
          import requests

          url = "https://lite-api.jup.ag/swap/v1/quote?inputMint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&outputMint=XsCPL9dNWBMvFtTmwcCA5v3xWPSMEBCszbQdiLLq6aN&amount=1000000000&slippageBps=50&maxAccounts=33"

          headers = {
              "Content-Type": "application/json"
          }

          response = requests.get(url, headers=headers)

          print(response.json())
          ```
        </CodeGroup>

        See the [Jupiter API docs](https://dev.jup.ag/docs/api/swap-api/quote) for more details.
      </Step>

      <Step title="Build the swap transaction">
        Build the swap transaction using the [swap endpoint](https://dev.jup.ag/docs/api/swap-api/swap) and pass in the quote response from the previous step.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://lite-api.jup.ag/swap/v1/swap \
              --header 'Content-Type: application/json' \
              --data '{"userPublicKey": "<user-public-key>", "quoteResponse": <quote-response>}'
          ```

          ```js Node.js theme={null}
          const url = 'https://lite-api.jup.ag/swap/v1/swap';
          const options = {
              method: 'POST',
              headers: {'Content-Type': 'application/json'},
              body: JSON.stringify({
                  userPublicKey: "<wallet-address>",
                  quoteResponse: <quote-response>
              })
          };

          try {
              const response = await fetch(url, options);
              const data = await response.json();
              console.log(data);
          } catch (error) {
              console.error(error);
          }
          ```

          ```python Python theme={null}
          import requests

          url = "https://lite-api.jup.ag/swap/v1/swap"

          headers = {
              "Content-Type": "application/json"
          }

          payload = {
              "userPublicKey": "<wallet-address>",
              "quoteResponse": <quote-response>
          }

          response = requests.post(url, json=payload, headers=headers)

          print(response.json())
          ```
        </CodeGroup>

        See the [Jupiter API docs](https://dev.jup.ag/docs/api/swap-api/swap) for more details.
      </Step>

      <Step title="Send the transaction">
        Follow the steps in the [Send a transaction](/wallets/v0/guides/send-transaction-solana#rest) guide to submit the returned transaction in the previous step.
      </Step>
    </Steps>
  </Tab>
</Tabs>


# Overview
Source: https://docs.crossmint.com/wallets/v0/overview

Create wallets for users, agents, or company operations

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/overview) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

Crossmint provides secure, programmable wallet infrastructure powering some of the World's leading fintechs and enterprises, like MoneyGram and Santander Bank.

A single SDK, configurable for any use case — from embedded, invisible wallets for your users, to high-throughput treasury wallets, to wallets for AI agents. All blockchain complexity is abstracted away from you and your users.

The APIs are chain-agnostic and take care of all wallet operations: creation, transaction execution, gas sponsorship, [onramps](/onramp/overview), compliance tools, advanced policies and controls, and more; so you can get started in minutes and be ready to scale.

Additionally, Crossmint provides wallet extensions for cards, swapping, staking, prediction markets, tokenized stocks, and other primitives so you can easily connect to the best external tools.

## Where to Start

<CardGroup>
  <Card title="Evaluating Crossmint?" icon="magnifying-glass" href="/wallets/v0/architecture">
    Read **Architecture** to understand the dual-layer model, then **Custody Modalities** for compliance implications.
  </Card>

  <Card title="Ready to build?" icon="code" href="/wallets/v0/quickstarts/react">
    Jump to a **Quickstart** for your platform. You can create a wallet in under 5 minutes.
  </Card>

  <Card title="Choosing signers?" icon="key" href="/wallets/v0/concepts/decision-tree">
    Use the **Decision Tree** to pick the right operational and recovery signer types for your use case.
  </Card>
</CardGroup>

## Next-gen architecture

Most wallet providers couple the private key and the wallet together. Crossmint takes a different approach: wallets are [smart contract wallets](/wallets/v0/why-smart-wallets) with a [modular signer architecture](/wallets/v0/concepts/wallet-signers). You choose the signing method, and you can change it anytime — without changing wallet addresses.

This architecture makes operating wallets cheaper, provides maximum flexibility around custody and use case, and removes vendor lock-in.

For a full technical explanation, see [Architecture](/wallets/v0/architecture).

**Key features:**

* **Seamless UX**: no passphrases, gas fees, or other blockchain gimmicks.
* **Flexible key management**: Choose your preferred signing methods. Rotate or update anytime if your needs change.
* **Operational signers**: Add scoped signers with permissions and limits.
* **Native gas sponsorship**: Crossmint pays for gas fees and bills you in fiat.
* **Built-in onramps**: headless flows to allow users to fund their wallets.
* **Multi-chain**: 50+ [supported chains](/introduction/supported-chains) via one unified API.
* **Reliability engine**: Crossmint operates a reliability layer for transaction submission with multi-RPC failover, queuing, batching, priority fee optimization, and more.
* **Powerful extensions**: Composable features like swaps, staking, cards, and more.
* **Native programmability**: enable functionality only possible with smart accounts, like subscriptions and advanced payment logic.
* **Account recovery**: allow users to retrieve their account, even if they lose access to their main signer.
* **Webhooks**: Real-time notifications for wallet events.
* **No vendor lock-in**: change vendors anytime by taking ownership of the contracts and migrating signers, without having to change wallet addresses or migrate vendors.

<CardGroup>
  <Card title="Test a live demo" icon="bolt" href="https://wallets.demos-crossmint.com">
    Sample demo and repo showcasing basic features
  </Card>
</CardGroup>

## Common use cases

<CardGroup>
  <Card title="Embedded wallets" icon="window" href="/wallets/v0/guides/create-wallet">
    Insert white-label wallets into your app.
  </Card>

  <Card title="Treasury wallets" icon="vault" href="/wallets/concepts/treasury">
    Manage your company's digital assets.
  </Card>

  <Card title="Agent wallets" icon="robot">
    Give wallets to your AI agents.
  </Card>
</CardGroup>

## Try it Live

Experience creating a wallet with this interactive demo:

<WalletCreationDemo />

## Choose your SDK

<CardGroup>
  <Card title="React" icon="react" href="/wallets/quickstarts/react" />

  <Card title="Node.js" icon="node-js" href="/wallets/quickstarts/nodejs" />

  <Card title="REST API" icon="server" href="/wallets/quickstarts/restapi" />

  <Card title="React Native" icon="mobile-notch" href="/wallets/quickstarts/react-native" />

  <Card title="Flutter" icon="mobile" href="/wallets/quickstarts/flutter" />

  <Card title="Swift" icon="swift" href="/wallets/quickstarts/swift" />

  <Card title="Kotlin" icon="android" href="/wallets/quickstarts/kotlin" />
</CardGroup>

## Learn More

* [Architecture](/wallets/v0/architecture)
* [Wallet Signers](/wallets/v0/concepts/wallet-signers)
* [Create a wallet](/wallets/v0/guides/create-wallet)
* [Transfer tokens](/wallets/v0/guides/transfer-tokens)
* [Get balance](/wallets/v0/guides/check-balances)
* [Webhooks](/wallets/guides/webhooks)
* [Glossary](/introduction/glossary)


# Kotlin
Source: https://docs.crossmint.com/wallets/v0/quickstarts/kotlin

Create user wallets from your mobile app in under 5 minutes

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/quickstarts/kotlin) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

This quickstart integrates the Crossmint Kotlin SDK into an Android app to create a non-custodial wallet for a user, fund it with testnet USDC on Base Sepolia, and send USDC to another wallet.

<CardGroup>
  <Snippet />

  <Card title="Android Demo App" icon="github" href="https://github.com/Crossmint/android-quickstart">
    See a full working example with a repository to clone.
  </Card>
</CardGroup>

<Steps>
  <Step title="Install the SDK">
    Add the Crossmint dependencies to your app's `build.gradle.kts` file:

    <Tabs>
      <Tab title="Version Catalog">
        ```kotlin build.gradle.kts theme={null}
        dependencies {
            implementation(libs.crossmint.sdk)
            implementation(libs.crossmint.compose)
        }
        ```

        ```toml libs.versions.toml theme={null}
        [versions]
        crossmint-compose = "0.0.2"
        crossmint-sdk = "0.0.2"

        [libraries]
        crossmint-compose = { module = "com.crossmint:crossmint-compose", version.ref = "crossmint-compose" }
        crossmint-sdk = { module = "com.crossmint:crossmint-sdk", version.ref = "crossmint-sdk" }
        ```
      </Tab>

      <Tab title="Direct">
        ```kotlin build.gradle.kts theme={null}
        dependencies {
            implementation("com.crossmint:crossmint-sdk:0.0.2")
            implementation("com.crossmint:crossmint-compose:0.0.2")
        }
        ```
      </Tab>
    </Tabs>

    ### Requirements

    * Minimum Android SDK: API 24 (Android 7.0+)
    * JDK 11 or newer
    * Jetpack Compose
  </Step>

  <Step title="Configure your API key">
    The Crossmint SDK requires a client API key for authentication. <br />
    [Get your client API key](/introduction/platform/api-keys/client-side) using the Crossmint Console.
  </Step>

  <Step title="Initialize the Crossmint SDK">
    Wrap your app content with `CrossmintSDKProvider` to initialize the SDK. This example uses [Crossmint Auth](/authentication/introduction)
    but you can use [any authentication provider of your choice](/wallets/v0/guides/bring-your-own-auth).

    ```kotlin QuickstartApp.kt theme={null}
    import androidx.compose.runtime.Composable
    import com.crossmint.kotlin.compose.CrossmintSDKProvider

    val CROSSMINT_API_KEY = "ck_staging_your_key_here"

    @Composable
    fun QuickstartApp() {
        CrossmintSDKProvider
            .Builder(CROSSMINT_API_KEY)
            .build {
                // Your app content goes here
                AppContent()
            }
    }
    ```

    <Note>
      The environment (staging vs production) is automatically determined by your API key. Staging keys start with `ck_staging_`, production keys with `ck_production_`.
    </Note>

    ### Access SDK instances

    Inside the `CrossmintSDKProvider`, access SDK functionality using `LocalCrossmintSDK.current`:

    ```kotlin theme={null}
    import com.crossmint.kotlin.compose.LocalCrossmintSDK

    val sdk = LocalCrossmintSDK.current
    val authManager = sdk.authManager
    val wallets = sdk.crossmintWallets
    ```
  </Step>

  <Step title="Authenticate users">
    Actions within the SDK are user-based, so first you need to authenticate a user.
    Choose your authentication method:

    <Tabs>
      <Tab title="Crossmint Auth (OTP)">
        Use Crossmint's built-in OTP authentication for easy, email-based login.

        <Accordion title="OTP Sample Code">
          This is a simple OTP form example you can use for this quickstart.

          ```kotlin theme={null}
          @Composable
          actual fun OTPDialog(
              onOTPSubmit: (String) -> Unit,
              onDismiss: () -> Unit,
          ) {
              var otpCode by remember { mutableStateOf("") }

              AlertDialog(
                  onDismissRequest = onDismiss,
                  title = { Text("Enter OTP Code") },
                  text = {
                      TextField(
                          value = otpCode,
                          onValueChange = { otpCode = it },
                          label = { Text("Enter OTP") },
                          singleLine = true,
                      )
                  },
                  confirmButton = {
                      Button(onClick = { onOTPSubmit(otpCode) }) {
                          Text("Submit")
                      }
                  },
                  dismissButton = {
                      TextButton(onClick = onDismiss) {
                          Text("Cancel")
                      }
                  },
              )
          }        
          ```
        </Accordion>

        <Steps>
          <Step title="Send OTP to user's email">
            ```kotlin theme={null}
            import com.crossmint.kotlin.compose.LocalCrossmintSDK

            val authManager = LocalCrossmintSDK.current.authManager
            when (val result = authManager.sendOtp("user_email")) {
                is Result.Success -> {
                    // OTP sent to email, now display an input for the OTP
                }
                is Result.Failure -> {
                    // Handle error: result.error.message
                }
            }
            ```
          </Step>

          <Step title="Enter the OTP sent to the user's email">
            ```kotlin theme={null}
            import com.crossmint.kotlin.compose.LocalCrossmintSDK

            val authManager = LocalCrossmintSDK.current.authManager
            when (val result = authManager.verifyOtp("user_email", "otp_sent_via_email")) {
                is Result.Success -> {
                    // User is authenticated, proceed
                }
                is Result.Failure -> {
                    // Handle errors
                }
            }
            ```
          </Step>
        </Steps>

        <Note>
          See the [Android Demo App](https://github.com/Crossmint/android-quickstart) repository for a complete UI implementation example with ViewModels and Compose screens.
        </Note>
      </Tab>

      <Tab title="Third-Party Auth (Prod)">
        If you have an existing auth provider (Auth0, Firebase, Supabase, etc.), authenticate users with your provider and pass the JWT to Crossmint.

        ```kotlin theme={null}
        import com.crossmint.kotlin.compose.LocalCrossmintSDK

        val authManager = LocalCrossmintSDK.current.authManager

        // After user authenticates with your provider, get their JWT
        val token = AuthToken(
            jwt = yourProviderJWT,
            refreshToken = yourProviderRefreshToken, // optional
            userId = yourProviderUserId, // optional
            userEmail = userEmail // optional
        )

        when (val result = authManager.authenticateWithToken(token)) {
            is Result.Success -> {
                // User authenticated with Crossmint
            }
            is Result.Failure -> {
                // Handle error: result.error.message
            }
        }
        ```

        <Note>
          Configure JWT authentication in the [Crossmint Console](https://console.crossmint.com) under API Keys → JWT Authentication before using third-party auth. See the [Crossmint Demo App](https://github.com/Crossmint/crossmint-kotlin-sdk/tree/main/crossmintDemoApp) for a complete Supabase integration example.
        </Note>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Create a wallet">
    After authentication, create the user's wallet. This example uses Base Sepolia (Base testnet) but you can chose any [supported chain](/introduction/supported-chains).<br />

    ```kotlin theme={null}
    import com.crossmint.kotlin.compose.LocalCrossmintSDK
    import com.crossmint.kotlin.types.EVMChain
    import com.crossmint.kotlin.types.SignerData

    val crossmintWallets = LocalCrossmintSDK.current.crossmintWallets
    val chain = EVMChain.BaseSepolia
    val signer = SignerData.Email("user_email")
    when (val result = crossmintWallets.getOrCreateWallet(chain, signer)) {
        is Result.Success -> {
            val wallet = result.value // Wallet is ready to use!
        }
        is Result.Failure -> {
            // Handle error: result.error.message
        }
    }
    ```
  </Step>

  <Step title="Send USDC">
    Before sending some USDC, we need to get some into the wallet.

    Get the wallet address:

    ```kotlin theme={null}
    val walletAddress = wallet.address
    ```

    Then, navigate to the [USDC Faucet](https://faucet.circle.com/) to get some USDC into the wallet.
    Make sure to select `Base Sepolia` and insert the wallet address.

    <img alt="Circle faucet — Base Sepolia selected" />

    Now, to send some USDC to another wallet, use the `wallet.send` function.

    ```kotlin theme={null}
    // Create the transaction
    val recipient = "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
    val tokenLocator = "base-sepolia:usdc"
    val amount = 0.01
    val sendResult = wallet.send(recipient, tokenLocator, amount)
    if (sendResult is Result.Failure) {
        // handle failure
    }

    // Approve the transaction
    val transaction = sendResult as Result.Success<Transaction>
    when (val approveResult = wallet.approve(transaction.value.id)) {
        is Result.Success -> {
            // Transaction successful, proceed
        }
        is Result.Failure -> {
            // Handle failure
        }
    }
    ```

    The very first time that a wallet sends a transaction on this device, an OTP will be required, sent to the user via email.

    Following transactions sent from the same device won't need OTP verification.

    To facilitate this, here's a simple component you can use for the OTP input:

    <Accordion title="OTP Sample code">
      This is a simple OTP form example you can use for this quickstart.

      ```kotlin theme={null}
      @Composable
      actual fun OTPDialog(
          onOTPSubmit: (String) -> Unit,
          onDismiss: () -> Unit,
      ) {
          var otpCode by remember { mutableStateOf("") }

          AlertDialog(
              onDismissRequest = onDismiss,
              title = { Text("Enter OTP Code") },
              text = {
                  TextField(
                      value = otpCode,
                      onValueChange = { otpCode = it },
                      label = { Text("Enter OTP") },
                      singleLine = true,
                  )
              },
              confirmButton = {
                  Button(onClick = { onOTPSubmit(otpCode) }) {
                      Text("Submit")
                  }
              },
              dismissButton = {
                  TextButton(onClick = onDismiss) {
                      Text("Cancel")
                  }
              },
          )
      }        
      ```
    </Accordion>

    and in `QuickstartApp.kt` where the `CrossmintSDKProvider` was initialized, use it like this:

    ```kotlin QuickstartApp.kt theme={null}
        CrossmintSDKProvider
            .Builder(CROSSMINT_API_KEY)
            .onTEERequired { onOTPSubmit, onDismiss ->
                OTPDialog(
                    onOTPSubmit = onOTPSubmit,
                    onDismiss = onDismiss,
                )
            }
            .build {
                // Your app content goes here
                AppContent()
            }
    ```

    And that's it! You just created a non-custodial wallet for your user and made a USDC transaction on Base Sepolia.
  </Step>
</Steps>

## Launching in Production

For production, the steps are almost identical, but some changes are required:

1. Create a developer account on the [production console](https://www.crossmint.com/console)
2. Create a production client API key on the [API Keys](https://www.crossmint.com/console/projects/apiKeys) page with the API scopes `users.create`, `users.read`, `wallets.read`, `wallets.create`, `wallets:transactions.create`, `wallets:transactions.sign`, `wallets:balance.read`, `wallets.fund`
3. Update your `local.properties` with the production API key
4. **Use your own authentication provider**: For production applications, Crossmint recommends using [third-party authentication](/wallets/v0/guides/bring-your-own-auth) (Option 2 from Step 4) with providers like Auth0, Firebase, or Supabase, rather than Crossmint Auth (OTP). Configure JWT authentication in the [Crossmint Console](https://www.crossmint.com/console/projects/apiKeys) under API Keys → JWT Authentication.


# Node.js
Source: https://docs.crossmint.com/wallets/v0/quickstarts/nodejs

Create user wallets from your backend in under 5 minutes

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/quickstarts/nodejs) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

<CardGroup>
  <Snippet />
</CardGroup>

<Steps>
  <Step title="Install the SDK">
    Run the following command to install the SDK:

    <Snippet />
  </Step>

  <Step title="Create a wallet">
    See all supported chains [here](/introduction/supported-chains).

    ```tsx index.ts theme={null}
    import { CrossmintWallets, createCrossmint } from "@crossmint/wallets-sdk";

    const crossmint = createCrossmint({
        apiKey: "<your-server-api-key>",
    });

    const crossmintWallets = CrossmintWallets.from(crossmint);

    const wallet = await crossmintWallets.createWallet({
        chain: "<your-chain>",
        signer: {
            type: "<signer-type>",
        },
    });

    console.log(wallet.address);
    ```
  </Step>
</Steps>

## Launching in Production

For production, the steps are almost identical, but some changes are required:

1. Create a developer account on the [production console](https://www.crossmint.com/console)
2. Create a production client API key on the [API Keys](https://www.crossmint.com/console/projects/apiKeys) page with the API scopes `users.create`, `users.read`, `wallets.read`, `wallets.create`, `wallets:transactions.create`, `wallets:transactions.sign`, `wallets:balance.read`, `wallets.fund`
3. Replace your test API key with the production key

## Learn More

<CardGroup>
  <Card title="Check Balances" icon="money-bill-transfer" href="/wallets/v0/guides/check-balances">
    Check the balance of a wallet.
  </Card>

  <Card title="Transfer Tokens" icon="coins" href="/wallets/v0/guides/transfer-tokens">
    Send tokens between wallets.
  </Card>

  <Card title="Operational Signers" icon="key" href="/wallets/v0/guides/signers/registering-a-signer">
    Register operational signers on a wallet.
  </Card>
</CardGroup>

## Other Links

<CardGroup>
  <Card title="API Reference" icon="terminal" href="/api-reference/wallets/create-wallet">
    Deep dive into API reference docs.
  </Card>

  <Card title="Talk to an expert" icon="message" href="https://www.crossmint.com/contact/sales">
    Contact our sales team for support.
  </Card>
</CardGroup>


# React
Source: https://docs.crossmint.com/wallets/v0/quickstarts/react

Create user wallets from your frontend in under 5 minutes

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/quickstarts/react) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

<CardGroup>
  <Snippet />

  <Card title="Wallets Quickstart" icon="github" href="https://github.com/Crossmint/wallets-quickstart">
    See a full working example.
  </Card>
</CardGroup>

<Steps>
  <Step title="Install the SDK">
    Run the following command to install the SDK:

    <Snippet />
  </Step>

  <Step title="Add the Crossmint providers to your app">
    Add the necessary Crossmint providers to your app. This example uses [Crossmint Auth](/authentication/introduction)
    but you can use [any authentication provider of your choice](/wallets/v0/guides/bring-your-own-auth).

    With the current setup, a wallet will be created automatically on login.

    <CodeGroup>
      ```tsx next.js theme={null}
      "use client";

      import {
          CrossmintProvider,
          CrossmintAuthProvider,
          CrossmintWalletProvider,
      } from "@crossmint/client-sdk-react-ui";

      export function Providers({ children }: { children: React.ReactNode }) {
          return (
              <CrossmintProvider apiKey="<crossmint-client-api-key>">
                  <CrossmintAuthProvider>
                      <CrossmintWalletProvider
                          createOnLogin={{
                              chain: "base-sepolia",
                              signer: {
                                  type: "email",
                              },
                          }}
                      >
                          {children}
                      </CrossmintWalletProvider>
                  </CrossmintAuthProvider>
              </CrossmintProvider>
          );
      }
      ```
    </CodeGroup>

    For detailed configuration options, see the [React SDK Reference](/sdk-reference/wallets/v0/react/providers#crossmintwalletprovider).
  </Step>

  <Step title="Build a wallet component with basic functionality">
    Create a component that handles authentication and basic wallet actions.

    ```tsx wallet-app.tsx theme={null}
    import { useState } from "react";
    import { useAuth, useWallet } from "@crossmint/client-sdk-react-ui";

    export function WalletApp() {
        const { login, logout, jwt, status } = useAuth();
        const { wallet } = useWallet();
        const [usdxmBalance, setUsdxmBalance] = useState<string>("");

        const fundWallet = async () => {
            if (!wallet || !jwt) return;
            await wallet.stagingFund(10);
        };

        const transferTokens = async () => {
            if (!wallet) return;
            
            const recipient = "0xdf8b5f9c19e187f1ea00730a1e46180152244315";
            const token = "usdxm";
            const amount = "1";
            
            await wallet.send(recipient, token, amount);
        };

        const checkBalance = async () => {
            if (!wallet) return;
            const balances = await wallet.balances(["usdxm"]);
            const usdxmBalance = balances.tokens.find(
                (token) => token.symbol === "usdxm"
            )?.amount;
            setUsdxmBalance(usdxmBalance || "0");
        };

        if (status === "initializing") {
            return <div>Loading...</div>;
        }

        if (wallet == null || status === "logged-out") {
            return <button onClick={login}>Login</button>;
        }

        return (
            <div>
                <h2>💼 Wallet: {wallet?.address}</h2>
                <h3>👤 {wallet?.owner}</h3><br />
                <button onClick={fundWallet}>💰 Fund with 10 USDXM</button><br />
                <button onClick={transferTokens}>📤 Send 1 USDXM</button><br />
                <button onClick={checkBalance}>🔍 Check Balance</button><br />
                <button onClick={logout}>🚪 Logout</button>
                {usdxmBalance && <p>💳 USDXM Balance: {usdxmBalance}</p>}
            </div>
        );
    }

    ```
  </Step>

  <Step title="Render the wallet app">
    Render the wallet app in your application.

    ```tsx app.tsx theme={null}
    "use client";

    import { Providers } from './providers';
    import { WalletApp } from './wallet-app';

    export default function Home() {
        return (
            <Providers>
                <WalletApp />
            </Providers>
        );
    }
    ```
  </Step>
</Steps>

## Launching in Production

For production, some changes are required:

1. Create a developer account on the [production console](https://www.crossmint.com/console)
2. Create a production client API key on the [API Keys](https://www.crossmint.com/console/projects/apiKeys) page with the API scopes `users.create`, `users.read`, `wallets.read`, `wallets.create`, `wallets:transactions.create`, `wallets:transactions.sign`, `wallets:balance.read`, `wallets.fund`
3. Replace your test API key with the production key
4. **Use your own authentication provider**: For production applications, Crossmint recommends using [third-party authentication](/wallets/v0/guides/bring-your-own-auth) with providers like Auth0, Firebase, or Supabase, rather than Crossmint Auth. Configure JWT authentication in the [Crossmint Console](https://www.crossmint.com/console/projects/apiKeys) under API Keys > JWT Authentication.

## Learn More

<CardGroup>
  <Card title="Check Balances" icon="money-bill-transfer" href="/wallets/v0/guides/check-balances">
    Check the balance of a wallet.
  </Card>

  <Card title="Transfer Tokens" icon="coins" href="/wallets/v0/guides/transfer-tokens">
    Send tokens between wallets.
  </Card>

  <Card title="Operational Signers" icon="key" href="/wallets/v0/guides/signers/registering-a-signer">
    Register operational signers on a wallet.
  </Card>
</CardGroup>

## Other Links

<CardGroup>
  <Card title="API Reference" icon="terminal" href="/api-reference/wallets/create-wallet">
    Deep dive into API reference docs.
  </Card>

  <Card title="Talk to an expert" icon="message" href="https://www.crossmint.com/contact/sales">
    Contact our sales team for support.
  </Card>
</CardGroup>


# React Native
Source: https://docs.crossmint.com/wallets/v0/quickstarts/react-native

Create user wallets from your frontend in under 5 minutes

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/quickstarts/react-native) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

<CardGroup>
  <Snippet />

  <Card title="Expo Wallets Quickstart" icon="github" href="https://github.com/Crossmint/wallets-expo-quickstart">
    See a full working example.
  </Card>
</CardGroup>

<Steps>
  <Step title="Install the SDK">
    Run the following command to install the SDK:

    <Snippet />
  </Step>

  <Step title="Add the Crossmint providers to your app">
    Add the necessary Crossmint providers to your app. This example uses [Crossmint Auth](/authentication/introduction)
    but you can use [any authentication provider of your choice](/wallets/v0/guides/bring-your-own-auth).

    With the current setup, a wallet will be created automatically on login.

    See all supported chains [here](/introduction/supported-chains).

    ```tsx providers.tsx theme={null}
    import {
        CrossmintAuthProvider,
        CrossmintProvider,
        CrossmintWalletProvider,
    } from "@crossmint/client-sdk-react-native-ui";

    type ProvidersProps = {
        children: React.ReactNode;
    };

    export default function CrossmintProviders({ children }: ProvidersProps) {

        return (
            <CrossmintProvider apiKey={"<your-client-api-key>"}>
                <CrossmintAuthProvider>
                    <CrossmintWalletProvider
                        createOnLogin={{
                            chain: "<your-chain>",
                            signer: {
                                type: "<signer-type>",
                            }
                        }}
                    >
                        {children}
                    </CrossmintWalletProvider>
                </CrossmintAuthProvider>
            </CrossmintProvider>
        );
    }
    ```

    For detailed configuration options, see the [React Native SDK Reference](/sdk-reference/wallets/v0/react-native/providers#crossmintwalletprovider).
  </Step>

  <Step title="Allow users to login and logout and access their wallet">
    Crossmint Auth in React Native is headless. You will need to implement your own login and logout buttons.

    ```tsx index.tsx theme={null}
    import React, { useEffect, useState } from "react";
    import {
        View,
        Text,
        TextInput,
        TouchableOpacity,
        ActivityIndicator,
        Alert,
    } from "react-native";
    import {
        useCrossmintAuth,
        useWallet,
    } from "@crossmint/client-sdk-react-native-ui";
    import * as Linking from "expo-linking";

    export default function Index() {
        const {
            loginWithOAuth,
            createAuthSession,
            user,
            crossmintAuth,
            logout,
            status,
        } = useCrossmintAuth();
        const { wallet } = useWallet();

        // Login state
        const [email, setEmail] = useState("");
        const [emailId, setEmailId] = useState("");
        const [otpSent, setOtpSent] = useState(false);
        const [otp, setOtp] = useState("");
        const [isPending, setIsPending] = useState(false);

        // Handle OAuth callback
        useEffect(() => {
            const url = Linking.useURL();
            if (url != null) {
                createAuthSession(url);
            }
        }, [createAuthSession]);

        // Login functions
        const sendOtp = async () => {
            if (!email.trim()) {
                Alert.alert("Error", "Please enter a valid email address");
                return;
            }

            setIsPending(true);
            try {
                const res = await crossmintAuth?.sendEmailOtp(email);
                setEmailId(res.emailId);
                setOtpSent(true);
            } catch (error) {
                Alert.alert("Error", "Failed to send OTP. Please try again.");
            } finally {
                setIsPending(false);
            }
        };

        const verifyOtp = async () => {
            if (!otp.trim()) {
                Alert.alert("Error", "Please enter the OTP code");
                return;
            }

            setIsPending(true);
            try {
                const oneTimeSecret = await crossmintAuth?.confirmEmailOtp(
                    email,
                    emailId,
                    otp
                );
                await createAuthSession(oneTimeSecret);
            } catch (error) {
                Alert.alert("Error", "Invalid OTP code. Please try again.");
            } finally {
                setIsPending(false);
            }
        };

        const handleLogout = async () => {
            try {
                logout();
                // Reset login state
                setEmail("");
                setEmailId("");
                setOtpSent(false);
                setOtp("");
            } catch (error) {
                Alert.alert("Error", "Failed to logout. Please try again.");
            }
        };

        // Loading state
        if (status === "initializing") {
            return (
                <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
                    <ActivityIndicator size="large" />
                    <Text>Initializing...</Text>
                </View>
            );
        }

        // Login screen
        if (status === "logged-out") {
            return (
                <View style={{ flex: 1, padding: 20, justifyContent: "center" }}>
                    <Text style={{ fontSize: 24, marginBottom: 20, textAlign: "center" }}>
                        Login
                    </Text>

                    <TextInput
                        style={{ borderWidth: 1, padding: 10, marginBottom: 10 }}
                        placeholder="Enter your email"
                        value={email}
                        onChangeText={setEmail}
                        editable={!otpSent}
                    />

                    {!otpSent ? (
                        <TouchableOpacity
                            style={{
                                backgroundColor: "#05b959",
                                padding: 15,
                                alignItems: "center",
                            }}
                            onPress={sendOtp}
                            disabled={isPending}
                        >
                            {isPending ? (
                                <ActivityIndicator color="#fff" size="small" />
                                ) : (
                                <Text style={{ color: "#fff" }}>Send OTP</Text>
                            )}
                        </TouchableOpacity>
                        ) : (
                        <>
                            <TextInput
                                style={{ borderWidth: 1, padding: 10, marginBottom: 10 }}
                                placeholder="Enter OTP code"
                                value={otp}
                                onChangeText={setOtp}
                            />
                            <TouchableOpacity
                                style={{
                                    backgroundColor: "#05b959",
                                    padding: 15,
                                    alignItems: "center",
                                    marginBottom: 10,
                                }}
                                onPress={verifyOtp}
                                disabled={isPending}
                            >
                                {isPending ? (
                                    <ActivityIndicator color="#fff" size="small" />
                                ) : (
                                    <Text style={{ color: "#fff" }}>Verify OTP</Text>
                                )}
                            </TouchableOpacity>
                            <TouchableOpacity
                                style={{
                                    backgroundColor: "#ccc",
                                    padding: 15,
                                    alignItems: "center",
                                }}
                                onPress={() => setOtpSent(false)}
                                disabled={isPending}
                            >
                                <Text>Back</Text>
                            </TouchableOpacity>
                        </>
                    )}

                    <View style={{ marginVertical: 20 }}>
                        <Text style={{ textAlign: "center", marginBottom: 10 }}>OR</Text>
                        <TouchableOpacity
                            style={{
                                backgroundColor: "#4285f4",
                                padding: 15,
                                alignItems: "center",
                            }}
                            onPress={() => loginWithOAuth("google")}
                        >
                            <Text style={{ color: "#fff" }}>Sign in with Google</Text>
                        </TouchableOpacity>
                    </View>
                </View>
            );
        }

        // Main app screen (logged in)
        return (
            <View style={{ flex: 1, padding: 20 }}>
                <View
                    style={{
                        flexDirection: "row",
                        justifyContent: "space-between",
                        marginBottom: 20,
                    }}
                >
                    <Text style={{ fontSize: 20 }}>Welcome!</Text>
                    <TouchableOpacity onPress={handleLogout}>
                        <Text style={{ color: "red" }}>Logout</Text>
                    </TouchableOpacity>
                </View>

                <View style={{ marginBottom: 20 }}>
                    <Text style={{ fontSize: 16, marginBottom: 5 }}>User Info:</Text>
                    <Text>Email: {user?.email}</Text>
                    <Text>User ID: {user?.id}</Text>
                </View>

                {wallet && (
                    <View style={{ marginBottom: 20 }}>
                        <Text style={{ fontSize: 16, marginBottom: 5 }}>Wallet Info:</Text>
                        <Text>Address: {wallet.address}</Text>
                    </View>
                )}

                <View>
                    <Text style={{ fontSize: 16, marginBottom: 10 }}>App Content:</Text>
                    <Text>You are now logged in and can access your wallet!</Text>
                </View>
            </View>
        );
    }

    ```
  </Step>
</Steps>

## Launching in Production

For production, some changes are required:

1. Create a developer account on the <a href="https://www.crossmint.com/console">production console</a>
2. Create a production client API key on the <a href="https://www.crossmint.com/console/projects/apiKeys">API Keys</a> page with the API scopes `users.create`, `users.read`, `wallets.read`, `wallets.create`, `wallets:transactions.create`, `wallets:transactions.sign`, `wallets:balance.read`, `wallets.fund`
3. Replace your test API key with the production key
4. **Use your own authentication provider**: For production applications, Crossmint recommends using [third-party authentication](/wallets/v0/guides/bring-your-own-auth) with providers like Auth0, Firebase, or Supabase, rather than Crossmint Auth. Configure JWT authentication in the <a href="https://www.crossmint.com/console/projects/apiKeys">Crossmint Console</a> under API Keys > JWT Authentication.

## Learn More

<CardGroup>
  <Card title="Check Balances" icon="money-bill-transfer" href="/wallets/v0/guides/check-balances">
    Check the balance of a wallet.
  </Card>

  <Card title="Transfer Tokens" icon="coins" href="/wallets/v0/guides/transfer-tokens">
    Send tokens between wallets.
  </Card>

  <Card title="Operational Signers" icon="key" href="/wallets/v0/guides/signers/registering-a-signer">
    Register operational signers on a wallet.
  </Card>
</CardGroup>

## Other Links

<CardGroup>
  <Card title="API Reference" icon="terminal" href="/api-reference/wallets/create-wallet">
    Deep dive into API reference docs.
  </Card>

  <Card title="Talk to an expert" icon="message" href="https://www.crossmint.com/contact/sales">
    Contact our sales team for support.
  </Card>
</CardGroup>


# REST API
Source: https://docs.crossmint.com/wallets/v0/quickstarts/restapi

Create and manage user wallets from your backend

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/quickstarts/restapi) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

In this quickstart you will learn how to create wallets, check balances, and transfer tokens from your backend using the Crossmint Wallets API.

<CardGroup>
  <Snippet />

  <Card title="Wallets Quickstart" icon="github" href="https://github.com/Crossmint/wallets-quickstart">
    See a full working example.
  </Card>
</CardGroup>

## Understanding Wallet Types

Crossmint supports two types of wallets:

* **Smart Wallets**: Account abstraction wallets with configurable signers. You control who can sign transactions (external wallets, passkeys, etc.).
* **MPC Wallets**: Custodial wallets where Crossmint manages the private keys using multi-party computation. Simpler setup with no signer configuration needed. [Contact us](https://www.crossmint.com/contact/sales) for access.

<Steps>
  <Step title="Create a wallet">
    <Tabs>
      <Tab title="EVM Smart Wallet">
        Smart wallets on EVM chains (Base, Polygon, Ethereum, etc.) with configurable signers.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: <x-api-key>' \
              --data '{
                  "chainType": "evm",
                  "type": "smart",
                  "config": {
                      "adminSigner": {
                          "type": "external-wallet",
                          "address": "<your-wallet-address>"
                      }
                  },
                  "owner": "email:user@example.com"
              }'
          ```

          ```javascript Node.js theme={null}
          const options = {
              method: 'POST',
              headers: {
                  'X-API-KEY': '<x-api-key>',
                  'Content-Type': 'application/json'
              },
              body: JSON.stringify({
                  chainType: "evm",
                  type: "smart",
                  config: {
                      adminSigner: {
                          type: "external-wallet",
                          address: "<your-wallet-address>"
                      }
                  },
                  owner: "email:user@example.com"
              })
          };

          fetch('https://staging.crossmint.com/api/2025-06-09/wallets', options)
              .then(response => response.json())
              .then(data => {
                  console.log('Wallet created:', data.address);
                  console.log('Full response:', data);
              })
              .catch(err => console.error(err));
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets"

          payload = {
              "chainType": "evm",
              "type": "smart",
              "config": {
                  "adminSigner": {
                      "type": "external-wallet",
                      "address": "<your-wallet-address>"
                  }
              },
              "owner": "email:user@example.com"
          }
          headers = {
              "X-API-KEY": "<x-api-key>",
              "Content-Type": "application/json"
          }

          response = requests.post(url, json=payload, headers=headers)
          data = response.json()

          print(f"Wallet created: {data['address']}")
          print(f"Full response: {data}")
          ```
        </CodeGroup>

        **Key Parameters:**

        * `chainType`: The blockchain family (`evm` for Ethereum-compatible chains)
        * `type`: Wallet type (`smart` for smart wallets)
        * `config.adminSigner`: The primary signer for the wallet
          * `type: "external-wallet"`: Use an external wallet address you control
          * `type: "api-key"`: Let Crossmint manage signing via API ([contact us](https://www.crossmint.com/contact/sales) for access)
        * `owner`: User identifier in format `email:user@example.com` (optional but recommended)

        <Accordion title="Sample Response (201 Created)">
          ```json theme={null}
          {
              "chainType": "evm",
              "type": "smart",
              "address": "0xABC1234567890DEF1234567890ABCDEF12345678",
              "owner": "email:user@example.com",
              "config": {
                  "adminSigner": {
                      "type": "external-wallet",
                      "address": "<your-wallet-address>",
                      "locator": "external-wallet:<your-wallet-address>"
                  }
              },
              "createdAt": "2025-12-15T10:30:00.000Z"
          }
          ```

          **Save the** `address` **field** - you'll need it to interact with this wallet.
        </Accordion>
      </Tab>

      <Tab title="Solana Smart Wallet">
        Smart wallets on Solana with configurable signers.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: <x-api-key>' \
              --data '{
                  "chainType": "solana",
                  "type": "smart",
                  "config": {
                      "adminSigner": {
                          "type": "external-wallet",
                          "address": "<your-wallet-address>"
                      }
                  },
                  "owner": "email:user@example.com"
              }'
          ```

          ```javascript Node.js theme={null}
          const options = {
              method: 'POST',
              headers: {
                  'X-API-KEY': '<x-api-key>',
                  'Content-Type': 'application/json'
              },
              body: JSON.stringify({
                  chainType: "solana",
                  type: "smart",
                  config: {
                      adminSigner: {
                          type: "external-wallet",
                          address: "<your-wallet-address>"
                      }
                  },
                  owner: "email:user@example.com"
              })
          };

          fetch('https://staging.crossmint.com/api/2025-06-09/wallets', options)
              .then(response => response.json())
              .then(data => console.log('Wallet created:', data.address))
              .catch(err => console.error(err));
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets"

          payload = {
              "chainType": "solana",
              "type": "smart",
              "config": {
                  "adminSigner": {
                      "type": "external-wallet",
                      "address": "<your-wallet-address>"
                  }
              },
              "owner": "email:user@example.com"
          }
          headers = {
              "X-API-KEY": "<x-api-key>",
              "Content-Type": "application/json"
          }

          response = requests.post(url, json=payload, headers=headers)
          print(f"Wallet created: {response.json()['address']}")
          ```
        </CodeGroup>
      </Tab>

      <Tab title="EVM MPC Wallet">
        <Note>[Contact us](https://www.crossmint.com/contact/sales) for access to MPC wallets.</Note>

        Custodial wallets on EVM chains.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: <x-api-key>' \
              --data '{
                  "chainType": "evm",
                  "type": "mpc",
                  "owner": "email:user@example.com"
              }'
          ```

          ```javascript Node.js theme={null}
          const options = {
              method: 'POST',
              headers: {
                  'X-API-KEY': '<x-api-key>',
                  'Content-Type': 'application/json'
              },
              body: JSON.stringify({
                  chainType: "evm",
                  type: "mpc",
                  owner: "email:user@example.com"
              })
          };

          fetch('https://staging.crossmint.com/api/2025-06-09/wallets', options)
              .then(response => response.json())
              .then(data => console.log('Wallet created:', data.address))
              .catch(err => console.error(err));
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets"

          payload = {
              "chainType": "evm",
              "type": "mpc",
              "owner": "email:user@example.com"
          }
          headers = {
              "X-API-KEY": "<x-api-key>",
              "Content-Type": "application/json"
          }

          response = requests.post(url, json=payload, headers=headers)
          print(f"Wallet created: {response.json()['address']}")
          ```
        </CodeGroup>

        <Note>
          MPC wallets don't require a `config` section. Crossmint manages the private keys securely using multi-party computation.
        </Note>
      </Tab>

      <Tab title="Solana MPC Wallet">
        <Note>[Contact us](https://www.crossmint.com/contact/sales) for access to MPC wallets.</Note>

        Custodial wallets on Solana.

        <CodeGroup>
          ```bash cURL theme={null}
          curl --request POST \
              --url https://staging.crossmint.com/api/2025-06-09/wallets \
              --header 'Content-Type: application/json' \
              --header 'X-API-KEY: <x-api-key>' \
              --data '{
                  "chainType": "solana",
                  "type": "mpc",
                  "owner": "email:user@example.com"
              }'
          ```

          ```javascript Node.js theme={null}
          const options = {
              method: 'POST',
              headers: {
                  'X-API-KEY': '<x-api-key>',
                  'Content-Type': 'application/json'
              },
              body: JSON.stringify({
                  chainType: "solana",
                  type: "mpc",
                  owner: "email:user@example.com"
              })
          };

          fetch('https://staging.crossmint.com/api/2025-06-09/wallets', options)
              .then(response => response.json())
              .then(data => console.log('Wallet created:', data.address))
              .catch(err => console.error(err));
          ```

          ```python Python theme={null}
          import requests

          url = "https://staging.crossmint.com/api/2025-06-09/wallets"

          payload = {
              "chainType": "solana",
              "type": "mpc",
              "owner": "email:user@example.com"
          }
          headers = {
              "X-API-KEY": "<x-api-key>",
              "Content-Type": "application/json"
          }

          response = requests.post(url, json=payload, headers=headers)
          print(f"Wallet created: {response.json()['address']}")
          ```
        </CodeGroup>
      </Tab>
    </Tabs>

    See the [API reference](/api-reference/wallets/create-wallet) for all available parameters.
  </Step>

  <Step title="Retrieve a wallet">
    Retrieve wallet information using a <Tooltip>wallet locator</Tooltip>. This is useful when you need to get wallet details without storing the wallet address.

    **Wallet Locator Formats:**

    * By address: `0xABC...` or `GbA2NZ...`
    * By email: `email:user@example.com:evm:smart`
    * By user ID: `userId:507f1f77bcf86cd799439011:solana:mpc`

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request GET \
          --url https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm:smart \
          --header 'X-API-KEY: <x-api-key>'
      ```

      ```javascript Node.js theme={null}
      const walletLocator = 'email:user@example.com:evm:smart';
      const options = {
          method: 'GET',
          headers: {'X-API-KEY': '<x-api-key>'}
      };

      fetch(`https://staging.crossmint.com/api/2025-06-09/wallets/${walletLocator}`, options)
          .then(response => response.json())
          .then(data => {
              console.log('Wallet address:', data.address);
              console.log('Owner:', data.owner);
          })
          .catch(err => console.error(err));
      ```

      ```python Python theme={null}
      import requests

      wallet_locator = "email:user@example.com:evm:smart"
      url = f"https://staging.crossmint.com/api/2025-06-09/wallets/{wallet_locator}"

      headers = {"X-API-KEY": "<x-api-key>"}

      response = requests.get(url, headers=headers)
      data = response.json()

      print(f"Wallet address: {data['address']}")
      print(f"Owner: {data['owner']}")
      ```
    </CodeGroup>

    <Accordion title="Sample Response (200 OK)">
      ```json theme={null}
      {
          "chainType": "evm",
          "type": "smart",
          "address": "0xABC1234567890DEF1234567890ABCDEF12345678",
          "owner": "email:user@example.com",
          "config": {
              "adminSigner": {
                  "type": "external-wallet",
                  "address": "<your-wallet-address>",
                  "locator": "external-wallet:<your-wallet-address>"
              }
          },
          "createdAt": "2025-12-15T10:30:00.000Z"
      }
      ```
    </Accordion>

    <Accordion title="More Wallet Locator Examples">
      * `0x1234567890123456789012345678901234567890` - Direct address
      * `email:user@example.com:evm:smart` - Email + wallet type
      * `userId:507f1f77bcf86cd799439011:solana:mpc` - User ID + wallet type
      * `phoneNumber:+12125551234:evm:smart` - Phone + wallet type
      * `twitter:johndoe:evm:smart` or `x:@johndoe:evm:smart` - Twitter/X + wallet type
      * `me:evm:smart` - Authenticated user (client-side only)
    </Accordion>
  </Step>

  <Step title="Check wallet balance">
    Check token balances for a wallet. You can query multiple tokens at once by providing a comma-separated list.

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request GET \
          --url 'https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/balances?tokens=usdc,eth' \
          --header 'X-API-KEY: <x-api-key>'
      ```

      ```javascript Node.js theme={null}
      const walletLocator = 'email:user@example.com:evm';
      const tokens = 'usdc,eth';
      const url = `https://staging.crossmint.com/api/2025-06-09/wallets/${walletLocator}/balances?tokens=${tokens}`;

      const options = {
          method: 'GET',
          headers: {'X-API-KEY': '<x-api-key>'}
      };

      fetch(url, options)
          .then(response => response.json())
          .then(data => {
              console.log('Native token balance:', data.nativeToken);
              console.log('Token balances:', data.tokens);
          })
          .catch(err => console.error(err));
      ```

      ```python Python theme={null}
      import requests

      wallet_locator = "email:user@example.com:evm"
      url = f"https://staging.crossmint.com/api/2025-06-09/wallets/{wallet_locator}/balances"

      params = {"tokens": "usdc,eth"}
      headers = {"X-API-KEY": "<x-api-key>"}

      response = requests.get(url, params=params, headers=headers)
      data = response.json()

      print(f"Native token: {data['nativeToken']}")
      print(f"Token balances: {data['tokens']}")
      ```
    </CodeGroup>

    **Query Parameters:**

    * `tokens` (required): Comma-separated list of token symbols (e.g., `usdc,eth,usdxm`)
    * `chains` (optional): Filter by specific chains when using multi-chain wallets

    <Accordion title="Sample Response (200 OK)">
      ```json theme={null}
      {
          "nativeToken": {
              "symbol": "ETH",
              "decimals": 18,
              "balance": "1500000000000000000",
              "balanceUSD": "4500.00"
          },
          "tokens": [
              {
                  "symbol": "USDC",
                  "decimals": 6,
                  "balance": "1000000000",
                  "balanceUSD": "1000.00",
                  "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
              }
          ]
      }
      ```

      Balances are returned as strings in the token's smallest unit (wei for ETH, lamports for SOL, etc.).
    </Accordion>
  </Step>

  <Step title="Transfer tokens">
    Send tokens from a wallet to a recipient. Smart wallets handle gas fees automatically through Crossmint's paymaster.

    **Token Locator Format**: `{chain}:{symbol}` or `{chain}:{contractAddress}` (e.g., `base-sepolia:eth`, `polygon:usdc`, `base-sepolia:0x123...`)

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request POST \
          --url 'https://staging.crossmint.com/api/2025-06-09/wallets/email:user@example.com:evm/tokens/base-sepolia:eth/transfers' \
          --header 'Content-Type: application/json' \
          --header 'X-API-KEY: <x-api-key>' \
          --data '{
              "recipient": "<recipient-wallet-address>",
              "amount": "0.001"
          }'
      ```

      ```javascript Node.js theme={null}
      const walletLocator = 'email:user@example.com:evm';
      const tokenLocator = 'base-sepolia:eth';
      const url = `https://staging.crossmint.com/api/2025-06-09/wallets/${walletLocator}/tokens/${tokenLocator}/transfers`;

      const options = {
          method: 'POST',
          headers: {
              'X-API-KEY': '<x-api-key>',
              'Content-Type': 'application/json'
          },
          body: JSON.stringify({
              recipient: "<recipient-wallet-address>",
              amount: "0.001"
          })
      };

      fetch(url, options)
          .then(response => response.json())
          .then(data => {
              console.log('Transaction ID:', data.id);
              console.log('Status:', data.status);
          })
          .catch(err => console.error(err));
      ```

      ```python Python theme={null}
      import requests

      wallet_locator = "email:user@example.com:evm"
      token_locator = "base-sepolia:eth"
      url = f"https://staging.crossmint.com/api/2025-06-09/wallets/{wallet_locator}/tokens/{token_locator}/transfers"

      payload = {
          "recipient": "<recipient-wallet-address>",
          "amount": "0.001"
      }
      headers = {
          "X-API-KEY": "<x-api-key>",
          "Content-Type": "application/json"
      }

      response = requests.post(url, json=payload, headers=headers)
      data = response.json()

      print(f"Transaction ID: {data['id']}")
      print(f"Status: {data['status']}")
      ```
    </CodeGroup>

    **Request Parameters:**

    * `recipient` (required): Destination address or AddressLocator. Supports wallet addresses (`0x...`) or identity-based locators like `email:user@example.com`, `phoneNumber:+12125551234`, `userId:abc123`
    * `amount` (required): Amount to transfer in decimal format (e.g., `"0.001"` for 0.001 ETH)
    * `signer` (optional): Signer locator if using operational signers (defaults to recovery signer)

    <Accordion title="Sample Response (201 Created)">
      ```json theme={null}
      {
          "id": "cm47h2m8e0003vn0zf8yz1234",
          "chainType": "evm",
          "walletType": "smart",
          "status": "pending",
          "params": {
              "calls": [...],
              "chain": "base-sepolia",
              "signer": {
                  "type": "evm-keypair",
                  "address": "0x..."
              }
          },
          "onChain": {
              "userOperationHash": "0x...",
              "txId": null
          },
          "sendParams": {
              "token": "base-sepolia:eth",
              "recipient": "<recipient-wallet-address>",
              "amount": "0.001"
          },
          "createdAt": "2025-12-15T10:35:00.000Z"
      }
      ```

      **Transaction Status Values:**

      * `awaiting-approval` - Transaction created, waiting for signer approval
      * `pending` - Transaction submitted to the blockchain
      * `success` - Transaction confirmed onchain
      * `failed` - Transaction failed

      Poll the transaction status using the transaction ID, or set up [webhooks](/wallets/guides/webhooks) for real-time updates.
    </Accordion>

    <Accordion title="Common Token Locators">
      **EVM Chains:**

      * `base-sepolia:eth` - ETH on Base Sepolia testnet
      * `base-sepolia:usdc` - USDC on Base Sepolia
      * `polygon:usdc` - USDC on Polygon mainnet
      * `ethereum:usdt` - USDT on Ethereum mainnet

      **Solana:**

      * `solana:sol` - Native SOL token
      * `solana:usdc` - USDC on Solana

      For contract tokens, use the contract address: `base-sepolia:0x123...`
    </Accordion>
  </Step>
</Steps>

### Using Idempotency Keys

Prevent duplicate wallet creation by using idempotency keys:

```bash theme={null}
curl --request POST \
    --url https://staging.crossmint.com/api/2025-06-09/wallets \
    --header 'Content-Type: application/json' \
    --header 'X-API-KEY: <x-api-key>' \
    --header 'x-idempotency-key: unique-operation-id-123' \
    --data '{
        "chainType": "evm",
        "type": "mpc",
        "owner": "email:user@example.com"
    }'
```

If you retry with the same idempotency key, you'll receive the same wallet without creating a duplicate.

## Launching in Production

Ready to go live? Here's what you need to do:

1. **Create a production account** at [www.crossmint.com/console](https://www.crossmint.com/console)
2. **Create a production API key** with the required scopes:
   * `wallets.create`, `wallets.read`, `wallets:balance.read`, `wallets:transactions.create`
3. **Update your API endpoint** from `staging.crossmint.com` to `www.crossmint.com`
4. **Update your API key** in your code to use the production key

<Warning>
  Never expose your server-side API keys in client-side code or public repositories. Store them securely in environment variables or a secrets manager.
</Warning>

## Learn More

<CardGroup>
  <Card title="Check Balances" icon="money-bill-transfer" href="/wallets/v0/guides/check-balances">
    Check the balance of a wallet.
  </Card>

  <Card title="Transfer Tokens" icon="coins" href="/wallets/v0/guides/transfer-tokens">
    Send tokens between wallets.
  </Card>

  <Card title="Operational Signers" icon="key" href="/wallets/v0/guides/signers/registering-a-signer">
    Register operational signers on a wallet.
  </Card>
</CardGroup>


# Swift
Source: https://docs.crossmint.com/wallets/v0/quickstarts/swift

Create user wallets from your iOS app in under 5 minutes

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/quickstarts/swift) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

This quickstart integrates the Crossmint Swift SDK into an iOS app to create a non-custodial wallet for a user, fund it with testnet USDC on Base Sepolia, and send USDC to another wallet.

<CardGroup>
  <Snippet />

  <Card title="iOS Demo App" icon="github" href="https://github.com/Crossmint/crossmint-swift-sdk/tree/main/Examples/SmartWalletsDemo">
    See a full working example with a repository to clone.
  </Card>
</CardGroup>

<Steps>
  <Step title="Install the SDK">
    Add the Crossmint Swift SDK to your project using Swift Package Manager.

    In Xcode, go to **File > Add Package Dependencies** and enter the repository URL:

    ```text theme={null}
    https://github.com/Crossmint/crossmint-swift-sdk
    ```

    Select the `CrossmintClientSDK` product to add to your target.

    ### Requirements

    * iOS 15.0+
    * Xcode 16.0+
    * Swift 5.9+
  </Step>

  <Step title="Configure your API key">
    The Crossmint SDK requires a client API key for authentication.
    [Get your client API key](/introduction/platform/api-keys/client-side) using the Crossmint Console.

    Create a file to store your configuration:

    ```swift CrossmintConfig.swift theme={null}
    import CrossmintAuth
    import CrossmintClient


    let crossmintApiKey = "<YOUR_API_KEY>"
    lazy var crossmintAuthManager: CrossmintAuthManager = {
        do {
            return try CrossmintAuthManager(apiKey: crossmintApiKey)
        } catch {
            fatalError("Invalid Crossmint configuration: \(error)")
        }
    }()
    ```

    <Note>
      The environment (staging vs production) is automatically determined by your API key. Staging keys start with `ck_staging_`, production keys with `ck_production_`.
    </Note>
  </Step>

  <Step title="Initialize the Crossmint SDK">
    Initialize the SDK in your app's entry point and add the non-custodial signer view modifier. This example uses [Crossmint Auth](/authentication/introduction) but you can use [any authentication provider of your choice](/wallets/v0/guides/bring-your-own-auth).

    ```swift YourApp.swift theme={null}
    import SwiftUI
    import CrossmintClient

    @main
    struct YourApp: App {
        var body: some Scene {
            WindowGroup {
                ContentView()
                    .crossmintNonCustodialSigner(
                        CrossmintSDK.shared(
                            apiKey: crossmintApiKey,
                            authManager: crossmintAuthManager
                        )
                    )
            }
        }
    }
    ```

    The `.crossmintNonCustodialSigner()` modifier is required for transaction signing. It embeds a hidden web view that securely manages the signing process.

    ### Access SDK instances

    Inside your views, access SDK functionality using `CrossmintSDK.shared`:

    ```swift theme={null}
    import CrossmintClient

    let sdk = CrossmintSDK.shared
    let authManager = sdk.authManager
    let wallets = sdk.crossmintWallets
    ```
  </Step>

  <Step title="Authenticate users">
    Actions within the SDK are user-based, so first you need to authenticate a user.
    Choose your authentication method:

    <Tabs>
      <Tab title="Crossmint Auth (OTP)">
        Use Crossmint's built-in OTP authentication for easy, email-based login.

        <Steps>
          <Step title="Send OTP to user's email">
            ```swift theme={null}
            import CrossmintClient

            let email = "user@example.com"

            do {
                let status = try await crossmintAuthManager.otpAuthentication(
                    email: email,
                    code: nil,
                    forceRefresh: false
                )

                if case let .emailSent(_, emailId) = status {
                    // OTP sent to email, now display an input for the OTP
                    // Store emailId for the verification step
                }
            } catch let error as AuthManagerError {
                // Handle error: error.errorMessage
            }
            ```
          </Step>

          <Step title="Verify the OTP sent to the user's email">
            ```swift theme={null}
            import CrossmintClient

            let otpCode = "123456" // Code entered by user

            do {
                let status = try await crossmintAuthManager.otpAuthentication(
                    email: email,
                    code: otpCode,
                    forceRefresh: false
                )

                if case .authenticated = status {
                    // User is authenticated, proceed to create wallet
                }
            } catch let error as AuthManagerError {
                // Handle error: error.errorMessage
            }
            ```
          </Step>
        </Steps>

        <Note>
          See the [iOS Demo App](https://github.com/Crossmint/crossmint-swift-sdk/tree/main/Examples/SmartWalletsDemo) repository for a complete UI implementation example with SwiftUI views.
        </Note>
      </Tab>

      <Tab title="Third-Party Auth (Prod)">
        If you have an existing auth provider (Auth0, Firebase, Supabase, etc.), authenticate users with your provider and pass the JWT to Crossmint.

        ```swift theme={null}
        import CrossmintClient

        // After user authenticates with your provider, get their JWT
        let authManager = CrossmintSDK.shared.authManager

        do {
            try await authManager.authenticateWithToken(
                jwt: yourProviderJWT,
                refreshToken: yourProviderRefreshToken // optional
            )
            // User authenticated with Crossmint
        } catch {
            // Handle error
        }
        ```

        <Note>
          Configure JWT authentication in the [Crossmint Console](https://console.crossmint.com) under API Keys > JWT Authentication before using third-party auth.
        </Note>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Create a wallet">
    After authentication, create the user's wallet. This example uses Base Sepolia (Base testnet) but you can choose any [supported chain](/introduction/supported-chains).

    ```swift theme={null}
    import CrossmintClient

    let sdk = CrossmintSDK.shared

    do {
        guard let email = await crossmintAuthManager.email else {
            // User not authenticated
            return
        }

        let wallet = try await sdk.crossmintWallets.getOrCreateWallet(
            chain: .baseSepolia,
            signer: .email(email)
        )

        // Wallet is ready to use!
        print("Wallet address: \(wallet.address)")
    } catch let error as WalletError {
        // Handle error: error.errorMessage
    }
    ```
  </Step>

  <Step title="Check wallet balance">
    Before sending tokens, check the wallet balance:

    ```swift theme={null}
    import CrossmintClient
    import Wallet
    import CrossmintCommonTypes

    // Convert to EVMWallet for EVM-specific operations
    guard let evmWallet = try? EVMWallet.from(wallet: wallet) else {
        return
    }

    do {
        let balance = try await evmWallet.balances([.eth, .usdc, .usdxm])

        // Access native token balance
        print("ETH: \(balance.nativeToken.amount)")

        // Access USDC balance
        print("USDC: \(balance.usdc.amount)")

        // Access other tokens
        for token in balance.tokens {
            print("\(token.token.name): \(token.amount)")
        }
    } catch let error as WalletError {
        // Handle error: error.errorMessage
    }
    ```
  </Step>

  <Step title="Fund the wallet">
    Before sending USDC, you need to get some into the wallet.

    **Option 1: Use the staging fund method (staging only)**

    ```swift theme={null}
    do {
        try await evmWallet.fund(token: .usdxm, amount: 10)
    } catch {
        // Handle error
    }
    ```

    **Option 2: Use the USDC Faucet**

    Get the wallet address and use the [USDC Faucet](https://faucet.circle.com/):

    ```swift theme={null}
    let walletAddress = wallet.address
    print("Fund this address: \(walletAddress)")
    ```

    Navigate to the faucet, select **Base Sepolia**, and enter the wallet address.

    <img alt="Circle faucet - Base Sepolia selected" />
  </Step>

  <Step title="Send USDC">
    Send USDC to another wallet using the `wallet.send` function:

    ```swift theme={null}
    import CrossmintClient
    import Wallet
    import CrossmintCommonTypes

    let recipientAddress = "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"

    do {
        guard let evmAddress = try? EVMAddress(address: recipientAddress) else {
            // Invalid address
            return
        }

        let result = try await wallet.send(
            token: .usdc,
            recipient: .address(.evm(.baseSepolia, evmAddress)),
            amount: "0.01"
        )

        // Transaction successful
        print("Transaction completed")
    } catch let error as TransactionError {
        switch error {
        case .userCancelled:
            // User cancelled the transaction
            break
        default:
            // Handle error: error.errorMessage
            break
        }
    }
    ```

    The first time a wallet sends a transaction on a device, an OTP verification is required. The SDK automatically handles this by presenting an OTP input view.

    To handle the OTP flow, observe the `isOTPRequired` publisher in your view:

    ```swift theme={null}
    import SwiftUI
    import CrossmintClient

    struct ContentView: View {
        @State private var showOTPView = false

        var body: some View {
            YourMainView()
                .onReceive(CrossmintSDK.shared.isOTPRequired) { required in
                    showOTPView = required
                }
                .sheet(isPresented: $showOTPView) {
                    OTPValidatorView()
                }
        }
    }
    ```

    Following transactions sent from the same device do not need OTP verification.
    And that is it! You just created a non-custodial wallet for your user and made a USDC transaction on Base Sepolia.
  </Step>
</Steps>

## Launching in Production

For production, the steps are almost identical, but some changes are required:

1. Create a developer account on the [production console](https://www.crossmint.com/console)
2. Create a production client API key on the [API Keys](https://www.crossmint.com/console/projects/apiKeys) page with the API scopes `users.create`, `users.read`, `wallets.read`, `wallets.create`, `wallets:transactions.create`, `wallets:transactions.sign`, `wallets:balance.read`, `wallets.fund`
3. Update your configuration with the production API key
4. **Use your own authentication provider**: For production applications, Crossmint recommends using [third-party authentication](/wallets/v0/guides/bring-your-own-auth) with providers like Auth0, Firebase, or Supabase, rather than Crossmint Auth (OTP). Configure JWT authentication in the [Crossmint Console](https://www.crossmint.com/console/projects/apiKeys) under API Keys > JWT Authentication

## Learn More

<CardGroup>
  <Card title="Check Balances" icon="money-bill-transfer" href="/wallets/v0/guides/check-balances">
    Check the balance of a wallet.
  </Card>

  <Card title="Transfer Tokens" icon="coins" href="/wallets/v0/guides/transfer-tokens">
    Send tokens between wallets.
  </Card>

  <Card title="Operational Signers" icon="key" href="/wallets/v0/guides/signers/registering-a-signer">
    Register operational signers on a wallet.
  </Card>
</CardGroup>

## Other Links

<CardGroup>
  <Card title="Swift SDK Reference" icon="https://mintcdn.com/crossmint/GBIHIdhwMt6rU_EY/images/icons/swift.svg?fit=max&auto=format&n=GBIHIdhwMt6rU_EY&q=85&s=91137deeec19366731790dd77c0982bc" href="/sdk-reference/wallets/swift/classes/wallet">
    Deep dive into Swift SDK reference docs.
  </Card>

  <Card title="Talk to an expert" icon="message" href="https://www.crossmint.com/contact/sales">
    Contact the Crossmint sales team for support.
  </Card>
</CardGroup>


# Why Smart Contract Wallets
Source: https://docs.crossmint.com/wallets/v0/why-smart-wallets

Why Crossmint chose smart contract wallets as the foundation for its wallet infrastructure.

<Warning>
  **You are viewing docs for the previous version of the Wallets SDK.** We recommend upgrading to V1.
  See the [updated version of this page](/wallets/architecture) or the [V1 migration guide](/wallets/guides/migrate-to-v1).
</Warning>

We believe wallets are becoming a foundational primitive for the entire economy — not just for crypto users, but for every person, company, AI agent, and connected device that needs to hold value or authorize payments. At that scale, wallet infrastructure must be extremely cheap to operate, flexible enough to support any custody model, and publicly auditable so that security is a matter of proof, not trust.

## The Problem with Off-Chain Key Storage

Most wallet infrastructure today stores keys off-chain, inside proprietary enclaves or distributed across MPC networks. This means:

* **Provider dependency**: Wallets depend on a specific provider's infrastructure to function.
* **Latency overhead**: Key reconstruction adds latency to every signature.
* **Painful migration**: Moving to a new provider means exporting keys and creating new wallet addresses.

These are reasonable trade-offs for certain use cases — but they are not the right foundation for millions of wallets transacting continuously.

## A Different Approach

Smart contract wallets take a different approach. The wallet is a program deployed on a public blockchain — it does not live in anyone's private infrastructure. The signer is completely separate and can be anything: a passkey on a user's phone, an AWS KMS key in your cloud, or a recovery credential.

The key stays whole. No splitting, no reconstruction, no added latency.

* **Security** is not a promise — it is code you can read.
* **Recovery** is not a key-share coordination problem — it is an onchain signer rotation.
* **Migration** is not an export — it is a signer swap.

## Why We Chose This Architecture

We chose this architecture because it is the only one that scales to the future we are building toward: **wallets as ubiquitous and permanent as email addresses, but programmable, auditable, and owned by no one except the people and systems that use them.**

<CardGroup>
  <Card title="Architecture" icon="layer-group" href="/wallets/v0/architecture">
    See how the dual-layer architecture works in practice.
  </Card>

  <Card title="Wallet Signers" icon="key" href="/wallets/v0/concepts/wallet-signers">
    Explore the signer types that plug into this architecture.
  </Card>
</CardGroup>